realtime: no WS/SSE transport — service-realtime is in-process only and clients long-poll; big-screen/command-center scenarios need real push

[os-zhuang]

Status

Maintainer decision (2026-08-13): scheduled for v18.

Current state (all honestly reported, per ADR-0076 D12)

• packages/runtime/src/http-dispatcher.ts:1441-1444 — capability discovery hard-codes websockets: { enabled: false }: "No WS/HTTP realtime surface is mounted anywhere — a mere in-process realtime service must not advertise websockets" (ADR-0076 D12, ADR-0076: remaining objectql/protocol layering work (cross-repo window) #2462).
• packages/services/service-realtime/ — in-memory, in-process pub/sub adapter only; no transport.
• packages/client/src/realtime-api.ts — long-polling placeholder; header comments: "For production WebSocket/SSE support, extend with transport adapters" / "WebSocket/SSE transport planned for future".
• The one live "near-realtime" mechanism is dashboard polling: dashboard.refreshInterval (seconds) is confirmed live in the objectui renderer (packages/spec/liveness/dashboard.json → DashboardRenderer.tsx setInterval(onRefresh)).

Why now

Solution scoping for an overseas port/terminal customer (2026-08): a command-center big screen showing gate traffic, yard inventory, and berth/operation status. 5–30s refreshInterval polling covers the baseline, but sub-5s "event hits the screen" (gate pass-through, weighbridge reading) needs push. The same transport would also serve in-app notifications (service-messaging inbox channel) and list-view live updates.

Suggested scope (for discussion)

1. SSE first — one-directional server→client fits the dashboard/notification cases, avoids WS proxy/auth complexity, and slots behind the existing service-realtime adapter seam.
2. Client transport adapter replacing the long-poll placeholder in realtime-api.ts (the reserved fields are already stubbed for it).
3. Flip capability discovery honestly per D12 only when the surface is actually mounted.
4. Multi-node fan-out: document that horizontal deployments need a shared bus (a service-cluster-redis seam already exists) — single-node in-process bridge is an acceptable first ship.

Related

• ADR-0076: remaining objectql/protocol layering work (cross-repo window) #2462 / ADR-0076 D12 (honest capabilities — the reason today's state is enabled: false rather than a broken promise)
• currency: no exchange-rate / home-currency conversion — dynamic multi-currency amounts cannot be reconciled or aggregated across currencies #8345, and the PDF re-plan issue from the same customer scoping batch (all v18)

[hotlong]

Triage: lands primarily in packages/services/service-realtime/** (the adapter seam the suggested SSE scope names), with packages/runtime/src/http-dispatcher.ts (capability discovery) and packages/client/src/realtime-api.ts as secondary touch points — domain:services.

Hold (2026-08-13): maintainer already scheduled this for v18 (per issue body) — a multi-milestone feature, not current-cycle work. pm:on-hold, not needs-user-decision (decision is already made; what's on hold is the build).

Restart trigger files — next PR touching any of these should pull this card back into scope for re-pricing:

• packages/runtime/src/http-dispatcher.ts (the websockets: { enabled: false } capability flag, ADR-0076 D12)
• packages/services/service-realtime/**
• packages/client/src/realtime-api.ts

---

Generated by Claude Code