@ultimat3/realtime 15.0.0 → 17.0.0

package/CLAUDE.md

@@ -63,6 +63,63 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   for a hand-written definition and `live-definition.test.ts` proves it for a real declared
   `query({ live: true })` — the second one matters, because a rule that only holds for test fakes
   is a rule no declaration can reach.
+- **Every numeric option is refused when it is not a FINITE number, `As of 2026-08-26`.**
+  `@ultimat3/core`'s `finite-option.ts` holds the one refusal, `finiteOption()`. `??` guards
+  nullish and `NaN` is not, so `Number(process.env.X)` on an unset variable reaches the bound
+  intact, and `Math.max`/`Math.min`/`Math.floor` propagate rather than validate — `AcceptBudget`
+  was `Math.max(1, options.perSecond)` and admitted every accept, because `NaN < 1` is false.
+- **"Pinned at zero" is a claim about the RATCHET, not about this package, and the two came apart
+  once (`As of 2026-08-26`).** `bun run finite-bounds` is a count of options defaulted with `??`
+  and never screened; `realtime` is absent from `scripts/lib/finite-bounds-pins.ts`, which is that
+  count reading zero. It read zero while **two** options were unscreened, because the rule's own
+  header names the shape it cannot see: an option with **no `??` default**. Both had one spelling
+  — a value the caller either supplies or does not, forwarded or compared as-is.
+  `SubscriptionBook`'s `maxPerTenant` (`count >= NaN` is false, so the only cap spanning the
+  sockets of one tenant was OFF; measured, 5,000 subscribes admitted under `maxPerTenant: NaN`,
+  and it sat two lines under the screened `maxPerSocket`), and `openNatsClient`'s
+  `maxReconnectAttempts`, handed to the library unscreened — measured, the dial then never
+  returns. It also cannot see WHERE a screen runs, which is the bullet below. So: a package's
+  numeric options are audited by reading its option interfaces, and the ratchet is the floor under
+  that, never the proof of it. `SyncGrant.expiresAt` is deliberately NOT on that list and is the
+  one number left with the same shape: it is DATA an app's `authenticate` returns, not a
+  configuration option, and `expiresAt: NaN` makes `GrantBook.expired()` skip that grant forever —
+  the same outcome as omitting it, which is already a supported spelling.
+- **A ceiling is refused where the object is BUILT, never inside a callback the runtime invokes
+  per connection (`As of 2026-08-26`).** `maxBufferedBytes`, `maxDroppedFrames`,
+  `maxFramesPerSecond` and `frameBurst` were screened only in `SyncSocket`'s constructor, which
+  `sync-node` runs inside `websocket.open`, which Bun runs SYNCHRONOUSLY inside `server.upgrade`.
+  Measured: `createSyncNode` did not throw, `/healthz` and `/readyz` both answered, `ready` was
+  true, and every upgrade threw `X_INVARIANT` with the node holding zero sockets — a node that
+  boots green and refuses every client, whose cause is one frame inside the runtime. They are
+  `socketCeilings()` in `sync-node-bounds.ts` now, called once by `createSyncNode`, and the
+  per-socket screen STAYS beside it: `SyncSocket` is exported and an app may build one directly,
+  which is the layered repair `finite-bounds`' own header prescribes for a check in another file.
+  `undefined` stays `undefined` — `SyncSocket` owns those four defaults, and a second spelling of
+  one is a number that can drift from it.
+- **An upgrade that THROWS gives the grant back, not only one that answers `false`
+  (`As of 2026-08-26`).** `handleUpgrade` records the grant before `server.upgrade` because `open`
+  reads it, and released it on the `false` branch alone — so a throw out of `open` left one
+  `GrantBook` entry per connection ATTEMPT, unreapable: `sweepGrants` only visits a grant carrying
+  an `expiresAt`, which `authenticate: async () => ({ actor })` does not produce. Measured, 20
+  failing upgrades left 20 grants. The `try` around `server.upgrade` rethrows untouched — the throw
+  is the operator's diagnosis and that line owes it the release, not a verdict.
+- **Every ceiling is refused when it is not a FINITE number, `As of 2026-08-26`.**
+  `AcceptBudget`'s `perSecond`/`burst`, `SyncSocket`'s `maxBufferedBytes`/`maxDroppedFrames` and
+  `SocketRegistry`'s `idleTimeoutMs` throw `X_INVARIANT` at construction on `NaN` and `±Infinity`.
+  Every comparison against a non-finite bound is FALSE, so each guard did not loosen — it switched
+  off, silently. Measured: `tryAccept()` asks `tokens < 1`, so `perSecond: NaN` admitted every
+  accept, herd included, on the node path AND on the per-socket frame flood budget;
+  `maxBufferedBytes: NaN` made `send()` answer TRUE with 10 MB queued, so a discarded frame was
+  neither counted in `channel_frames_dropped_total` nor desync-marked — the delivery-accounting
+  guarantee this file states, voidable through one option; `idleTimeoutMs: NaN` left a socket idle
+  for 10,000,000 ms out of `idle()`. `??` guards only nullish and `Math.max` is a clamp, not a
+  validator: `Number(process.env.X)` on an unset variable reaches the comparison intact.
+- **A SQLSTATE off the wire is DATA, so `pg-wire.ts`'s `FIXES` is read with `Object.hasOwn`.**
+  `FIXES['constructor']` answered the `Object` function — not nullish, so `?? GENERIC_FIX` never
+  fired — and `UltimateError` then ran `singleLine(fn)`: a `TypeError` out of the constructor of
+  the error that exists to explain the failure, so the caller lost `X_REPLICATION_FAILED`, its
+  cause and its fix at once. This was `realtime`'s one `proto-index` pin, and the pin's stated
+  reason ("keyed by a replication op this package declares") described a different read.
 - **A name nothing registered is `X_LIVE_QUERY_UNKNOWN`, never `X_PROTOCOL_VERSION`.** The frame
   parsed and the version matched — one string in it names nothing — so "x build && redeploy the
   client" is the one instruction that cannot work: a rebuilt client spells the typo the same way,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "15.0.0",
