@ultimat3/realtime 1.2.0 → 3.0.0

package/src/sync-protocol.ts

@@ -2,7 +2,8 @@
 // offline mutation drain are frames in the same union. Moving a route from tier 2 to tier 3 is a
 // config flag (`persist: true`), never a new protocol — that promise is enforced here.
 
-import type { LiveCursor } from './cursor';
+import { renderThrowable, stringField } from '@ultimat3/core';
+import { CURSOR_ID_LIMIT, type LiveCursor } from './cursor';
 import { ProtocolVersionError } from './errors';
 import {
   isJsonObject,
@@ -15,6 +16,27 @@ import {
 
 export const PROTOCOL_VERSION = 1;
 
+/**
+ * What one frame may contain. Hard ceilings a caller cannot widen — the shape
+ * `packages/mcp/src/query-limits.ts` uses — because every one of them is read off a socket the
+ * node has already paid for: an unbounded `cursor.ids` was consumed raw into a `Set`, and an
+ * `input` of arbitrary depth reached `canonicalJson`, which recurses.
+ *
+ * Every number clears what this node itself produces, or the decoder refuses its own frames on
+ * the next reconnect: `cursorIds` is `CURSOR_ID_LIMIT`, `patches` clears
+ * `defaultReconnectBudget.maxPatches`.
+ */
+export const FRAME_LIMITS = Object.freeze({
+  cursorIds: CURSOR_ID_LIMIT,
+  patches: 4_096,
+  rows: 10_000,
+  members: 4_096,
+  /** Nesting one `input` may reach. 32 is far past any query's real argument shape. */
+  inputDepth: 32,
+  /** Values one `input` may hold in total, so a flat-but-enormous object is refused too. */
+  inputNodes: 10_000,
+});
+
 export type ConflictStrategyName = 'server-wins' | 'last-write-wins' | 'custom';
 
 export interface WireError {
@@ -46,6 +68,17 @@ export type SubscribeTarget =
       readonly cursor: LiveCursor | null;
     };
 
+/**
+ * The opening frame, and the heartbeat's. It carries **no cursors**: resume is decided per
+ * subscription by `subscribe`, whose target already carries the cursor and whose `(name, input)`
+ * is what the node needs to authorize the read and reach the retained window at all. A cursor's
+ * `qid` is `qidOf(name, input)` — a digest, not an input — so a resume list here could never be
+ * more than a second, unauthorized restatement of that decision, and it cost every reconnect a
+ * duplicate copy of up to `CURSOR_ID_LIMIT` ids per subscription during the exact restart storm
+ * `thundering-herd.ts` exists to bound. Removing it needs no `PROTOCOL_VERSION` bump: `decode`
+ * builds a whitelist, so a node reads an old client's `resume` as absent and an old node reads a
+ * new client's omission the way it already read an empty list.
+ */
 export interface HelloFrame {
   readonly type: 'hello';
   readonly v: number;
@@ -53,7 +86,6 @@ export interface HelloFrame {
   /** Server-assigned on the reply, `null` on the client's opening frame. */
   readonly sessionId: string | null;
   readonly actorId: string | null;
-  readonly resume: readonly LiveCursor[];
 }
 
 export interface SubscribeFrame {
@@ -70,6 +102,14 @@ export interface SnapshotFrame {
   readonly sid: string;
   readonly rows: readonly Row[];
   readonly cursor: LiveCursor;
+  /**
+   * The entity every row of this result set belongs to — the client's identity scope, so two
+   * queries returning post #7 hold one row rather than two copies. Optional and **additive**: it
+   * is the one thing a browser cannot derive (the shape is compiled server-side from `sql`), and
+   * a client that does not receive it keeps its rows in a scope private to that subscription. Both
+   * skews are safe in both directions, which is why it carries no `PROTOCOL_VERSION` bump.
+   */
+  readonly entity?: string;
 }
 
 export interface PatchFrame {
@@ -115,6 +155,14 @@ export interface PresenceFrame {
   readonly topic: string;
   readonly op: 'join' | 'leave' | 'update' | 'sync';
   readonly members: readonly PresenceMember[];
+  /**
+   * Members in the whole set behind a `sync` frame, which is capped: a 5,000-avatar row is not a UI
+   * anyone renders, and the count is what lets a client say "and 4,744 others" without holding
+   * them. Optional and **additive**, exactly like `snapshot.entity`: an old node omits it and a new
+   * one reads its absence as "this frame is the whole set", so neither skew is unreadable and
+   * `PROTOCOL_VERSION` does not move. Never set on a `join`/`leave`/`update` — those are deltas.
+   */
+  readonly total?: number;
 }
 
 export interface ReconnectFrame {
@@ -185,7 +233,6 @@ export function decode(raw: string | Uint8Array): Frame {
         buildId: str(parsed, 'buildId'),
         sessionId: nullableStr(parsed, 'sessionId'),
         actorId: nullableStr(parsed, 'actorId'),
-        resume: list(parsed, 'resume').map(cursor),
       };
     case 'subscribe':
       return {
@@ -195,20 +242,23 @@ export function decode(raw: string | Uint8Array): Frame {
         sid: str(parsed, 'sid'),
         target: target(parsed['target']),
       };
-    case 'snapshot':
-      return {
+    case 'snapshot': {
+      const base = {
         type: 'snapshot',
         v: PROTOCOL_VERSION,
         sid: str(parsed, 'sid'),
-        rows: list(parsed, 'rows').map(row),
+        rows: list(parsed, 'rows', FRAME_LIMITS.rows).map(row),
         cursor: cursor(parsed['cursor']),
-      };
+      } as const;
+      const entity = nullableStr(parsed, 'entity');
+      return entity === null ? base : { ...base, entity };
+    }
     case 'patch':
       return {
         type: 'patch',
         v: PROTOCOL_VERSION,
         sid: str(parsed, 'sid'),
-        patches: list(parsed, 'patches').map(patch),
+        patches: list(parsed, 'patches', FRAME_LIMITS.patches).map(patch),
         lsn: str(parsed, 'lsn'),
       };
     case 'mutate':
@@ -218,7 +268,7 @@ export function decode(raw: string | Uint8Array): Frame {
         key: str(parsed, 'key'),
         seq: num(parsed, 'seq'),
         name: str(parsed, 'name'),
-        input: parsed['input'] ?? null,
+        input: bounded(parsed['input'] ?? null, 'input'),
       };
     case 'ack':
       return {
@@ -237,14 +287,16 @@ export function decode(raw: string | Uint8Array): Frame {
         strategy: pick(parsed, 'strategy', ['server-wins', 'last-write-wins', 'custom'] as const),
         row: parsed['row'] === null ? null : row(parsed['row']),
       };
-    case 'presence':
-      return {
+    case 'presence': {
+      const base = {
         type: 'presence',
         v: PROTOCOL_VERSION,
         topic: str(parsed, 'topic'),
         op: pick(parsed, 'op', ['join', 'leave', 'update', 'sync'] as const),
-        members: list(parsed, 'members').map(member),
-      };
+        members: list(parsed, 'members', FRAME_LIMITS.members).map(member),
+      } as const;
+      return parsed['total'] === undefined ? base : { ...base, total: num(parsed, 'total') };
+    }
     case 'reconnect':
       return {
         type: 'reconnect',
@@ -261,13 +313,17 @@ export function decode(raw: string | Uint8Array): Frame {
 
 /** Project any thrown value onto the wire without losing the error contract's three fields. */
 export function toWireError(error: unknown): WireError {
-  const shape = error as { code?: unknown; cause?: unknown; fix?: unknown; docs?: unknown } | null;
-  const code = typeof shape?.code === 'string' ? shape.code : 'X_PROTOCOL_VERSION';
-  const cause = typeof shape?.cause === 'string' ? shape.cause : String(error);
-  const fix = typeof shape?.fix === 'string' ? shape.fix : 'x doctor realtime';
-  return typeof shape?.docs === 'string'
-    ? { code, cause, fix, docs: shape.docs }
-    : { code, cause, fix };
+  // The throwable is an app mutator's, a live query's or a policy's, so its `toString` is the
+  // app's too: `String()` here raised inside the handler's catch and the socket got no frame at
+  // all, which a reconnect cannot repair because the same call throws the same way.
+  // `renderThrowable` keeps an Error's own words without trusting `instanceof` or `.message`, and
+  // `stringField` makes the four probes above it as total as the fallback they choose between —
+  // `shape?.code` was a raw property read on that same app value.
+  const code = stringField(error, 'code') ?? 'X_PROTOCOL_VERSION';
+  const cause = stringField(error, 'cause') ?? renderThrowable(error);
+  const fix = stringField(error, 'fix') ?? 'x doctor realtime';
+  const docs = stringField(error, 'docs');
+  return docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
 }
 
 function fail(detail: string): ProtocolVersionError {
@@ -302,10 +358,45 @@ function pick<T extends string>(obj: JsonObject, key: string, allowed: readonly
   return found;
 }
 
-function list(obj: JsonObject, key: string): JsonValue[] {
+/**
+ * An array field, with the ceiling the caller had to choose. `max` is required rather than
+ * defaulted: a new list field on a new frame is a new thing an authenticated socket can make
+ * arbitrarily large, and a default would let one ship without anyone deciding its size.
+ */
+function list(obj: JsonObject, key: string, max: number, label = key): JsonValue[] {
   const value = obj[key];
   if (value === undefined || value === null) return [];
-  if (!Array.isArray(value)) throw fail(`field "${key}" must be an array`);
+  if (!Array.isArray(value)) throw fail(`field "${label}" must be an array`);
+  if (value.length > max) {
+    throw fail(`field "${label}" carries ${value.length} entries, over the limit of ${max}`);
+  }
+  return value;
+}
+
+/**
+ * A client-supplied value, walked ITERATIVELY to its limits. Iteratively because the thing being
+ * refused is a stack overflow: `qidOf` -> `canonicalJson` recurses over exactly this value, so a
+ * depth check that recursed would be the same crash one frame earlier.
+ */
+function bounded(value: JsonValue, label: string): JsonValue {
+  const stack: { node: JsonValue; depth: number }[] = [{ node: value, depth: 1 }];
+  let seen = 0;
+  while (stack.length > 0) {
+    // `pop` cannot answer undefined here — the loop guard is the length — and the check is what
+    // makes that readable to the compiler without a cast.
+    const next = stack.pop();
+    if (next === undefined) break;
+    seen += 1;
+    if (seen > FRAME_LIMITS.inputNodes) {
+      throw fail(`field "${label}" holds more than ${FRAME_LIMITS.inputNodes} values`);
+    }
+    if (next.depth > FRAME_LIMITS.inputDepth) {
+      throw fail(`field "${label}" is nested deeper than ${FRAME_LIMITS.inputDepth}`);
+    }
+    if (next.node === null || typeof next.node !== 'object') continue;
+    const children = Array.isArray(next.node) ? next.node : Object.values(next.node);
+    for (const child of children) stack.push({ node: child, depth: next.depth + 1 });
+  }
   return value;
 }
 
@@ -320,7 +411,7 @@ function cursor(value: unknown): LiveCursor {
     qid: str(value, 'qid'),
     lsn: str(value, 'lsn'),
     digest: str(value, 'digest'),
-    ids: list(value, 'ids').map((id) => {
+    ids: list(value, 'ids', FRAME_LIMITS.cursorIds, 'cursor.ids').map((id) => {
       if (typeof id !== 'string') throw fail('cursor.ids must be strings');
       return id;
     }),
@@ -357,7 +448,7 @@ function target(value: unknown): SubscribeTarget {
   return {
     kind,
     qid: str(value, 'qid'),
-    input: value['input'] ?? null,
+    input: bounded(value['input'] ?? null, 'input'),
     cursor:
       value['cursor'] === null || value['cursor'] === undefined ? null : cursor(value['cursor']),
   };

package/src/sync-upgrade.ts

@@ -0,0 +1,124 @@
+// The node's HTTP surface: health, readiness, load shedding and the authenticated upgrade. Split
+// from `sync-node.ts` because deciding whether a request becomes a websocket is a different job
+// from what the socket then does — the same line `sync-frames.ts` and `sync-listen.ts` already draw.
+
+import { healthzPayload, readyzPayload, reportError } from '@ultimat3/core';
+import { SocketAuthUnavailableError, SocketUnauthenticatedError } from './errors';
+import type { SyncAuthenticator, SyncGrant } from './sync-auth';
+import { toWireError } from './sync-protocol';
+import type { AcceptBudget, Rng } from './thundering-herd';
+
+/**
+ * What the upgrade hands the socket. It carries no actor: the grant does, and one identity written
+ * in two places is two that disagree the moment a re-auth renews one of them.
+ */
+export interface WsData {
+  readonly socketId: string;
+  readonly clientBuildId: string;
+}
+
+/** Structural view of `Bun.serve`'s server object; keeps this module free of a Bun import. */
+export interface UpgradeTarget {
+  upgrade(request: Request, options: { data: WsData }): boolean;
+}
+
+/**
+ * Everything the decision reads, supplied by the node. `ready` and `socketCount` are functions
+ * rather than values because both move while a request is parked inside `authenticate` — reading
+ * them once at the top is exactly the staleness this file exists to refuse.
+ */
+export interface UpgradeDeps {
+  readonly path: string;
+  readonly buildId: string;
+  readonly maxConnections: number;
+  readonly accept: AcceptBudget;
+  readonly rng: Rng;
+  ready(): boolean;
+  socketCount(): number;
+  newSocketId(): string;
+  readonly authenticate?: SyncAuthenticator | undefined;
+  /** Recorded only after the upgrade took: a grant for a socket that never opened is never closed. */
+  onGranted(socketId: string, grant: SyncGrant): void;
+}
+
+/**
+ * `undefined` means the upgrade took and Bun owns the connection now. Async because `authenticate`
+ * is: the credential is decided *before* `server.upgrade`, so a refused one never costs a websocket.
+ */
+export async function handleUpgrade(
+  deps: UpgradeDeps,
+  request: Request,
+  server: UpgradeTarget,
+): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  // Health is the process's, readiness is this node's: a draining node stays healthy while it hands
+  // its sockets to the rest of the fleet.
+  if (url.pathname === '/healthz') return json(healthzPayload());
+  if (url.pathname === '/readyz') {
+    const payload = readyzPayload();
+    return deps.ready() ? json(payload) : json({ status: 503, body: payload.body });
+  }
+  if (url.pathname !== deps.path) return new Response('not found', { status: 404 });
+  // The count, not the rate. Shed the same way and with the same delay attached: a client refused
+  // for a full node and one refused for a fast one have the same next move, and the refusal is
+  // decided before `authenticate` so a full node costs no token service call.
+  if (deps.socketCount() >= deps.maxConnections || !deps.ready() || !deps.accept.tryAccept()) {
+    return shed(deps);
+  }
+  let grant: SyncGrant | null = null;
+  if (deps.authenticate) {
+    try {
+      grant = await deps.authenticate(request);
+    } catch (error) {
+      // A failure is not a denial. The token service timing out must not read to a client as "you
+      // may not connect" — it is told to come back, and this node is the one that pages.
+      reportError(error, { source: 'realtime', scope: { operation: 'sync.authenticate' } });
+      return wireErrorResponse(
+        503,
+        new SocketAuthUnavailableError({ detail: 'see the node log for the cause' }),
+      );
+    }
+    // The decision, made before a socket exists: an upgrade is the cheapest thing to refuse and the
+    // most expensive thing to take back.
+    if (grant === null) {
+      return wireErrorResponse(
+        401,
+        new SocketUnauthenticatedError({ reason: 'authenticate() resolved no actor' }),
+      );
+    }
+  }
+  // Asked again, because `authenticate` is app code and awaiting it is awaiting a token service: a
+  // request that passed the check above can be parked there when SIGTERM lands, and the `accept`
+  // phase is over by the time it gets here. Upgrading then is the one socket that phase exists to
+  // refuse — the load balancer has already been told this node is out, so nothing takes it over. No
+  // second `tryAccept()`: that budget was spent above.
+  if (!deps.ready()) return shed(deps);
+  const data: WsData = {
+    socketId: deps.newSocketId(),
+    clientBuildId: url.searchParams.get('build') ?? deps.buildId,
+  };
+  if (!server.upgrade(request, { data })) {
+    return new Response('expected websocket', { status: 426 });
+  }
+  if (grant) deps.onGranted(data.socketId, grant);
+  return undefined;
+}
+
+/** Load shedding with a delay attached: refusing without one just moves the herd next door. */
+function shed(deps: UpgradeDeps): Response {
+  return new Response('retry', {
+    status: 503,
+    headers: { 'retry-after-ms': String(deps.accept.retryAfterMs(deps.rng)) },
+  });
+}
+
+function wireErrorResponse(status: number, error: unknown): Response {
+  return json({ status, body: { error: toWireError(error) } });
+}
+
+function json(payload: { status: number; body: unknown }): Response {
+  return new Response(JSON.stringify(payload.body), {
+    status: payload.status,
+    headers: { 'content-type': 'application/json' },
+  });
+}

package/src/thundering-herd.ts

@@ -49,6 +49,22 @@ export function backoffDelay(
   }
 }
 
+/**
+ * The timer half of mechanism 2. Returns its own canceller rather than a handle, so nothing has to
+ * name a type that differs between Bun, the browser and `node:timers`. Injected because a reconnect
+ * only provable by sleeping is a reconnect no test proves — and an unproven one silently did not
+ * fire at all until `As of 2026-08`.
+ */
+export type Scheduler = (fn: () => void, ms: number) => () => void;
+
+/** The production scheduler: the one `setTimeout` on the client's reconnect path. */
+export const timeoutScheduler: Scheduler = (fn, ms) => {
+  const handle = setTimeout(fn, ms);
+  return () => {
+    clearTimeout(handle);
+  };
+};
+
 export type ReconnectReason = 'drain' | 'overload' | 'rebalance';
 
 export interface DrainPlanEntry {
@@ -131,6 +147,11 @@ export class AcceptBudget {
     return Math.floor(this.#tokens);
   }
 
+  /** The sustained rate this bucket was built with — what a refusal has to name to be actionable. */
+  get perSecond(): number {
+    return this.#perSecond;
+  }
+
   #refill(): void {
     const now = this.#clock.monotonic();
     const elapsed = now - this.#lastRefill;

package/src/transport-env.ts

@@ -7,8 +7,8 @@
 import type { Clock } from '@ultimat3/core';
 import type { Transport } from './fanout';
 import { InProcessTransport } from './fanout';
+import type { NatsConnect } from './nats-client';
 import { assertBucket } from './nats-jetstream';
-import type { NatsStream, NatsTarget } from './nats-socket';
 import { NatsTransport } from './nats-transport';
 
 /** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
@@ -51,7 +51,7 @@ export interface SelectTransportOptions {
   readonly presenceTtlMs?: number | undefined;
   readonly clock?: Clock | undefined;
   /** Injected so a boot — reconnect included — can be proven with no network. */
-  readonly open?: ((target: NatsTarget) => Promise<NatsStream>) | undefined;
+  readonly connect?: NatsConnect | undefined;
 }
 
 const nonEmpty = (value: string | undefined): string | undefined =>
@@ -91,7 +91,7 @@ export function selectTransport(
     bucket,
     presenceTtlMs,
     ...(options.clock === undefined ? {} : { clock: options.clock }),
-    ...(options.open === undefined ? {} : { open: options.open }),
+    ...(options.connect === undefined ? {} : { connect: options.connect }),
   });
   return {
     transport,

package/src/type-pins.ts

@@ -0,0 +1,72 @@
+// Compile-time pins for the typed query hook. Source, not a `.test.ts`, on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level assertion written there can never fail. This module emits nothing and exports
+// nothing anybody imports — a regression is a build error, the only enforcement that counts
+// (axiom 3). What it protects is the whole reason `liveHookFor` exists: `useLiveFeed({ orgId })`
+// carrying the query's own input and row types. Lose that and the hook still runs — it just
+// stops catching the typo that makes a subscription match nothing.
+
+import type { Query } from '@ultimat3/query';
+import type { LiveHandle, Unsubscribe } from './client';
+import type { LiveRows } from './hooks';
+import type { LiveQueryHook, LiveQuerySource } from './query-hook';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/** The input type a `Query` accepts, read off its call signature rather than its schema. */
+type InputOf<Q> = Q extends (input: infer I, options?: never) => unknown ? I : never;
+
+interface FeedInput {
+  readonly orgId: string;
+}
+
+interface FeedRow {
+  readonly id: string;
+  readonly title: string;
+}
+
+type FeedHook = LiveQueryHook<FeedInput, FeedRow>;
+
+/** The hook takes the query's own input, as a value or as the thunk `useLive` reads once. */
+export type _HookInputIsTheQueryInput = Assert<
+  Equals<Parameters<FeedHook>[0], FeedInput | (() => FeedInput)>
+>;
+
+/** …and answers in the query's own row type, not the wire's `Row`. */
+export type _HookRowsAreTheQueryRows = Assert<
+  Equals<ReturnType<ReturnType<FeedHook>>, readonly FeedRow[]>
+>;
+
+/**
+ * A wrong key is refused. Written as a negative because that is the failure being pinned: a hook
+ * whose input widened to `JsonValue` would still compile everywhere and silently accept `orgIdd`.
+ */
+export type _WrongInputKeyIsRefused = Assert<
+  [{ readonly orgIdd: string }] extends [Parameters<FeedHook>[0]] ? false : true
+>;
+
+/**
+ * The seam itself: a declared `@ultimat3/query` `Query` assigns to the structural shape
+ * `liveHookFor` binds. Named structurally rather than imported as a value, so this stays the one
+ * place a change to `Query` — losing `isLive`, ceasing to be callable — fails, instead of every
+ * component call site in every app.
+ */
+export type _DeclaredQueryBindsToTheHook = Assert<
+  [Query] extends [LiveQuerySource<InputOf<Query>, Record<string, unknown>>] ? true : false
+>;
+
+/**
+ * The handle `LiveClient.useLive()` returns must stay `Disposable`, or `using sub =
+ * client.useLive(...)` silently degrades to "never unsubscribes" the moment someone drops the
+ * `[Symbol.dispose]` member while refactoring `unsubscribe`.
+ */
+export type _LiveHandleIsDisposable = Assert<[LiveHandle] extends [Disposable] ? true : false>;
+
+/** Same pin, one layer up: the hook's callable result set must stay `Disposable` too. */
+export type _LiveRowsIsDisposable = Assert<[LiveRows] extends [Disposable] ? true : false>;
+
+/** `channel.subscribe()`'s return must stay both callable and `Disposable`. */
+export type _UnsubscribeIsDisposable = Assert<[Unsubscribe] extends [Disposable] ? true : false>;

package/src/window-lock.ts

@@ -0,0 +1,21 @@
+// One serial lane per live query id, over that query's shared window.
+//
+// The window is a read-modify-write across awaits — match, apply, append, then one policy pass per
+// subscriber — and nothing upstream orders the callers: `sync` fires `void registry.deliver(change)`
+// straight off the bus. Two of those interleaving is one subscriber shown lsn 2 before lsn 1, its
+// cursor then rewound to 1, and a gate deciding about a row against a window that has moved past it.
+
+/** FIFO, one task at a time. A task that rejects hands its rejection to its own caller and no one else. */
+export class WindowLock {
+  #tail: Promise<unknown> = Promise.resolve();
+
+  run<T>(work: () => Promise<T>): Promise<T> {
+    const result = this.#tail.then(work);
+    // The lane chains on a settled shadow, never on `result`: one delivery that threw must not
+    // reject every delivery queued behind it, and an unwatched shadow must not look unhandled.
+    this.#tail = result.then(ignore, ignore);
+    return result;
+  }
+}
+
+const ignore = (): void => undefined;

package/src/nats-commands.ts

@@ -1,97 +0,0 @@
-// Single responsibility: the client half of the NATS protocol — the commands a client writes.
-// Split from the parser on purpose: encoding is pure string building with no state at all, while
-// decoding has to carry a buffer across chunk boundaries, and mixing the two hides both.
-
-import { TransportProtocolError } from './errors';
-import { concatBytes, type NatsHeaders } from './nats-protocol';
-
-const encoder = new TextEncoder();
-const CRLF = '\r\n';
-
-export interface NatsConnectOptions {
-  readonly verbose?: boolean; // default false
-  readonly pedantic?: boolean; // default false
-  readonly name?: string; // client name, default 'ultimate'
-  readonly user?: string | undefined;
-  readonly pass?: string | undefined;
-  readonly authToken?: string | undefined;
-  readonly tlsRequired?: boolean; // default false
-}
-const CLIENT_VERSION = '0.0.1';
-
-/** `CONNECT {json}\r\n` — the first frame a client sends, before subscribing or publishing. */
-export function connectMessage(options: NatsConnectOptions = {}): Uint8Array {
-  const payload: Record<string, unknown> = {
-    verbose: options.verbose ?? false,
-    pedantic: options.pedantic ?? false,
-    tls_required: options.tlsRequired ?? false,
-    name: options.name ?? 'ultimate',
-    lang: 'bun',
-    version: CLIENT_VERSION,
-    protocol: 1,
-    headers: true,
-    no_responders: true,
-  };
-  if (options.user !== undefined && options.pass !== undefined) {
-    payload['user'] = options.user;
-    payload['pass'] = options.pass;
-  }
-  if (options.authToken !== undefined) payload['auth_token'] = options.authToken;
-  return encoder.encode(`CONNECT ${JSON.stringify(payload)}${CRLF}`);
-}
-
-/**
- * A header line ends at the first CRLF, so a break inside a key or value closes the line early and
- * everything after it is read as a fresh command. A security boundary, not a style rule.
- */
-const HEADER_BREAK = /[\r\n]/;
-
-const encodeHeaderBlock = (headers: NatsHeaders): Uint8Array => {
-  let block = `NATS/1.0${CRLF}`;
-  for (const [key, value] of headers) {
-    if (HEADER_BREAK.test(key) || HEADER_BREAK.test(value)) {
-      throw new TransportProtocolError({
-        transport: 'nats',
-        stage: 'headers',
-        // Quoted through JSON so the break that caused this cannot break the message reporting it.
-        detail: `header ${JSON.stringify(key)} carries a CR or LF, which would inject a command`,
-        fix: "strip the breaks first: headers.set(name, value.replace(/[\\r\\n]+/g, ' '))",
-      });
-    }
-    block += `${key}: ${value}${CRLF}`;
-  }
-  return encoder.encode(`${block}${CRLF}`);
-};
-
-/** `PUB` when there are no headers, `HPUB` when there are — never both shapes for one call. */
-export function pubMessage(args: {
-  readonly subject: string;
-  readonly payload?: Uint8Array | undefined;
-  readonly replyTo?: string | undefined;
-  readonly headers?: NatsHeaders | undefined;
-}): Uint8Array {
-  const payload = args.payload ?? new Uint8Array(0);
-  const replyPart = args.replyTo !== undefined ? ` ${args.replyTo}` : '';
-  const crlfBytes = encoder.encode(CRLF);
-  if (args.headers === undefined || args.headers.size === 0) {
-    const control = `PUB ${args.subject}${replyPart} ${payload.length}${CRLF}`;
-    return concatBytes(encoder.encode(control), payload, crlfBytes);
-  }
-  const headerBlock = encodeHeaderBlock(args.headers);
-  const total = headerBlock.length + payload.length;
-  const control = `HPUB ${args.subject}${replyPart} ${headerBlock.length} ${total}${CRLF}`;
-  return concatBytes(encoder.encode(control), headerBlock, payload, crlfBytes);
-}
-
-export function subMessage(subject: string, sid: string, queue?: string): Uint8Array {
-  const queuePart = queue !== undefined ? ` ${queue}` : '';
-  return encoder.encode(`SUB ${subject}${queuePart} ${sid}${CRLF}`);
-}
-
-export function unsubMessage(sid: string, max?: number): Uint8Array {
-  const maxPart = max !== undefined ? ` ${max}` : '';
-  return encoder.encode(`UNSUB ${sid}${maxPart}${CRLF}`);
-}
-
-export const PING_MESSAGE: Uint8Array = encoder.encode(`PING${CRLF}`);
-export const PONG_MESSAGE: Uint8Array = encoder.encode(`PONG${CRLF}`);