@ultimat3/realtime 30.9.0 → 31.1.0

package/src/offline-queue.ts

@@ -10,72 +10,22 @@
 //      `ack`/`fail` frame settles it, or a lost connection returns it to the queue.
 
 import type { ActionPin } from '@ultimat3/core/page';
-import { renderThrowable, stringField } from '@ultimat3/core/page';
+import { finiteCount, renderThrowable, stringField } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
-import { OfflineQueueAbandonedError } from './page-errors';
+import type { MutationStatus, QueuedMutation, QueueState, QueueStore } from './offline-queue-store';
+import { OfflineQueueAbandonedError, OfflineQueueFullError } from './page-errors';
 import type { WireError } from './sync-protocol';
 
-export type MutationStatus = 'pending' | 'inflight' | 'acked' | 'failed';
-
-export interface QueuedMutation {
-  /** Idempotency key. Supplied by the mutator, stable across retries and reloads. */
-  readonly key: string;
-  /** Monotonic per client. Never renumbered — rebase replays in this order. */
-  readonly seq: number;
-  readonly name: string;
-  readonly input: JsonValue;
-  /** The action's `http` pin, when the write was made against one (`pinned-wire.ts`). */
-  readonly http?: ActionPin | undefined;
-  readonly enqueuedAt: number;
-  attempts: number;
-  status: MutationStatus;
-  error: WireError | null;
-}
-
-export interface QueueState {
-  readonly mutations: readonly QueuedMutation[];
-  readonly nextSeq: number;
-}
-
-/**
- * One change to the durable queue: these entries written BY KEY, these keys deleted, and the
- * sequence floor. Never the whole queue — two tabs of one user share the store, and a whole-queue
- * save let the last tab to save erase the other's queued write.
- */
-export interface QueueChange {
-  readonly puts: readonly QueuedMutation[];
-  readonly deletes: readonly string[];
-  readonly nextSeq: number;
-}
-
-/** Durability seam: IndexedDB in the browser (`page-outbox.ts`), memory in tests. */
-export interface QueueStore {
-  load(): Promise<QueueState>;
-  write(change: QueueChange): Promise<void>;
-}
-
-export class MemoryQueueStore implements QueueStore {
-  readonly #mutations = new Map<string, QueuedMutation>();
-  #nextSeq = 1;
-
-  async load(): Promise<QueueState> {
-    return {
-      mutations: [...this.#mutations.values()].map((m) => ({ ...m })),
-      nextSeq: this.#nextSeq,
-    };
-  }
-
-  async write(change: QueueChange): Promise<void> {
-    for (const key of change.deletes) this.#mutations.delete(key);
-    for (const mutation of change.puts) this.#mutations.set(mutation.key, { ...mutation });
-    this.#nextSeq = Math.max(this.#nextSeq, change.nextSeq);
-  }
-}
-
-/** The one way to build the in-process queue store; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
-export function memoryQueueStore(): MemoryQueueStore {
-  return new MemoryQueueStore();
-}
+// The shapes and the memory store moved next door; their importers keep this path.
+export {
+  MemoryQueueStore,
+  type MutationStatus,
+  memoryQueueStore,
+  type QueueChange,
+  type QueuedMutation,
+  type QueueState,
+  type QueueStore,
+} from './offline-queue-store';
 
 export interface DrainReport {
   readonly sent: number;
@@ -87,9 +37,25 @@ export interface DrainReport {
 
 export type MutationSender = (mutation: QueuedMutation) => Promise<void>;
 
+export interface OfflineQueueOptions {
+  /**
+   * The most writes held at once. Past it a NEW key is refused (`X_OFFLINE_QUEUE_FULL`); a key
+   * already held still collapses, and nothing queued is ever dropped. Absent: no ceiling.
+   */
+  readonly maxQueued?: number | undefined;
+}
+
 export class OfflineQueue {
   readonly #store: QueueStore;
-  #mutations: QueuedMutation[] = [];
+  readonly #maxQueued: number | undefined;
+  /**
+   * By key, HELD in sequence order: a key is a lookup and the queue reads in seq order with no sort.
+   * A scan per enqueue and ack plus a sort per `pending()` made a long offline session quadratic.
+   * Written through `#seat` and `#append` only, which are what keep the order true.
+   */
+  #mutations = new Map<string, QueuedMutation>();
+  /** The highest seq held: an append above it keeps the order without a sort. */
+  #tailSeq = 0;
   #nextSeq = 1;
   #collapsed = 0;
   /** The drain lane: one pass at a time, in call order. See `drain`. */
@@ -106,9 +72,12 @@ export class OfflineQueue {
   #writing = 0;
   #written = 0;
 
-  private constructor(store: QueueStore, state: QueueState) {
+  private constructor(store: QueueStore, state: QueueState, options: OfflineQueueOptions) {
     this.#store = store;
-    this.#mutations = state.mutations.map((mutation) => ({ ...mutation }));
+    const max = options.maxQueued;
+    this.#maxQueued =
+      max === undefined ? undefined : finiteCount('OfflineQueue', 'maxQueued', max, 1);
+    this.#seat(state.mutations.map((mutation) => ({ ...mutation })));
     this.#nextSeq = state.nextSeq;
   }
 
@@ -122,8 +91,8 @@ export class OfflineQueue {
    * write the old page did get through is answered from the action's idempotency store and is
    * never applied twice. That requirement is what makes this resend safe, not the key alone.
    */
-  static async open(store: QueueStore): Promise<OfflineQueue> {
-    const queue = new OfflineQueue(store, await store.load());
+  static async open(store: QueueStore, options: OfflineQueueOptions = {}): Promise<OfflineQueue> {
+    const queue = new OfflineQueue(store, await store.load(), options);
     await queue.#reclaimInflight();
     return queue;
   }
@@ -137,7 +106,7 @@ export class OfflineQueue {
   async reload(): Promise<void> {
     if (this.#abandoned) return;
     const state = await this.#store.load();
-    this.#mutations = state.mutations.map((mutation) => ({ ...mutation }));
+    this.#seat(state.mutations.map((mutation) => ({ ...mutation })));
     this.#nextSeq = Math.max(this.#nextSeq, state.nextSeq);
     await this.#reclaimInflight();
   }
@@ -162,7 +131,7 @@ export class OfflineQueue {
   #adopt(state: QueueState): void {
     const onDisk = new Map(state.mutations.map((mutation) => [mutation.key, mutation]));
     const kept: QueuedMutation[] = [];
-    for (const mutation of this.#mutations) {
+    for (const mutation of this.#mutations.values()) {
       const disk = onDisk.get(mutation.key);
       onDisk.delete(mutation.key);
       // Gone from the disk: another tab's pass settled it. One on THIS tab's wire stays its own.
@@ -174,18 +143,42 @@ export class OfflineQueue {
       kept.push(mutation);
     }
     for (const disk of onDisk.values()) kept.push({ ...disk });
-    this.#mutations = kept;
+    this.#seat(kept);
     this.#nextSeq = Math.max(this.#nextSeq, state.nextSeq);
   }
 
+  /** The whole queue replaced — a load, a reload, a refresh: sorted ONCE here, never on a read. */
+  #seat(mutations: readonly QueuedMutation[]): void {
+    const ordered = [...mutations].sort((a, b) => a.seq - b.seq);
+    this.#mutations = new Map(ordered.map((mutation) => [mutation.key, mutation]));
+    this.#tailSeq = ordered.at(-1)?.seq ?? 0;
+  }
+
+  /** One new entry. Its seq is the queue's newest in every path today; one that is not re-seats. */
+  #append(mutation: QueuedMutation): void {
+    if (mutation.seq > this.#tailSeq) {
+      this.#mutations.set(mutation.key, mutation);
+      this.#tailSeq = mutation.seq;
+      return;
+    }
+    this.#seat([...this.#mutations.values(), mutation]);
+  }
+
+  /** Is this the entry the queue holds for its key? Identity: a re-issued key is another entry. */
+  #holds(mutation: QueuedMutation): boolean {
+    return this.#mutations.get(mutation.key) === mutation;
+  }
+
   async #reclaimInflight(): Promise<void> {
-    const reclaimed = this.#mutations.filter((mutation) => mutation.status === 'inflight');
+    const reclaimed = [...this.#mutations.values()].filter(
+      (mutation) => mutation.status === 'inflight',
+    );
     for (const mutation of reclaimed) mutation.status = 'pending';
     if (reclaimed.length > 0) await this.#persist(reclaimed);
   }
 
   get size(): number {
-    return this.#mutations.length;
+    return this.#mutations.size;
   }
 
   get collapsed(): number {
@@ -197,7 +190,7 @@ export class OfflineQueue {
   }
 
   find(key: string): QueuedMutation | undefined {
-    return this.#mutations.find((mutation) => mutation.key === key);
+    return this.#mutations.get(key);
   }
 
   /**
@@ -205,13 +198,13 @@ export class OfflineQueue {
    * anything downstream is allowed to use, and the count a UI renders as "unsynced".
    */
   pending(): readonly QueuedMutation[] {
-    return this.#mutations
-      .filter((mutation) => mutation.status === 'pending' || mutation.status === 'inflight')
-      .sort((a, b) => a.seq - b.seq);
+    return [...this.#mutations.values()].filter(
+      (mutation) => mutation.status === 'pending' || mutation.status === 'inflight',
+    );
   }
 
   all(): readonly QueuedMutation[] {
-    return [...this.#mutations].sort((a, b) => a.seq - b.seq);
+    return [...this.#mutations.values()];
   }
 
   async enqueue(args: {
@@ -237,12 +230,21 @@ export class OfflineQueue {
       this.#collapsed += 1;
       return existing;
     }
+    // After the collapse, never before it: a held key — even a failed one re-issued in place — is
+    // no new write. Refused, never made room for: a dropped entry is an intent the user saw saved.
+    // Counted as `pending()` counts — still to send: a refused entry kept for the UI never drains,
+    // and counting it filled the queue for good, across reloads. Walked only once at the size.
+    const max = this.#maxQueued;
+    const full = max !== undefined && this.#mutations.size >= max && this.pending().length >= max;
+    if (existing === undefined && full) {
+      throw new OfflineQueueFullError({ name: args.name, maxQueued: max });
+    }
     // A terminally failed entry is a decision the server already made about this key, kept for the
     // UI — collapsing onto it makes an explicit idempotency key unusable for the rest of the
     // session, because nothing ever retries a denial. Re-issuing one is a NEW intent, so the old
     // entry is dropped and this one takes a new sequence at the back of the queue.
     // By identity: `existing` IS the entry for this key, found above — no second key comparison.
-    if (existing) this.#mutations = this.#mutations.filter((entry) => entry !== existing);
+    if (existing) this.#mutations.delete(existing.key);
     const mutation: QueuedMutation = {
       key: args.key,
       seq: this.#nextSeq,
@@ -255,7 +257,7 @@ export class OfflineQueue {
       error: null,
     };
     this.#nextSeq += 1;
-    this.#mutations.push(mutation);
+    this.#append(mutation);
     await this.#persist([mutation]);
     return mutation;
   }
@@ -302,7 +304,7 @@ export class OfflineQueue {
     this.#epoch += 1;
     let returned = 0;
     const back: QueuedMutation[] = [];
-    for (const mutation of this.#mutations) {
+    for (const mutation of this.#mutations.values()) {
       if (mutation.status !== 'inflight') continue;
       mutation.status = 'pending';
       returned += 1;
@@ -333,8 +335,7 @@ export class OfflineQueue {
     const mutation = this.find(key);
     if (!mutation) return;
     mutation.status = 'acked';
-    // By identity: `find` already matched it, and a second comparison of the key is the same question.
-    this.#mutations = this.#mutations.filter((entry) => entry !== mutation);
+    this.#mutations.delete(key);
     await this.#persist([], [key]);
   }
 
@@ -361,14 +362,12 @@ export class OfflineQueue {
    * nothing at all.
    */
   #stillSendable(mutation: QueuedMutation): boolean {
-    return mutation.status === 'pending' && this.#mutations.includes(mutation);
+    return mutation.status === 'pending' && this.#holds(mutation);
   }
 
   /** Never sent on this connection. `inflight` is excluded: it is already on a socket. */
   #sendable(): readonly QueuedMutation[] {
-    return this.#mutations
-      .filter((mutation) => mutation.status === 'pending')
-      .sort((a, b) => a.seq - b.seq);
+    return [...this.#mutations.values()].filter((mutation) => mutation.status === 'pending');
   }
 
   /** One drain pass. Never called concurrently with itself — `drain` owns that. */
@@ -417,7 +416,7 @@ export class OfflineQueue {
       } catch (error) {
         // Settled inside `send` before it threw (the page outbox acks or fails it, then a merge may
         // raise): writing it back as `pending` would replay what the server already decided.
-        if (this.#mutations.includes(mutation) && statusOf(mutation) !== 'failed') {
+        if (this.#holds(mutation) && statusOf(mutation) !== 'failed') {
           mutation.status = 'pending';
           mutation.error = toQueueError(error);
           await this.#persist([mutation]);
@@ -432,7 +431,7 @@ export class OfflineQueue {
     }
     // Only what this pass touched AND the queue still holds: an entry the server settled during the
     // pass was already deleted by `ack`, and writing it back would resurrect it.
-    await this.#persist(touched.filter((mutation) => this.#mutations.includes(mutation)));
+    await this.#persist(touched.filter((mutation) => this.#holds(mutation)));
     return {
       sent,
       collapsed: this.#collapsed,
@@ -442,8 +441,9 @@ export class OfflineQueue {
   }
 
   async clear(): Promise<void> {
-    const keys = this.#mutations.map((mutation) => mutation.key);
-    this.#mutations = [];
+    const keys = [...this.#mutations.keys()];
+    this.#mutations = new Map();
+    this.#tailSeq = 0;
     await this.#persist([], keys);
   }
 

package/src/page-errors.ts

@@ -109,6 +109,21 @@ export class OfflineQueueAbandonedError extends RealtimeError {
   }
 }
 
+/**
+ * A write made while the outbox already holds its `maxQueued` unsent writes. REFUSED to the caller
+ * that made it, never made room for: dropping a queued write would lose an intent the user was
+ * shown as saved. A key already queued is no new write and is never refused.
+ */
+export class OfflineQueueFullError extends RealtimeError {
+  constructor(args: { name: string; maxQueued: number }) {
+    super({
+      code: 'X_OFFLINE_QUEUE_FULL',
+      cause: `the write "${args.name}" was refused: the offline queue already holds ${args.maxQueued} unsent writes (maxQueued), and none is dropped to make room — call the mutation again once the page is back online`,
+      fix: 'OfflineQueue.open(store, { maxQueued })   # raise the ceiling, or let the page reconnect so the queue drains',
+    });
+  }
+}
+
 /**
  * Something that can only mean "talk to the socket" ran on the server client — a mutation, a
  * publish, a topic subscription, a dial. There is no socket during a server render and there never

package/src/page-outbox.ts

@@ -8,6 +8,7 @@ import type { ClientScope, UltimateError } from '@ultimat3/core/page';
 import {
   classifyThrown,
   clientTransport,
+  finiteCount,
   OUTBOX_DRAIN_MESSAGE,
   onRescope,
   pageClient,
@@ -74,6 +75,11 @@ export interface OutboxOptions {
   readonly tabs?: ((heard: (scope: string | null) => void) => OutboxTabs) | undefined;
   /** Where a disk that refused the queue is said, by code. Default `console.warn`. */
   readonly warn?: ((error: UltimateError) => void) | undefined;
+  /**
+   * The most writes queued at once, on every queue this outbox opens. Past it a NEW write is
+   * refused (`X_OFFLINE_QUEUE_FULL`) and nothing queued is dropped. Absent: no ceiling.
+   */
+  readonly maxQueued?: number | undefined;
 }
 
 const EMPTY: DrainReport = { sent: 0, collapsed: 0, remaining: 0, stoppedAt: null };
@@ -88,6 +94,12 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
   const principal =
     options.principal ?? ((): ClientScope['principal'] => pageClient().scope.principal);
   const send = options.send ?? sendOverHttp;
+  // Refused HERE, where the outbox is built: inside `open` a bad ceiling would read as a refused
+  // disk, and the memory fallback would throw it again with nobody to catch it.
+  const ceiling =
+    options.maxQueued === undefined
+      ? {}
+      : { maxQueued: finiteCount('localOutbox', 'maxQueued', options.maxQueued, 1) };
   const overlays =
     options.overlays ?? ((): OutboxOverlays | undefined => peekPageRealtime()?.store);
   /**
@@ -142,10 +154,10 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
     const scope = scopeKey(principal());
     let queue: OfflineQueue;
     try {
-      queue = await OfflineQueue.open(queueStore(await options.local, scope));
+      queue = await OfflineQueue.open(queueStore(await options.local, scope), ceiling);
     } catch (error) {
       unavailable('the outbox could not be opened', error);
-      queue = await OfflineQueue.open(memoryQueueStore());
+      queue = await OfflineQueue.open(memoryQueueStore(), ceiling);
     }
     // The principal left while the disk was being read: this queue is the one that left with it,
     // and the handler that saw the change has already chained the next open.
@@ -390,7 +402,9 @@ async function sendOverHttp(entry: OutboxEntry, carried: Set<string>): Promise<u
  * The page's outbox, created once per tab. In a browser it replays on open, on `online`, and on the
  * service worker's drain message; with no `document` it is a memory queue that listens for nothing.
  */
-export function pageOutbox(options: Pick<OutboxOptions, 'beforeEnqueue'> = {}): PageOutbox {
+export function pageOutbox(
+  options: Pick<OutboxOptions, 'beforeEnqueue' | 'maxQueued'> = {},
+): PageOutbox {
   const host = globalThis as OutboxHost;
   const existing = host[OUTBOX_KEY];
   // Only this function writes the slot, so what it holds is always a `PageOutbox`.
@@ -399,6 +413,7 @@ export function pageOutbox(options: Pick<OutboxOptions, 'beforeEnqueue'> = {}):
   const outbox = localOutbox({
     local: pageLocalStore(),
     beforeEnqueue: options.beforeEnqueue,
+    maxQueued: options.maxQueued,
     // Every tab of this user shares the durable queue; each re-reads it when another changes it.
     ...(browser ? { tabs: (heard) => outboxTabs(globalThis as OutboxTabsWindow, heard) } : {}),
   });

package/src/pg-connection.ts

@@ -124,7 +124,15 @@ export class PgConnection {
       // or role default like `America/New_York` writes a pre-1883 instant at its LMT offset,
       // `-04:56:02`. The decoder reads that too, but UTC text is the one form with no ambient zone
       // in it — and a client option outranks every server-side default, `ALTER ROLE … SET` included.
-      options: '-c datestyle=ISO -c intervalstyle=postgres -c extra_float_digits=3 -c TimeZone=UTC',
+      //
+      // Then the SERVER's TCP keepalives. Both sessions this opens are held idle for hours — the
+      // replicator's advisory lock IS its session — and a holder lost without a FIN (a failover
+      // moving the address, a NAT drop) kept the lock until the OS default, ~2 h 11 m: no standby
+      // took over. Probed after 10 s idle, every 5 s, dead after 3 misses — ~25 s. Ignored, not
+      // refused, on a Unix socket, where there is no TCP to probe.
+      options:
+        '-c datestyle=ISO -c intervalstyle=postgres -c extra_float_digits=3 -c TimeZone=UTC ' +
+        '-c tcp_keepalives_idle=10 -c tcp_keepalives_interval=5 -c tcp_keepalives_count=3',
     };
     if (options.replication !== undefined) parameters['replication'] = options.replication;
     // A handshake fails on ordinary conditions — no password, an ErrorResponse, an EOF — and on

package/src/pg-preflight.ts

@@ -4,10 +4,15 @@
 // stop every app on the default replica identity from starting.
 
 import { logger } from '@ultimat3/core';
-import { ReplicaIdentityError, ReplicationFailedError } from './errors';
+import {
+  ReplicaIdentityError,
+  ReplicationFailedError,
+  ReplicationSlotInvalidatedError,
+} from './errors';
 import type { PgConnection } from './pg-connection';
 import { assertIdentifier } from './pg-identifier';
 import { ensurePublication } from './pg-publication';
+import { awaitSlotReleased } from './pg-slot-release';
 
 /**
  * The four things that are always misconfigured. `wal_level` and the slot produce an unreadable
@@ -17,13 +22,16 @@ import { ensurePublication } from './pg-publication';
  * simple queries, so the identifier charset is the injection boundary; re-asserted here rather than trusted, so the guarantee
  * travels with the function instead of living only in `start()`.
  */
+/** What preflight found the slot as: there already, or created just now by this call. */
+export type SlotState = 'existing' | 'created';
+
 export async function preflight(
   connection: PgConnection,
   slot: string,
   publication: string,
   entities: ReadonlySet<string>,
   fullIdentity: ReadonlySet<string> = new Set(),
-): Promise<void> {
+): Promise<SlotState> {
   assertIdentifier('slot', slot);
   assertIdentifier('publication', publication);
   const [walLevel] = await connection.query('SHOW wal_level');
@@ -39,14 +47,19 @@ export async function preflight(
   await ensurePublication(connection, publication, entities);
   await warnPartialIdentity(connection, entities);
   await warnChannelIdentity(connection, entities, fullIdentity);
+  // `wal_status` in the same statement: `lost` is a slot postgres invalidated, which no restart
+  // can stream from — said with its own code, never as the generic failure START_REPLICATION gives.
+  // `active_pid` too: a walsender still on its way out holds the slot, and START_REPLICATION would
+  // refuse a restart right behind it with 55006 (`pg-slot-release.ts`).
   const [existing] = await connection.query(
-    `SELECT plugin FROM pg_replication_slots WHERE slot_name = '${slot}'`,
+    `SELECT plugin, wal_status, active_pid FROM pg_replication_slots WHERE slot_name = '${slot}'`,
   );
   if (existing === undefined) {
     // Plain SQL rather than CREATE_REPLICATION_SLOT: the replication command exports a snapshot
-    // that pins xmin for the session, and its option syntax changed in postgres 15.
+    // that pins xmin for the session, and its option syntax changed in postgres 15. The caller
+    // decides what a NEW slot means — a resume position it had is now a gap (`pg-replication-dial.ts`).
     await connection.query(`SELECT pg_create_logical_replication_slot('${slot}', 'pgoutput')`);
-    return;
+    return 'created';
   }
   if (existing[0] !== 'pgoutput') {
     throw new ReplicationFailedError({
@@ -55,6 +68,9 @@ export async function preflight(
       fix: `SELECT pg_drop_replication_slot('${slot}'); -- then start the replicator again`,
     });
   }
+  if (existing[1] === 'lost') throw new ReplicationSlotInvalidatedError({ slot });
+  await awaitSlotReleased(connection, slot, existing[2]);
+  return 'existing';
 }
 
 /**

package/src/pg-replication-dial.ts

@@ -0,0 +1,95 @@
+// Single responsibility: bring one replication stream up — open the walsender session, preflight
+// it, and START_REPLICATION from the right place — and say whether the resume position it was
+// handed still means anything. Reading the stream once it is up is `pg-replication.ts`'s.
+
+import { logger } from '@ultimat3/core';
+import type { PostgresChangeFeedOptions } from './changefeed';
+import { ReplicationSlotRecreatedError } from './errors';
+import { printLsn } from './pg-bytes';
+import { PgConnection } from './pg-connection';
+import { paramsChannelTables } from './pg-identity-tables';
+import { preflight } from './pg-preflight';
+import { commitPositionOf } from './pg-replication-position';
+import { bunPgStream, parsePgUrl } from './pg-socket';
+
+/** The identifiers the stream already put through `assertIdentifier`. */
+export interface StreamNames {
+  readonly slot: string;
+  readonly publication: string;
+  readonly entities: ReadonlySet<string>;
+}
+
+/**
+ * A slot this stream created under a resume position, carried until a dial gets through. A dial
+ * that created it and then failed (START_REPLICATION refused, the socket dropped) leaves the next
+ * one finding it EXISTING — and the gap no smaller. Owned by the stream, written here.
+ */
+export interface SlotGap {
+  createdUnder: string | null;
+}
+
+export interface DialedStream {
+  readonly connection: PgConnection;
+  /** Where START_REPLICATION began — what the stream confirms until its first commit. */
+  readonly confirmed: bigint;
+  /** The resume filter for this run: `undefined` once the slot it pointed into is gone. */
+  readonly from: string | undefined;
+  /** Why every reader must re-read now, or `null` when the stream is continuous. */
+  readonly resync: string | null;
+}
+
+/**
+ * Open, preflight, START_REPLICATION. On any failure after the socket opened, the session is closed
+ * before the failure is rethrown: the dial failure explains the boot, a close that also failed
+ * does not, and nothing is left holding the slot.
+ */
+export async function dialReplication(
+  options: PostgresChangeFeedOptions,
+  names: StreamNames,
+  from: string | undefined,
+  gap: SlotGap,
+): Promise<DialedStream> {
+  const target = parsePgUrl(options.url);
+  const stream = await (options.stream ?? bunPgStream)(target);
+  const connection = await PgConnection.open({
+    stream,
+    user: target.user,
+    password: target.password,
+    database: target.database,
+    replication: 'database',
+    applicationName: `ultimate-replicator:${names.slot}`,
+    rng: options.rng,
+    ssl: target.ssl,
+  });
+  try {
+    const full = new Set(options.fullIdentityTables ?? paramsChannelTables());
+    const slot = await preflight(connection, names.slot, names.publication, names.entities, full);
+    // A NEW slot under a resume position is a gap: it starts at the server's current WAL, so the
+    // changes between the old confirm and now were never streamed — and after a failover the old
+    // position is another server's WAL, so it must neither start the stream nor filter it.
+    if (slot === 'created' && from !== undefined) gap.createdUnder ??= from;
+    const under = from === undefined ? null : gap.createdUnder;
+    const recreated = under !== null;
+    const resumeFrom = recreated ? undefined : from;
+    if (recreated) {
+      const said = new ReplicationSlotRecreatedError({ slot: names.slot, from: under });
+      // FIELDS, never interpolation; the message is the CODE alone (`pg-preflight.ts`).
+      logger.warn(said.code, { cause: said.cause, fix: said.fix, slot: names.slot, from: under });
+    }
+    const confirmed = resumeFrom === undefined ? 0n : commitPositionOf(resumeFrom);
+    await connection.startCopyBoth(
+      `START_REPLICATION SLOT ${names.slot} LOGICAL ${printLsn(confirmed)} ` +
+        `(proto_version '1', publication_names '${names.publication}', messages 'true')`,
+    );
+    // Through: the gap is the caller's to say now, and no later dial owes it again.
+    gap.createdUnder = null;
+    const resync = recreated
+      ? `replication slot "${names.slot}" was recreated under resume position ${under}: ` +
+        'the changes in between were never streamed'
+      : null;
+    return { connection, confirmed, from: resumeFrom, resync };
+  } catch (failure) {
+    await connection.close().catch(() => undefined);
+    throw failure;
+  }
+}