@ultimat3/realtime 1.0.0

package/src/cursor.ts

@@ -0,0 +1,188 @@
+// Reconnect. The highest-risk surface in the framework: a deploy drops N sockets at once and
+// every one of them asks "what changed since X?". The cursor exists to make that answer cheap,
+// and the budget exists to make the expensive answer (a snapshot) the *chosen* one, not the
+// accidental one. See README "Reconnect is the hard part".
+
+import { type Clock, systemClock } from '@ultimat3/core';
+import { CursorStaleError } from './errors';
+import { canonicalJson, fnv1a, type Row, type RowPatch } from './json';
+
+/** Ids are bounded so a cursor stays small enough to ship in a `hello` frame. */
+export const CURSOR_ID_LIMIT = 512;
+
+/** A digest of `''` means "not verified at this lsn" — set on every delta resume. */
+export const DIGEST_UNVERIFIED = '';
+
+export interface LiveCursor {
+  readonly qid: string;
+  /** Last lsn the subscriber has applied. Lexicographically comparable (see `formatLsn`). */
+  readonly lsn: string;
+  /** Result-set digest at the last snapshot, or `DIGEST_UNVERIFIED` after a delta resume. */
+  readonly digest: string;
+  /** Last-seen row ids, truncated at `CURSOR_ID_LIMIT`. */
+  readonly ids: readonly string[];
+  /** Number of rows in the result set — survives id truncation. */
+  readonly count: number;
+  readonly at: number;
+}
+
+export interface ReconnectBudget {
+  /** Hard ceiling on replayed patches, independent of the cost model. */
+  readonly maxPatches: number;
+  /** A cursor older than this is presumed to have drifted; re-snapshot instead of trusting it. */
+  readonly maxLagMs: number;
+  /** Cost of one snapshot, expressed in replayed-patch equivalents. This is the crossover point. */
+  readonly snapshotCost: number;
+  readonly patchCost: number;
+}
+
+/**
+ * 250 patch-equivalents per snapshot is the measured-intent default: a bounded `orderBy + limit`
+ * snapshot is one indexed query, a patch is one buffer read plus one frame. Replaying more than
+ * ~250 patches costs more wall-clock *and* more client work than starting over.
+ */
+export const defaultReconnectBudget: ReconnectBudget = {
+  maxPatches: 500,
+  maxLagMs: 5 * 60_000,
+  snapshotCost: 250,
+  patchCost: 1,
+};
+
+export type ResumeReason =
+  | 'in-window'
+  | 'unknown-query'
+  | 'out-of-window'
+  | 'lag-exceeded'
+  | 'budget-exceeded'
+  | 'digest-unverified';
+
+export interface ResumeDecision {
+  readonly resnapshot: boolean;
+  readonly reason: ResumeReason;
+  /** Replay cost in patch-equivalents, for logs and the reconnect benchmark. */
+  readonly cost: number;
+}
+
+/** Retained-change source behind a resume. Implemented by `RingChangeBuffer` in the replicator. */
+export interface ResumeSource {
+  append(qid: string, patch: RowPatch): void;
+  /** Patches strictly after `lsn`, or `null` when the gap is not covered by the retained window. */
+  since(qid: string, lsn: string): RowPatch[] | null;
+  headLsn(qid: string): string | null;
+}
+
+export type ResumeResult<R extends Row = Row> =
+  | { readonly kind: 'delta'; readonly patches: readonly RowPatch[]; readonly cursor: LiveCursor }
+  | { readonly kind: 'snapshot'; readonly rows: readonly R[]; readonly cursor: LiveCursor };
+
+export interface ResumeDeps<R extends Row = Row> {
+  readonly source: ResumeSource;
+  /** Bounded re-read of the query at a current lsn. Omit only if a stale cursor should throw. */
+  readonly snapshot?: (qid: string) => Promise<{ rows: readonly R[]; lsn: string }>;
+  readonly budget?: ReconnectBudget;
+  readonly clock?: Clock;
+}
+
+export function makeCursor(
+  qid: string,
+  lsn: string,
+  rows: readonly Row[],
+  now: number,
+): LiveCursor {
+  return {
+    qid,
+    lsn,
+    digest: digestOf(rows),
+    ids: rows.slice(0, CURSOR_ID_LIMIT).map((r) => r.id),
+    count: rows.length,
+    at: now,
+  };
+}
+
+/** FNV-1a over `id:row` pairs in result order — order-sensitive, so a re-sort is detected. */
+export function digestOf(rows: readonly Row[]): string {
+  return fnv1a(rows.map((row) => `${row.id}:${canonicalJson(row)}`).join(';'));
+}
+
+/** Client-side drift check: a mismatch after delta resumes is a request for a fresh snapshot. */
+export function verifyDigest(cursor: LiveCursor, rows: readonly Row[]): boolean {
+  if (cursor.digest === DIGEST_UNVERIFIED) return false;
+  return cursor.digest === digestOf(rows);
+}
+
+export function shouldResnapshot(
+  cursor: LiveCursor,
+  available: readonly RowPatch[] | null,
+  now: number,
+  budget: ReconnectBudget = defaultReconnectBudget,
+): ResumeDecision {
+  if (available === null) {
+    return { resnapshot: true, reason: 'out-of-window', cost: budget.snapshotCost };
+  }
+  if (now - cursor.at > budget.maxLagMs) {
+    return { resnapshot: true, reason: 'lag-exceeded', cost: budget.snapshotCost };
+  }
+  const cost = available.length * budget.patchCost;
+  if (available.length > budget.maxPatches || cost > budget.snapshotCost) {
+    return { resnapshot: true, reason: 'budget-exceeded', cost };
+  }
+  return { resnapshot: false, reason: 'in-window', cost };
+}
+
+/**
+ * The reconnect entry point. Cheap path = replay the retained window. Fallback = one bounded
+ * snapshot. There is deliberately no third path: WAL history traversal is what turns a rolling
+ * restart into a self-inflicted outage.
+ */
+export async function resumeFrom<R extends Row = Row>(
+  cursor: LiveCursor,
+  deps: ResumeDeps<R>,
+): Promise<ResumeResult<R>> {
+  const clock = deps.clock ?? systemClock;
+  const budget = deps.budget ?? defaultReconnectBudget;
+  const now = clock.now().getTime();
+  const available = deps.source.since(cursor.qid, cursor.lsn);
+  const decision = shouldResnapshot(cursor, available, now, budget);
+
+  if (!decision.resnapshot && available !== null) {
+    const head = deps.source.headLsn(cursor.qid) ?? cursor.lsn;
+    return { kind: 'delta', patches: available, cursor: advance(cursor, available, head, now) };
+  }
+
+  if (!deps.snapshot) {
+    throw new CursorStaleError({ qid: cursor.qid, lsn: cursor.lsn, reason: decision.reason });
+  }
+  const fresh = await deps.snapshot(cursor.qid);
+  return {
+    kind: 'snapshot',
+    rows: fresh.rows,
+    cursor: makeCursor(cursor.qid, fresh.lsn, fresh.rows, now),
+  };
+}
+
+/** Advance a cursor across a delta without re-reading rows: ids are patchable, the digest is not. */
+export function advance(
+  cursor: LiveCursor,
+  patches: readonly RowPatch[],
+  lsn: string,
+  now: number,
+): LiveCursor {
+  const ids = new Set(cursor.ids);
+  let count = cursor.count;
+  for (const patch of patches) {
+    if (patch.op === 'delete') {
+      if (ids.delete(patch.id)) count -= 1;
+    } else if (patch.op === 'insert' && !ids.has(patch.id)) {
+      ids.add(patch.id);
+      count += 1;
+    }
+  }
+  return {
+    qid: cursor.qid,
+    lsn,
+    digest: DIGEST_UNVERIFIED,
+    ids: [...ids].slice(0, CURSOR_ID_LIMIT),
+    count,
+    at: now,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,253 @@
+// Realtime's X_* codes. Every throw in this package goes through one of these classes so
+// the same string renders in the terminal, the browser overlay, and `--json`.
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const REALTIME_OWNED_ERROR_CODES = [
+  'X_TOPIC_FORBIDDEN',
+  'X_SUBSCRIPTION_LIMIT',
+  'X_PROTOCOL_VERSION',
+  'X_CURSOR_STALE',
+  'X_REBASE_CONFLICT',
+  'X_TRANSPORT_UNAVAILABLE',
+  'X_TRANSPORT_PROTOCOL',
+  'X_REPLICATION_PROTOCOL',
+  'X_REPLICATION_FAILED',
+  'X_REPLICATOR_SLOT_HELD',
+  'X_LIVE_CLIENT_MISSING',
+  'X_LIVE_ROW_UNIDENTIFIED',
+] as const;
+
+/**
+ * `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.
+ */
+export const REALTIME_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
+
+/** Every code realtime can throw through `RealtimeError`: the ones it owns plus the borrowed one. */
+export const REALTIME_ERROR_CODES = [
+  ...REALTIME_OWNED_ERROR_CODES,
+  ...REALTIME_BORROWED_ERROR_CODES,
+] as const;
+
+export type RealtimeOwnedErrorCode = (typeof REALTIME_OWNED_ERROR_CODES)[number];
+export type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[number];
+
+export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, string>> = {
+  X_TOPIC_FORBIDDEN: 'the actor may not subscribe to this topic',
+  X_SUBSCRIPTION_LIMIT: 'socket or tenant hit its subscription cap',
+  X_PROTOCOL_VERSION: 'client and sync node disagree on the wire protocol',
+  X_CURSOR_STALE: 'the resume LSN is outside the change buffer',
+  X_REBASE_CONFLICT: 'a local mutation could not be rebased',
+  X_TRANSPORT_UNAVAILABLE: 'the fanout bus is unreachable',
+  X_TRANSPORT_PROTOCOL: 'the bus does not speak the protocol this build speaks',
+  X_REPLICATION_PROTOCOL: 'the WAL stream cannot be decoded',
+  X_REPLICATION_FAILED: 'the replication connection was refused',
+  X_REPLICATOR_SLOT_HELD: 'another replicator already owns this database',
+  X_LIVE_CLIENT_MISSING: 'a realtime hook ran with no LiveClient registered',
+  X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
+};
+
+// One unconditional call, so a second package claiming one of realtime's codes throws
+// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(REALTIME_ERROR_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);
+
+const DOCS_BASE = 'https://ultimate.dev/errors/';
+
+/** Base for every realtime error: fills `docs` from the code so no call site can forget it. */
+export class RealtimeError extends UltimateError {
+  constructor(opts: { code: RealtimeErrorCode; cause: string; fix: string }) {
+    super({
+      code: opts.code,
+      cause: opts.cause,
+      fix: opts.fix,
+      docs: `${DOCS_BASE}${opts.code}`,
+    });
+  }
+}
+
+/** Subscribe (or an actor change) denied by the topic's policy. Never leaks the topic's data. */
+export class TopicForbiddenError extends RealtimeError {
+  constructor(args: { topic: string; actorId: string | null; reason: string }) {
+    super({
+      code: 'X_TOPIC_FORBIDDEN',
+      cause: `actor ${args.actorId ?? '<anonymous>'} may not subscribe to "${args.topic}": ${args.reason}`,
+      fix: `declare a guard for this topic: hub.guard('${args.topic}', ({ actor }) => ...)`,
+    });
+  }
+}
+
+/** Load shedding, not a crash: a socket or tenant asked for more subscriptions than the cap. */
+export class SubscriptionLimitError extends RealtimeError {
+  constructor(args: { scope: 'socket' | 'tenant'; id: string; limit: number }) {
+    super({
+      code: 'X_SUBSCRIPTION_LIMIT',
+      cause: `${args.scope} ${args.id} reached the subscription cap of ${args.limit}`,
+      fix: `raise realtime.limits.${args.scope === 'socket' ? 'perSocket' : 'perTenant'} in app.config.ts, or unsubscribe unused live queries`,
+    });
+  }
+}
+
+/**
+ * Client and server disagree on the wire format — a version mismatch or a malformed frame.
+ * Both are the same class of bug (a peer speaking a shape we do not have), so both get one code.
+ */
+export class ProtocolVersionError extends RealtimeError {
+  constructor(args: { got: unknown; expected: number; detail?: string }) {
+    super({
+      code: 'X_PROTOCOL_VERSION',
+      cause:
+        args.detail ??
+        `frame protocol version ${String(args.got)} is not the server version ${args.expected}`,
+      fix: 'x build && redeploy the client; the sync node sends `update-available` before it drains',
+    });
+  }
+}
+
+/** A resume cursor cannot be honoured and no snapshot path was supplied. */
+export class CursorStaleError extends RealtimeError {
+  constructor(args: { qid: string; lsn: string; reason: string }) {
+    super({
+      code: 'X_CURSOR_STALE',
+      cause: `cursor for query ${args.qid} at lsn ${args.lsn} cannot be resumed: ${args.reason}`,
+      fix: 'pass `snapshot` to resumeFrom() so the fallback path can re-snapshot instead of failing',
+    });
+  }
+}
+
+/** A rebase could not be resolved: `custom(merge)` returned nothing, or the base row vanished. */
+export class RebaseConflictError extends RealtimeError {
+  constructor(args: { key: string; entity: string; reason: string }) {
+    super({
+      code: 'X_REBASE_CONFLICT',
+      cause: `mutation ${args.key} on ${args.entity} could not be rebased: ${args.reason}`,
+      fix: "set conflict: 'server-wins' on the mutator, or return a row from custom(merge)",
+    });
+  }
+}
+
+/** The fanout bus is down. `sync` nodes are stateless, so this is always recoverable. */
+export class TransportUnavailableError extends RealtimeError {
+  constructor(args: { transport: string; reason: string; fix?: string }) {
+    super({
+      code: 'X_TRANSPORT_UNAVAILABLE',
+      cause: `transport "${args.transport}" is unavailable: ${args.reason}`,
+      // Names the key `selectTransport` actually reads, and a command that actually exists.
+      fix: args.fix ?? 'x doctor — then check NATS_URL points at a reachable nats-server',
+    });
+  }
+}
+
+/**
+ * The bytes on the bus socket are not the protocol we speak: an unknown NATS verb, a header block
+ * that is not `NATS/1.0`, a JetStream reply in a shape the API never produces. Always a version or
+ * configuration mismatch rather than a transient fault, so reconnecting to the same server cannot
+ * help — which is exactly why it is a different code from `X_TRANSPORT_UNAVAILABLE`.
+ */
+export class TransportProtocolError extends RealtimeError {
+  constructor(args: { transport: string; stage: string; detail: string; fix?: string }) {
+    super({
+      code: 'X_TRANSPORT_PROTOCOL',
+      cause: `transport "${args.transport}" ${args.stage}: ${args.detail}`,
+      fix:
+        args.fix ??
+        'x doctor transport — the bus must be nats-server >= 2.11 with JetStream enabled (`nats-server -js`)',
+    });
+  }
+}
+
+/**
+ * The bytes on the replication socket are not the bytes the protocol allows: a truncated message,
+ * an unknown pgoutput tag, an auth method we do not speak. Always a version or configuration
+ * mismatch rather than a transient fault, so retrying the same connection cannot help.
+ */
+export class ReplicationProtocolError extends RealtimeError {
+  constructor(args: { stage: string; detail: string; fix?: string }) {
+    super({
+      code: 'X_REPLICATION_PROTOCOL',
+      cause: `postgres replication ${args.stage}: ${args.detail}`,
+      fix:
+        args.fix ??
+        'x doctor db — the server must be postgres >= 14 with a pgoutput publication and wal_level=logical',
+    });
+  }
+}
+
+/**
+ * The replication connection itself failed — refused credentials, a slot another process holds,
+ * an `ErrorResponse` from the server. The server's own message is passed through verbatim
+ * because it names the object that has to change.
+ */
+export class ReplicationFailedError extends RealtimeError {
+  constructor(args: { stage: string; detail: string; fix: string }) {
+    super({
+      code: 'X_REPLICATION_FAILED',
+      cause: `postgres replication ${args.stage} failed: ${args.detail}`,
+      fix: args.fix,
+    });
+  }
+}
+
+/**
+ * A second replicator found the advisory lock held. Distinct from `X_REPLICATION_FAILED` because
+ * nothing is wrong with this process: the database already has its one replicator, and a second
+ * one that started anyway would publish every change twice. Terminal for a container whose whole
+ * job is that role — the scheduler is the thing that has to change, not the connection.
+ */
+export class ReplicatorSlotHeldError extends RealtimeError {
+  constructor(args: { key: string; holder?: string | undefined }) {
+    super({
+      code: 'X_REPLICATOR_SLOT_HELD',
+      cause:
+        `advisory lock ${args.key} is held${args.holder === undefined ? '' : ` by ${args.holder}`}` +
+        ' — one database has exactly one replicator',
+      fix: 'scale the replicator to 1 per database: kubectl scale deploy/replicator --replicas=1',
+    });
+  }
+}
+
+/**
+ * A hook was called before the app entry registered its client. Never a transient fault: the
+ * registration is a single call in the entry, so the fix is the call itself rather than a retry.
+ */
+export class LiveClientMissingError extends RealtimeError {
+  constructor(args: { hook: string }) {
+    super({
+      code: 'X_LIVE_CLIENT_MISSING',
+      cause: `${args.hook}() ran before any LiveClient was registered`,
+      fix: 'setLiveClient(new LiveClient({ signal: createSignal, connect, buildId })) in the app entry, above the first render',
+    });
+  }
+}
+
+/**
+ * A subscribable read projected a row with no `id`. Patches, cursors and the local store all
+ * address a row by `id`, so such a row cannot be delivered — and delivering it anyway produces a
+ * subscription that looks correct until the first update nobody can apply.
+ */
+export class LiveRowUnidentifiedError extends RealtimeError {
+  constructor(args: { query: string; keys: readonly string[] }) {
+    super({
+      code: 'X_LIVE_ROW_UNIDENTIFIED',
+      cause: `live query "${args.query}" returned a row with no id (columns: ${args.keys.join(', ') || 'none'})`,
+      fix: `select the primary key in ${args.query}'s sql(), or drop live: true from it`,
+    });
+  }
+}
+
+/** 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 }) {
+    super({
+      code: 'X_NOT_IMPLEMENTED',
+      cause: `${args.what} is interface-complete but not implemented in this build`,
+      fix: args.fix,
+    });
+  }
+}

package/src/fanout.ts

@@ -0,0 +1,159 @@
+// Cross-node fanout. This interface is the reason `sync` nodes are stateless: every piece of state
+// that must survive one node's death (subscription routing, presence) lives behind `Transport`,
+// never in a node's heap. Subjects are NATS-shaped (`x.change.posts.org-1`) so the in-process
+// default and the real bus route identically.
+
+import { type Clock, systemClock } from '@ultimat3/core';
+import { TransportUnavailableError } from './errors';
+
+export type TransportHandler = (payload: string, subject: string) => void;
+
+export interface TransportSubscription {
+  readonly subject: string;
+  unsubscribe(): void;
+}
+
+export interface TransportSetEntry {
+  readonly member: string;
+  readonly value: string;
+  readonly expiresAt: number;
+}
+
+/**
+ * TTL'd keyed sets on the bus (NATS KV / Redis hashes). Presence uses this so a lost node loses
+ * nothing: members simply stop heartbeating and expire on their own.
+ */
+export interface TransportSet {
+  put(key: string, member: string, value: string, ttlMs: number): Promise<void>;
+  /** `false` when the member had already expired — the caller must re-`put` (that is a re-join). */
+  touch(key: string, member: string, ttlMs: number): Promise<boolean>;
+  drop(key: string, member: string): Promise<void>;
+  entries(key: string): Promise<readonly TransportSetEntry[]>;
+}
+
+export interface Transport {
+  readonly name: string;
+  publish(subject: string, payload: string): Promise<void>;
+  subscribe(subject: string, handler: TransportHandler): Promise<TransportSubscription>;
+  readonly shared: TransportSet;
+  close(): Promise<void>;
+}
+
+/** NATS subject semantics: `*` matches one token, `>` matches one-or-more trailing tokens. */
+export function subjectMatches(pattern: string, subject: string): boolean {
+  const p = pattern.split('.');
+  const s = subject.split('.');
+  for (let i = 0; i < p.length; i += 1) {
+    const token = p[i];
+    if (token === '>') return s.length > i;
+    if (i >= s.length) return false;
+    if (token !== '*' && token !== s[i]) return false;
+  }
+  return p.length === s.length;
+}
+
+export interface InProcessTransportOptions {
+  readonly clock?: Clock;
+  /** A failing subscriber must not break fanout for the others. */
+  readonly onError?: (error: unknown, subject: string) => void;
+}
+
+class InProcessSet implements TransportSet {
+  readonly #keys = new Map<string, Map<string, TransportSetEntry>>();
+  readonly #clock: Clock;
+
+  constructor(clock: Clock) {
+    this.#clock = clock;
+  }
+
+  async put(key: string, member: string, value: string, ttlMs: number): Promise<void> {
+    const bucket = this.#keys.get(key) ?? new Map<string, TransportSetEntry>();
+    bucket.set(member, { member, value, expiresAt: this.#clock.now().getTime() + ttlMs });
+    this.#keys.set(key, bucket);
+  }
+
+  async touch(key: string, member: string, ttlMs: number): Promise<boolean> {
+    const entry = this.#keys.get(key)?.get(member);
+    if (!entry || entry.expiresAt <= this.#clock.now().getTime()) return false;
+    await this.put(key, member, entry.value, ttlMs);
+    return true;
+  }
+
+  async drop(key: string, member: string): Promise<void> {
+    const bucket = this.#keys.get(key);
+    bucket?.delete(member);
+    if (bucket && bucket.size === 0) this.#keys.delete(key);
+  }
+
+  async entries(key: string): Promise<readonly TransportSetEntry[]> {
+    const bucket = this.#keys.get(key);
+    if (!bucket) return [];
+    const now = this.#clock.now().getTime();
+    const live: TransportSetEntry[] = [];
+    for (const entry of bucket.values()) {
+      if (entry.expiresAt > now) live.push(entry);
+      else bucket.delete(entry.member);
+    }
+    return live;
+  }
+}
+
+/** Single-node default: `x dev`, tests, and small deployments that have not earned a bus yet. */
+export class InProcessTransport implements Transport {
+  readonly name = 'in-process';
+  readonly shared: TransportSet;
+  readonly #handlers = new Map<string, Set<TransportHandler>>();
+  readonly #onError: (error: unknown, subject: string) => void;
+  #closed = false;
+
+  constructor(options: InProcessTransportOptions = {}) {
+    this.shared = new InProcessSet(options.clock ?? systemClock);
+    this.#onError = options.onError ?? (() => undefined);
+  }
+
+  async publish(subject: string, payload: string): Promise<void> {
+    this.#assertOpen();
+    for (const [pattern, handlers] of this.#handlers) {
+      if (!subjectMatches(pattern, subject)) continue;
+      for (const handler of handlers) {
+        try {
+          handler(payload, subject);
+        } catch (error) {
+          this.#onError(error, subject);
+        }
+      }
+    }
+  }
+
+  async subscribe(subject: string, handler: TransportHandler): Promise<TransportSubscription> {
+    this.#assertOpen();
+    const handlers = this.#handlers.get(subject) ?? new Set<TransportHandler>();
+    handlers.add(handler);
+    this.#handlers.set(subject, handlers);
+    return {
+      subject,
+      unsubscribe: () => {
+        handlers.delete(handler);
+        if (handlers.size === 0) this.#handlers.delete(subject);
+      },
+    };
+  }
+
+  async close(): Promise<void> {
+    this.#closed = true;
+    this.#handlers.clear();
+  }
+
+  get subjectCount(): number {
+    return this.#handlers.size;
+  }
+
+  #assertOpen(): void {
+    if (this.#closed) {
+      throw new TransportUnavailableError({ transport: this.name, reason: 'transport is closed' });
+    }
+  }
+}
+
+// The production bus lives in `nats-transport.ts`: it needs a socket, a codec and a JetStream
+// client, none of which belong in the file that defines what a transport *is*.