+  "version": "17.0.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": "15.0.0",
-    "@ultimat3/query": "15.0.0",
+    "@ultimat3/core": "17.0.0",
+    "@ultimat3/query": "17.0.0",
     "nats": "2.29.3"
   }
 }

package/src/change-buffer.ts

@@ -13,6 +13,7 @@
 // node fills from the change stream it already subscribes to, which is a `ResumeSource` shape
 // change, not a placement change.
 
+import { finiteOption } from '@ultimat3/core';
 import type { ResumeSource } from './cursor';
 import type { RowPatch } from './json';
 
@@ -64,10 +65,18 @@ export class RingChangeBuffer implements ResumeSource {
   #bytes = 0;
 
   constructor(options: ChangeBufferOptions = {}) {
-    this.#capacity = options.capacity ?? 1024;
-    this.#maxQueries = options.maxQueries ?? 4096;
-    this.#maxBytesPerQuery = options.maxBytesPerQuery ?? DEFAULT_MAX_BUFFER_BYTES_PER_QUERY;
-    this.#maxBytes = options.maxBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+    this.#capacity = finiteOption('ChangeBuffer', 'capacity', options.capacity ?? 1024);
+    this.#maxQueries = finiteOption('ChangeBuffer', 'maxQueries', options.maxQueries ?? 4096);
+    this.#maxBytesPerQuery = finiteOption(
+      'ChangeBuffer',
+      'maxBytesPerQuery',
+      options.maxBytesPerQuery ?? DEFAULT_MAX_BUFFER_BYTES_PER_QUERY,
+    );
+    this.#maxBytes = finiteOption(
+      'ChangeBuffer',
+      'maxBytes',
+      options.maxBytes ?? DEFAULT_MAX_BUFFER_BYTES,
+    );
   }
 
   /** Retained bytes across every query on this node. The number the ceiling is about. */

package/src/changefeed.ts

@@ -3,6 +3,7 @@
 // replicator, and the fanout never learn which one they are attached to.
 
 import type { Clock } from '@ultimat3/core';
+import { finiteOption } from '@ultimat3/core';
 import { ReplicationFailedError } from './errors';
 import type { Row } from './json';
 import { PgReplicationStream, type ReplicationStreamStats } from './pg-replication';
