# Bridge Migration Guide (180.C.38.03)

Status: `180.C.38.03` — migrating consumers from the OLD
`apps/bellona/bridge-blender` / `bridge-unreal` services to the NEW Remote Host
command envelopes.

This guide executes the migration-examples section of the
[bridge coexistence and deprecation plan](./bridge-coexistence-and-deprecation-plan.md)
(`180.C.16.15`). See also the
[parallel-operation guide](./bridge-parallel-operation.md) (`180.C.38.02`) and
the [deprecation timeline](./bridge-deprecation-timeline.md) (`180.C.38.04`).

## Two migration paths

You have two ways off the old bridges, in increasing order of effort and value:

1. **Zero-code-change shim** (interim). Keep your existing legacy `{ bridge,
   type, payload }` request shape and send it to the gateway's compatibility
   endpoint `POST /v1/legacy-bridge/commands`. The gateway translates it into a
   `RemoteCommandEnvelope` via the 38.01 shim
   (`libs/bellona/remote-protocol/src/bridge-compat.ts`,
   `translateLegacyBridgeRequest`) and dispatches it through the real pipeline.
   This buys time but every call is counted as legacy usage
   (`remote_gateway.legacy_bridge.usage.count`) and is refused once the
   `acceptLegacyBridgeProtocol` flag flips OFF at hard cutover (see the
   timeline).
2. **Native Remote Host SDK** (target). Replace the bridge call with the
   `@bellona/client` Remote SDK (`createBellonaRemoteClient`,
   `libs/bellona/client/src/remote/client.ts`). This is the only supported
   long-term path.

The before/after examples below show BOTH the interim shim payload and the
target SDK call for each command.

## Command mapping (legacy → Remote Host)

The shim covers every legacy command that has a Remote Host equivalent today.
Commands without parity (e.g. `blender:set-frame`, `unreal:load-level`,
`unreal:execute-console-command`) stay on the loopback bridge until their
replacement stage lands; the shim FAILS LOUD on them
(`UnsupportedLegacyBridgeCommandError`) rather than silently dropping them.

| Legacy command | Remote Host command | Risk |
| --- | --- | --- |
| `blender:get-scene-info` | `blender.scene.info` | read-only |
| `blender:create-object` | `blender.object.create_primitive` | safe-mutation |
| `blender:import-asset` | `blender.asset.import` | safe-mutation |
| `blender:export-asset` | `blender.asset.export` | safe-mutation |
| `blender:render` | `blender.render.capture` | safe-mutation |
| `unreal:get-world-info` | `unreal.world.query` | read-only |
| `unreal:spawn-actor` | `unreal.actor.spawn` | safe-mutation |
| `unreal:destroy-actor` | `unreal.actor.destroy` | destructive (needs approval) |
| `unreal:set-actor-property` | `unreal.actor.set_property` | safe-mutation |
| `unreal:call-blueprint-function` | `unreal.blueprint.call_function` | safe-mutation |
| `unreal:set-material-parameter` | `unreal.material.set_parameter` | safe-mutation |

The authoritative source for this table is `LEGACY_BRIDGE_COMMAND_MAP` in
`libs/bellona/remote-protocol/src/bridge-compat.ts` (and
`SUPPORTED_LEGACY_BRIDGE_COMMAND_TYPES`).

## Example 1 — Blender: create a cube

### BEFORE (legacy `@bellona/bridge-blender` WebSocket command)

```ts
// Old: a flat bridge-core command on ws://127.0.0.1:9001/blender
bridge.request('blender:create-object', {
  type: 'mesh',
  name: 'Hero',
  location: [1, 2, 3],
  rotation: [0, 0, 0],
  scale: [2, 2, 2],
});
```

### AFTER — interim shim (no payload rewrite)

```ts
// POST http://127.0.0.1:4070/v1/legacy-bridge/commands
await fetch('http://127.0.0.1:4070/v1/legacy-bridge/commands', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    bridge: 'blender',
    type: 'blender:create-object',
    payload: { type: 'mesh', name: 'Hero', location: [1, 2, 3], scale: [2, 2, 2] },
    context: {
      sessionId: 'session:studio-1',
      deviceId: 'device:workstation-7',
      issuedByParticipantId: 'participant:director-jo',
      idempotencyKey: 'create-hero-0001',
      issuedAt: new Date().toISOString(),
      consumerId: 'studio-bellona-bridge-blender-route-map',
    },
  }),
});
// The gateway translates this to a `blender.object.create_primitive` envelope.
```

### AFTER — target Remote Host SDK

