Eve library

Bellona Bridge Coexistence and Deprecation Plan

Guide

Revision 1

On this page

Status: 180.C.16.15 coexistence and deprecation plan.

Implementation date: 2026-04-23.

This plan covers the old apps/bellona/bridge-blender and apps/bellona/bridge-unreal consumers while the Remote Host path becomes the only supported authority. Execution belongs to Stage 180.C.38; this note fixes the expected shim behavior, parallel-operation rules, hard cutover date, and final removal gate so later migration work does not invent a second plan.

Sources Reviewed#

  • apps/bellona/bridge-blender/src/main.ts
  • apps/bellona/bridge-unreal/src/main.ts
  • apps/bellona/remote-host/src/blender-adapter.ts
  • apps/bellona/remote-host/src/unreal-adapter.ts
  • apps/bellona/remote-host/README.md
  • docs/domains/bellona/extras/remote-control/unreal-plugin-architecture.md
  • TODOS/phase-180.md

Coexistence Model#

The old bridges and the new Remote Host do not own the same responsibility:

  • the old bridges are loopback WebSocket forwarders with bridge-core command names
  • the Remote Host is the only long-term gateway-facing authority and owns policy, approvals, audit, timeline, and protocol envelopes

During rollout, the compatibility shim keeps the old bridge command names alive without letting the old bridges reclaim gateway authority.

Legacy Command Strategy#

Blender#

apps/bellona/bridge-blender exposes six blender:* commands on ws://127.0.0.1:9001/blender.

  • Translate now:
    • blender:get-scene-info -> blender.scene.info
    • blender:create-object -> blender.object.create_primitive for the safe primitive subset only
  • Keep on compatibility path until later Blender production stages:
    • blender:import-asset
    • blender:export-asset
    • blender:set-frame
    • blender:render

Unreal#

apps/bellona/bridge-unreal exposes eleven unreal:* commands on ws://127.0.0.1:9003/unreal.

  • Translate now:
    • unreal:get-world-info -> unreal.world.query
    • unreal:spawn-actor -> unreal.actor.spawn
  • Keep on compatibility path until later Unreal production stages:
    • unreal:destroy-actor
    • unreal:set-actor-property
    • unreal:call-blueprint-function
    • unreal:load-level
    • unreal:unload-level
    • unreal:set-material-parameter
    • unreal:sequencer-control
    • unreal:execute-console-command
    • unreal:take-screenshot

unreal:execute-console-command is compatibility-only. The target Remote Host architecture does not let arbitrary console execution survive final cutover.

Parallel Operation Rules#

  • Legacy bridges remain loopback-only on their existing ports.
  • The Remote Host keeps exclusive ownership of gateway connectivity, policy, approvals, audit, and timeline.
  • Health and discovery may run in parallel, but only one write path may own mutating traffic for a Blender or Unreal project at a time.
  • When a protocol-owned Remote Host equivalent already exists, the shim must translate into that path first so production traffic exercises the future authority before cutover.
  • Commands without Remote Host parity may stay on the compatibility path only until their replacement stages land or telemetry proves no consumers remain.

Cutover Date#

The hard cutover date is October 21, 2026 (2026-10-21T00:00:00.000Z).

Stage 180.C.38.04 must publish the public warning and final removal dates around that anchor. This plan requires at least 56 days of warning lead time before hard cutover.

Final Removal Gate#

The old bridges cannot be removed until Stage 180.C.38.09, and that gate stays blocked until all of the following are true:

  • Stage 180.C.29.10 final GA acceptance is complete on origin/main
  • Stages 180.C.38.01 through .08 are complete
  • every compatibility-only command either has a released Remote Host replacement or zero consumers in telemetry
  • telemetry shows zero production consumers for 30 consecutive days after October 21, 2026
  • post-removal verification proves no Oshun service, test, script, or docs still depend on the old bridges

The executable local contract for Stage 180.C.38.07 through .10 is documented in Bridge Retirement Gate. That gate is intentionally separate from this coexistence plan: this note keeps the compatibility period coherent, while the retirement gate proves the old bridge apps can actually be removed.

Execution Mapping#

This plan feeds the later Stage 180.C.38 work directly:

  1. 180.C.38.01: implement the shim strategies listed here.
  2. 180.C.38.02: document the parallel-operation and conflict rules listed here.
  3. 180.C.38.03: write migration examples using the command mappings listed here.
  4. 180.C.38.04: publish the warning, cutover, and removal dates anchored to October 21, 2026.
  5. 180.C.38.05-.09: enforce, measure, and finally remove the old bridges using the removal gate listed here.

Verification#

bash
pnpm exec vitest run --config vitest.config.ts tests/bridge-coexistence-plan.test.ts --reporter=verbose
pnpm nx run-many -p @bellona/remote-control-testing -t lint,typecheck,test,build --skip-nx-cache --verbose