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
(180.C.16.15). It is the operational companion to:
- the compatibility shim —
bridge-migration-guide.md(180.C.38.03) - the deprecation timeline —
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.blendfile pathunreal-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:
interface BridgeOperation {
origin: 'legacy-bridge' | 'remote-host';
resource: RemoteLockResource; // { kind, key }
mode: RemoteLockMode; // 'shared' (read) | 'exclusive' (write)
label?: string;
}
The rule:
- Different resources (
remoteLockResourceIddiffers) → no conflict. They coexist freely. - Same resource, both
shared(read/read) → no conflict. Shared locks coexist; both proceed. - Same resource, both
exclusive(write/write) →write-writeconflict, mutual exclusion. The lock manager grants whoever acquires FIRST and refuses/queues the other; they cannot run concurrently. The pure rule reportsmutualExclusion: trueand leaveswinnerundefined — the manager, with its FIFOwaitqueue and lease expiry, breaks the tie, not this stateless helper. - Same resource, exactly one
exclusive(read/write) →read-writeconflict. 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#
- 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). - Prefer the future authority. When a Remote Host equivalent exists, route
through it (the shim does this automatically — a translatable legacy command
becomes a
RemoteCommandEnvelopeand 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. - Reads never block reads. Discovery/health/scene-info on either surface use
sharedlocks and run concurrently. - 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.
- 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#
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.