Fleet Studio B2b · slice 3 — SSE fan-in on the observation /event (ADR 0033 D1-D4)

[jeonghun-jj-lee]

Important

Problem — The observation /event stream carries only the local arm; a peer-owned session's events never reach this window, so a remote session shows no live activity — you'd have to re-open it to see what happened. See #1540 and ADR 0033.
Approach — Implement ADR 0033 D1–D4 verbatim on the observation /event handler: a fan-in aggregator (local + one upstream per reachable session-owning peer), an id:-namespaced, frame-preserving relay, a composite per-namespace cursor, an always-present local arm, and per-namespace bounded buffering. Each upstream authenticates as itself. Gated on observation readiness, not the premium flag.
Scope — in: the fan-in aggregator + relay + composite cursor + per-namespace buffering on the observation /event. · out: the write plane (slice 2); UI (slice 4); the premium AMICO_FLEET_MULTIPLEX multiplex.
Assumptions — the owner map + reader tokens already feed the reachable session-owning peer set (observation readiness).

Warning

Deliberate-review corrections (2026-09-24) — these BIND over any stale text below.

• This is a NEW interception, not a re-gate. The only wired /event fan-in today is server.ts fleetMultiplexEnabled() && this.fleetPlane?.eventFanIn (premium flag + premium plane); the observation branch wires none ("NO SSE fan-in — flag-gated/premium"). Add a new, separately-armed /event interception on the observation path that reuses SseFanIn* as a library; leave the premium server.ts gate untouched. It is NOT behind AMICO_FLEET_MULTIPLEX and NOT behind the multiplexer.
• ADR contradiction resolved by ADR 0033 Amendment 1 — read it. The "no SSE crosses the multiplexer until behind the flag" invariant holds because this path is not behind the multiplexer at all.
• "Observation readiness" is the arming predicate: holds observe on ≥1 reachable session-owning peer (fed by the landed Fleet Studio: owner-routed open of a peer session + retire orphaned dropdown helpers (B2a, from #1525) #1537 owner-map + reader tokens). State it inline in the AC.
• Byte-identity guard lives in the DRIVER (it declines at zero non-local owners), not in "an always-present local arm" — and it holds only absent a focus-snapshot provider (the aggregator emits a focus frame ahead of the local arm when one is configured). The byte-identity test must target the route with no observation plane armed as the oracle.
  Full record: ADR 0034 D6 + ADR 0033 Amendment 1.

Acceptance Criteria

• Zero peers → the aggregate /event stream is frame-for-frame identical to today's local stream (fleet-of-one byte-identity) — the first test.
• A peer-owned session's events stream live into this window's single /event.
• A composite reconnect cursor resumes each namespace from its own last id; an id-less frame does not advance its namespace.
• An unreachable owner emits an honest comment frame, not a silent gap.
• A slow/flapping peer degrades in isolation (bounded buffer) and resumes from its cursor on recovery — no head-of-line-blocking of other namespaces (including local).

Testing Decisions

Reuse ADR 0033's stated test plan verbatim: D2 relay frame-preservation (feed a synthetic frame sequence with id:/multi-line data:/comments/retry:, assert every line preserved and only id: namespaced), D3 cursor round-trip + per-namespace resume params (spy the upstream opener), D4 fleet-of-one byte-identity, D1 membership churn + honest unreachable frame. New suite for the aggregator; reuse the session_multiplexer SSE helpers.

Key Decisions

• Fan-in at the origin, not per-session subscription (D1) — preserves the single-origin, one-cursor client with the smallest app change.
• id: namespaced by owner (<machineId>\u001f<peerId>; local = reserved local) (D2).
• Composite cursor parsed only at the origin (D3); the client keeps treating it as one opaque string.
• Local arm always present (D4).
• Per-namespace bounded buffers (ADR 0033 decision 3B); per-peer self-auth upstream (ADR 0033 decision 1A).

Data Contracts

The reconnect cursor is a composite local=<id>;<machineId>=<id>;…, opaque to the client, parsed at the origin into per-namespace resume params.

Constraints & Invariants

• Byte-identity for fleet-of-one / flag-off is the guard test.
• AMICO_FLEET_MULTIPLEX stays the premium-only gate; this fan-in has its own observation-readiness activation.

Prior Art

Read first: ADR 0033 (the full mechanics + accepted decision record), session_multiplexer (openSseStream and the SseStreamHandle), the app's single global /event consumer, and #1264 (the lossless-reconnect cursor being generalized).

Source

• Part of Fleet Studio B2b — remote peer-studio control + live streaming on the observation path #1540
• Design-of-record: ADR 0034 (docs/adr/0034-base-peer-studio-control.md), decision D6; consumes ADR 0033.

Notes

Independent of the grant/write plane — hangs off the existing owner-map + observation readiness, so it runs in parallel with the #S1→slice-2 spine. Mechanical and pinned by ADR 0033's test plan → AFK. Largest slice; may sub-split per-D (D2 relay / D3 cursor / D4 local-arm / D1 membership) if it grows.