@ultimat3/realtime 11.1.0 → 11.2.0

package/CLAUDE.md

@@ -397,6 +397,34 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   liveHookFor(liveFeed)` runs at import; `registerQueries()` stamps the name later, at boot.
 - Type claims about the hook go in `type-pins.ts`, never in a `.test.ts` — `tsconfig.json` excludes
   test files, so `tsc -b` never reads one and an assertion written there can never fail.
+- **`backoffDelay` is `@ultimat3/core`'s, and `attempt + 1` is the whole of the seam** (`As of
+  2026-08-23`). A client counts its first reconnect as attempt **0** and core counts the first wait
+  as attempt **1**, so dropping the shift doubles every reconnect delay in the framework —
+  silently, and only under the load this file exists to survive.
+  `thundering-herd-core-parity.test.ts` pins it with the numbers (`[500, 1_000, 2_000, 4_000]`) and
+  with 17,280 comparisons across every jitter mode, base, cap, factor, attempt and roll.
+  `JitterMode` is core's type re-exported and `Rng` is core's `Random` — never a second spelling of
+  either. `drainPlan()` and `AcceptBudget` are NOT backoff and keep their own arithmetic: a slot in
+  a spread and a token bucket's refusal delay are different questions. `bun run flight-copies` is the
+  guard: a second curve-and-jitter function anywhere in `packages/*/src` is a build error, matched
+  on the literal shape rather than the name.
+- **The SHARED window read carries a deadline, and it frees the SLOT — it cannot cancel the read**
+  (`As of 2026-08-23`). One `definition.snapshot` that never settled pinned `entry.reading` for the
+  life of the process, and every later cold subscriber joined a promise nothing would ever resolve:
+  one wedged read took every future subscriber of that query id with it. `startRead` now races the
+  read against `entry.schedule(…, entry.readDeadlineMs)`, default `DEFAULT_READ_DEADLINE_MS` (30s),
+  injectable per entry and through `new LiveQueryRegistry({ readDeadlineMs, schedule })`. Three
+  rules, each with its own test in `query-window.test.ts` and each proven by mutation:
+  - **A race, not just an eviction.** Freeing the slot alone leaves every caller ALREADY joined
+    awaiting a promise nothing settles; they are told instead, with `X_TIMEOUT`.
+  - **`X_TIMEOUT`, not a silent empty window.** A superseded read is discarded silently because a
+    strictly better window already exists to serve from; a timed-out read has none, and serving
+    `rows: []` as the whole result set is the exact fault `live-query.ts`'s `#read` refuses. The
+    rejecting-read path (`readSnapshot`'s catch) is the shape this matches, not the superseded one.
+  - **`stale` is put back**, for `readSnapshot`'s reason: a read that did not answer must not leave
+    the window looking authoritative.
+  There is **no "off" spelling** — a shared read with no deadline is the defect itself — and a `0`,
+  negative, `NaN` or `Infinity` value falls back to the default rather than to "now".
 - The client owns its own reconnect: a closed socket arms **one** timer through the injected
   `Scheduler`, and that timer calls `connect()`. `reconnectAt` is the render half and never the
   mechanism — publishing it without arming anything is exactly the bug that shipped. Rules that
@@ -764,7 +792,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 | `nats-lib-client.ts` | the `nats` adapter — **the only file in the repo that imports `nats`** |
 | `nats-jetstream.ts` / `nats-kv.ts` / `nats-transport.ts` | the JetStream KV bucket, presence over it, and the production `Transport` — all three written against the port |
 | `nats-fake.ts` | an in-memory bus implementing the port — server semantics, not wire bytes; the only way to prove multi-node fanout under a sealed network |
-| `cursor.ts` / `change-buffer.ts` / `thundering-herd.ts` | reconnect — the highest-risk area |
+| `cursor.ts` / `change-buffer.ts` / `thundering-herd.ts` | reconnect — the highest-risk area. `thundering-herd.ts`'s backoff is core's, shifted 0-based to 1-based; the drain plan and the accept budget are its own |
 | `identity-map.ts` | the client's single source of truth: one row value per `(scope, id)`, its holds and its batched change notification |
 | `live-rows.ts` | one subscription's window over that map — its scope, its order, its retain/release, and `Registration` itself |
 | `local-store.ts` / `offline-queue.ts` / `rebase.ts` | tier 3 |

package/README.md

@@ -196,6 +196,7 @@ wire.
 | live subscriptions per socket | 128 | `new LiveQueryRegistry({ maxPerSocket })` | `X_SUBSCRIPTION_LIMIT` |
 | live subscriptions per tenant | unset | `new LiveQueryRegistry({ maxPerTenant, tenantOf })` — **both**, or it arms nothing | `X_SUBSCRIPTION_LIMIT` |
 | distinct `(query, input)` pairs per node | 10,000 | `new LiveQueryRegistry({ maxEntries })` | `X_SUBSCRIPTION_LIMIT` |
+| how long one entry's SHARED snapshot read may hold its slot | 30s | `new LiveQueryRegistry({ readDeadlineMs })` | `X_TIMEOUT`, to that read's caller AND every subscriber joined to it |
 | channel topics per socket | 64 | `new ChannelHub({ maxTopicsPerSocket })` | `X_SUBSCRIPTION_LIMIT` |
 | distinct channel topics per node | 10,000 | `new ChannelHub({ maxTopicsPerNode })` | `X_SUBSCRIPTION_LIMIT` |
 | outbound bytes buffered on one socket | 1 MiB | `createSyncNode({ maxBufferedBytes })` | the frame is dropped and `send` answers `false` |
@@ -543,7 +544,11 @@ wire twice by a reconnect that raced an ack.
 `X_REPLICATION_FAILED` · `X_REPLICATION_PROTOCOL` · `X_REPLICATOR_SLOT_HELD` ·
 `X_LIVE_CLIENT_MISSING` · `X_LIVE_SERVER_RENDER` · `X_LIVE_QUERY_UNKNOWN` ·
 `X_LIVE_REPLICA_IDENTITY` ·
-`X_SOCKET_UNAUTHENTICATED` · `X_SOCKET_AUTH_UNAVAILABLE` · `X_NOT_IMPLEMENTED`
+`X_SOCKET_UNAUTHENTICATED` · `X_SOCKET_AUTH_UNAVAILABLE` · `X_NOT_IMPLEMENTED` ·
+`X_TIMEOUT`
+
+`X_NOT_IMPLEMENTED` and `X_TIMEOUT` are **borrowed** from `@ultimat3/core`, which owns and titles
+them — `REALTIME_BORROWED_ERROR_CODES`. Everything else on that list is realtime's own.
 
 Topics deny by default: a topic with no matching guard is forbidden. An authz hole is not a config
 option someone forgot to set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "11.1.0",
+  "version": "11.2.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -36,8 +36,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.1.0",
-    "@ultimat3/query": "11.1.0",
+    "@ultimat3/core": "11.2.0",
+    "@ultimat3/query": "11.2.0",
     "nats": "2.29.3"
   }
 }

package/src/errors.ts

@@ -32,8 +32,13 @@ export const REALTIME_OWNED_ERROR_CODES = [
  * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s, and `X_FORBIDDEN` — thrown by the surface denials this
  * package renders — is `@ultimat3/policy`'s. Neither is titled here: the owner writes the one title
  * every surface renders, and a copy kept alongside it is a copy that goes stale unnoticed.
+ *
+ * `X_TIMEOUT` is core's too — titled in `CORE_CODE_TITLES` and classified `retryable` there, which
+ * is what a blown deadline owes a caller. Borrowed rather than owned for the same reason
+ * `@ultimat3/http` borrows it (`HTTP_BORROWED_ERROR_CODES`): the concept is core's, and a title
+ * registered here would throw `X_ERROR_CODE_DUPLICATE` at import.
  */
