@ultimat3/realtime 27.6.0 → 27.7.0

package/CLAUDE.md

@@ -119,12 +119,13 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 ## The node, the bus and presence
 
 - `sync` is stateless: no sticky sessions, nothing on a socket survives a restart.
-- **`selectTransport(env, realtime)` is the one place `realtime.transport` + env become a bus** (KV
-  bucket and presence TTL come back with it). The config decides, the env supplies: `'nats'` refuses
-  (`X_CONFIG_INVALID`) when the `urlEnv` variable is unset; `'memory'` refuses a set one.
-- **`nats` is imported only by `nats-lib-client.ts`**; its reconnect re-subscribes. Only when it
-  GIVES UP (`onClosed`) does `NatsTransport` re-dial on backoff and re-bind kept subscriptions
-  (`nats-subscriptions.ts`); callers meanwhile are refused. KV semantics: `nats-jetstream`/`nats-kv`.
+- **`selectTransport(env, realtime, { use })` is the one place config + env become a bus** (bucket
+  and presence TTL come back). `'nats'` refuses (`X_CONFIG_INVALID`) an unset `urlEnv` variable;
+  `'memory'` a set one. `use`: `'sockets'`/`'feed'` await a 15 s dial, then
+  `X_TRANSPORT_UNAVAILABLE`; `'publish'` dials in background. Never `waitOnFirstConnect`
+  (retries forever). A publish with no live connection is refused.
+- **`nats` is imported only by `nats-lib-client.ts`**; its reconnect re-subscribes. When it GIVES
+  UP (`onClosed`) `NatsTransport` re-dials on backoff and re-binds.
 - **Nothing leaves `NatsTransport` uncoded** — `#translating` wraps `publish`/`subscribe` refusals
   as `X_TRANSPORT_UNAVAILABLE`. `#ensure` reuses a mid-reconnect client on purpose;
   `Transport.onReconnect(listener)` (required) announces each recovery.

package/README.md

@@ -800,7 +800,22 @@ principal.
   fanout across nodes. Until 22.0.0 `NATS_URL` alone decided and both keys were read by nothing.
   `presenceTtlMs` comes back with it because the bucket's whole-stream age limit was derived from
   it — a `PresenceRegistry` given a different number would report members leaving that never left.
-  Selection is pure; `connect()` is the dial, so an unreachable bus fails at boot.
+  Selection is pure; `connect()` is the dial. **What the process does with the bus decides whether
+  that dial is waited for** — `selectTransport(env, realtime, { use })`, `BusUse`:
+  `'sockets'` (a `sync` node; the default) awaits it and the presence bucket, retried on backoff for
+  `connectWithinMs` (default `BUS_CONNECT_WAIT_MS`, 15 s) and then `X_TRANSPORT_UNAVAILABLE`;
+  `'feed'` (the replicator) awaits it and asks JetStream for nothing; `'publish'` (`web`, `worker`,
+  `scheduler`) starts it in the background and resolves at once. `selection.state()` answers
+  `'up' | 'connecting'`.
+- **`NatsTransport` has two ways to open.** `connect({ withinMs, fix })` is for a node that cannot
+  work without the bus. `connectInBackground()` is for a process that only publishes: retried on the
+  transport's own backoff until it lands or `close()` runs, announced through `onReconnect`, and
+  until then every `publish`/`subscribe` rejects at once with `X_TRANSPORT_UNAVAILABLE` — never
+  parked, never queued. A publish made while the client is **reconnecting** is refused too: the
+  `nats` client would buffer it without bound and replay it late. `presenceBucket: 'first-use'`
+  asserts the KV bucket when `shared` is first read instead of at the dial, so a publisher needs no
+  JetStream. The first dial is ONE attempt of the library's — `waitOnFirstConnect` is not set,
+  because under it nats@2.29.3 retries a failed first dial forever and the promise never settles.
 - **`NatsTransport` runs on the official `nats` client** — `nats@2.29.3`, pinned exact, admitted at
   this transport seam and nowhere else
   ([`docs/idea/18-build-vs-wrap.md`](../../docs/idea/18-build-vs-wrap.md)). The package reaches it

package/package.json

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

package/src/nats-client.ts

