Eve library

Bridge Deprecation Timeline (180.C.38.04)

Guide

Revision 1

On this page

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)#

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. 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.