@ultimat3/realtime 27.6.1 → 27.8.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

@@ -128,11 +128,11 @@ leaves `joining` on the node's first answer; nothing waits for app traffic.
 
 | State | Entered when | Left when |
 |---|---|---|
-| `joining` | the subscribe is sent (on hold, and again on every reconnect) | the node's answer: a `records` channel's `replay-gap` (a fresh seat) or the `records` frame at a current cursor; an `events` channel's roster — sent on every seat, an empty one from a node with no presence (24.0.0) |
+| `joining` | the subscribe is sent (on hold, and again on every reconnect); or the node refused it with `X_TRANSPORT_UNAVAILABLE` — its bus is away, which is its condition and not its verdict. The heartbeat re-asks every interval | the node's answer: a `records` channel's `replay-gap` (a fresh seat) or the `records` frame at a current cursor; an `events` channel's roster — sent on every seat, an empty one from a node with no presence (24.0.0) |
 | `catching-up` | a `replay-gap`, or a frame in a new epoch: the `catchUp` query is re-read, frames held behind it | the read lands → `live` (the held frames applied in order) |
 | `live` | as above | the socket drops → `offline`; a gap → `catching-up` |
 | `offline` | the page socket closed | it reopens → `joining` |
-| `failed` | the node refused the subscribe (`error()` is the coded refusal), or a catch-up read failed (retried on the client's curve, and on the next open) | a successful retry → `live` |
+| `failed` | the node **decided** against the subscribe — a policy denial, an undeclared channel, a cap (`error()` is the coded refusal; terminal until the socket reopens) — or a catch-up read failed (retried on the client's curve, and on the next open) | a successful retry → `live` |
 
 A channel declared with **neither** `records` nor `events` carries nothing, so nothing answers its
 join and it reads `joining` for as long as it is held.
@@ -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.1",
+  "version": "27.8.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.1",
-    "@ultimat3/entity": "27.6.1",
-    "@ultimat3/policy": "27.6.1",
-    "@ultimat3/query": "27.6.1",
+    "@ultimat3/core": "27.8.0",
+    "@ultimat3/entity": "27.8.0",
+    "@ultimat3/policy": "27.8.0",
+    "@ultimat3/query": "27.8.0",
     "nats": "2.29.3"
   }
 }

package/src/client-channels.ts

@@ -174,10 +174,21 @@ export class ChannelBook {
     }
   }
 