```ts
import { createBellonaRemoteClient } from '@bellona/client';

const client = createBellonaRemoteClient({ baseUrl: 'http://127.0.0.1:4070' });

await client.blender.run({
  id: 'command:create-hero-0001',
  sessionId: 'session:studio-1',
  issuedByParticipantId: 'participant:director-jo',
  idempotencyKey: 'create-hero-0001',
  issuedAt: new Date().toISOString(),
  target: { deviceId: 'device:workstation-7', commandName: 'blender.object.create_primitive' },
  riskClass: 'safe-mutation',
  rollbackStrategy: 'undo_stack',
  arguments: {
    name: 'Hero',
    primitiveType: 'cube', // legacy 'mesh' maps to 'cube'
    transform: {
      location: { x: 1, y: 2, z: 3 },
      rotationEuler: { x: 0, y: 0, z: 0 },
      scale: { x: 2, y: 2, z: 2 },
    },
  },
});
```

## Example 2 — Unreal: spawn an actor

### BEFORE (legacy `@bellona/bridge-unreal` WebSocket command)

```ts
// Old: a flat bridge-core command on ws://127.0.0.1:9003/unreal
bridge.request('unreal:spawn-actor', {
  className: 'StaticMeshActor',
  location: { x: 10, y: 20, z: 30 },
  rotation: { pitch: 0, yaw: 90, roll: 0 },
});
```

### AFTER — interim shim

```ts
await fetch('http://127.0.0.1:4070/v1/legacy-bridge/commands', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    bridge: 'unreal',
    type: 'unreal:spawn-actor',
    payload: {
      className: 'StaticMeshActor',
      location: { x: 10, y: 20, z: 30 },
      rotation: { pitch: 0, yaw: 90, roll: 0 },
    },
    context: {
      sessionId: 'session:studio-1',
      deviceId: 'device:workstation-7',
      issuedByParticipantId: 'participant:director-jo',
      idempotencyKey: 'spawn-prop-0001',
      issuedAt: new Date().toISOString(),
      consumerId: 'studio-bellona-bridge-unreal-route-map',
    },
  }),
});
```

### AFTER — target Remote Host SDK

```ts
await client.unreal.run({
  id: 'command:spawn-prop-0001',
  sessionId: 'session:studio-1',
  issuedByParticipantId: 'participant:director-jo',
  idempotencyKey: 'spawn-prop-0001',
  issuedAt: new Date().toISOString(),
  target: { deviceId: 'device:workstation-7', commandName: 'unreal.actor.spawn' },
  riskClass: 'safe-mutation',
  rollbackStrategy: 'undo_stack',
  arguments: {
    actorClass: { className: 'StaticMeshActor' },
    transform: {
      location: { x: 10, y: 20, z: 30 },
      rotation: { pitch: 0, yaw: 90, roll: 0 },
      scale: { x: 1, y: 1, z: 1 },
    },
  },
});
```

## Example 3 — Unreal: destroy an actor (a destructive command)

A destructive command requires `approvalRequired: true` plus a dry-run plan, per
the protocol's `RemoteCommandEnvelopeSchema` invariants. The interim shim
synthesizes these for you (it derives a stable `dryRunPlanId` from the
idempotency key); the native SDK call must supply them.

### BEFORE

```ts
bridge.request('unreal:destroy-actor', { actorId: 'actor-123' });
```

### AFTER — interim shim (approval + dry-run plan synthesized by the shim)

```ts
await fetch('http://127.0.0.1:4070/v1/legacy-bridge/commands', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    bridge: 'unreal',
    type: 'unreal:destroy-actor',
    payload: { actorId: 'actor-123' },
    context: {
      sessionId: 'session:studio-1',
      deviceId: 'device:workstation-7',
      issuedByParticipantId: 'participant:director-jo',
      idempotencyKey: 'destroy-actor-0001',
      issuedAt: new Date().toISOString(),
    },
  }),
});
// Shim sets approvalRequired=true, metadata.dryRunSupported=true,
// metadata.dryRunPlanId='dry-run-plan:destroy-actor-0001'.
```

### AFTER — target Remote Host SDK

```ts
await client.unreal.run({
  id: 'command:destroy-actor-0001',
  sessionId: 'session:studio-1',
  issuedByParticipantId: 'participant:director-jo',
  idempotencyKey: 'destroy-actor-0001',
  issuedAt: new Date().toISOString(),
  target: { deviceId: 'device:workstation-7', commandName: 'unreal.actor.destroy' },
  riskClass: 'destructive',
  approvalRequired: true,
  rollbackStrategy: 'undo_stack',
  metadata: { dryRunSupported: true, dryRunPlanId: 'dry-run-plan:destroy-actor-0001' },
  arguments: { actorId: 'actor-123' },
});
```

## Response handling

The shim also restores the LEGACY response shape so your existing response code
keeps working during the interim: `translateRemoteResponseToLegacy(legacyType,
result)` (`libs/bellona/remote-protocol/src/bridge-compat.ts`) maps a Remote Host
result back to the old `{ objectName, objectType, success }` /
`{ actorId, actorName, className, success }` shapes. When you adopt the native
SDK, read the `RemoteCommandDispatchRecord` / `RemoteCommandView` returned by
`client.<engine>.run(...)` instead.

## Verification

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