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
(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)#
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:
- → 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. - → 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.
- → hard-cutover (2026-10-21).
180.C.29.10final GA acceptance is complete onorigin/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). - → 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 do180.C.38.07/.09delete the old packages and this timeline'sremovedphase 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. 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#
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.