-  /** The sid a channel is subscribed under — what a refusal `ack` names. */
+  /**
+   * A refusal `ack` naming the sid a channel is subscribed under. `false` when no membership
+   * here answers to it.
+   */
   refused(sid: string, error: unknown): boolean {
     const entry = [...this.#byTopic.values()].find((candidate) => sidOf(candidate) === sid);
     if (entry === undefined) return false;
+    if (isTransientRefusal(error)) {
+      // Not a decision: the node's bus is away, so nothing reaches this seat (or there is none
+      // yet). `joining` — asked, unanswered — and never `failed`: the beat re-asks every interval
+      // and the node's first answer (a roster, a `records` frame, a `replay-gap`) ends it. A read
+      // in flight and a terminal refusal keep their own state.
+      if (entry.state === 'live') this.#set(entry, 'joining');
+      return true;
+    }
     entry.error = error;
     this.#set(entry, 'failed');
     return true;
@@ -361,6 +372,17 @@ export class ChannelBook {
   }
 }
 
+/**
+ * The one refusal that is the NODE's condition and not its verdict: its bus is away
+ * (`X_TRANSPORT_UNAVAILABLE`). Everything else an `ack` carries — a policy denial, an unknown
+ * channel, a cap — is a decision and terminal. Read off `unknown`: a refusal is the node's data.
+ */
+export function isTransientRefusal(error: unknown): boolean {
+  return (
+    (error as { readonly code?: unknown } | null | undefined)?.code === 'X_TRANSPORT_UNAVAILABLE'
+  );
+}
+
 /** A channel membership's sid is its topic behind this — what the socket engine routes on too. */
 export const CHANNEL_SID_PREFIX = 'channel:';
 

package/src/detach.ts

@@ -15,13 +15,16 @@ import { logger, renderThrowable, reportError } from '@ultimat3/core';
  * with nothing above it to answer. `channel.ts` already imports it for the same reason.
  */
 export function detach(work: Promise<unknown>, operation: string, at?: string): void {
-  void work.catch((error: unknown) => {
-    logger.error(`${operation} failed`, {
-      ...(at === undefined ? {} : { at }),
-      error: renderThrowable(error),
-    });
-    // Nobody is awaiting this, so the log is the only trace it leaves — and a log is not a signal
-    // anyone is paged on. The bus is this node's dependency, never the client's.
-    reportError(error, { source: 'realtime', scope: { operation } });
+  void work.catch((error: unknown) => reportDetached(error, operation, at));
+}
+
+/** What `detach` says of a failure — also `sync-bus-outage.ts`'s answer to one that is no outage. */
+export function reportDetached(error: unknown, operation: string, at?: string): void {
+  logger.error(`${operation} failed`, {
+    ...(at === undefined ? {} : { at }),
+    error: renderThrowable(error),
   });
+  // Nobody is awaiting this, so the log is the only trace it leaves — and a log is not a signal
+  // anyone is paged on. The bus is this node's dependency, never the client's.
+  reportError(error, { source: 'realtime', scope: { operation } });
 }

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 {
@@ -118,6 +118,7 @@ class LibNatsClient implements NatsClient {
     payload: Uint8Array,
     options: NatsRequestOptions = {},
   ): Promise<NatsMessage> {
+    this.#assertLive(subject);
     const built = headersOf(options.headers);
     try {
       const reply = await this.#connection.request(subject, payload, {
@@ -140,6 +141,7 @@ class LibNatsClient implements NatsClient {
     payload: Uint8Array,
     options: NatsRequestManyOptions,
   ): Promise<readonly NatsMessage[]> {
+    this.#assertLive(subject);
     const collected: NatsMessage[] = [];
     try {
       const replies = await this.#connection.requestMany(subject, payload, {
@@ -162,6 +164,21 @@ class LibNatsClient implements NatsClient {
     await this.#connection.close();
   }
 
+  /**
+   * A request has an answer to wait for, so one made with no live connection is refused HERE.
+   * The library takes it instead — buffered with its publishes, sent if the reconnect lands and
+   * timed out if it does not — so every presence write on a `sync` node whose bus was away held
+   * its socket's frame lane for the whole request timeout before saying what was already known.
+   * The fake has always refused it (`nats-fake.ts`, `#assertLive`); this is the client agreeing.
+   */
+  #assertLive(subject: string): void {
+    if (this.connected) return;
+    throw unavailable(
+      this.#target,
+      `${subject} was not asked: the client is reconnecting to the bus`,
+    );
+  }
+
   /**
    * The library's own status stream is the only place a drop or a recovery is announced. Nothing
    * awaits it, so it can neither throw nor end the process: a drop reports and flips `connected`,
@@ -211,6 +228,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 +259,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 +280,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-reports.ts

@@ -0,0 +1,80 @@
+// Single responsibility: where a `NatsTransport`'s background failures go, and how often. A FAULT
+// (a subscriber that threw, a re-subscribe the server refused) is said every time. An OUTAGE (a
+// drop, a refused dial, a client the library gave up on) is one fact however long it lasts: said
+// on its 1st, 2nd, 4th, 8th, … failure and once more when the bus answers again.
+
+import { isOutageMilestone, isUltimateError, logger, renderThrowable } from '@ultimat3/core';
+
+export interface NatsReportsOptions {
+  readonly transport: string;
+  /** The app's own sink. Absent, or throwing, the logger line is written instead. */
+  readonly onError: ((error: unknown, subject: string) => void) | undefined;
+  /**
+   * `'error'` for a process that cannot do its job without the bus (a `sync` node, a replicator);
+   * `'warn'` for one that only publishes — degraded, and still serving.
+   */
+  readonly outageLevel: 'warn' | 'error';
+}
+
+export class NatsReports {
+  readonly #options: NatsReportsOptions;
+  /** Failures of the bus itself since it last answered. */
+  #failures = 0;
+
+  constructor(options: NatsReportsOptions) {
+    this.#options = options;
+  }
+
+  /**
+   * Every background failure lands here or in `outage`. Dropping it when the caller passed no
+   * handler is what turns "no changes arrive" into a debugging session with nothing to read, so
+   * the default emits rather than swallows.
+   */
+  fault(error: unknown, subject: string): void {
+    this.#say(error, subject, 'error');
+  }
+
+  /**
+   * One more failure of the bus itself, thinned and at the level its owner chose. `always` is for
+   * a TRANSITION rather than a retry — the library giving up on a client happens once per client,
+   * and it is the line that says the transport's own re-dial took over.
+   */
+  outage(error: unknown, always = false): void {
+    this.#failures += 1;
+    if (!always && !isOutageMilestone(this.#failures)) return;
+    this.#say(error, this.#options.transport, this.#options.outageLevel, this.#failures);
+  }
+
+  /** The bus answers again: one line saying after how many failures, and the count starts over. */
+  recovered(): void {
+    const after = this.#failures;
+    if (after === 0) return;
+    this.#failures = 0;
+    logger.info('nats transport recovered', { transport: this.#options.transport, after });
+  }
+
+  #say(error: unknown, subject: string, level: 'warn' | 'error', failures?: number): void {
+    const handler = this.#options.onError;
+    if (handler !== undefined) {
+      // 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[level]('nats transport error', {
+      transport: this.#options.transport,
+      subject,
+      ...(failures === undefined ? {} : { failures }),
+      code: isUltimateError(error) ? error.code : undefined,
+      // `renderThrowable`, never `String(error)`: this is a reporter, and a throwable that fights
+      // being read makes the report the thing that throws.
+      error: renderThrowable(error),
+    });
+  }
+}

package/src/nats-transport.ts

@@ -3,12 +3,16 @@
 // 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,
   finiteOption,
   isUltimateError,
-  logger,
   renderThrowable,
   systemClock,
 } from '@ultimat3/core';
@@ -16,9 +20,11 @@ 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';
+import { NatsReports } from './nats-reports';
 import { NatsSubscriptions } from './nats-subscriptions';
 import { type BackoffPolicy, defaultBackoff, policyDelay, type Rng } from './thundering-herd';
 
@@ -39,6 +45,20 @@ 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;
+  /**
+   * The level an OUTAGE is logged at. `'error'` (the default) is a process that cannot do its job
+   * without the bus — a `sync` node, a replicator. `'warn'` is one that only publishes: degraded,
+   * and still serving. A subscriber that throws is an `error` under either.
+   */
+  readonly outageLevel?: 'warn' | 'error';
 }
 
 const DEFAULT_ATTEMPTS = 10;
@@ -57,9 +77,20 @@ 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;
+  /** Where background failures go: a fault every time, an outage thinned (`nats-reports.ts`). */
+  readonly #reports: NatsReports;
   readonly #subscriptions = new NatsSubscriptions();
   readonly #reconnectListeners = new Set<() => void>();
 
@@ -68,6 +99,11 @@ export class NatsTransport implements Transport {
     // a container that reports itself healthy on one is a container nothing will ever page about.
     parseNatsUrl(options.url);
     this.#options = options;
+    this.#reports = new NatsReports({
+      transport: this.name,
+      onError: options.onError,
+      outageLevel: options.outageLevel ?? 'error',
+    });
     this.#connect = options.connect ?? openNatsClient;
     this.#backoff = options.backoff ?? defaultBackoff;
     this.#attempts = finiteOption(
@@ -76,16 +112,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 +165,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
@@ -118,7 +199,7 @@ export class NatsTransport implements Transport {
         try {
           handler(decoder.decode(message.payload), message.subject);
         } catch (error) {
-          this.#report(error, message.subject);
+          this.#reports.fault(error, message.subject);
         }
       },
       (call) => this.#translating(`subscribe to ${subject}`, call),
@@ -167,7 +248,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,10 +280,11 @@ 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),
-      onError: (error) => this.#report(error, this.name),
+      onError: (error) => this.#reports.outage(error),
       onReconnect: () => this.#recovered(),
       onClosed: () => {
         if (opened === undefined) closedEarly = true;
@@ -208,7 +292,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 +313,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
@@ -242,32 +337,39 @@ export class NatsTransport implements Transport {
     if (this.#closed || this.#client !== client) return;
     this.#client = undefined;
     this.#subscriptions.orphan();
-    this.#report(
+    this.#reports.outage(
       new TransportUnavailableError({
         transport: this.name,
         reason: 'the connection closed once its reconnect budget was spent; re-dialling',
       }),
-      this.name,
+      true,
     );
     void this.#redial();
   }
 
   /**
-   * 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;
+          this.#reports.recovered();
           // 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(
+            this.#reports.fault(
               this.#coded(`re-subscribe to ${failure.subject}`, failure.error),
               failure.subject,
             );
@@ -275,12 +377,19 @@ export class NatsTransport implements Transport {
           this.#announce();
         } catch (error) {
           if (this.#closed) return;
-          this.#report(error, this.name);
+          this.#lastFailure = renderThrowable(error);
+          // Thinned (`#outage`): said at once and then ever more rarely, rather than once per
+          // dial per pod for as long as it lasts.
+          this.#reports.outage(error);
           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;
     }
   }
 
@@ -318,8 +427,11 @@ export class NatsTransport implements Transport {
     this.#retries = 0;
     const client = this.#client;
     if (client === undefined) return;
+    this.#reports.recovered();
     // 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.#reports.outage(error));
     this.#announce();
   }
 
@@ -328,7 +440,7 @@ export class NatsTransport implements Transport {
       try {
         listener();
       } catch (error) {
-        this.#report(error, this.name);
+        this.#reports.fault(error, this.name);
       }
     }
   }
@@ -355,25 +467,4 @@ export class NatsTransport implements Transport {
       reason: `${what} was refused: ${renderThrowable(error)}`,
     });
   }
-
-  /**
-   * Every background failure lands here — a lost connection, a throwing subscriber, an exhausted
-   * reconnect. Dropping it when the caller passed no handler is what turns "no changes arrive"
-   * into a debugging session with nothing to read, so the default emits rather than swallows.
-   */
-  #report(error: unknown, subject: string): void {
-    const handler = this.#options.onError;
-    if (handler !== undefined) {
-      handler(error, subject);
-      return;
-    }
-    logger.error('nats transport error', {
-      transport: this.name,
-      subject,
-      code: isUltimateError(error) ? error.code : undefined,
-      // `renderThrowable`, never `String(error)`: this is a reporter, and a throwable that fights
-      // being read makes the report the thing that throws.
-      error: renderThrowable(error),
-    });
-  }
 }

package/src/presence.ts

@@ -93,6 +93,13 @@ export class PresenceRegistry {
     return this.#ttlMs;
   }
 
+  /** Rooms with a member this node has seen — what the next `sweepAll` will read the bus for. */
+  get rooms(): number {
+    let rooms = 0;
+    for (const members of this.#seen.values()) if (members.size > 0) rooms += 1;
+    return rooms;
+  }
+
   /** Recommended client heartbeat interval: one lost beat must not read as a leave. */
   get heartbeatMs(): number {
     return Math.max(1_000, Math.floor(this.#ttlMs / 3));

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/sync-bus-handlers.ts

@@ -14,12 +14,15 @@ import {
   parseEnvelope,
   type SeqGapDetector,
 } from './replicator-envelope';
+import type { BusOutage } from './sync-bus-outage';
 
 export interface SyncBus {
   readonly registry: LiveQueryRegistry;
   readonly hub: ChannelHub;
   readonly gaps: SeqGapDetector;
   readonly producers: ProducerKinds;
+  /** The node's outage: a bus that reconnected has answered. */
+  readonly outage?: Pick<BusOutage, 'answered'> | undefined;
 }
 
 /**
@@ -123,6 +126,7 @@ export function changeHandler(bus: SyncBus): (payload: string) => void {
  */
 export function reconnectHandler(bus: SyncBus): () => void {
   return () => {
+    bus.outage?.answered();
     bus.gaps.forget();
     const marked = bus.registry.invalidate();
     const channelGaps = bus.hub.invalidate();

package/src/sync-bus-outage.ts

@@ -0,0 +1,62 @@
+// Single responsibility: what a `sync` node says while its bus is away. Without the bus the node
+// cannot do its job — that is an ERROR — but it is ONE fact however many sockets beat into it and
+// however many sweeps fail: said on failures 1, 2, 4, 8, … and once more when the bus answers.
+// Until 2026-10-10 it was `presence.sweep failed` every sweep and one monitor event per refused beat.
+
+import { outageLog, renderThrowable, reportError } from '@ultimat3/core';
+import { reportDetached } from './detach';
+import type { PresenceRegistry } from './presence';
+
+/** The line a node writes while its bus is away; `<event> recovered` when it is back. */
+export const SYNC_BUS_UNAVAILABLE = 'sync.bus_unavailable';
+
+export interface BusOutage {
+  /**
+   * `true` when `error` is the bus being away — counted, and logged + reported only on the
+   * outage's milestones. `false` for anything else, which stays the caller's to report.
+   */
+  refused(error: unknown, operation: string, at?: string): boolean;
+  /** The bus answered: the outage, if there was one, is over. */
+  answered(): void;
+  /** `detach` for work that reaches the bus: an outage is thinned, any other failure is not. */
+  detach(work: Promise<unknown>, operation: string, at?: string): void;
+  /** One presence sweep. A pass that read at least one room is the bus answering. */
+  sweep(presence: PresenceRegistry): void;
+}
+
+const codeOf = (error: unknown): unknown =>
+  typeof error === 'object' && error !== null ? (error as { readonly code?: unknown }).code : null;
+
+export function busOutage(): BusOutage {
+  const log = outageLog({ event: SYNC_BUS_UNAVAILABLE, level: 'error' });
+  const refused = (error: unknown, operation: string, at?: string): boolean => {
+    if (codeOf(error) !== 'X_TRANSPORT_UNAVAILABLE') return false;
+    const said = log.failed({
+      operation,
+      ...(at === undefined ? {} : { at }),
+      error: renderThrowable(error),
+    });
+    // The monitor is thinned with the log: one outage is not one event per socket per beat.
+    if (said) reportError(error, { source: 'realtime', scope: { operation } });
+    return true;
+  };
+  const detached = (work: Promise<unknown>, operation: string, at?: string): void => {
+    void work.catch((error: unknown) => {
+      if (!refused(error, operation, at)) reportDetached(error, operation, at);
+    });
+  };
+  return {
+    refused,
+    answered: () => log.recovered(),
+    detach: detached,
+    sweep(presence) {
+      const rooms = presence.rooms;
+      detached(
+        presence.sweepAll().then(() => {
+          if (rooms > 0) log.recovered();
+        }),
+        'presence.sweep',
+      );
+    },
+  };
+}

package/src/sync-frames.ts

@@ -22,6 +22,8 @@ export interface FrameRouterOptions {
   readonly heartbeatMs?: number | undefined;
   /** Shared with the node, which names a seat's sid when a re-auth drops it. */
   readonly channelSids?: ChannelSids | undefined;
+  /** Told when a presence read or write landed: the bus answered (`sync-bus-outage.ts`). */
+  readonly busAnswered?: (() => void) | undefined;
 }
 
 /**
@@ -73,6 +75,7 @@ export function frameRouter(options: FrameRouterOptions): FrameRouter {
       : beat && (await presence.heartbeat(name, socket.id))
         ? await presence.roster(name)
         : await presence.join(name, { id: socket.id, actorId: socket.actorId });
+    if (presence) options.busAnswered?.();
     // Read, though nothing here can repair it: the next beat re-sends the set, and the log is the
     // only trace a dropped one leaves anywhere.
     if (!socket.send(presenceFrame(name, 'sync', roster.members, roster.total))) {

package/src/sync-node.ts

@@ -27,6 +27,7 @@ import { idleSweepPeriodMs } from './socket-idle';
 import { actorChangeHandler } from './sync-actor-change';
 import { GrantBook, sweepGrants } from './sync-auth';
 import { changeHandler, ProducerKinds, reconnectHandler } from './sync-bus-handlers';
+import { busOutage } from './sync-bus-outage';
 import { ackRefOf, frameRouter } from './sync-frames';
 import {
   clientHeartbeatMs,
@@ -73,6 +74,7 @@ export function syncNode(options: SyncNodeOptions): SyncNode {
   const gaps = new SeqGapDetector();
   // Kept across restarts of the bus subscription: a table's producer kind is a fact of the fleet.
   const producers = new ProducerKinds();
+  const outage = busOutage();
   const channelSids = new ChannelSids();
   let reconnects: (() => void) | null = null;
   /** The re-auth pass in flight, shared by every tick that lands while it runs. */
@@ -145,7 +147,7 @@ export function syncNode(options: SyncNodeOptions): SyncNode {
         const leave = presence.leave(name, socket.id);
         // Detached as well as returned: `detach` attaches the reporting catch, so a caller that
         // awaits this later is awaiting a promise whose rejection is already handled.
-        detach(leave, 'presence.leave', name);
+        outage.detach(leave, 'presence.leave', name);
         leaves.push(leave);
       }
     }
@@ -237,13 +239,14 @@ export function syncNode(options: SyncNodeOptions): SyncNode {
     buildId: options.buildId,
     presence,
     channelSids,
+    busAnswered: outage.answered,
     heartbeatMs: clientHeartbeatMs(presence?.heartbeatMs, sockets.idleTimeoutMs),
   });
 
   /** Everything `start()` does, fenced on the generation it began under — see `started`. */
   const begin = async (): Promise<void> => {
     const run = generation;
-    const bus = { registry: options.registry, hub: options.hub, gaps, producers };
+    const bus = { registry: options.registry, hub: options.hub, gaps, producers, outage };
     const subscription = await options.transport.subscribe(CHANGE_SUBJECT_ALL, changeHandler(bus));
     // A stop or drain ran inside that await: what it released did not include this yet.
     if (run !== generation) {
@@ -255,10 +258,7 @@ export function syncNode(options: SyncNodeOptions): SyncNode {
     // One pass per heartbeat window: a member is swept only once it has actually missed its
     // window, and the interval never holds the process open — shutdown is the drain's job.
     if (presence) {
-      sweeping = setInterval(
-        () => detach(presence.sweepAll(), 'presence.sweep'),
-        presence.heartbeatMs,
-      );
+      sweeping = setInterval(() => outage.sweep(presence), presence.heartbeatMs);
       sweeping.unref();
     }
     // The half-open connection Bun's own `idleTimeout` renews through its ping/pong: a client
@@ -409,7 +409,7 @@ export function syncNode(options: SyncNodeOptions): SyncNode {
           } catch (error) {
             // The ack frame tells the client what it did wrong; the monitor only hears about what
             // this node did wrong. Same rule the HTTP pipeline applies at `status >= 500`.
-            if (!isClientFault(error)) {
+            if (!outage.refused(error, 'sync.frame') && !isClientFault(error)) {
               reportError(error, {
                 source: 'realtime',
                 scope: { operation: 'sync.frame', extra: { socketId: socket.id } },

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,39 @@ 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',
+    // A publisher without the bus is degraded and still serves; a node that serves FROM it is not.
+    outageLevel: use === 'publish' ? 'warn' : 'error',
     ...(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'),
   };
 }