-export const REALTIME_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
+export const REALTIME_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED', 'X_TIMEOUT'] as const;
 
 /**
  * The two codes an authz **decision** carries. Everything else a gate throws — a rule that reached
@@ -407,6 +412,24 @@ export class SocketAuthUnavailableError extends RealtimeError {
   }
 }
 
+/**
+ * The shared window read for one live query id blew its deadline.
+ *
+ * Freeing the slot alone would leave every caller ALREADY joined to that read waiting on a promise
+ * nothing will ever settle, so they are TOLD instead — the same answer this file's other
+ * non-answering read gives, and the reason `fillWindow` needed no new branch to carry it. The read
+ * itself is not cancellable from here and this does not pretend to have stopped it.
+ */
+export class WindowReadTimeoutError extends RealtimeError {
+  constructor(args: { qid: string; afterMs: number }) {
+    super({
+      code: 'X_TIMEOUT',
+      cause: `the shared snapshot read for live query "${args.qid}" did not answer within ${args.afterMs}ms, so the window slot it held was released`,
+      fix: 'x doctor --json   # then raise readDeadlineMs on the live query registry, or fix the snapshot read that stopped answering',
+    });
+  }
+}
+
 /** Deep infrastructure that is interface-complete but not wired. Carries the exact next step. */
 export class NotImplementedError extends RealtimeError {
   constructor(args: { what: string; fix: string }) {

package/src/index.ts

@@ -60,6 +60,7 @@ export {
   TopicForbiddenError,
   TransportProtocolError,
   TransportUnavailableError,
+  WindowReadTimeoutError,
 } from './errors';
 // ---- the client hooks --------------------------------------------------------------------------
 export {

package/src/live-query.ts

@@ -26,6 +26,7 @@ import type { SyncSocket } from './socket';
 import { type Subscriber, SubscriberGate, type SubscriberGateOptions } from './subscriber-gate';
 import { SubscriptionBook, subscriptionKey } from './subscription-book';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
+import type { Scheduler } from './thundering-herd';
 
 export interface LiveQueryRegistryOptions extends SubscriberGateOptions {
   readonly source: ResumeSource;
@@ -40,6 +41,15 @@ export interface LiveQueryRegistryOptions extends SubscriberGateOptions {
    * a `WindowLock` and a fanout target each — until the process dies.
    */
   readonly maxEntries?: number;
+  /**
+   * How long one entry's SHARED snapshot read may hold its slot. Defaults to
+   * `DEFAULT_READ_DEADLINE_MS`. Without it a `definition.snapshot` that never settles pinned the
+   * slot for the life of the process and every later cold subscriber joined a promise nothing
+   * would resolve — one wedged read taking every future subscriber of that query id with it.
+   */
+  readonly readDeadlineMs?: number;
+  /** Injected so that deadline is provable without waiting for one. Production uses `setTimeout`. */
+  readonly schedule?: Scheduler;
 }
 
 /**
@@ -384,7 +394,10 @@ export class LiveQueryRegistry {
         knob: 'maxEntries',
       });
     }
-    const created = createEntry(qid, definition, input, definition.matcher(input));
+    const created = createEntry(qid, definition, input, definition.matcher(input), {
+      readDeadlineMs: this.#options.readDeadlineMs,
+      schedule: this.#options.schedule,
+    });
     this.#entries.set(qid, created);
     return created;
   }

package/src/query-window.ts

@@ -2,11 +2,30 @@
 // read once for N subscribers, and how one that is known to be wrong is replaced. The authz
 // decision is never here — `live-query.ts` owns that, once per subscriber, over what this returns.
 
+import { WindowReadTimeoutError } from './errors';
 import type { JsonValue, Row } from './json';
 import type { LiveQueryDefinition, LiveSubscription, SnapshotResult } from './live-contract';
 import type { IncrementalMatcher, SubscriptionShape } from './matcher-bridge';
+import type { Scheduler } from './thundering-herd';
+import { timeoutScheduler } from './thundering-herd';
 import { WindowLock } from './window-lock';
 
+/**
+ * How long the SHARED read may hold the slot before it is released. On by default and with no
+ * "off" spelling: a shared read with no deadline is exactly the defect this closes — one
+ * `definition.snapshot` that never settles pinned `entry.reading` for the life of the process and
+ * every later cold subscriber joined a promise nothing would resolve. A caller that wants a longer
+ * one names a bigger number.
+ */
+export const DEFAULT_READ_DEADLINE_MS = 30_000;
+
+export interface EntryOptions {
+  /** Non-finite or non-positive falls back to the default — `0` cannot mean both "now" and "never". */
+  readonly readDeadlineMs?: number | undefined;
+  /** Injected so a deadline is provable without waiting for one. */
+  readonly schedule?: Scheduler | undefined;
+}
+
 export interface QueryEntry {
   readonly qid: string;
   readonly definition: LiveQueryDefinition;
@@ -40,6 +59,8 @@ export interface QueryEntry {
   generation: number;
   /** The generation of the newest read whose rows are in `rows`. `0` before the first one lands. */
   applied: number;
+  readonly readDeadlineMs: number;
+  readonly schedule: Scheduler;
 }
 
 /**
@@ -57,6 +78,7 @@ export function createEntry(
   definition: LiveQueryDefinition,
   input: JsonValue,
   matcher: IncrementalMatcher,
+  options?: EntryOptions,
 ): QueryEntry {
   return {
     qid,
@@ -83,6 +105,8 @@ export function createEntry(
     reading: null,
     generation: 0,
     applied: 0,
+    readDeadlineMs: usableDeadline(options?.readDeadlineMs),
+    schedule: options?.schedule ?? timeoutScheduler,
   };
 }
 
@@ -145,15 +169,54 @@ function applyRead(entry: QueryEntry, pending: PendingRead, result: SnapshotResu
   if (result.lsn > entry.lsn) entry.lsn = result.lsn;
 }
 
-/** Publishes the in-flight read, and clears it as it settles — the share is per read, not a cache. */
+function usableDeadline(declared: number | undefined): number {
+  if (declared === undefined) return DEFAULT_READ_DEADLINE_MS;
+  return Number.isFinite(declared) && declared > 0 ? declared : DEFAULT_READ_DEADLINE_MS;
+}
+
+/**
+ * Publishes the in-flight read, and clears it as it settles — the share is per read, not a cache.
+ *
+ * The deadline frees the SLOT. It cannot cancel the read — nothing here can, and pretending
+ * otherwise would be a second, false promise — so the abandoned read runs to completion with
+ * nobody listening, and the next caller issues its own instead of joining a corpse.
+ */
 function startRead(entry: QueryEntry): PendingRead {
   // Cleared here rather than when the read lands: the read about to be issued is the one that
   // answers the staleness, so a second caller must join it instead of forcing another.
   entry.stale = false;
   entry.generation += 1;
-  const reading: PendingRead = { generation: entry.generation, result: readSnapshot(entry) };
+
+  const read = readSnapshot(entry);
+  let expire: () => void = noop;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    // Assigned synchronously — a Promise executor runs before the constructor returns — so `done`
+    // can never fire against the placeholder and leave a timer armed.
+    expire = entry.schedule(() => {
+      // The same restoration `readSnapshot`'s catch makes, and for the same reason: a read that
+      // did not answer must not leave the window looking authoritative. Unconditional even when a
+      // NEWER read already holds the slot, which can only cost one extra read — over-reading is
+      // safe here and under-reading is the divergence `stale` exists to prevent.
+      entry.stale = true;
+      reject(new WindowReadTimeoutError({ qid: entry.qid, afterMs: entry.readDeadlineMs }));
+    }, entry.readDeadlineMs);
+  });
+
+  const reading: PendingRead = {
+    generation: entry.generation,
+    // A race, not just an eviction: freeing the slot alone would leave every caller ALREADY joined
+    // awaiting a promise nothing settles. `Promise.race` subscribes to both, so a read that
+    // rejects AFTER losing the race is still handled and never surfaces as an unhandled rejection.
+    result: Promise.race([read, deadline]),
+  };
   entry.reading = reading;
+
   const done = (): void => {
+    // An armed timer per completed read keeps the process alive and is a leak in its own right.
+    expire();
+    // Identity, never presence — the rule the deadline makes load-bearing rather than merely
+    // careful: a read that answers after its deadline released the slot must not clear whatever
+    // holds it now, or that newer read's joiners share a promise the entry no longer answers for.
     if (entry.reading === reading) entry.reading = null;
   };
   void reading.result.then(done, done);
@@ -185,3 +248,5 @@ export function orgIdOf(input: JsonValue): string | null {
   const value = input['orgId'];
   return typeof value === 'string' ? value : null;
 }
+
+const noop = (): void => undefined;

package/src/server.ts

@@ -144,6 +144,8 @@ export {
 } from './presence';
 export {
   createEntry,
+  DEFAULT_READ_DEADLINE_MS,
+  type EntryOptions,
   fillWindow,
   orgIdOf,
   type PendingRead,

package/src/thundering-herd.ts

@@ -6,13 +6,20 @@
 //   2. backoffDelay() — the client's own jittered retry, for failures nobody scheduled
 //   3. AcceptBudget   — the receiving node's token bucket, so recovery sheds instead of collapsing
 
-import { type Clock, systemClock } from '@ultimat3/core';
+import {
+  type Clock,
+  backoffDelay as coreBackoffDelay,
+  type JitterMode,
+  type Random,
+  systemClock,
+} from '@ultimat3/core';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
 
 /** Injected so tests are deterministic and `local` mutators stay replayable. */
-export type Rng = () => number;
+export type Rng = Random;
 
-export type JitterMode = 'full' | 'equal' | 'none';
+/** Core's, re-exported under this package's name — never a second copy of the same three modes. */
+export type { JitterMode };
 
 export interface BackoffPolicy {
   readonly baseMs: number;
@@ -32,21 +39,28 @@ export const defaultBackoff: BackoffPolicy = {
   jitter: 'full',
 };
 
-/** Attempt is 0-based. Result is always in `[0, maxMs]`. */
+/**
+ * Attempt is 0-BASED. Result is always in `[0, maxMs]`.
+ *
+ * The arithmetic is core's, and `attempt + 1` is the WHOLE of the seam: a client counts its first
+ * reconnect as attempt 0 and core counts the first wait as attempt 1, so dropping the shift would
+ * double every reconnect delay in the framework — silently, and only under the load this file
+ * exists to survive. `thundering-herd-core-parity.test.ts` pins the numbers.
+ */
 export function backoffDelay(
   attempt: number,
   policy: BackoffPolicy = defaultBackoff,
   rng: Rng = Math.random,
 ): number {
-  const ceiling = Math.min(policy.maxMs, policy.baseMs * policy.factor ** Math.max(0, attempt));
-  switch (policy.jitter) {
-    case 'none':
-      return Math.round(ceiling);
-    case 'equal':
-      return Math.round(ceiling / 2 + (rng() * ceiling) / 2);
-    case 'full':
-      return Math.round(rng() * ceiling);
-  }
+  return coreBackoffDelay({
+    attempt: attempt + 1,
+    base: policy.baseMs,
+    max: policy.maxMs,
+    factor: policy.factor,
+    curve: 'exponential',
+    jitter: policy.jitter,
+    random: rng,
+  });
 }
 
 /**