@@ -72,7 +73,7 @@ export class InMemoryChangeFeed implements ChangeFeed {
   #lastLsn: string | null = null;
 
   constructor(options: InMemoryChangeFeedOptions = {}) {
-    this.#retain = options.retain ?? 1024;
+    this.#retain = finiteOption('the change feed', 'retain', options.retain ?? 1024);
   }
 
   async start(options: ChangeFeedStartOptions): Promise<void> {

package/src/channel.ts

@@ -4,7 +4,7 @@
 // append-only stream, so tier 1 needs no frame of its own. That is why climbing the ladder is a
 // config change: the client's frame handler is the same code at every rung.
 
-import { type Actor, logger, renderThrowable } from '@ultimat3/core';
+import { type Actor, finiteOption, logger, renderThrowable } from '@ultimat3/core';
 import { formatLsn } from './changefeed';
 import {
   isPolicyDenial,
@@ -101,8 +101,16 @@ export class ChannelHub {
   constructor(options: ChannelHubOptions) {
     this.#transport = options.transport;
     this.#sockets = options.sockets;
-    this.#maxTopicsPerSocket = options.maxTopicsPerSocket ?? 64;
-    this.#maxTopicsPerNode = options.maxTopicsPerNode ?? DEFAULT_MAX_TOPICS_PER_NODE;
+    this.#maxTopicsPerSocket = finiteOption(
+      'ChannelHub',
+      'maxTopicsPerSocket',
+      options.maxTopicsPerSocket ?? 64,
+    );
+    this.#maxTopicsPerNode = finiteOption(
+      'ChannelHub',
+      'maxTopicsPerNode',
+      options.maxTopicsPerNode ?? DEFAULT_MAX_TOPICS_PER_NODE,
+    );
   }
 
   /** Sockets this node will deliver `name` to. The metric the fanout reads. */

package/src/client.ts

@@ -3,7 +3,7 @@
 // serves all three tiers: `useLive` is tier 2, and a `store` + `queue` makes the same call tier 3
 // with nothing about the subscription changing — that is the ladder's whole promise.
 
-import { type Clock, systemClock, uuid } from '@ultimat3/core';
+import { type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
 import type { Topic } from './channel';
 import type {
   ClientSocket,
@@ -110,7 +110,11 @@ export class LiveClient<T extends TableMap = TableMap> {
     this.#connected = connected;
     this.#setConnected = setConnected;
     this.#heartbeat = new Heartbeat({
-      intervalMs: options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
+      intervalMs: finiteOption(
+        'the sync client',
+        'heartbeatMs',
+        options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
+      ),
       schedule: options.scheduler ?? timeoutScheduler,
       now: () => this.#clock.now().getTime(),
       beat: () => this.#beat(),

package/src/live-definition.ts

@@ -9,6 +9,7 @@
 // every time. Collapsing the second onto the first is privilege escalation with a cache hit rate.
 
 import type { Ctx } from '@ultimat3/core';
+import { finiteOption } from '@ultimat3/core';
 import { type AnyQuery, queryHash, queryName } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
@@ -120,7 +121,7 @@ export function liveQueryDefinition(
       },
     };
     windows.set(qid, built);
-    evictOldest(windows, options.maxWindows ?? 256);
+    evictOldest(windows, finiteOption('live()', 'maxWindows', options.maxWindows ?? 256));
     return built;
   };
 

package/src/live-query.ts

@@ -6,7 +6,7 @@
 // policy is never sent to that actor — it arrives as a `delete` if they hold it, and is dropped
 // otherwise.
 
-import { type Actor, type Clock, systemClock, uuid } from '@ultimat3/core';
+import { type Actor, type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
 import { queryHash } from '@ultimat3/query';
 import type { ChangeEvent } from './changefeed';
 import {
@@ -76,7 +76,11 @@ export class LiveQueryRegistry {
     this.#options = options;
     this.#clock = options.clock ?? systemClock;
     this.#gate = new SubscriberGate(options);
-    this.#maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this.#maxEntries = finiteOption(
+      'the live-query registry',
+      'maxEntries',
+      options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+    );
     // The book owns the caps because it is the only thing that can answer them in O(1).
     this.#book = new SubscriptionBook(options);
     this.#fanout = { gate: this.#gate, source: options.source, clock: this.#clock };

package/src/nats-lib-client.ts

@@ -14,7 +14,7 @@
 // This header said "every failure leaves here as an `UltimateError`" until 2026-08, which a reader
 // took as a guarantee it never was.
 
-import { renderThrowable } from '@ultimat3/core';
+import { finiteOption, renderThrowable } from '@ultimat3/core';
 import { connect, Events, headers, Match, type Msg, type MsgHdrs, type NatsConnection } from 'nats';
 import { TransportUnavailableError } from './errors';
 import {
@@ -76,7 +76,11 @@ class LibNatsClient implements NatsClient {
   constructor(connection: NatsConnection, target: NatsTarget, options: NatsClientOptions) {
     this.#connection = connection;
     this.#target = target;
-    this.#timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.#timeoutMs = finiteOption(
+      'the nats client',
+      'requestTimeoutMs',
+      options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+    );
     this.#report = options.onError ?? ((): void => undefined);
     void this.#watch(options);
   }
@@ -192,14 +196,22 @@ class LibNatsClient implements NatsClient {
  */
 export const openNatsClient = async (options: NatsClientOptions): Promise<NatsClient> => {
   const target = parseNatsUrl(options.url);
+  // Screened BEFORE the try, and before the dial. Two reasons, and the second is why it is not a
+  // line further down: the value is FORWARDED to the library rather than compared here, so there is
+  // no `??` for `bun run finite-bounds` to see — the same conditional-spread shape that hid the
+  // sync node's four socket ceilings; and inside the `try`, the catch below would re-render a
+  // misconfiguration as `X_TRANSPORT_UNAVAILABLE`, which is a bus outage nobody can fix by looking
+  // at the bus. `-1` stays legal: that is the library's "reconnect forever".
+  const maxReconnectAttempts =
+    options.maxReconnectAttempts === undefined
+      ? undefined
+      : finiteOption('the nats client', 'maxReconnectAttempts', options.maxReconnectAttempts);
   try {
     const connection = await connect({
       servers: [`${target.host}:${target.port}`],
       name: options.name ?? 'ultimate',
       waitOnFirstConnect: true,
-      ...(options.maxReconnectAttempts === undefined
-        ? {}
-        : { maxReconnectAttempts: options.maxReconnectAttempts }),
+      ...(maxReconnectAttempts === undefined ? {} : { maxReconnectAttempts }),
       ...(options.reconnectDelay === undefined
         ? {}
         : { reconnectDelayHandler: options.reconnectDelay }),

package/src/nats-transport.ts

@@ -3,7 +3,14 @@
 // re-establishing subscriptions, which is what makes a `sync` node stateless: a lost connection is
 // re-dialled and re-subscribed underneath the caller, and this file keeps no socket state at all.
 
-import { type Clock, isUltimateError, logger, renderThrowable, systemClock } from '@ultimat3/core';
+import {
+  type Clock,
+  finiteOption,
+  isUltimateError,
+  logger,
+  renderThrowable,
+  systemClock,
+} from '@ultimat3/core';
 import { TransportUnavailableError } from './errors';
 import type { Transport, TransportHandler, TransportSet, TransportSubscription } from './fanout';
 import type { NatsClient, NatsConnect } from './nats-client';
@@ -56,7 +63,11 @@ export class NatsTransport implements Transport {
     this.#options = options;
     this.#connect = options.connect ?? openNatsClient;
     this.#backoff = options.backoff ?? defaultBackoff;
-    this.#attempts = options.maxReconnectAttempts ?? DEFAULT_ATTEMPTS;
+    this.#attempts = finiteOption(
+      'createNatsTransport',
+      'maxReconnectAttempts',
+      options.maxReconnectAttempts ?? DEFAULT_ATTEMPTS,
+    );
     this.#rng = options.rng ?? Math.random;
     this.shared = new NatsKvSet({
       client: () => this.#ensure(),
@@ -172,7 +183,11 @@ export class NatsTransport implements Transport {
     return ensureKvBucket(
       client,
       this.#options.bucket,
-      this.#options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS,
+      finiteOption(
+        'createNatsTransport',
+        'presenceTtlMs',
+        this.#options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS,
+      ),
     );
   }
 

package/src/pg-replication.ts

@@ -3,7 +3,7 @@
 // the framing and the pgoutput decode live next door; what is decided here is *ordering*, because
 // the lsn is the only authority the pipeline has.
 
-import { type Clock, logger, renderThrowable, systemClock } from '@ultimat3/core';
+import { type Clock, finiteOption, logger, renderThrowable, systemClock } from '@ultimat3/core';
 import type { ChangeEvent, ChangeOp, PgLogicalReplicationOptions } from './changefeed';
 import { ReplicationProtocolError } from './errors';
 import { isRow, type Row } from './json';
@@ -184,9 +184,16 @@ export class PgReplicationStream {
     // supervisor that reads it never sees the replicator come back.
     this.#failure = null;
     this.#confirmFailures = 0;
-    this.#timer = setInterval(() => {
-      void this.#confirmOnTimer();
-    }, this.#options.statusIntervalMs ?? DEFAULT_STATUS_INTERVAL_MS);
+    this.#timer = setInterval(
+      () => {
+        void this.#confirmOnTimer();
+      },
+      finiteOption(
+        'the replication stream',
+        'statusIntervalMs',
+        this.#options.statusIntervalMs ?? DEFAULT_STATUS_INTERVAL_MS,
+      ),
+    );
     // A pending timer must not be what keeps `x dev` alive after the app is done with it.
     this.#timer.unref?.();
     this.#pump = this.#drain(connection, handlers);

package/src/pg-wire.ts

@@ -195,13 +195,25 @@ export const FIXES: Readonly<Record<string, string>> = {
   '0A000': 'set wal_level = logical in postgresql.conf and restart the server',
 };
 
-/** An `ErrorResponse` becomes the one error class whose `fix` names the command to run. */
+/** What a SQLSTATE this table has no entry for is answered with. */
+const GENERIC_FIX = 'x doctor db — the postgres message above names the object to change';
+
+/**
+ * An `ErrorResponse` becomes the one error class whose `fix` names the command to run.
+ *
+ * `Object.hasOwn`, because `code` is `fields['C']` — read off the WIRE, so it is data and this
+ * table is keyed by it. `FIXES['constructor']` answered the `Object` function, which is not
+ * nullish, so `?? GENERIC_FIX` never fired and `UltimateError` ran `singleLine(fn)`: a `TypeError`
+ * out of the constructor of the error that exists to explain the failure, so the caller lost
+ * `X_REPLICATION_FAILED`, its cause and its fix at once. `packages/schema/src/errors.ts` shipped
+ * the same shape and `scripts/proto-index.ts` was written for it.
+ */
 export const serverError = (stage: string, body: Uint8Array): ReplicationFailedError => {
   const fields = responseFields(body);
   const code = fields['C'] ?? '';
   return new ReplicationFailedError({
     stage,
     detail: describeFields(fields),
-    fix: FIXES[code] ?? 'x doctor db — the postgres message above names the object to change',
+    fix: Object.hasOwn(FIXES, code) ? (FIXES[code] ?? GENERIC_FIX) : GENERIC_FIX,
   });
 };

package/src/presence.ts

@@ -4,7 +4,7 @@
 // simply stop heartbeating and expire, and every other node already sees the same set. Ephemeral
 // state is never modelled as rows — that rule is what keeps presence off the write path entirely.
 
-import { type Clock, systemClock, uuid } from '@ultimat3/core';
+import { type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
 import type { ChannelHub, Topic } from './channel';
 import type { Transport } from './fanout';
 import type { JsonObject } from './json';
@@ -66,8 +66,11 @@ export class PresenceRegistry {
     this.#transport = options.transport;
     this.#hub = options.hub;
     this.#clock = options.clock ?? systemClock;
-    this.#ttlMs = options.ttlMs ?? 30_000;
-    this.#maxMembers = Math.max(1, options.maxMembers ?? DEFAULT_MAX_PRESENCE_MEMBERS);
+    this.#ttlMs = finiteOption('presence', 'ttlMs', options.ttlMs ?? 30_000);
+    this.#maxMembers = Math.max(
+      1,
+      finiteOption('presence', 'maxMembers', options.maxMembers ?? DEFAULT_MAX_PRESENCE_MEMBERS),
+    );
     this.#nodeId = options.nodeId ?? uuid();
   }
 

package/src/socket.ts

@@ -10,6 +10,7 @@ import {
   type Clock,
   type Counter,
   counter,
+  finiteOption,
   logger,
   recordConnection,
   systemClock,
@@ -102,6 +103,14 @@ export function actorIdOf(actor: Actor | null): string | null {
   return actor === null ? null : actor.id;
 }
 
+/**
+ * MEASURED, both directions: with `maxBufferedBytes: NaN`, `getBufferedAmount() > NaN` is false and
+ * `send()` answered TRUE with 10 MB already buffered — backpressure never trips, the caller is told
+ * the frame left, and the drop reaches neither `channel_frames_dropped_total` nor the desync mark;
+ * with `idleTimeoutMs: NaN`, `idleFor(now) > NaN` is false and a socket idle for 10,000,000 ms is
+ * not in `idle()`, so a wedged client holds its grant, its subscriptions and its topic membership
+ * forever. `@ultimat3/core`'s `finiteOption` is the one refusal; `bun run finite-bounds` is the ratchet over it.
+ */
 export class SyncSocket {
   readonly id: string;
   readonly clientBuildId: string;
@@ -150,10 +159,16 @@ export class SyncSocket {
     this.serverBuildId = options.serverBuildId;
     this.actor = options.actor ?? null;
     this.#maxBufferedBytes = options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+    finiteOption('SyncSocket', 'maxBufferedBytes', this.#maxBufferedBytes);
     this.#maxDroppedFrames = options.maxDroppedFrames ?? 32;
+    finiteOption('SyncSocket', 'maxDroppedFrames', this.#maxDroppedFrames);
     this.frameBudget = new AcceptBudget({
-      perSecond: options.maxFramesPerSecond ?? DEFAULT_MAX_FRAMES_PER_SECOND,
-      burst: options.frameBurst ?? DEFAULT_FRAME_BURST,
+      perSecond: finiteOption(
+        'SyncSocket',
+        'maxFramesPerSecond',
+        options.maxFramesPerSecond ?? DEFAULT_MAX_FRAMES_PER_SECOND,
+      ),
+      burst: finiteOption('SyncSocket', 'frameBurst', options.frameBurst ?? DEFAULT_FRAME_BURST),
       clock: this.#clock,
     });
     // Two clocks on purpose: `openedAt` is an instant a human reads, `lastSeenMonotonicMs` is the
@@ -287,6 +302,7 @@ export class SocketRegistry {
   constructor(options: SocketRegistryOptions = {}) {
     this.#clock = options.clock ?? systemClock;
     this.#idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    finiteOption('SocketRegistry', 'idleTimeoutMs', this.#idleTimeoutMs);
   }
 
   /**

package/src/subscription-book.ts

@@ -4,6 +4,7 @@
 // the only thing that knows what exists. Every question it answers is indexed, never scanned.
 
 import type { Actor } from '@ultimat3/core';
+import { finiteOption } from '@ultimat3/core';
 import { SubscriptionIdTakenError, SubscriptionLimitError } from './errors';
 import type { LiveSubscription } from './live-contract';
 import type { SyncSocket } from './socket';
@@ -36,6 +37,8 @@ export interface SubscriptionCaps {
 /** Sockets may open this many live queries before `X_SUBSCRIPTION_LIMIT`. */
 export const DEFAULT_MAX_PER_SOCKET = 128;
 
+const SUBJECT = 'the subscription caps';
+
 /**
  * Every live subscription on this node, keyed by `(socket, sid)`.
  *
@@ -70,9 +73,28 @@ export class SubscriptionBook {
   /** The same claims counted per tenant, because that cap spans sockets and a lane cannot see it. */
   readonly #claimedPerTenant = new Map<string, number>();
   readonly #caps: SubscriptionCaps;
+  /**
+   * BOTH caps screened here, once, rather than on the subscribe path — and `maxPerTenant` was not
+   * screened at all: it has no `??` default, which is the one shape `bun run finite-bounds` states
+   * in its own header that it cannot see. `count >= NaN` is false, so the only cap that spans the
+   * sockets of one tenant was off in silence; measured, a book built with `maxPerTenant: NaN`
+   * admitted 5,000 subscribes for one tenant. `undefined` stays `undefined`, because there the
+   * caller is saying "no per-tenant cap" rather than handing a number that is not one.
+   */
+  readonly #maxPerSocket: number;
+  readonly #maxPerTenant: number | undefined;
 
   constructor(caps: SubscriptionCaps = {}) {
     this.#caps = caps;
+    this.#maxPerSocket = finiteOption(
+      SUBJECT,
+      'maxPerSocket',
+      caps.maxPerSocket ?? DEFAULT_MAX_PER_SOCKET,
+    );
+    this.#maxPerTenant =
+      caps.maxPerTenant === undefined
+        ? undefined
+        : finiteOption(SUBJECT, 'maxPerTenant', caps.maxPerTenant);
   }
 
   get(socketId: string, sid: string): LiveSubscription | undefined {
@@ -160,7 +182,7 @@ export class SubscriptionBook {
    * node to an entry, a matcher and a read.
    */
   assertCapacity(socket: SyncSocket): void {
-    const perSocket = this.#caps.maxPerSocket ?? DEFAULT_MAX_PER_SOCKET;
+    const perSocket = this.#maxPerSocket;
     const claimed = this.#claimedBySocket.get(socket.id)?.size ?? 0;
     if (socket.queries.size + claimed >= perSocket) {
       throw new SubscriptionLimitError({
@@ -170,7 +192,7 @@ export class SubscriptionBook {
         knob: 'maxPerSocket',
       });
     }
-    const perTenant = this.#caps.maxPerTenant;
+    const perTenant = this.#maxPerTenant;
     const tenant = this.#tenantFor(socket);
     if (perTenant === undefined || tenant === null) return;
     if (this.tenantCount(tenant) + (this.#claimedPerTenant.get(tenant) ?? 0) >= perTenant) {

package/src/sync-listen.ts

@@ -2,7 +2,7 @@
 // so the node itself stays testable with no server: this file is the only place realtime calls
 // `Bun.serve`, and the only thing in the package that knows a port exists.
 
-import { markListening, onShutdown } from '@ultimat3/core';
+import { finiteOption, markListening, onShutdown } from '@ultimat3/core';
 import type { SyncNode } from './sync-node';
 
 export interface ListenOptions {
@@ -21,7 +21,7 @@ export interface SyncListener {
  */
 export function listenSyncNode(node: SyncNode, options: ListenOptions = {}): SyncListener {
   const server = Bun.serve({
-    port: options.port ?? 3001,
+    port: finiteOption('listenSyncNode', 'port', options.port ?? 3001),
     fetch: node.fetch,
     websocket: node.websocket,
   });

package/src/sync-node-bounds.ts

@@ -0,0 +1,129 @@
+// Every numeric option `listenSyncNode` accepts, read and REFUSED in one place — split out of
+// `sync-node.ts`, which is at the 500-line ceiling `x verify`'s `filesize` step enforces.
+//
+// WHY A REFUSAL AND NOT A CLAMP: `@ultimat3/core`'s `finite-option.ts` carries the argument in full. The short version is
+// that `??` guards nullish, `NaN` is not nullish, and every comparison against a non-finite bound
+// reads false — so `maxConnections: NaN` is a node that accepts without limit and says nothing.
+
+import { finiteOption } from '@ultimat3/core';
+
+const SUBJECT = 'the sync node';
+
+/**
+ * How often an expired grant is re-decided. A third of the shortest TTL worth issuing: a grant is
+ * re-checked on the pass after it expires, so the window a revoked actor keeps its socket is this
+ * interval and not its token's lifetime.
+ */
+export const DEFAULT_REAUTH_INTERVAL_MS = 30_000;
+
+/**
+ * Concurrent sockets one node will hold. The accept budget bounds the accept RATE and nothing
+ * bounded the COUNT: at the 500/s that budget permits, an attacker holding each socket open with
+ * one keepalive frame a minute reaches 1.8M sockets an hour, each carrying a `GrantBook` entry.
+ *
+ * The number clears the 50,000 real clients this repo has measured on one node
+ * (`scripts/bench/restart-bench.ts`) with room to spare, because a ceiling that refuses a proven
+ * workload is an outage the framework caused.
+ */
+export const DEFAULT_MAX_CONNECTIONS = 250_000;
+
+/**
+ * Inbound bytes one frame may carry. Bun's own default is 16 MiB, which one authenticated socket
+ * can push continuously; a `subscribe` frame carrying a full 512-id cursor is under 32 KiB.
+ */
+export const DEFAULT_MAX_FRAME_BYTES = 256 * 1024;
+
+export const DEFAULT_DRAIN_SPREAD_MS = 30_000;
+export const DEFAULT_DRAIN_GRACE_MS = 5_000;
+
+/** The subset of `SyncNodeOptions` this module reads. Structural, so the full type satisfies it. */
+export interface SyncNodeNumericOptions {
+  readonly maxConnections?: number | undefined;
+  readonly reauthenticateIntervalMs?: number | undefined;
+  readonly maxFrameBytes?: number | undefined;
+  readonly drainSpreadMs?: number | undefined;
+}
+
+export interface SyncNodeBounds {
+  readonly maxConnections: number;
+  readonly reauthenticateIntervalMs: number;
+  readonly maxFrameBytes: number;
+  readonly drainSpreadMs: number;
+}
+
+export function syncNodeBounds(options: SyncNodeNumericOptions): SyncNodeBounds {
+  return {
+    maxConnections: finiteOption(
+      SUBJECT,
+      'maxConnections',
+      options.maxConnections ?? DEFAULT_MAX_CONNECTIONS,
+    ),
+    reauthenticateIntervalMs: finiteOption(
+      SUBJECT,
+      'reauthenticateIntervalMs',
+      options.reauthenticateIntervalMs ?? DEFAULT_REAUTH_INTERVAL_MS,
+    ),
+    maxFrameBytes: finiteOption(
+      SUBJECT,
+      'maxFrameBytes',
+      options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES,
+    ),
+    drainSpreadMs: finiteOption(
+      SUBJECT,
+      'drainSpreadMs',
+      options.drainSpreadMs ?? DEFAULT_DRAIN_SPREAD_MS,
+    ),
+  };
+}
+
+/**
+ * The four ceilings this node forwards to every socket it builds, and the only options it accepts
+ * that `SyncSocket` — not this module — owns the default of.
+ *
+ * They were screened only in `SyncSocket`'s constructor, which Bun runs inside `websocket.open`,
+ * which Bun runs SYNCHRONOUSLY inside `server.upgrade`. Measured: `createSyncNode` did not throw,
+ * `/healthz` and `/readyz` both answered, `ready` was true, and every upgrade threw `X_INVARIANT`
+ * with the node holding zero sockets — a misconfiguration that fails per connection instead of at
+ * boot, and each of those throws leaked the grant `handleUpgrade` records before the upgrade.
+ *
+ * `undefined` stays `undefined` rather than acquiring a default here: `SyncSocket` owns those four
+ * numbers, and a second spelling of one is a number that can drift from the one it copies. Nothing
+ * narrower than "finite" either — `maxDroppedFrames: 0` is "close on the first drop",
+ * `maxFramesPerSecond: 0` is clamped to 1 by `AcceptBudget`'s own documented floor, and a screen
+ * that refused either would turn a working deployment into a boot failure.
+ *
+ * The per-socket screen STAYS, because `SyncSocket` is exported and an app may build one directly
+ * — the layered form `finite-bounds`' own header prescribes for a repair in a different file.
+ */
+export interface SocketCeilings {
+  // `?: number` and never `?: number | undefined`, unlike `SyncNodeNumericOptions` above: this one
+  // is SPREAD into `SyncSocketOptions`, and under `exactOptionalPropertyTypes` an explicit
+  // `undefined` is a different type from an absent key. The build error is the enforcement — a
+  // screened ceiling that arrived as `undefined` would silently take the socket's default.
+  readonly maxFramesPerSecond?: number;
+  readonly frameBurst?: number;
+  readonly maxBufferedBytes?: number;
+  readonly maxDroppedFrames?: number;
+}
+
+export function socketCeilings(options: SocketCeilings): SocketCeilings {
+  const { maxFramesPerSecond, frameBurst, maxBufferedBytes, maxDroppedFrames } = options;
+  return {
+    ...(maxFramesPerSecond === undefined
+      ? {}
+      : { maxFramesPerSecond: finiteOption(SUBJECT, 'maxFramesPerSecond', maxFramesPerSecond) }),
+    ...(frameBurst === undefined
+      ? {}
+      : { frameBurst: finiteOption(SUBJECT, 'frameBurst', frameBurst) }),
+    ...(maxBufferedBytes === undefined
+      ? {}
+      : { maxBufferedBytes: finiteOption(SUBJECT, 'maxBufferedBytes', maxBufferedBytes) }),
+    ...(maxDroppedFrames === undefined
+      ? {}
+      : { maxDroppedFrames: finiteOption(SUBJECT, 'maxDroppedFrames', maxDroppedFrames) }),
+  };
+}
+
+/** Per CALL, not per node: `drain({ graceMs })` is an argument, so it is refused where it arrives. */
+export const drainGraceMs = (graceMs: number | undefined): number =>
+  finiteOption('the sync node drain', 'graceMs', graceMs ?? DEFAULT_DRAIN_GRACE_MS);

package/src/sync-node.ts

@@ -23,6 +23,7 @@ import {
 } from './socket';
 import { GrantBook, type SyncAuthenticator, sweepGrants } from './sync-auth';
 import { ackRefOf, createFrameRouter, type MutationHandler } from './sync-frames';
+import { drainGraceMs, socketCeilings, syncNodeBounds } from './sync-node-bounds';
 import { decode, type Frame, PROTOCOL_VERSION, toWireError } from './sync-protocol';
 import { handleUpgrade, type UpgradeTarget, type WsData } from './sync-upgrade';
 import {
@@ -38,29 +39,13 @@ export type { UpgradeTarget, WsData } from './sync-upgrade';
 
 export type SyncWs = WsLike & { readonly data: WsData };
 
-/**
- * How often an expired grant is re-decided. A third of the shortest TTL worth issuing: a grant is
- * re-checked on the pass after it expires, so the window a revoked actor keeps its socket is this
- * interval and not its token's lifetime.
- */
-export const DEFAULT_REAUTH_INTERVAL_MS = 30_000;
-
-/**
- * Concurrent sockets one node will hold. The accept budget bounds the accept RATE and nothing
- * bounded the COUNT: at the 500/s that budget permits, an attacker holding each socket open with
- * one keepalive frame a minute reaches 1.8M sockets an hour, each carrying a `GrantBook` entry.
- *
- * The number clears the 50,000 real clients this repo has measured on one node
- * (`scripts/bench/restart-bench.ts`) with room to spare, because a ceiling that refuses a proven
- * workload is an outage the framework caused.
- */
-export const DEFAULT_MAX_CONNECTIONS = 250_000;
-
-/**
- * Inbound bytes one frame may carry. Bun's own default is 16 MiB, which one authenticated socket
- * can push continuously; a `subscribe` frame carrying a full 512-id cursor is under 32 KiB.
- */
-export const DEFAULT_MAX_FRAME_BYTES = 256 * 1024;
+// Moved to `sync-node-bounds.ts` with the refusals that read them, and re-exported here because
+// `server.ts` publishes all three and a moved constant must not become a moved import path.
+export {
+  DEFAULT_MAX_CONNECTIONS,
+  DEFAULT_MAX_FRAME_BYTES,
+  DEFAULT_REAUTH_INTERVAL_MS,
+} from './sync-node-bounds';
 
 export interface SyncNodeOptions {
   readonly hub: ChannelHub;
@@ -153,7 +138,11 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     });
   const clock = options.clock ?? systemClock;
   const accept = options.accept ?? new AcceptBudget({ perSecond: 500, burst: 2000, clock });
-  const maxConnections = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
+  const bounds = syncNodeBounds(options);
+  // Screened at construction, once, and reused per socket: the four ceilings below are read inside
+  // `websocket.open`, which Bun runs synchronously inside `server.upgrade`, so refusing them there
+  // is a node that boots clean and throws out of every upgrade. `sync-node-bounds.ts` carries why.
+  const ceilings = socketCeilings(options);
   const path = options.path ?? '/_x/sync';
   const presence = options.presence;
   const grants = new GrantBook();
@@ -318,7 +307,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       if (options.authenticate) {
         reauthing = setInterval(
           () => detach(reauthenticate(), 'sync.reauthenticate'),
-          options.reauthenticateIntervalMs ?? DEFAULT_REAUTH_INTERVAL_MS,
+          bounds.reauthenticateIntervalMs,
         );
         reauthing.unref();
       } else {
@@ -348,7 +337,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
         {
           path,
           buildId: options.buildId,
-          maxConnections,
+          maxConnections: bounds.maxConnections,
           accept,
           rng: options.rng ?? Math.random,
           // Read per call, never captured: `ready` and the socket count both move while a request
@@ -377,7 +366,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       // one filtered `send` per socket through `SocketRegistry.deliver`, which is the only path
       // that can count the frame it dropped — a flag configuring a mechanism nothing uses reads
       // as a live one to the next person who has to decide how delivery works.
-      maxPayloadLength: options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES,
+      maxPayloadLength: bounds.maxFrameBytes,
       sendPings: true,
 
       open(ws: SyncWs): void {
@@ -391,16 +380,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
           serverBuildId: options.buildId,
           actor: grants.get(ws.data.socketId)?.actor ?? null,
           clock,
-          ...(options.maxFramesPerSecond === undefined
-            ? {}
-            : { maxFramesPerSecond: options.maxFramesPerSecond }),
-          ...(options.frameBurst === undefined ? {} : { frameBurst: options.frameBurst }),
-          ...(options.maxBufferedBytes === undefined
-            ? {}
-            : { maxBufferedBytes: options.maxBufferedBytes }),
-          ...(options.maxDroppedFrames === undefined
-            ? {}
-            : { maxDroppedFrames: options.maxDroppedFrames }),
+          ...ceilings,
         });
         sockets.add(socket);
       },
@@ -452,7 +432,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       ready = false;
       const ids = [...sockets.all()].map((socket) => socket.id);
       const spread = drainPlan(ids, {
-        spreadMs: options.drainSpreadMs ?? 30_000,
+        spreadMs: bounds.drainSpreadMs,
         ...(options.rng ? { rng: options.rng } : {}),
       });
       // The answer is read, not assumed: this frame IS the socket's slot, so a client that never
@@ -467,7 +447,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       if (notified < plan.length) {
         logger.warn('sync.drain_frames_dropped', { sockets: plan.length, notified });
       }
-      const graceMs = drainOptions.graceMs ?? 5_000;
+      const graceMs = drainGraceMs(drainOptions.graceMs);
       if (graceMs > 0) await new Promise((resolve) => setTimeout(resolve, graceMs));
       // Through `evict`, never `sockets.remove` + `grants.delete`: those are three of `teardown`'s
       // five steps, and the two they skip are the ones the rest of the fleet can see. A drained

package/src/sync-upgrade.ts

@@ -124,7 +124,22 @@ export async function handleUpgrade(
   // not return until it has, so a grant recorded on the next line is one the socket was already
   // built without.
   if (grant) deps.onGranted(data.socketId, grant);
-  if (!server.upgrade(request, { data })) {
+  let upgraded: boolean;
+  try {
+    upgraded = server.upgrade(request, { data });
+  } catch (error) {
+    // The other exit that never opens a socket, and the one the `false` branch below hid. Bun runs
+    // `websocket.open` synchronously inside `upgrade`, so ANYTHING that throws in there — a socket
+    // refusing its own ceiling, an app-supplied registry, an `open` a later change adds work to —
+    // comes out here, with no `close` callback behind it. Unreleased, that is one `GrantBook` entry
+    // per connection ATTEMPT, and an unreapable one: `sweepGrants` only visits a grant carrying an
+    // `expiresAt`, which `authenticate: async () => ({ actor })` does not produce. Measured, 20
+    // failing upgrades left 20 grants. Rethrown untouched — the throw is the operator's diagnosis,
+    // and this line owes it the release, not a verdict.
+    deps.onUngranted(data.socketId);
+    throw error;
+  }
+  if (!upgraded) {
     deps.onUngranted(data.socketId);
     return new Response('expected websocket', { status: 426 });
   }

package/src/thundering-herd.ts

@@ -9,6 +9,7 @@
 import {
   type Clock,
   backoffDelay as coreBackoffDelay,
+  finiteOption,
   type JitterMode,
   type Random,
   systemClock,
@@ -111,7 +112,7 @@ export function drainPlan(
   socketIds: readonly string[],
   options: DrainPlanOptions = {},
 ): DrainPlanEntry[] {
-  const spreadMs = options.spreadMs ?? 30_000;
+  const spreadMs = finiteOption('drainPlan', 'spreadMs', options.spreadMs ?? 30_000);
   const rng = options.rng ?? Math.random;
   const total = socketIds.length;
   if (total === 0) return [];
@@ -146,6 +147,14 @@ export class AcceptBudget {
   #lastRefill: number;
 
   constructor(options: AcceptBudgetOptions) {
+    // `Math.max(1, …)` is a CLAMP, not a validator, and it propagates every non-finite value it is
+    // handed. Measured: `perSecond: NaN` makes `#tokens` NaN, `tryAccept` asks `#tokens < 1`,
+    // `NaN < 1` is false — so the bucket admits every accept, forever, and `retryAfterMs()`
+    // answers NaN, which `JSON.stringify` writes into the `reconnect` frame as `null`. `Infinity`
+    // is the same failure spelled differently: a budget that never refuses is not a budget. A
+    // finite clamp is monotone and safe, so 0 and negatives keep their floor of 1.
+    finiteOption('AcceptBudget', 'perSecond', options.perSecond);
+    finiteOption('AcceptBudget', 'burst', options.burst ?? options.perSecond);
     this.#perSecond = Math.max(1, options.perSecond);
     this.#burst = Math.max(1, options.burst ?? options.perSecond);
     this.#clock = options.clock ?? systemClock;

package/src/transport-env.ts

@@ -5,6 +5,7 @@
 // two sides, and a caller that had to pass each one separately could quietly set them apart.
 
 import type { Clock } from '@ultimat3/core';
+import { finiteOption } from '@ultimat3/core';
 import type { Transport } from './fanout';
 import { InProcessTransport } from './fanout';
 import type { NatsConnect } from './nats-client';
@@ -67,7 +68,11 @@ export function selectTransport(
   env: TransportEnvironment,
   options: SelectTransportOptions = {},
 ): TransportSelection {
-  const presenceTtlMs = options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS;
+  const presenceTtlMs = finiteOption(
+    'the transport env',
+    'presenceTtlMs',
+    options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS,
+  );
   const url = nonEmpty(env['NATS_URL']);
 
   if (url === undefined) {