[hartz0]

Realtime topics currently share a JSON-only FIFO connection to one endpoint. Add explicit subscription interests, bounded priority scheduling, negotiated codecs, and health-based endpoint failover in one documented frontend transport contract.

Closes #256
Closes #257
Closes #258
Closes #259

Changes

• Canonical, reference-counted interest descriptors with entity IDs, inclusive version/timestamp floors, optional projections, explicit broad opt-in, defensive matching, and 150ms hook debounce. Oracle interests follow cover selection; pool interests identify the network's protocol pool. REST stays authoritative; realtime flags default off.
• Explicit topic priorities; FIFO queues per class; 8:1 critical/bulk fairness; 2048-event caps per class; 4ms/64-event drain budgets; drop counters and worst critical latency logging; synchronous passthrough for one active topic.
• Ordered WebSocket subprotocol negotiation: default JSON and a dependency-free compact UTF-8 tuple codec. Shared envelope validation and readable downstream payloads; empty/unknown selection falls back to JSON.
• Network-scoped ordered endpoints, health scoring using failures/success age/first-message latency, 10-second silent-connection timeout, exponential reconnect, replay, and automatic preferred retries after 60 seconds on fallback, with one socket slot.
• Wire formats, configuration, observability, overflow semantics, backend boundary, and evidence documented in docs/realtime-transport.md.

Tests and evidence

• 21 new tests pass: npx vitest run --config vitest.config.mts src/lib/realtime/realtime.test.ts src/hooks/useRealtimeTopic.test.ts --reporter=verbose --silent=false.
• Four existing pool fallback tests pass: npx vitest run --config vitest.config.mts --environment jsdom src/hooks/dataSourceFallback.test.ts -t usePoolStats.
• Synthetic 2000-event bulk backlog: critical events overtake bulk, preserve order, and show 0.233ms worst critical queue latency in the final local run (50ms assertion budget). Fairness and both queue caps are tested.
• Negotiation tests cover JSON, compact, empty, and unsupported selections. Representative oracle envelope: 97 JSON bytes / 46 tuple bytes, 53% smaller.
• Filtering mock: stale A, unrelated B, current A => only current A reaches matching listeners, one of three events. Equivalent interests share a wire subscription; rapid selection changes produce one replacement.
• Mock transport tests cover refusal, fallback, successful preferred return, repeated preferred refusal, replay, silent endpoints, malformed frames, subscriber isolation, and cleanup.
• Scoped TypeScript passes. Scoped ESLint passes with the existing malformed no-restricted-syntax selector disabled. Diff, files, author, and single-commit ancestry verified before push.

Existing upstream blockers

Independently reproduced on pristine upstream main 826026687eced83ce2d59552bf5b17e775981e81:

• Full suite: 62 failing tests across 10 files. This branch reproduces the same 62 failures; all new tests pass. The default vitest.config.ts is empty; use the populated .mts config.
• Whole-project typecheck fails on existing cover-page JSX parse errors, starting at upstream line 320.
• ESLint fails parsing the existing selector Literal[value=1e7].
• Clean npm ci fails on the existing dependency/lockfile state. Local install used --legacy-peer-deps --package-lock=false; @testing-library/dom was installed locally without saving. Dependency and lockfiles are unchanged.
• The existing lint-staged pre-commit hook was bypassed after running scoped checks separately because of these baseline blockers.

Unrelated failures remain outside this PR. Repository CI and reviewer approval remain pending, and neither is claimed. Backend filtering and codec implementation are out of scope. Preferred retries briefly reconnect fallback, and browser throttling or slow synchronous subscribers prevent an absolute wall-clock latency SLA.

One commit directly atop freshly fetched upstream main, authored and committed by hartz0 wendyshima1@gmail.com, without co-authors. No force push.

[drips-wave]

@hartz0 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits