# Bellona Bridge Coexistence and Deprecation Plan

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](./bridge-retirement-gate.md). 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
```
