# Bridge Deprecation Timeline (180.C.38.04)

Status: `180.C.38.04` — the dated phases for warning emission, hard cutover, and
final removal of the OLD `apps/bellona/bridge-blender` / `bridge-unreal`
services.

This timeline executes the dates section of the
[bridge coexistence and deprecation plan](./bridge-coexistence-and-deprecation-plan.md)
(`180.C.16.15`), which fixes the hard-cutover anchor at **2026-10-21**, requires
**≥ 56 days** of warning lead time, and a **30-day** zero-consumer removal gate.
The phase logic is real, tested code, not just prose:
`bridgeDeprecationPhase(now, schedule)` in
`libs/bellona/remote-protocol/src/bridge-deprecation.ts` (tested in
`bridge-deprecation.test.ts`).

## The five phases

`bridgeDeprecationPhase` maps a wall-clock `now` + a `BridgeDeprecationSchedule`
to one of five monotonic phases and the operational facts each implies:

| Phase | Shim active? | `acceptLegacyBridgeProtocol` default (38.05) | Warning emitted? | Old packages removed? |
| --- | --- | --- | --- | --- |
| `pre-deprecation` | yes | **ON** | no | no |
| `warning` | yes | **ON** | yes | no |
| `soft-deprecated` | yes | **ON** | yes | no |
| `hard-cutover` | yes (drills only) | **OFF** | yes | no |
| `removed` | no | OFF | no | **yes** |

The `acceptLegacyByDefault` column is exactly the default value of the 38.05
feature flag (`acceptLegacyBridgeProtocol`,
`apps/bellona/remote-gateway/src/config.ts`): legacy protocol is accepted until
hard cutover, then refused by default (a forced-migration drill may flip it back
ON briefly, which is why the shim CODE survives hard cutover and is only deleted
at `removed`).

## The canonical schedule (anchored to the 16.15 plan)

```ts
const schedule: BridgeDeprecationSchedule = {
  warningStartsAt:          '2026-08-26T00:00:00.000Z', // 56 days before cutover
  softDeprecationStartsAt:  '2026-09-21T00:00:00.000Z', // 30 days before cutover
  hardCutoverAt:            '2026-10-21T00:00:00.000Z', // the plan's anchor
  removalAt:                '2026-11-20T00:00:00.000Z', // 30-day zero-consumer gate
};
```

| Boundary | Date | Why this date |
| --- | --- | --- |
| Warning emission begins | **2026-08-26** | ≥ 56 days of lead time before hard cutover (plan requirement). |
| Soft-deprecation begins | **2026-09-21** | 30 days out; deprecation goes loud, holdout chase escalates. |
| Hard cutover | **2026-10-21** | The plan's fixed anchor. `acceptLegacyBridgeProtocol` defaults OFF; legacy protocol refused with a migration-required error. |
| Final removal | **2026-11-20** | Earliest date the 30-day zero-consumer removal gate can clear (telemetry must show zero production consumers for 30 consecutive days after cutover). |

`BridgeDeprecationScheduleSchema` enforces that these boundaries are strictly
increasing; a non-monotonic schedule fails loud at parse time.

## Phase-transition criteria

A date is necessary but not sufficient — each transition also has a gate:

1. **→ warning (2026-08-26).** The shim, the 38.05 flag, and the 38.06 usage
   telemetry (`remote_gateway.legacy_bridge.usage.count`) are all live; the
   public deprecation notice is published.
2. **→ soft-deprecated (2026-09-21).** Holdouts identified from the 38.06
   telemetry have been contacted; every legacy call emits a deprecation warning;
   the hard-cutover date is announced in release notes.
3. **→ hard-cutover (2026-10-21).** `180.C.29.10` final GA acceptance is complete
   on `origin/main`, and every compatibility-only command either has a released
   Remote Host replacement OR zero consumers in telemetry. The flag default
   flips to OFF (`BELLONA_REMOTE_GATEWAY_ACCEPT_LEGACY_BRIDGE_PROTOCOL=false`).
4. **→ removed (2026-11-20 earliest).** The 30-day zero-consumer window has
   elapsed with telemetry showing no production legacy usage; post-removal
   verification (`180.C.38.08`) proves no Oshun service, test, script, or doc
   depends on the old bridges. Only then do `180.C.38.07`/`.09` delete the old
   packages and this timeline's `removed` phase becomes true.

The removal itself (`180.C.38.07`/`.09`/`.10`) is gated on Remote Host GA and
zero consumers and is intentionally NOT part of this stage's deliverable — this
stage builds the coexistence/deprecation machinery that precedes removal.

## Forced-migration drills (38.05)

Before the real hard cutover, operators can rehearse it by setting
`BELLONA_REMOTE_GATEWAY_ACCEPT_LEGACY_BRIDGE_PROTOCOL=false` for a window. During
a drill, `resolveLegacyBridgeAcceptance(false, request)`
(`apps/bellona/remote-gateway/src/legacy-bridge.ts`) refuses every legacy request
with a `LegacyBridgeProtocolDisabledError` (HTTP `410` at
`POST /v1/legacy-bridge/commands`) whose message points at the
[migration guide](./bridge-migration-guide.md). A drill surfaces remaining
holdouts as hard failures rather than waiting for the real cutover.

## Command-level deprecation registry (29.15)

The calendar phases above are complemented by a version-level deprecation
registry built on the 29.15 `RemoteDeprecationRegistry`
(`libs/bellona/remote-protocol/src/protocol-evolution.ts`).
`createBridgeDeprecationRegistry()`
(`libs/bellona/remote-protocol/src/bridge-deprecation.ts`) registers every
legacy command as a deprecation announced in protocol `0.1.0` and sunset at
`1.0.0` (Remote Host GA), pointing at its replacement command. This lets the
protocol's generic `assertCommandNotSunset` machinery reason about the legacy
aliases the same way it reasons about any deprecated command/field.

## Verification

```bash
cd libs/bellona/remote-protocol && npx vitest run src/bridge-deprecation.test.ts
```

The phase boundaries, the flag defaults per phase, and the monotonic-schedule
guard are verified by the `describe('bridgeDeprecationPhase — 180.C.38.04')`
block in `libs/bellona/remote-protocol/src/bridge-deprecation.test.ts`.
