Repository navigation
P1a: engine-side sequencing — port main's epoch:seq stamping, shared replay buffer, and the reset contract onto the lane (#1803) #1806
Description
Important
Problem — The lane's event sequencing lives in the frontdoor's ring, which only sees what the frontdoor saw and dies with frontdoor restarts; engine restarts are invisible to it. Main's #1770 (which landed after our Oct-13 merge, so the lane does not carry it) put the sequence at the SOURCE: the global bus stamps every frame <epoch>:<seq>, a shared bounded replay buffer honors cursors, and unservable cursors get an explicit reset frame — engine restarts become a natural resync boundary and source-side sequencing survives every middle-hop death. This is P1a of #1803's port list, the largest and most load-bearing port: taking it obsoletes the frontdoor ring (P1b flips the frontdoor to a dumb pipe).
Approach — A PORTED COMMIT, not a merge: study main's implementation (the bus modules + their route wiring, six commits listed in Prior Art), and apply its architecture onto THIS lane's engine overlay — which has diverged (our event route carries the bounded fan-out, the SSE-TICK telemetry, and the lastEventID cursor replay from the stall campaign). The port composes with our liveness machinery, it does not replace it. Per #1803's doctrine: one port, behind the probe suite, green before the next.
Scope — in: the engine overlay's global-bus <epoch>:<seq> stamping, the shared replay buffer (byte+age bounded, env-configurable), the cursor-resume path, the explicit reset frame, the reset contract's tests, composition with the existing fan-out/telemetry. · out: the frontdoor (P1b — the ring stays this slice; it simply starts seeing engine-stamped ids on the engine hop), main's patch-body/sync-copy commits (#1778's 06eac85 belongs to P3), any client-side changes beyond wire compatibility.
Acceptance Criteria
- The engine's global event stream stamps every frame with an
<epoch>:<seq>id (a per-process random epoch, a strictly monotonic seq — main's GlobalBus shape, including the pre-dispatch tap ordering and the mirror window for sync copies). - A shared replay buffer (one per bus, shared by every subscriber, bounded by bytes and age, env-tunable with main's defaults 32MB/5min) serves cursor resumption: a servable cursor gets the frames after it, then live.
- An unservable cursor (evicted past the bound, or a foreign epoch) gets an explicit reset frame — the client knows it must resync, never silently gaps.
- An engine restart changes the epoch and the reset contract holds across it (the natural resync boundary).
- The port composes with the lane's existing machinery: the bounded fan-out and SSE-TICK telemetry still hold (a corpse subscriber still drops; the tick lines still flow), and the lastEventID query/header cursor path works against the new ids.
- Every behavior above carries a test (stamping monotonicity, buffer eviction, cursor resume, reset-on-unservable, reset-across-epoch) — red → green, per port.
- The existing engine suites stay green: zero new failures vs the known baselines (test/session 599/5, test/server class); drift gate PASS.
Testing Decisions
Unit/integration in the overlay opencode package for the bus, buffer, and reset semantics; the wire-contract test asserts the id format on the wire (<epoch>:<seq> parseable, the preamble contract untouched). The lossless-resume E2E (kill the link mid-turn, reconnect, transcript equals fresh load) is P1b's acceptance against the sharded hub — P1a proves the semantics at the engine level.
Key Decisions
- PORT, NOT MERGE: no main-side files arrive wholesale; the architecture is applied to our tree, adapted to our event route's shape, and our liveness machinery is preserved.
- The
<epoch>:<seq>id is wire-compatible with the lane's existing lastEventID replay (any string id) — the client needs no change for P1a. - Sequencing goes in pre-dispatch (main's tap design) so nested emits stay strictly ordered.
Constraints & Invariants
- The frontdoor's ring is untouched this slice (P1b's scope).
- The fan-out bound, the FIN discipline, and the telemetry contracts (Engine SSE heartbeat tick stalls fleet-wide while HTTP stays healthy — the #775 cousin, last open cause of the stuck-thinking class #1798, The panel render gate: dead-widgets-zero wired into deploy-gate.sh — acceptance measured in what the panel renders #1804) hold through the port.
- No engine deploy — the live plane is HITL (Aaron's), and per the live-test doctrine the port rides the ritual when it lands.
Prior Art
- The port sources (main, Fleet event stream is lossy by construction — remote sessions lag and desync during live activity #1770/feat(engine): sequenced, replayable global event stream (epoch:seq ids, replay buffer, reset) #1776): commits d401ea0 (stamp frames
<epoch>:<seq>), a4cb720 (cursor resume via shared replay buffer), a13c802 (reset frame for unservable cursors), d2f51c9 (byte+age bounds, env-tunable), dea6cd4 (opt-in sync copies — port the mirror window, the opt-in subscription flag may ride with it) — files:packages/app-bundle/overlay/packages/opencode/src/bus/global.tsandbus/global-replay.tson origin/main, plus the route wiring in main'shandlers/global.ts; client referenceapp/src/context/stream-cursor.ts. - The lane's target:
handlers/event.ts(our instance route — bounded fan-out, SSE-TICK telemetry, lastEventID replay), the engine overlay's global bus emission as the base defines it. - Peer-fleet × hub-fleet: the layered merge — ports, not rebases (the convergence evidence and the ranked port list) #1803's doctrine and port order (sequencing before liveness before volume).
Source
Part of #1803 (P1a — the engine half of port P1). P1b (the frontdoor drops its ring, passes ids through) follows green on this slice.
Notes
Main's 06eac85 (summary diffs carry no patch bodies) is deliberately excluded — that is P3 (burst-volume cuts), not P1.
Activity
Merge P1a epoch:seq sequencing (#1806/PR #1807) into the lane for liv…