@ultimat3/realtime 22.15.0 → 24.0.0

package/src/live-query.ts

@@ -1,63 +1,31 @@
 // Tier 2: live queries. Registration, per-subscriber authz, snapshot, patch stream.
 //
 // The rule this file exists to enforce: **policy is evaluated once per subscriber, never once per
-// query**. The DB read is shared across subscribers of the same query id; the authz decision is
-// not. Two actors on one live query see two different result sets, and a row that fails an actor's
+// query**. The DB read is shared across subscribers of the same query id IN ONE TENANT
+// (`live-tenant.ts`); the authz decision is not shared at all. Two actors on one live query see two different result sets, and a row that fails an actor's
 // policy is never sent to that actor — it arrives as a `delete` if they hold it, and is dropped
 // otherwise.
 
-import { type Actor, type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
+import { type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
 import { queryHash } from '@ultimat3/query';
 import type { ChangeEvent } from './changefeed';
-import {
-  advance,
-  type LiveCursor,
-  makeCursor,
-  type ReconnectBudget,
-  type ResumeSource,
-  resumeFrom,
-} from './cursor';
+import { type LiveCursor, makeCursor } from './cursor';
 import { isPolicyDenial, LiveQueryUnknownError, SubscriptionLimitError } from './errors';
 import type { JsonValue } from './json';
 import type { LiveQueryDefinition, LiveSubscription, SnapshotResult } from './live-contract';
 import { type FanoutDeps, fanoutChange, snapshotFrame } from './live-fanout';
+import { floorAfterRead } from './live-floor';
+import { DEFAULT_MAX_ENTRIES, type LiveQueryRegistryOptions } from './live-query-options';
+import { refuseSubscription } from './live-refusal';
+import { resumeOnto } from './live-resume';
+import { liveTenantOf, windowId } from './live-tenant';
 import { createEntry, fillWindow, type QueryEntry } from './query-window';
 import type { SyncSocket } from './socket';
-import { type Subscriber, SubscriberGate, type SubscriberGateOptions } from './subscriber-gate';
+import { type Subscriber, SubscriberGate } from './subscriber-gate';
 import { SubscriptionBook, subscriptionKey } from './subscription-book';
-import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
-import type { Scheduler } from './thundering-herd';
+import type { Frame } from './sync-protocol';
 
-export interface LiveQueryRegistryOptions extends SubscriberGateOptions {
-  readonly source: ResumeSource;
-  readonly budget?: ReconnectBudget;
-  readonly clock?: Clock;
-  readonly maxPerSocket?: number;
-  readonly maxPerTenant?: number;
-  readonly tenantOf?: (actor: Actor | null) => string | null;
-  /**
-   * Distinct `(query, input)` pairs this node will hold at once. A `qid` derives from
-   * client-chosen input, so without a ceiling one socket mints entries — a matcher, a row window,
-   * a `WindowLock` and a fanout target each — until the process dies.
-   */
-  readonly maxEntries?: number;
-  /**
-   * How long one entry's SHARED snapshot read may hold its slot. Defaults to
-   * `DEFAULT_READ_DEADLINE_MS`. Without it a `definition.snapshot` that never settles pinned the
-   * slot for the life of the process and every later cold subscriber joined a promise nothing
-   * would resolve — one wedged read taking every future subscriber of that query id with it.
-   */
-  readonly readDeadlineMs?: number;
-  /** Injected so that deadline is provable without waiting for one. Production uses `setTimeout`. */
-  readonly schedule?: Scheduler;
-}
-
-/**
- * Live `(query, input)` pairs one node holds. Reached, the next NEW pair is refused with
- * `X_SUBSCRIPTION_LIMIT`; subscribing to a pair that already exists keeps working, because the
- * cost this bounds is the entry, not the subscriber.
- */
-export const DEFAULT_MAX_ENTRIES = 10_000;
+export { DEFAULT_MAX_ENTRIES, type LiveQueryRegistryOptions } from './live-query-options';
 
 export class LiveQueryRegistry {
   readonly #definitions = new Map<string, LiveQueryDefinition>();
@@ -71,6 +39,11 @@ export class LiveQueryRegistry {
   /** What one lane needs, and nothing this class holds beyond it. */
   readonly #fanout: FanoutDeps;
   #lastLsn = '';
+  /**
+   * This node's mark for a window read before it held any position: unique to the process, and
+   * `!` sorts below every hex digit, so every real change is above it.
+   */
+  readonly #origin = `!${uuid()}`;
   #staleChanges = 0;
 
   constructor(options: LiveQueryRegistryOptions) {
@@ -111,10 +84,15 @@ export class LiveQueryRegistry {
    * whose lsn never moved, subscribers whose cursors never moved, and therefore nothing that would
    * ever ask for a re-snapshot. The repair lands on the next change to each query — which is the
    * event that proves the query is moving at all.
+   *
+   * `entity` narrows it to the windows that read that entity: a filtered write
+   * (`updateWhere`/`deleteWhere`) names its entity but no row, and staling every window on the node
+   * for it re-read every live query in the process on each bulk write to any table.
    */
-  invalidate(): number {
+  invalidate(entity?: string): number {
     let marked = 0;
     for (const entry of this.#entries.values()) {
+      if (entity !== undefined && !entry.shape.entities.includes(entity)) continue;
       entry.stale = true;
       for (const subscription of entry.subscribers.values()) {
         subscription.socket.markDesynced(subscription.sid);
@@ -165,7 +143,15 @@ export class LiveQueryRegistry {
     // dispatched concurrently, N of them reading a count nothing had grown yet.
     const slot = this.#book.reserve(args.socket, sid);
     try {
-      return await this.#subscribeReserved(definition, sid, args);
+      for (;;) {
+        // `authorize`, the read and the row pass all await, and a re-auth that lands under them
+        // re-decides only what is ATTACHED. So a subscription seated for an actor the socket no
+        // longer carries is taken back and served again under the one it does.
+        const actor = args.socket.actor;
+        const served = await this.#subscribeReserved(definition, sid, args);
+        if (args.socket.actor === actor) return served;
+        this.unsubscribe(args.socket.id, sid);
+      }
     } finally {
       // After the attach on every path, so the slot is only ever given back to a count that has
       // already grown — or, on a failure, to one that never will.
@@ -188,8 +174,11 @@ export class LiveQueryRegistry {
     // may not subscribe is work an unauthorized client gets to schedule.
     await definition.prepare?.(args.input);
 
-    const qid = queryHash(args.name, args.input);
-    const entry = this.#entryFor(qid, definition, args.input);
+    // The window is the subscriber's TENANT's: two orgs on one `(query, input)` are two entries,
+    // two reads and two retained rings, so no shared row ever stands between them and a policy.
+    const tenant = liveTenantOf(args.socket.actor);
+    const qid = windowId(queryHash(args.name, args.input), tenant);
+    const entry = this.#entryFor(qid, definition, args.input, tenant);
     try {
       return await this.#serve(entry, sid, args);
     } catch (error) {
@@ -215,48 +204,30 @@ export class LiveQueryRegistry {
     const qid = entry.qid;
     const now = this.#clock.now().getTime();
 
-    if (args.cursor) {
-      const cursor = args.cursor;
-      const resumed = await resumeFrom(cursor, {
-        source: this.#options.source,
-        ...(this.#options.budget ? { budget: this.#options.budget } : {}),
-        clock: this.#clock,
-        snapshot: async () => await this.#read(entry, { sid, actor: args.socket.actor }),
-      });
-      if (resumed.kind === 'delta') {
-        // The gate decides about whole rows out of the shared window, and an entry nothing has read
-        // yet has none — every patch would meet an empty window and be withheld. Filling is
-        // conditional on purpose: a restart storm resumes onto entries that already hold a live
-        // window, and re-reading per resuming subscriber is the cost a delta resume exists to skip.
-        if (entry.lsn === '') await fillWindow(entry);
-        // The live entry on purpose: a resume runs outside the lane, so the window under it may
-        // have moved on — always forwards, and a row whose grant was revoked in the meantime is
-        // one this pass must refuse rather than replay from the state it had at the cursor's lsn.
-        const patches = await this.#gate.filterPatches(
-          entry,
-          { sid, actor: args.socket.actor },
-          resumed.patches,
-          new Set(cursor.ids),
-        );
-        // Advanced over the FILTERED list, never over `resumed.cursor` — which `resumeFrom` built
-        // by advancing across the retained window, and that window is PRE-POLICY. Seated as it
-        // came back, this subscriber's `cursor.ids` gained the id of every row inserted for every
-        // OTHER actor while it was away; `subscriber-gate` then reads `held.has(patch.id)` off it,
-        // takes the "the subscriber holds this row" branch, and delivers a `delete` frame carrying
-        // another tenant's row id and the instant it went. The leak that branch closes, re-opened
-        // one layer up. `live-fanout.ts` advances over `allowed` for exactly this reason.
-        const seated = advance(cursor, patches, resumed.cursor.lsn, now);
-        const subscription = this.#attachUnlessGone(entry, args.socket, sid, seated);
-        return {
-          subscription,
-          frame: { type: 'patch', v: PROTOCOL_VERSION, sid, patches, lsn: seated.lsn },
-        };
-      }
+    // A cursor is CLIENT data, and its `qid` names the window whose retained patches a resume
+    // replays. One that names another window — the same browser, signed in to another org, or a
+    // forged frame — is not a position in this one: it is a cold start, never a replay of a ring
+    // this subscriber's window does not own.
+    //
+    // Nor is ANY cursor a position in a window known to have missed a change: the ring still
+    // answers a delta for it, and that delta is the hole. A stale entry serves cold starts only.
+    if (args.cursor && args.cursor.qid === qid && !entry.stale) {
+      const who = { sid, actor: args.socket.actor };
+      const resumed = await resumeOnto(
+        {
+          source: this.#options.source,
+          budget: this.#options.budget,
+          clock: this.#clock,
+          gate: this.#gate,
+          read: () => this.#read(entry, who),
+        },
+        entry,
+        who,
+        args.cursor,
+        now,
+      );
       const subscription = this.#attachUnlessGone(entry, args.socket, sid, resumed.cursor);
-      return {
-        subscription,
-        frame: snapshotFrame(entry, sid, resumed.rows, resumed.cursor),
-      };
+      return { subscription, frame: resumed.frame };
     }
 
     const fresh = await this.#read(entry, { sid, actor: args.socket.actor });
@@ -314,6 +285,11 @@ export class LiveQueryRegistry {
    * what is no longer allowed. Survivors are marked desynced so the next flush re-snapshots them
    * under the new actor's row policy. Returns the sids that were dropped — a denial and nothing
    * else, so a caller may tell the client "you may no longer see this" and be right.
+   *
+   * A survivor whose actor now belongs to ANOTHER tenant cannot stay where it is: its window is the
+   * old org's. It is re-seated — dropped, subscribed again under the new tenant, and sent that
+   * window's snapshot under the same sid — or, when that cannot complete, refused on the socket
+   * under the sid (`refuseSubscription`), never kept on the old org's window.
    */
   async reauthorize(socket: SyncSocket): Promise<readonly string[]> {
     const dropped: string[] = [];
@@ -322,6 +298,7 @@ export class LiveQueryRegistry {
     // nobody updates is a count that drifts from the book for the rest of the process.
     this.#book.retenant(socket);
     for (const subscription of this.#book.ofSocket(socket.id)) {
+      let failed: { readonly error: unknown } | undefined;
       try {
         await subscription.definition.authorize?.({
           actor: socket.actor,
@@ -330,6 +307,9 @@ export class LiveQueryRegistry {
       } catch (error) {
         if (isPolicyDenial(error)) {
           this.unsubscribe(socket.id, subscription.sid);
+          // Said under the sid, as a refused subscribe is: unsaid, the client kept the rows on
+          // screen in state `live` for a subscription this node no longer serves.
+          refuseSubscription(socket, subscription.sid, error);
           dropped.push(subscription.sid);
           continue;
         }
@@ -343,12 +323,46 @@ export class LiveQueryRegistry {
           { sid: subscription.sid, actor: socket.actor },
           error,
         );
+        failed = { error };
       }
+      if (await this.#reseat(socket, subscription, failed)) continue;
       socket.markDesynced(subscription.sid);
     }
     return dropped;
   }
 
+  /**
+   * Move one subscription onto its actor's CURRENT tenant's window. `false` when it is already
+   * there. A re-seat that cannot complete leaves the subscription dropped — never attached to the
+   * window of an org its actor has left — and REFUSED on the socket under its sid, the frame a
+   * refused subscribe gets, so the client's window renders `failed` instead of going quiet.
+   *
+   * `failed` is the `authorize` this pass already saw fail: it is not asked again — the store that
+   * just timed out is the one `subscribe` would ask — and it is not counted twice.
+   */
+  async #reseat(
+    socket: SyncSocket,
+    subscription: LiveSubscription,
+    failed: { readonly error: unknown } | undefined,
+  ): Promise<boolean> {
+    const { sid, input, definition } = subscription;
+    const wanted = windowId(queryHash(definition.name, input), liveTenantOf(socket.actor));
+    if (wanted === subscription.qid) return false;
+    this.unsubscribe(socket.id, sid);
+    if (failed !== undefined) {
+      refuseSubscription(socket, sid, failed.error);
+      return true;
+    }
+    try {
+      const { frame } = await this.subscribe({ socket, name: definition.name, input, sid });
+      if (!socket.send(frame)) socket.markDesynced(sid);
+    } catch (error) {
+      this.#gate.failedAuthorize(wanted, { sid, actor: socket.actor }, error);
+      refuseSubscription(socket, sid, error);
+    }
+    return true;
+  }
+
   /**
    * Fan one change out. Matched once per query id, authorized once per subscriber. Returns the
    * number of frames sent — the metric the reconnect benchmark watches.
@@ -410,6 +424,10 @@ export class LiveQueryRegistry {
     cursor: LiveCursor,
   ): LiveSubscription {
     const subscription = this.#attach(entry, socket, sid, cursor);
+    // The policy pass ran outside the lane, so a change may have been folded into the window
+    // between the rows this subscriber was served and this attach: it is in neither their frame
+    // nor their patch stream. Marked, so the next delivery re-snapshots them out of the window.
+    if (entry.lsn !== cursor.lsn) socket.markDesynced(sid);
     if (socket.closed) this.unsubscribe(socket.id, sid);
     return subscription;
   }
@@ -437,7 +455,12 @@ export class LiveQueryRegistry {
     return subscription;
   }
 
-  #entryFor(qid: string, definition: LiveQueryDefinition, input: JsonValue): QueryEntry {
+  #entryFor(
+    qid: string,
+    definition: LiveQueryDefinition,
+    input: JsonValue,
+    tenant: string | null,
+  ): QueryEntry {
     const existing = this.#entries.get(qid);
     if (existing) return existing;
     // The node-wide ceiling, refused where the entry would be born. `qid` derives from
@@ -454,6 +477,7 @@ export class LiveQueryRegistry {
     const created = createEntry(qid, definition, input, definition.matcher(input), {
       readDeadlineMs: this.#options.readDeadlineMs,
       schedule: this.#options.schedule,
+      tenant,
     });
     this.#entries.set(qid, created);
     return created;
@@ -466,6 +490,10 @@ export class LiveQueryRegistry {
    */
   async #read(entry: QueryEntry, who: Subscriber): Promise<SnapshotResult> {
     const window = await fillWindow(entry);
-    return { rows: await this.#gate.filterRows(entry, who, window.rows), lsn: window.lsn };
+    const lsn = floorAfterRead(this.#options.source, entry, window, {
+      lastLsn: this.#lastLsn,
+      origin: this.#origin,
+    });
+    return { rows: await this.#gate.filterRows(entry, who, window.rows), lsn };
   }
 }

package/src/live-refusal.ts

@@ -0,0 +1,21 @@
+// A live subscription refused AFTER it was served: the frame a refused `subscribe` gets — an `ack`
+// whose `ref` is the sid — sent by the node itself, so the client's window renders `failed` with
+// the code, cause and fix instead of going quiet. `sync-node.ts` sends the same frame when a
+// subscribe frame throws.
+
+import { logger } from '@ultimat3/core';
+import type { SyncSocket } from './socket';
+import { PROTOCOL_VERSION, toWireError } from './sync-protocol';
+
+export function refuseSubscription(socket: SyncSocket, sid: string, error: unknown): void {
+  const sent = socket.send({
+    type: 'ack',
+    v: PROTOCOL_VERSION,
+    ref: sid,
+    lsn: null,
+    error: toWireError(error),
+  });
+  // Read, never assumed: the subscription is already gone, so a dropped refusal leaves a client
+  // waiting on a window nothing serves — the log is the only trace it would leave.
+  if (!sent) logger.warn('sync.refusal_dropped', { socketId: socket.id, sid });
+}

package/src/live-replicator.ts

@@ -125,14 +125,14 @@ export async function startLiveReplicator(options: LiveReplicatorOptions): Promi
 
     /**
      * A filtered write names rows this seam never saw, so there is no event to shape. Every window
-     * on the node is marked stale instead and re-read on the next change — `invalidate()` is the
-     * node's own answer to "the change stream skipped something", used here for the one write that
-     * genuinely does. Silence would be the alternative, and a subscriber told nothing happened
-     * diverges with nobody ever asking again.
+     * over THAT entity is marked stale instead and re-read, its subscribers re-snapshotted, on the
+     * next change — `invalidate()` is the node's own answer to "the change stream skipped
+     * something", used here for the one write that genuinely does. Silence would be the
+     * alternative, and a subscriber told nothing happened diverges with nobody ever asking again.
      */
-    onBulk(_change: RowBulkChange): void {
+    onBulk(change: RowBulkChange): void {
       if (stopped) return;
-      registry.invalidate();
+      registry.invalidate(change.entity);
     },
   };
 

package/src/live-resume.ts

@@ -0,0 +1,74 @@
+// One subscriber resuming onto its window from a cursor: replay the retained patches when the
+// cursor is inside them, serve one bounded snapshot when it is not. Split from `live-query.ts` at
+// that file's size ceiling — the registry owns the entry table and who is attached to what; this
+// owns what a returning subscriber is SENT. It attaches nothing: the caller seats the cursor.
+
+import type { Clock } from '@ultimat3/core';
+import {
+  advance,
+  type LiveCursor,
+  type ReconnectBudget,
+  type ResumeSource,
+  resumeFrom,
+} from './cursor';
+import type { SnapshotResult } from './live-contract';
+import { snapshotFrame } from './live-fanout';
+import { fillWindow, type QueryEntry } from './query-window';
+import type { Subscriber, SubscriberGate } from './subscriber-gate';
+import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
+
+export interface ResumeOntoDeps {
+  readonly source: ResumeSource;
+  readonly budget?: ReconnectBudget | undefined;
+  readonly clock: Clock;
+  readonly gate: SubscriberGate;
+  /** The window, read once for the entry and filtered for THIS subscriber. */
+  read(): Promise<SnapshotResult>;
+}
+
+/**
+ * The frame a resuming subscriber needs and the cursor it is seated under. The caller has already
+ * established that `cursor` names THIS window: a cursor is client data, and one minted for another
+ * window is a cold start, never a replay of a ring this window does not own.
+ */
+export async function resumeOnto(
+  deps: ResumeOntoDeps,
+  entry: QueryEntry,
+  who: Subscriber,
+  cursor: LiveCursor,
+  now: number,
+): Promise<{ readonly cursor: LiveCursor; readonly frame: Frame }> {
+  const resumed = await resumeFrom(cursor, {
+    source: deps.source,
+    ...(deps.budget ? { budget: deps.budget } : {}),
+    clock: deps.clock,
+    snapshot: () => deps.read(),
+  });
+  if (resumed.kind !== 'delta') {
+    return {
+      cursor: resumed.cursor,
+      frame: snapshotFrame(entry, who.sid, resumed.rows, resumed.cursor),
+    };
+  }
+  // The gate decides about whole rows out of the shared window, and an entry nothing has read
+  // yet has none — every patch would meet an empty window and be withheld. Filling is
+  // conditional on purpose: a restart storm resumes onto entries that already hold a live
+  // window, and re-reading per resuming subscriber is the cost a delta resume exists to skip.
+  if (entry.lsn === '') await fillWindow(entry);
+  // The live entry on purpose: a resume runs outside the lane, so the window under it may
+  // have moved on — always forwards, and a row whose grant was revoked in the meantime is
+  // one this pass must refuse rather than replay from the state it had at the cursor's lsn.
+  const patches = await deps.gate.filterPatches(entry, who, resumed.patches, new Set(cursor.ids));
+  // Advanced over the FILTERED list, never over `resumed.cursor` — which `resumeFrom` built
+  // by advancing across the retained window, and that window is PRE-POLICY. Seated as it
+  // came back, this subscriber's `cursor.ids` gained the id of every row inserted for every
+  // OTHER actor while it was away; `subscriber-gate` then reads `held.has(patch.id)` off it,
+  // takes the "the subscriber holds this row" branch, and delivers a `delete` frame carrying
+  // another tenant's row id and the instant it went. The leak that branch closes, re-opened
+  // one layer up. `live-fanout.ts` advances over `allowed` for exactly this reason.
+  const seated = advance(cursor, patches, resumed.cursor.lsn, now);
+  return {
+    cursor: seated,
+    frame: { type: 'patch', v: PROTOCOL_VERSION, sid: who.sid, patches, lsn: seated.lsn },
+  };
+}

package/src/live-tenant.ts

@@ -0,0 +1,25 @@
+// Which tenant a live window belongs to, and the id that keeps two tenants' windows apart.
+//
+// A window is the SHARED, pre-policy read of one `(query, input)`. Shared across every subscriber
+// of one org it is the fan-out the pipeline is built on; shared across two orgs it is one org's
+// rows in a window the other is served from, with a row policy as the only thing in between. So
+// the tenant is part of the window's identity — the same place `@ultimat3/query`'s read cache puts
+// its authority — and the read under it runs in a context that carries that tenant
+// (`live-definition.ts`), which is where `@ultimat3/entity`'s guard takes it from on every surface.
+
+import type { Actor } from '@ultimat3/core';
+
+/** The org a subscriber's windows are read for. `null`: anonymous, or an actor in no org. */
+export function liveTenantOf(actor: Actor | null): string | null {
+  const orgId = actor?.orgId;
+  return typeof orgId === 'string' && orgId !== '' ? orgId : null;
+}
+
+/**
+ * One window's id: the query id, qualified by the tenant it is read for. JSON for the reason
+ * `readAuthority` gives — an org id is app data and may carry any separator, and a value that can
+ * spell a boundary can spell someone else's. An org-less window keeps the bare query id.
+ */
+export function windowId(queryId: string, tenant: string | null): string {
+  return tenant === null ? queryId : JSON.stringify([queryId, tenant]);
+}

package/src/nats-client.ts

@@ -81,6 +81,8 @@ export interface NatsClientOptions {
 export type NatsConnect = (options: NatsClientOptions) => Promise<NatsClient>;
 
 export const DEFAULT_NATS_PORT = 4222;
+
+const NATS_URL_FIX = 'export NATS_URL=nats://user:password@host:4222';
 export const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
 
 /**
@@ -92,9 +94,12 @@ export function parseNatsUrl(url: string): NatsTarget {
   try {
     parsed = new URL(url);
   } catch {
+    // The variable, never its value: a bus URL carries the credential, and an error is the one
+    // thing that reaches a log, `--json`, an agent transcript and a ticket. `parsePgUrl`'s rule.
     throw new TransportUnavailableError({
       transport: 'nats',
-      reason: `"${url}" is not a connection URL`,
+      reason: 'NATS_URL is not a connection URL',
+      fix: NATS_URL_FIX,
     });
   }
   if (parsed.protocol !== 'nats:' && parsed.protocol !== 'tls:') {
@@ -104,7 +109,11 @@ export function parseNatsUrl(url: string): NatsTarget {
     });
   }
   if (parsed.hostname === '') {
-    throw new TransportUnavailableError({ transport: 'nats', reason: `"${url}" has no host` });
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: 'NATS_URL has no host',
+      fix: NATS_URL_FIX,
+    });
   }
   const hasUser = parsed.username !== '';
   const hasPass = parsed.password !== '';

package/src/nats-open.ts

@@ -0,0 +1,9 @@
+// The production `NatsConnect`, as a door: the adapter and the `nats` library behind it — 65
+// vendor modules — are imported when a client is OPENED, never when this package is. Every role
+// of every app imports `@ultimat3/realtime/server`; only one configured for the NATS transport
+// ever opens a client.
+
+import type { NatsClient, NatsClientOptions } from './nats-client';
+
+export const openNatsClient = async (options: NatsClientOptions): Promise<NatsClient> =>
+  (await import('./nats-lib-client')).openNatsClient(options);

package/src/nats-transport.ts

@@ -17,7 +17,7 @@ import type { NatsClient, NatsConnect } from './nats-client';
 import { parseNatsUrl } from './nats-client';
 import { ensureKvBucket } from './nats-jetstream';
 import { NatsKvSet } from './nats-kv';
-import { openNatsClient } from './nats-lib-client';
+import { openNatsClient } from './nats-open';
 import { type BackoffPolicy, defaultBackoff, policyDelay, type Rng } from './thundering-herd';
 
 const encoder = new TextEncoder();
@@ -55,6 +55,7 @@ export class NatsTransport implements Transport {
   #dialing: Promise<NatsClient> | undefined;
   #retries = 0;
   #closed = false;
+  readonly #reconnectListeners = new Set<() => void>();
 
   constructor(options: NatsTransportOptions) {
     // Parsed here rather than at the first publish: a malformed NATS_URL is a boot-time fault, and
@@ -116,6 +117,19 @@ export class NatsTransport implements Transport {
     return { subject, unsubscribe: () => live.unsubscribe() };
   }
 
+  /**
+   * Told every time the client comes back from a drop. Fanout is at-most-once, so the gap between
+   * the drop and this call is changes the subscriber never saw — and with no later message there
+   * is no sequence number to notice it by. A `sync` node invalidates its windows on it. Returns
+   * the unsubscribe.
+   */
+  onReconnect(listener: () => void): () => void {
+    this.#reconnectListeners.add(listener);
+    return () => {
+      this.#reconnectListeners.delete(listener);
+    };
+  }
+
   async close(): Promise<void> {
     this.#closed = true;
     const client = this.#client;
@@ -200,7 +214,15 @@ export class NatsTransport implements Transport {
     this.#retries = 0;
     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));
+    for (const listener of [...this.#reconnectListeners]) {
+      try {
+        listener();
+      } catch (error) {
+        this.#report(error, this.name);
+      }
+    }
   }
 
   /**