# Bridge Parallel-Operation Guide (180.C.38.02)

Status: `180.C.38.02` — running the OLD bridges and the NEW Remote Host
simultaneously, with conflict detection and reconciliation rules.

This guide executes the parallel-operation section of the
[bridge coexistence and deprecation plan](./bridge-coexistence-and-deprecation-plan.md)
(`180.C.16.15`). It is the operational companion to:

- the compatibility shim — [`bridge-migration-guide.md`](./bridge-migration-guide.md)
  (`180.C.38.03`)
- the deprecation timeline — [`bridge-deprecation-timeline.md`](./bridge-deprecation-timeline.md)
  (`180.C.38.04`)

## What runs in parallel

| Surface | Process | Ports | Owns |
| --- | --- | --- | --- |
| Legacy Blender bridge | `apps/bellona/bridge-blender` | `ws://127.0.0.1:9001/blender` | Loopback WS command forwarding only |
| Legacy Unreal bridge | `apps/bellona/bridge-unreal` | `ws://127.0.0.1:9003/unreal` | Loopback WS command forwarding only |
| Remote Host gateway | `apps/bellona/remote-gateway` | `:4070` (`POST /v1/commands`, `POST /v1/legacy-bridge/commands`) | Policy, approvals, audit, timeline, **distributed locks**, command envelopes |

During rollout BOTH may run. The Remote Host is the single long-term authority;
the legacy bridges keep working through the compatibility shim
(`libs/bellona/remote-protocol/src/bridge-compat.ts`,
`translateLegacyBridgeRequest`) which is reached at the gateway via
`POST /v1/legacy-bridge/commands`
(`apps/bellona/remote-gateway/src/legacy-bridge.ts`,
`acceptLegacyBridgeRequest`). Every legacy call is counted by the
`remote_gateway.legacy_bridge.usage.count` telemetry series
(`recordLegacyBridgeUsage`, `apps/bellona/remote-gateway/src/telemetry.ts`).

## The shared resources both surfaces contend for

Two operations — one on each surface — can target the SAME shared resource. The
contended resource kinds are defined by `RemoteLockResourceKind`
(`libs/bellona/remote-protocol/src/fleet.ts`); the two that matter for
engine coexistence are:

- `blender-file` — a `.blend` file path
- `unreal-map` — an Unreal map/level path (e.g. `/Game/Maps/Main`)

A resource is identified by `(kind, key)` via `remoteLockResourceId(resource)`
(it renders as `blender-file::/proj/scene.blend`). Two operations address the
same target iff their `(kind, key)` match.

## The arbiter: the 30.04 distributed lock manager

The gateway's `InMemoryDistributedLockManager`
(`apps/bellona/remote-gateway/src/distributed-lock-manager.ts`, stage
`180.C.30.04`) is the single authority that grants/denies access to a shared
resource. It is a reader/writer lock per `(kind, key)`:

- **shared** (`RemoteLockMode = 'shared'`, read) holders coexist — any number.
- **exclusive** (`RemoteLockMode = 'exclusive'`, write) is mutually exclusive —
  exactly one holder, refused/queued while any other holder is present.

A host never grants its own lock; the gateway does. This is what lets the legacy
bridges and the Remote Host coexist safely: BOTH write paths acquire a lock from
the same gateway authority before mutating a Blender file or an Unreal map, so
the gateway serializes them.

## Conflict-detection rule (code, not prose)

The coexistence rule is a real, tested helper, not a doc paragraph:
`detectBridgeConflict(legacyOp, remoteOp)` in
`libs/bellona/remote-protocol/src/bridge-compat.ts` (tested in
`bridge-compat.test.ts`). Each `BridgeOperation` carries:

```ts
interface BridgeOperation {
  origin: 'legacy-bridge' | 'remote-host';
  resource: RemoteLockResource; // { kind, key }
  mode: RemoteLockMode;         // 'shared' (read) | 'exclusive' (write)
  label?: string;
}
```

The rule:

1. **Different resources** (`remoteLockResourceId` differs) → **no conflict**.
   They coexist freely.
2. **Same resource, both `shared` (read/read)** → **no conflict**. Shared locks
   coexist; both proceed.
3. **Same resource, both `exclusive` (write/write)** → **`write-write` conflict,
   mutual exclusion**. The lock manager grants whoever acquires FIRST and
   refuses/queues the other; they cannot run concurrently. The pure rule reports
   `mutualExclusion: true` and leaves `winner` undefined — the *manager*, with
   its FIFO `wait` queue and lease expiry, breaks the tie, not this stateless
   helper.
4. **Same resource, exactly one `exclusive` (read/write)** → **`read-write`
   conflict**. The **writer wins** the exclusive lock (`winner` = the writer);
   the reader must serialize — wait for, or run before, the writer.

### Who wins, concretely

| Legacy op | Remote op | Outcome | Winner |
| --- | --- | --- | --- |
| read `/proj/a.blend` | read `/proj/a.blend` | coexist | both |
| read `/Game/Maps/Main` | write `/Game/Maps/Main` | reader serializes behind writer | Remote Host (writer) |
| write `/proj/scene.blend` | read `/proj/scene.blend` | reader serializes behind writer | Legacy bridge (writer) |
| write `/proj/scene.blend` | write `/proj/scene.blend` | mutual exclusion | first acquirer (lock manager FIFO) |

## How a conflict surfaces

A losing acquire is **fail-loud**, never a silent clobber. The lock manager
returns a `DistributedLockGrant` with `granted: false`,
`outcome: 'conflict'`, the blocking `conflictingHolderIds`, and a human `reason`
(`apps/bellona/remote-gateway/src/distributed-lock-manager.ts`). A caller may
instead pass `wait: true` to be QUEUED (FIFO) and receive its queue position; a
later release or lease expiry that satisfies the head of the queue grants it.

## Reconciliation rules

1. **Single writer per engine resource.** Only one write path may own mutating
   traffic for a given Blender file or Unreal map at a time — enforced by the
   exclusive lock, regardless of whether the writer is a legacy bridge or the
   Remote Host (this is the plan's "only one write path may own mutating
   traffic" rule, made executable by `detectBridgeConflict` + the lock manager).
2. **Prefer the future authority.** When a Remote Host equivalent exists, route
   through it (the shim does this automatically — a translatable legacy command
   becomes a `RemoteCommandEnvelope` and acquires the gateway lock like any
   native command). This means legacy write traffic and native write traffic
   contend on the SAME lock, so they cannot both mutate the resource.
3. **Reads never block reads.** Discovery/health/scene-info on either surface use
   `shared` locks and run concurrently.
4. **Leases bound a crashed holder.** A bridge or host that dies without
   releasing has its lock reclaimed once the lease elapses, so a crash on one
   surface cannot permanently wedge the other.
5. **Commands without Remote Host parity stay loopback-only** (e.g.
   `blender:set-frame`, `unreal:load-level`) until their replacement stage lands
   or telemetry proves zero consumers. The shim FAILS LOUD on these
   (`UnsupportedLegacyBridgeCommandError`) rather than fabricating an envelope,
   so they are never silently routed to a non-existent Remote Host command.

## Verification

```bash
cd libs/bellona/remote-protocol && npx vitest run src/bridge-compat.test.ts
cd apps/bellona/remote-gateway && npx vitest run src/distributed-lock-manager.test.ts
```

The `detectBridgeConflict` rule above is verified by the
`describe('detectBridgeConflict — 180.C.38.02')` block in
`libs/bellona/remote-protocol/src/bridge-compat.test.ts`.