@@ -71,6 +71,11 @@ export interface NatsClientOptions {
   /** Our jitter policy, asked once per attempt — the herd is ours to spread, not the library's. */
   readonly reconnectDelay?: (() => number) | undefined;
   readonly requestTimeoutMs?: number | undefined;
+  /**
+   * How long ONE dial may sit before it is an attempt that failed. The library's own default is
+   * 20 s, which a server that accepts the socket and says nothing spends in full.
+   */
+  readonly connectTimeoutMs?: number | undefined;
   /** A background failure: a dropped connection, a server error, an exhausted reconnect. */
   readonly onError?: ((error: unknown) => void) | undefined;
   /** The library re-established the connection. The cluster behind it may be a different one. */

package/src/nats-dial-wait.ts

@@ -0,0 +1,61 @@
+// Single responsibility: how long a dial is waited for — one attempt's connect timeout, and the
+// bounded wait a process that cannot work without the bus puts on the whole retry loop.
+
+import { finiteOption } from '@ultimat3/core';
+import { TransportUnavailableError } from './errors';
+
+/**
+ * One dial's connect timeout. Well under `BUS_CONNECT_WAIT_MS`: a black-holed server must fail
+ * several attempts inside a `sync` node's boot wait, so its refusal carries the attempt's own
+ * reason rather than an empty one, and a background dial keeps its backoff instead of the
+ * library's 20 s.
+ */
+export const DIAL_TIMEOUT_MS = 4_000;
+
+export interface NatsConnectWait {
+  /** Refuse with `X_TRANSPORT_UNAVAILABLE` once this long has passed without a connection. */
+  readonly withinMs?: number | undefined;
+  /** The `fix:` of that refusal — the caller knows which role is waiting and what it needs. */
+  readonly fix?: string | undefined;
+}
+
+export interface DialWait {
+  readonly transport: string;
+  /** `host:port`, never the url: the url carries the credential. */
+  readonly server: string;
+  readonly withinMs: number;
+  readonly fix: string | undefined;
+  /** The last attempt's own refusal, read when the wait runs out. */
+  readonly lastFailure: () => string | undefined;
+}
+
+/**
+ * `landing`, or a coded refusal once `withinMs` has passed. A real timer, never an injected clock:
+ * the wait bounds a container's boot, which the kubelet counts in real seconds. The loser is not
+ * cancelled — a dial cannot be — so the caller's `close()` is what ends it.
+ */
+export async function landWithin(
+  landing: Promise<void> | undefined,
+  wait: DialWait,
+): Promise<void> {
+  const withinMs = finiteOption('createNatsTransport', 'connect.withinMs', wait.withinMs);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      const failure = wait.lastFailure();
+      const last = failure === undefined ? '' : ` — last attempt: ${failure}`;
+      reject(
+        new TransportUnavailableError({
+          transport: wait.transport,
+          reason: `${wait.server} did not accept a connection within ${withinMs}ms${last}`,
+          ...(wait.fix === undefined ? {} : { fix: wait.fix }),
+        }),
+      );
+    }, withinMs);
+  });
+  try {
+    await Promise.race([landing, late]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/nats-lib-client.ts

@@ -92,7 +92,7 @@ class LibNatsClient implements NatsClient {
   }
 
   get connected(): boolean {
-    return this.#connected && !this.#connection.isClosed();
+    return this.#connected && !this.#connection.isClosed() && protocolUp(this.#connection);
   }
 
   publish(subject: string, payload: Uint8Array): void {
@@ -211,6 +211,29 @@ class LibNatsClient implements NatsClient {
   }
 }
 
+/**
+ * The library's own flag, read where it is set. `#connected` above follows the status ITERATOR,
+ * which delivers a disconnect a tick or more after the socket dropped; in between the library
+ * already knows (`protocol.connected` is cleared in the socket's close handler) and already
+ * buffers every publish. nats@2.29.3 has no option to forbid that buffer, so the flag is the only
+ * way to refuse a publish it would queue. It is not on the typed surface: a library that moves it
+ * answers `true` here and the status iterator is the reading again — the behaviour before this.
+ */
+const protocolUp = (connection: NatsConnection): boolean => {
+  const protocol: unknown = Reflect.get(connection, 'protocol');
+  if (typeof protocol !== 'object' || protocol === null) return true;
+  return Reflect.get(protocol, 'connected') !== false;
+};
+
+/**
+ * How often the client pings, and how many may go unanswered. The library's defaults are two
+ * minutes and two: a connection whose packets are silently dropped stays "connected" — and keeps
+ * buffering publishes — for up to six minutes. 10 s and two is noticed within half a minute, for
+ * one 6-byte frame every ten seconds on a connection that is otherwise idle.
+ */
+export const PING_INTERVAL_MS = 10_000;
+export const MAX_PINGS_OUT = 2;
+
 /** `QueuedIterator.stop()` is the library's, and missing from the `AsyncIterable` it is typed as. */
 const stopStream = (stream: unknown): void => {
   if (typeof stream !== 'object' || stream === null || !('stop' in stream)) return;
@@ -219,9 +242,14 @@ const stopStream = (stream: unknown): void => {
 };
 
 /**
- * The production `NatsConnect`. The first dial retries on the same budget as a later loss
- * (`waitOnFirstConnect`), so a `sync` container that raced the bus into readiness recovers on its
- * own — and a budget that runs out rejects here rather than leaving a half-live connection behind.
+ * The production `NatsConnect`: ONE first dial, refused at once when the server is not there.
+ *
+ * Deliberately not `waitOnFirstConnect`. Until 2026-10 it was set, on the reading that the first
+ * dial "retries on the same budget as a later loss" — it does not: in nats@2.29.3 a failed first
+ * dial under that option `continue`s past the attempt counter, so it retries FOREVER, and the
+ * promise this returns never settles while the server is down. Every role awaited it at boot, so
+ * a pod that restarted during a NATS outage hung before it bound a socket. The retry is the
+ * transport's (`NatsTransport.#redial`), on our backoff, where `close()` can end it.
  */
 export const openNatsClient = async (options: NatsClientOptions): Promise<NatsClient> => {
   const target = parseNatsUrl(options.url);
@@ -235,11 +263,17 @@ export const openNatsClient = async (options: NatsClientOptions): Promise<NatsCl
     options.maxReconnectAttempts === undefined
       ? undefined
       : finiteOption('the nats client', 'maxReconnectAttempts', options.maxReconnectAttempts);
+  const connectTimeoutMs =
+    options.connectTimeoutMs === undefined
+      ? undefined
+      : finiteOption('the nats client', 'connectTimeoutMs', options.connectTimeoutMs);
   try {
     const connection = await connect({
       servers: [`${target.host}:${target.port}`],
       name: options.name ?? 'ultimate',
-      waitOnFirstConnect: true,
+      pingInterval: PING_INTERVAL_MS,
+      maxPingOut: MAX_PINGS_OUT,
+      ...(connectTimeoutMs === undefined ? {} : { timeout: connectTimeoutMs }),
       ...(maxReconnectAttempts === undefined ? {} : { maxReconnectAttempts }),
       ...(options.reconnectDelay === undefined
         ? {}

package/src/nats-transport.ts

@@ -3,6 +3,11 @@
 // re-establishing subscriptions, which is what makes a `sync` node stateless. The one loss it does
 // not own is its own end: a client closed for good once its reconnect budget is spent is replaced
 // here, on our backoff, and every kept subscription is bound again on the new one.
+//
+// Two ways to open it, because two kinds of process hold one. A node that SERVES from the bus
+// awaits `connect()` and refuses to boot without it; a process that only PUBLISHES calls
+// `connectInBackground()` and boots regardless — its publishes are refused, typed and at once,
+// until the dial lands.
 
 import {
   type Clock,
@@ -16,6 +21,7 @@ import { TransportUnavailableError } from './errors';
 import type { Transport, TransportHandler, TransportSet, TransportSubscription } from './fanout';
 import type { NatsClient, NatsConnect } from './nats-client';
 import { parseNatsUrl } from './nats-client';
+import { DIAL_TIMEOUT_MS, landWithin, type NatsConnectWait } from './nats-dial-wait';
 import { ensureKvBucket } from './nats-jetstream';
 import { NatsKvSet } from './nats-kv';
 import { openNatsClient } from './nats-open';
@@ -39,6 +45,14 @@ export interface NatsTransportOptions {
   readonly rng?: Rng;
   /** Injected so the whole transport — reconnect included — runs in a test with no network. */
   readonly connect?: NatsConnect;
+  /**
+   * When the presence bucket is asserted. `'dial'` (the default) is a node that serves presence: no
+   * JetStream, no connection. `'first-use'` is a process that only publishes — it never reads
+   * `shared`, so a server without JetStream, or without the bucket, must not cost it the bus.
+   */
+  readonly presenceBucket?: 'dial' | 'first-use';
+  /** One dial's connect timeout. Default `DIAL_TIMEOUT_MS`. */
+  readonly dialTimeoutMs?: number;
 }
 
 const DEFAULT_ATTEMPTS = 10;
@@ -57,8 +71,17 @@ export class NatsTransport implements Transport {
   #dialing: Promise<NatsClient> | undefined;
   #retries = 0;
   #closed = false;
-  /** Set while a client the library gave up on is being replaced; the attempt in flight. */
+  /** False until the first dial lands: what a refusal says while a background dial is in flight. */
+  #everUp = false;
+  readonly #lazyBucket: boolean;
+  readonly #dialTimeoutMs: number;
+  /** Under `'first-use'`: the clients whose bucket has been asserted since they last connected. */
+  readonly #bucketed = new WeakSet<NatsClient>();
+  /** Set while no client is held and one is being dialled in the background; the attempt in flight. */
   #redialing: number | undefined;
+  #redialLoop: Promise<void> | undefined;
+  /** The last background dial's own refusal, for the cause of a `connect({ withinMs })` that gave up. */
+  #lastFailure: string | undefined;
   #wakeRedial: (() => void) | undefined;
   readonly #subscriptions = new NatsSubscriptions();
   readonly #reconnectListeners = new Set<() => void>();
@@ -76,16 +99,51 @@ export class NatsTransport implements Transport {
       options.maxReconnectAttempts ?? DEFAULT_ATTEMPTS,
     );
     this.#rng = options.rng ?? Math.random;
+    this.#dialTimeoutMs = finiteOption(
+      'createNatsTransport',
+      'dialTimeoutMs',
+      options.dialTimeoutMs ?? DIAL_TIMEOUT_MS,
+    );
+    this.#lazyBucket = options.presenceBucket === 'first-use';
     this.shared = new NatsKvSet({
-      client: () => this.#ensure(),
+      client: () => this.#presenceClient(),
       bucket: options.bucket,
       clock: options.clock ?? systemClock,
     });
   }
 
-  /** Fail fast at boot rather than on the first change: `/readyz` is meant to catch a dead bus. */
-  async connect(): Promise<void> {
-    await this.#ensure();
+  /**
+   * Fail fast at boot rather than on the first change: `/readyz` is meant to catch a dead bus.
+   * Bare, it is ONE dial. With `withinMs` the dial is retried on our backoff for that long — a
+   * node that raced the bus into readiness recovers on its own — and then refused, naming the
+   * server, the wait and the last attempt's own failure. The retry is not stopped by the refusal;
+   * `close()` stops it, and that is what a failed boot calls.
+   */
+  async connect(wait: NatsConnectWait = {}): Promise<void> {
+    if (wait.withinMs === undefined) {
+      await this.#ensure();
+      return;
+    }
+    const target = parseNatsUrl(this.#options.url);
+    await landWithin(this.#client === undefined ? this.#redial() : undefined, {
+      transport: this.name,
+      server: `${target.host}:${target.port}`,
+      withinMs: wait.withinMs,
+      fix: wait.fix,
+      lastFailure: () => this.#lastFailure,
+    });
+    // The loop also ends when the transport is closed under it.
+    if (this.#client === undefined) await this.#ensure();
+  }
+
+  /**
+   * Dial without being waited for: retried on our backoff until it lands or `close()` runs, and
+   * announced to the `onReconnect` listeners when it does. Until then every publish and subscribe
+   * is refused at once (`#ensure`) — never parked behind the dial, never queued.
+   */
+  connectInBackground(): void {
+    if (this.#closed || this.#client !== undefined) return;
+    void this.#redial();
   }
 
   get connected(): boolean {
@@ -94,6 +152,16 @@ export class NatsTransport implements Transport {
 
   async publish(subject: string, payload: string): Promise<void> {
     const client = await this.#ensure();
+    // The library BUFFERS a publish made while it reconnects, without bound, and replays the lot
+    // when the server is back: a queue nobody sized, delivering events whose only meaning was
+    // "re-read now" minutes late. A subscriber is told of the gap (`onReconnect`); the publisher
+    // is told here.
+    if (!client.connected) {
+      throw new TransportUnavailableError({
+        transport: this.name,
+        reason: `publish to ${subject} was refused: the client is reconnecting to the bus`,
+      });
+    }
     // `client.publish` is synchronous and refuses locally: a bad subject, a payload over the
     // server's `max_payload`, a connection torn down between the `#ensure` and this line. Those
     // are the LIBRARY's errors — or an app-supplied `connect`'s — so they arrive uncoded, and
@@ -167,7 +235,9 @@ export class NatsTransport implements Transport {
       return Promise.reject(
         new TransportUnavailableError({
           transport: this.name,
-          reason: `the connection closed once its reconnect budget was spent, and re-dial attempt ${this.#redialing} is in progress`,
+          reason: this.#everUp
+            ? `the connection closed once its reconnect budget was spent, and re-dial attempt ${this.#redialing} is in progress`
+            : `the bus has not connected yet, and dial attempt ${this.#redialing} is in progress`,
         }),
       );
     }
@@ -197,6 +267,7 @@ export class NatsTransport implements Transport {
       url: this.#options.url,
       name: 'ultimate',
       maxReconnectAttempts: this.#attempts,
+      connectTimeoutMs: this.#dialTimeoutMs,
       // The library retries; the spread is ours, so a cluster restart does not bring every node
       // back on the same millisecond.
       reconnectDelay: () => policyDelay(this.#backoff, ++this.#retries, this.#rng),
@@ -208,7 +279,7 @@ export class NatsTransport implements Transport {
       },
     });
     try {
-      await this.#ensureBucket(client);
+      if (!this.#lazyBucket) await this.#ensureBucket(client);
       if (closedEarly) {
         throw new TransportUnavailableError({
           transport: this.name,
@@ -229,10 +300,21 @@ export class NatsTransport implements Transport {
     }
     opened = client;
     this.#client = client;
+    this.#everUp = true;
     this.#retries = 0;
     return client;
   }
 
+  /** `shared`'s client: under `'first-use'` this is where the bucket is asserted, once per client. */
+  async #presenceClient(): Promise<NatsClient> {
+    const client = await this.#ensure();
+    if (this.#lazyBucket && !this.#bucketed.has(client)) {
+      await this.#ensureBucket(client);
+      this.#bucketed.add(client);
+    }
+    return client;
+  }
+
   /**
    * The library spent its reconnect budget and closed the client. Handing it out again is a node
    * that refuses every publish until somebody restarts it — and the liveness probe never asks the
@@ -253,18 +335,24 @@ export class NatsTransport implements Transport {
   }
 
   /**
-   * Re-dial until a client is up or the transport is closed. Bounded by our backoff between
-   * attempts (capped at the policy's `maxMs`), and each attempt is itself a library dial with its
-   * own budget, so a long outage costs one dial per interval rather than a spin. A dial that lands
-   * re-binds every kept subscription and is announced: changes published in the gap are gone.
+   * Dial until a client is up or the transport is closed — the first dial of a process that does
+   * not wait for the bus, and the replacement of a client the library gave up on. One loop however
+   * many callers ask. Bounded by our backoff between attempts (capped at the policy's `maxMs`), so
+   * a long outage costs one dial per interval rather than a spin. A dial that lands re-binds every
+   * kept subscription and is announced: changes published in the gap are gone.
    */
-  async #redial(): Promise<void> {
-    if (this.#redialing !== undefined) return;
+  #redial(): Promise<void> {
+    this.#redialLoop ??= this.#redialUntilUp();
+    return this.#redialLoop;
+  }
+
+  async #redialUntilUp(): Promise<void> {
     try {
       for (let attempt = 1; !this.#closed && this.#client === undefined; attempt += 1) {
         this.#redialing = attempt;
         try {
           const client = await this.#dialOnce();
+          this.#lastFailure = undefined;
           // Coded like a first subscribe's refusal; the subscription stays kept for the next client.
           for (const failure of this.#subscriptions.bindAll(client)) {
             this.#report(
@@ -275,12 +363,19 @@ export class NatsTransport implements Transport {
           this.#announce();
         } catch (error) {
           if (this.#closed) return;
-          this.#report(error, this.name);
+          this.#lastFailure = renderThrowable(error);
+          // Attempts 1, 2, 4, 8, …: an outage is said at once and then ever more rarely, rather
+          // than once per dial per pod for as long as it lasts.
+          if ((attempt & (attempt - 1)) === 0) this.#report(error, this.name);
           await this.#pause(policyDelay(this.#backoff, attempt, this.#rng));
         }
       }
     } finally {
+      // Both, HERE, in the loop's own last synchronous step — never in a reaction to its promise.
+      // A reaction runs a microtask later, and a client lost in that gap (`#lost`) was handed the
+      // finished loop back: nothing dialled again and its subscriptions stayed orphaned.
       this.#redialing = undefined;
+      this.#redialLoop = undefined;
     }
   }
 
@@ -319,7 +414,9 @@ export class NatsTransport implements Transport {
     const client = this.#client;
     if (client === undefined) return;
     // Not awaited: the library calls this from its status loop. The failure has one place to go.
-    void this.#ensureBucket(client).catch((error: unknown) => this.#report(error, this.name));
+    // A lazy bucket is forgotten instead, and asserted again by whoever next reads `shared`.
+    if (this.#lazyBucket) this.#bucketed.delete(client);
+    else void this.#ensureBucket(client).catch((error: unknown) => this.#report(error, this.name));
     this.#announce();
   }
 
@@ -364,8 +461,16 @@ export class NatsTransport implements Transport {
   #report(error: unknown, subject: string): void {
     const handler = this.#options.onError;
     if (handler !== undefined) {
-      handler(error, subject);
-      return;
+      // Total: the handler is injected, and its throw would land in whatever called this — the
+      // dial loop (started with `void`: an unhandled rejection and no more retries), the
+      // library's status loop, a subscriber's delivery. A reporter that cannot report is not a
+      // reason to stop dialling; the fault falls through to the logger line below.
+      try {
+        handler(error, subject);
+        return;
+      } catch (thrown) {
+        logger.error('nats transport onError threw', { error: renderThrowable(thrown) });
+      }
     }
     logger.error('nats transport error', {
       transport: this.name,

package/src/pg-array.ts

@@ -1,10 +1,10 @@
-// The Postgres array TEXT literal — `{a,b}`, `{"a,b",NULL}`, `{{1,2},{3,4}}` — and the element
-// type behind an array oid. Split from `pg-values.ts` so that file stays the oid switch and this
-// one stays the grammar; the element decoder arrives as a parameter, so neither imports the other.
+// The element type behind an array type oid. The WAL names only the ARRAY type and carries the
+// value as its TEXT literal (`{a,b}`), while `@ultimat3/entity`'s repository hands an `arrayOf()`
+// column back as a JS array — and a live row and a repository row have to be the same object.
 //
-// It exists because `@ultimat3/entity`'s repository hands an `arrayOf()` column back as a JS array
-// (the driver parses the literal) while the WAL carries the literal itself. A live row and a
-// repository row have to be the same object, so the literal is parsed here rather than shipped.
+// The GRAMMAR of that literal is `@ultimat3/entity`'s `parsePgArray`: the repository reads the
+// same text when a driver leaves an array unparsed, and one grammar has one reader. This file
+// keeps the half only the WAL needs — which element decoder an oid selects.
 
 /**
  * `text[]` -> `text`. The wire names only the ARRAY type, so the element type behind it is a
@@ -41,101 +41,3 @@ const ELEMENT_OF = Object.freeze<Record<number, number>>({
 export function arrayElementOid(typeOid: number): number | undefined {
   return Object.hasOwn(ELEMENT_OF, typeOid) ? ELEMENT_OF[typeOid] : undefined;
 }
-
-/** Where the scan is, so every branch below advances one cursor rather than slicing the text. */
-interface Scan {
-  readonly text: string;
-  at: number;
-}
-
-/**
- * One array literal -> a nested JS array, or `null` when the text is not one this grammar
- * describes. `null` is not an error: a dimension prefix (`[0:2]={…}`), a `DateStyle` this decoder
- * does not read, or a corrupted literal all mean the same thing to the caller — keep the text it
- * arrived as rather than deliver an array that is missing a member.
- *
- * `decode` is the ELEMENT decoder. It never sees a quoted element's quotes or its backslash
- * escapes: an unquoted `NULL` is the null value and a quoted `"NULL"` is the four-character
- * string, which is the one distinction the quoting exists to carry.
- */
-export function parsePgArray<T>(text: string, decode: (raw: string) => T): PgArray<T> | null {
-  const scan: Scan = { text, at: 0 };
-  const parsed = readArray(scan, decode);
-  // Trailing content means the literal was not what this grammar accepted, whatever it parsed.
-  return parsed === null || scan.at !== text.length ? null : parsed;
-}
-
-/** A member is a decoded value, the null member, or — for a multidimensional array — a row of them. */
-export type PgArray<T> = (T | null | PgArray<T>)[];
-
-function readArray<T>(scan: Scan, decode: (raw: string) => T): PgArray<T> | null {
-  if (scan.text[scan.at] !== '{') return null;
-  scan.at += 1;
-  const out: PgArray<T> = [];
-  if (scan.text[scan.at] === '}') {
-    scan.at += 1;
-    return out;
-  }
-  for (;;) {
-    const member = readMember(scan, decode);
-    if (member === FAILED) return null;
-    out.push(member);
-    const next = scan.text[scan.at];
-    scan.at += 1;
-    if (next === '}') return out;
-    if (next !== ',') return null;
-  }
-}
-
-/** A sentinel, because `null` is a legal member and `undefined` would be a second spelling of it. */
-const FAILED = Symbol('pg-array-failed');
-
-function readMember<T>(
-  scan: Scan,
-  decode: (raw: string) => T,
-): T | null | PgArray<T> | typeof FAILED {
-  const head = scan.text[scan.at];
-  if (head === '{') {
-    const nested = readArray(scan, decode);
-    return nested === null ? FAILED : nested;
-  }
-  if (head === '"') {
-    const quoted = readQuoted(scan);
-    return quoted === null ? FAILED : decode(quoted);
-  }
-  const start = scan.at;
-  while (scan.at < scan.text.length) {
-    const char = scan.text[scan.at];
-    if (char === ',' || char === '}') break;
-    // A brace or a quote inside a bare element is a literal this grammar does not describe.
-    if (char === '{' || char === '"') return FAILED;
-    scan.at += 1;
-  }
-  if (scan.at === scan.text.length) return FAILED;
-  const raw = scan.text.slice(start, scan.at);
-  // Unquoted and case-insensitive is the ONLY spelling of the null member; `"NULL"` is a string.
-  return raw.toUpperCase() === 'NULL' ? null : decode(raw);
-}
-
-/** The text between one pair of quotes, with `\\` and `\"` unescaped. `null` if it never closes. */
-function readQuoted(scan: Scan): string | null {
-  scan.at += 1;
-  let out = '';
-  while (scan.at < scan.text.length) {
-    const char = scan.text[scan.at];
-    if (char === '"') {
-      scan.at += 1;
-      return out;
-    }
-    if (char === '\\') {
-      const escaped = scan.text[scan.at + 1];
-      if (escaped === undefined) return null;
-      out += escaped;
-      scan.at += 2;
-      continue;
-    }
-    out += char ?? '';
-    scan.at += 1;
-  }
-  return null;
-}

package/src/pg-values.ts

@@ -11,9 +11,10 @@
 // in the component the first patch reached.
 
 import { renderThrowable } from '@ultimat3/core';
+import { parsePgArray } from '@ultimat3/entity';
 import { ReplicationProtocolError } from './errors';
 import type { JsonValue } from './json';
-import { arrayElementOid, parsePgArray } from './pg-array';
+import { arrayElementOid } from './pg-array';
 
 /**
  * What a row value can be between the WAL and the wire: JSON, plus the two JS shapes a repository

package/src/replicator.ts

@@ -11,7 +11,7 @@
 // its feed and reports `/readyz` false. A stream that ENDS — or a lock that is LOST — is this file's
 // to answer: `running` goes false, everything is let go, and the process asks again on a backoff.
 
-import { logger, renderThrowable, uuidV7, withSpan } from '@ultimat3/core';
+import { isUltimateError, logger, renderThrowable, uuidV7, withSpan } from '@ultimat3/core';
 import type { AdvisoryLock } from './advisory-lock';
 import type { ChangeEvent, ChangeFeed } from './changefeed';
 import { ReplicationFailedError } from './errors';
@@ -100,6 +100,18 @@ interface Refusal {
  */
 export const STOP_DEADLINE_MS = 5_000;
 
+/**
+ * How long a publish refused because the bus is AWAY is waited out, in the handler, before the run
+ * ends: three more attempts over two seconds. A NATS restart is a second or two, and ending the
+ * run for it costs a stream stop, an unlock, a backoff and a re-read from `lastLsn` — with
+ * `/readyz` false throughout. Longer than this is an outage, and the takeover loop's to handle.
+ */
+export const PUBLISH_RETRY_DELAYS_MS: readonly number[] = [100, 400, 1_500];
+
+/** The bus is unreachable — as opposed to a change it will never take (a payload over the limit). */
+const busAway = (thrown: unknown): boolean =>
+  isUltimateError(thrown) && thrown.code === 'X_TRANSPORT_UNAVAILABLE';
+
 const fencedOut = (reason: string): ReplicationFailedError =>
   new ReplicationFailedError({
     stage: 'stream',
@@ -131,6 +143,8 @@ export function changeFeedReplicator(options: ReplicatorOptions): Replicator {
   /** The run whose stream and lock still speak for this replicator. */
   let current: Run | undefined;
   let cancelRetry: (() => void) | undefined;
+  /** Ends the publish retry's wait in flight, if any — see `publishThroughBlip`. */
+  let endBlipWait: (() => void) | undefined;
   /** Stops listening for the lock being lost. Held only while this replicator holds the lock. */
   let unwatchLock: (() => void) | undefined;
   const unwatch = (): void => {
@@ -180,6 +194,39 @@ export function changeFeedReplicator(options: ReplicatorOptions): Replicator {
     return outcome.how === 'failed' ? outcome.error : undefined;
   };
 
+  /**
+   * One envelope, published — retried on `PUBLISH_RETRY_DELAYS_MS` while the bus is away. The SAME
+   * envelope each time, so a consumer sees one `seq`. Fenced after every wait: a run that ended
+   * meanwhile publishes nothing, for the reason the handler below gives.
+   */
+  const publishThroughBlip = async (run: Run, subject: string, envelope: string): Promise<void> => {
+    for (let retry = 0; ; retry += 1) {
+      try {
+        await options.transport.publish(subject, envelope);
+        return;
+      } catch (thrown) {
+        const delay = PUBLISH_RETRY_DELAYS_MS[retry];
+        if (delay === undefined || !busAway(thrown)) throw thrown;
+        await new Promise<void>((resolve) => {
+          const cancel = schedule(() => {
+            endBlipWait = undefined;
+            resolve();
+          }, delay);
+          // Held so `stop()` can end the wait: the timer is cleared AND the wait settles, into the
+          // fence below. A stop that only waited it out held the feed's handler for up to 1.5 s.
+          endBlipWait = (): void => {
+            endBlipWait = undefined;
+            cancel();
+            resolve();
+          };
+        });
+        if (current !== run || run.over !== null) {
+          throw fencedOut(run.over ?? 'a newer run started');
+        }
+      }
+    }
+  };
+
   const changeHandler =
     (run: Run) =>
     async (raw: ChangeEvent): Promise<void> => {
@@ -200,7 +247,7 @@ export function changeFeedReplicator(options: ReplicatorOptions): Replicator {
       await withSpan('realtime.replicate', async () => {
         seq += 1;
         try {
-          await options.transport.publish(subjectOf(change), encodeEnvelope(change, seq, producer));
+          await publishThroughBlip(run, subjectOf(change), encodeEnvelope(change, seq, producer));
         } catch (thrown) {
           const error = renderThrowable(thrown);
           const same = refusal !== null && refusal.lsn === change.lsn;
@@ -391,6 +438,8 @@ export function changeFeedReplicator(options: ReplicatorOptions): Replicator {
       pumping = false;
       if (current !== undefined) current.over ??= 'the replicator was stopped';
       current = undefined;
+      // After the run is marked over, so the wait it ends lands in the fence and publishes nothing.
+      endBlipWait?.();
       unwatch();
       // Whatever the feed said: a lock kept because the stream would not close politely is a
       // slot no standby can take. Its refusal is still the one the caller is owed.

package/src/server.ts

@@ -256,6 +256,8 @@ export {
   reconnectFrame,
 } from './thundering-herd';
 export {
+  BUS_CONNECT_WAIT_MS,
+  type BusUse,
   DEFAULT_PRESENCE_BUCKET,
   DEFAULT_PRESENCE_TTL_MS,
   type SelectTransportOptions,

package/src/transport-env.ts

@@ -11,6 +11,7 @@ import { InProcessTransport } from './fanout';
 import type { NatsConnect } from './nats-client';
 import { assertBucket } from './nats-jetstream';
 import { NatsTransport } from './nats-transport';
+import type { BackoffPolicy } from './thundering-herd';
 
 /**
  * The keys read here, and nothing else. Named once so docs and tests cannot drift from the code.
@@ -36,6 +37,27 @@ export const DEFAULT_PRESENCE_TTL_MS = 30_000;
 
 export type TransportEnvironment = Readonly<Record<string, string | undefined>>;
 
+/**
+ * What this process does with the bus, which decides whether its boot waits for it:
+ *
+ * - `'sockets'` — it serves sockets from the bus (a `sync` node). The dial and the presence bucket
+ *   are awaited, and a bus that is not there within `connectWithinMs` refuses the boot.
+ * - `'feed'` — it feeds those nodes (the replicator). The dial is awaited; it reads no presence,
+ *   so it asks JetStream for nothing.
+ * - `'publish'` — it only publishes channel events and cache invalidations (`web`, `worker`,
+ *   `scheduler`). The dial runs in the background and the boot does not wait: both kinds of
+ *   message mean "re-read", and a page that cannot say it is still a page.
+ */
+export type BusUse = 'sockets' | 'feed' | 'publish';
+
+/** How long a process that cannot work without the bus waits for it before refusing its boot. */
+export const BUS_CONNECT_WAIT_MS = 15_000;
+
+const NEEDS: Record<Exclude<BusUse, 'publish'>, string> = {
+  sockets: 'serves sockets from the bus',
+  feed: 'feeds the sync nodes over the bus',
+};
+
 export interface TransportSelection {
   readonly transport: Transport;
   /** `embedded` fans out in this process only; `external` reaches every node on the bus. */
@@ -50,12 +72,18 @@ export interface TransportSelection {
   readonly bucket: string | null;
   /** What `PresenceRegistry` must be given, so its TTL and the bucket's cannot disagree. */
   readonly presenceTtlMs: number;
+  /** What the process does with the bus, as `connect()` and `state()` obey it. */
+  readonly use: BusUse;
   /**
    * Dial now rather than on the first change nobody receives. Selection itself stays pure — it
    * parses env and constructs, it does not touch a socket — so a boot can order its dials.
-   * Embedded resolves immediately: there is nothing to reach.
+   * Embedded resolves immediately: there is nothing to reach. Under `use: 'publish'` it STARTS the
+   * dial and resolves at once; under the other two it resolves connected or rejects with
+   * `X_TRANSPORT_UNAVAILABLE` inside `connectWithinMs`.
    */
   connect(): Promise<void>;
+  /** `'connecting'` while a NATS bus is not reachable; the in-process bus is always `'up'`. */
+  state(): 'up' | 'connecting';
 }
 
 export interface SelectTransportOptions {
@@ -63,6 +91,14 @@ export interface SelectTransportOptions {
   readonly clock?: Clock | undefined;
   /** Injected so a boot — reconnect included — can be proven with no network. */
   readonly connect?: NatsConnect | undefined;
+  /** Default `'sockets'`: a caller that does not say is held to the strictest reading. */
+  readonly use?: BusUse | undefined;
+  /** Default `BUS_CONNECT_WAIT_MS`. Read under `'sockets'` and `'feed'` only. */
+  readonly connectWithinMs?: number | undefined;
+  /** The dial's retry curve; the transport's own default when unset. */
+  readonly backoff?: BackoffPolicy | undefined;
+  /** Where the transport's background failures go; its own logger line when unset. */
+  readonly onError?: ((error: unknown, subject: string) => void) | undefined;
 }
 
 const nonEmpty = (value: string | undefined): string | undefined =>
@@ -92,6 +128,7 @@ export function selectTransport(
     'presenceTtlMs',
     options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS,
   );
+  const use = options.use ?? 'sockets';
 
   if (topology.transport === 'memory') {
     refuseStrayBusUrl(env, topology);
@@ -104,7 +141,9 @@ export function selectTransport(
       detail: `in-process fanout — set realtime.transport 'nats' in ${CONFIG_FILE} and NATS_URL to reach the other nodes`,
       bucket: null,
       presenceTtlMs,
+      use,
       connect: () => Promise.resolve(),
+      state: () => 'up',
     };
   }
 
@@ -124,16 +163,37 @@ export function selectTransport(
     url,
     bucket,
     presenceTtlMs,
+    // Only a node that serves presence needs the bucket to exist before it can start.
+    presenceBucket: use === 'sockets' ? 'dial' : 'first-use',
     ...(options.clock === undefined ? {} : { clock: options.clock }),
     ...(options.connect === undefined ? {} : { connect: options.connect }),
+    ...(options.backoff === undefined ? {} : { backoff: options.backoff }),
+    ...(options.onError === undefined ? {} : { onError: options.onError }),
   });
+  const withinMs = finiteOption(
+    'the transport env',
+    'connectWithinMs',
+    options.connectWithinMs ?? BUS_CONNECT_WAIT_MS,
+  );
   return {
     transport,
     mode: 'external',
     detail: urlEnv,
     bucket,
     presenceTtlMs,
-    connect: () => transport.connect(),
+    use,
+    connect: async () => {
+      if (use === 'publish') {
+        transport.connectInBackground();
+        return;
+      }
+      await transport.connect({
+        withinMs,
+        // The variable, never the url behind it. `-js` only where the bucket is asked for.
+        fix: `x doctor — then check ${urlEnv} names a reachable nats-server${use === 'sockets' ? ' started with -js (JetStream)' : ''} — this process ${NEEDS[use]} and cannot start without it; the web, worker and scheduler roles boot without one and connect in the background`,
+      });
+    },
+    state: () => (transport.connected ? 'up' : 'connecting'),
   };
 }