Context
Slice 3 of #16741 (S7, epic #16168), truth-folded at PR #17116's cycle-2 review to the v1 actually delivered: the consumer of the slice-2 SSE stream is the relay (ai/services/fleet/, Node fetch-streaming), because the transitional cockpit holds only the process bearer and cannot present fleet-surface admission itself. The browser-direct consumer and every browser/app-gate AC live in #17130 (the C2-cutover client this body previously bundled). Slice-1's shipped poll-digest (PR #16796) is the catch-up truth primitive — push for latency, poll for truth.
Contract facts frozen by slice 2 + hardened by this slice's review cycles
- Fetch-streaming, not bare
EventSource: credentials ride headers (fetch + ReadableStream parse of text/event-stream).
- The relay presents ONE credential: its fleet-client plane-admission bearer (class 1, its own mint —
fleet.planeAdmissionBearer / planeAdmissionBearerFile), never the plane-MCP credential, and no second header is synthesized. The composed server's boot arming covers the shared viewer identity; the per-viewer class-3 arming path belongs to the browser client (#17130).
- The
state handshake carries {armed, reason, lastPushAt, connectedIdentities, armedForViewer, subscriptionId?} — subscriptionId is ADDITIVE (this slice's change to the frozen surface): present when the lane is armed for the viewer, vouched by the server's own arming context (the fan-out route key), and it is the cold catch-up authority.
- Wake frames:
event: wake, data: {subscriptionId, envelope} (signed digest envelope, schemaVersion '1.0').
- Catch-up fires once per connection the moment the subscription id is known — cold start included, no live wake required — via
poll-digest {subscriptionId, sinceLogId} with the client-held watermark (never server-persisted).
- Caps are real: 30 connect attempts/min/viewer, 8 streams/viewer, 64 total; the
retry: hint is the reconnect floor under capped exponential backoff.
The Fix (as delivered by PR #17116)
- Relay fetch-streaming consumer (
fleetWakeSseConsumer.mjs): frame grammar parser, per-viewer state + wake observation, handshake-vouched cold catch-up, reconnect with the held watermark, staleness horizon (90s silence ⇒ unconfirmed).
- Class-1 credential chain:
resolveFleetPlaneAdmissionBearer (direct wins → secret file → empty) + class teeth refusing bytes that alias the plane-MCP bearer or the bootstrap admission token; EMPTY declares honest-unarmed with the leaf names in the reason; ALIASED refuses the boot loudly.
- Delivery-liveness axis goes live (
devFleetServer.mjs): resolveDeliveryLiveness renders the stream observation through the EXISTING fleetWakeRoutesSource → sourceHealth pipeline — zero apps/** changes; terminal-delivery failures stay honestly unknown (the stream does not vouch receipts).
- Honest-absence throughout: not-running / refused (HTTP reason) / disconnected / silent-past-horizon / no-credential-declared / no-vouched-id all render as reasoned
unknown — never a fabricated verdict.
Contract Ledger (T3)
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback / Edge Case |
Docs |
Evidence |
fleet.planeAdmissionBearer / planeAdmissionBearerFile (new leaves) |
Credential-class ledger (class 1: fleet-client plane admission; custody CLIENT-side per the custodian shapes — no plane-side secret exists, compose deliberately untouched; the mint comes from the deployment's external secret custodian) |
Direct value wins; file is the secret-custody indirection; resolved at the use site by the Fleet entry |
EMPTY ⇒ consumer not constructed, axis renders no fleet-surface credential declared (…); ALIASED to the plane-MCP bearer or bootstrap token ⇒ loud boot refusal |
configBase JSDoc + PR body |
fleetWakeArming.spec.mjs (precedence, both alias refusals, absence-not-substitution) + FleetServerComposition.spec.mjs (production resolver chain → real admission: admitted mint connects, plane-MCP mint 401) |
SSE state frame subscriptionId (additive wire field) |
The composed server's arming context (fleetWakeFanout.describeStateFor — the routes map is keyed by it) |
Present iff armed for the viewer; the client's cold catch-up authority |
Absent (not armed, or a pre-vouch server) ⇒ catch-up honestly unfired — no guessed target, no fabricated count |
fanout + consumer JSDoc |
fleetWakeFanout.spec.mjs (armed viewer's id carried; unarmed viewer gets none) + consumer no-vouch falsifier |
Connection catch-up (poll-digest per connection) |
Slice-1 contract (PR #16796): client-held watermark, cursor-stateless plane |
Fires once per connection when the id is known; cold sinceLogId: 0 drains pending with zero live wakes; reconnect carries the held watermark |
pollDigest seam absent ⇒ skipped, observation says so; a failed poll leaves pendingAtCatchUp null (never a count) |
consumer JSDoc |
consumer arc + cold-window + composition end-to-end specs |
resolveDeliveryLiveness projection |
fleetWakeRoutesSource delivery-axis contract |
{alive: true, reason} with the arming answer + caught-up note while connected and fresh; unknown with the disconnect reason or staleness otherwise |
Stream down ⇒ unknown + "poll remains the truth lane"; >90s silence ⇒ unconfirmed |
devFleetServer branch comment |
consumer liveness specs + the L3 live witness (Residual-Owner #16741) |
| Terminal-failure axis |
Delivery authority is container-side |
UNCHANGED: honestly unknown — this slice deliberately does not vouch receipts |
n/a |
PR body Deltas |
axis stub assertion in the composition wiring |
Acceptance Criteria (delivered scope)
Out of Scope
Server push composition (slice 2, #17100 merged) · MC-side telemetry (slice 4, #17102 / PR #17119) · the browser-direct consumer (#17130) · wake daemon changes.
Related
Parent #16741 · slice 1 #16800 (merged, PR #16796) · slice 2 #17100 (merged, PR #17103) · slice 4 #17102 (PR #17119, in review) · #17130 (the transferred browser half) · epic #16168.
Live latest-open sweep: latest 20 open checked at 2026-08-14T08:1xZ (creation) + truth-fold 2026-08-14T17:07Z.
Origin Session ID: c4996813-01b9-4234-8bdd-ed3bf22c0970
Retrieval Hint: query_raw_memories("relay wake stream consumer plane-admission bearer vouched cold catch-up delivery liveness")
Context
Slice 3 of #16741 (S7, epic #16168), truth-folded at PR #17116's cycle-2 review to the v1 actually delivered: the consumer of the slice-2 SSE stream is the relay (
ai/services/fleet/, Node fetch-streaming), because the transitional cockpit holds only the process bearer and cannot present fleet-surface admission itself. The browser-direct consumer and every browser/app-gate AC live in #17130 (the C2-cutover client this body previously bundled). Slice-1's shippedpoll-digest(PR #16796) is the catch-up truth primitive — push for latency, poll for truth.Contract facts frozen by slice 2 + hardened by this slice's review cycles
EventSource: credentials ride headers (fetch+ReadableStreamparse oftext/event-stream).fleet.planeAdmissionBearer/planeAdmissionBearerFile), never the plane-MCP credential, and no second header is synthesized. The composed server's boot arming covers the shared viewer identity; the per-viewer class-3 arming path belongs to the browser client (#17130).statehandshake carries{armed, reason, lastPushAt, connectedIdentities, armedForViewer, subscriptionId?}—subscriptionIdis ADDITIVE (this slice's change to the frozen surface): present when the lane is armed for the viewer, vouched by the server's own arming context (the fan-out route key), and it is the cold catch-up authority.event: wake,data: {subscriptionId, envelope}(signed digest envelope,schemaVersion '1.0').poll-digest {subscriptionId, sinceLogId}with the client-held watermark (never server-persisted).retry:hint is the reconnect floor under capped exponential backoff.The Fix (as delivered by PR #17116)
fleetWakeSseConsumer.mjs): frame grammar parser, per-viewerstate+wakeobservation, handshake-vouched cold catch-up, reconnect with the held watermark, staleness horizon (90s silence ⇒ unconfirmed).resolveFleetPlaneAdmissionBearer(direct wins → secret file → empty) + class teeth refusing bytes that alias the plane-MCP bearer or the bootstrap admission token; EMPTY declares honest-unarmed with the leaf names in the reason; ALIASED refuses the boot loudly.devFleetServer.mjs):resolveDeliveryLivenessrenders the stream observation through the EXISTINGfleetWakeRoutesSource→sourceHealthpipeline — zeroapps/**changes; terminal-delivery failures stay honestlyunknown(the stream does not vouch receipts).unknown— never a fabricated verdict.Contract Ledger (T3)
fleet.planeAdmissionBearer/planeAdmissionBearerFile(new leaves)no fleet-surface credential declared (…); ALIASED to the plane-MCP bearer or bootstrap token ⇒ loud boot refusalfleetWakeArming.spec.mjs(precedence, both alias refusals, absence-not-substitution) +FleetServerComposition.spec.mjs(production resolver chain → real admission: admitted mint connects, plane-MCP mint 401)stateframesubscriptionId(additive wire field)fleetWakeFanout.describeStateFor— the routes map is keyed by it)fleetWakeFanout.spec.mjs(armed viewer's id carried; unarmed viewer gets none) + consumer no-vouch falsifierpoll-digestper connection)sinceLogId: 0drains pending with zero live wakes; reconnect carries the held watermarkpollDigestseam absent ⇒ skipped, observation says so; a failed poll leavespendingAtCatchUpnull (never a count)resolveDeliveryLivenessprojectionfleetWakeRoutesSourcedelivery-axis contract{alive: true, reason}with the arming answer + caught-up note while connected and fresh;unknownwith the disconnect reason or staleness otherwiseunknown+ "poll remains the truth lane"; >90s silence ⇒ unconfirmedunknown— this slice deliberately does not vouch receiptsAcceptance Criteria (delivered scope)
Out of Scope
Server push composition (slice 2, #17100 merged) · MC-side telemetry (slice 4, #17102 / PR #17119) · the browser-direct consumer (#17130) · wake daemon changes.
Related
Parent #16741 · slice 1 #16800 (merged, PR #16796) · slice 2 #17100 (merged, PR #17103) · slice 4 #17102 (PR #17119, in review) · #17130 (the transferred browser half) · epic #16168.
Live latest-open sweep: latest 20 open checked at 2026-08-14T08:1xZ (creation) + truth-fold 2026-08-14T17:07Z.
Origin Session ID: c4996813-01b9-4234-8bdd-ed3bf22c0970
Retrieval Hint:
query_raw_memories("relay wake stream consumer plane-admission bearer vouched cold catch-up delivery liveness")