@ultimat3/realtime 23.0.0 → 24.0.0

package/src/live-definition.ts

@@ -27,8 +27,10 @@ export interface LiveDefinitionOptions {
    */
   readonly ctx: Ctx;
   /**
-   * Where the shared window sits in the change stream, asked at snapshot time. Without a feed
-   * position a reconnect can only re-snapshot, so a node with a replicator should pass its lsn.
+   * Where the shared window sits in the change stream, asked at snapshot time — the node's newest
+   * received change (`registry.lastLsn`). Omitted, or answering `''` before the first change, the
+   * snapshot claims no position and the retained ring is floored by its first patch instead: a
+   * cursor minted before that patch re-snapshots, one that received it resumes as a delta.
    */
   readonly lsn?: () => string;
   /** Pins the reconnect epoch in tests; the server derives it from the build. */
@@ -165,6 +167,9 @@ export function liveQueryDefinition(
       // The position is taken BEFORE the rows: the rows are then at least that new, so the claim
       // is true. Taken after, a commit landing mid-read was claimed and missing — and every change
       // up to it is dropped downstream as already folded.
+      // `''` when the node holds no position — no `lsn` option, or no change received yet. Never
+      // a made-up one: a position the node never held becomes a ring floor every foreign cursor
+      // is "inside", and the client that resumed there kept rows this node never patched.
       const lsn = options.lsn?.() ?? '';
       return { rows: await readFor(options.ctx, tenant, () => window.read()), lsn };
     },
@@ -191,15 +196,25 @@ function evictOldest(windows: Map<string, SharedWindow>, max: number): void {
 }
 
 /**
- * Rows crossing the wire are addressed by `id` — patches, cursors and the local store all key on
- * it. A projection without one is refused here rather than delivered as a row nobody can patch:
- * the alternative is a subscription that appears to work until the first update.
+ * Rows crossing the wire are addressed by a TEXT `id` — patches, cursors and the local store all
+ * key on it. A safe-integer id is stringified, the one normalisation the change feed applies to the
+ * same row (`pg-replication.ts`'s `toRow`), so a snapshot row and its later patch name one identity.
+ * Anything else is refused here rather than delivered as a row nobody can patch.
  */
 function rowsOf(query: string, rows: readonly object[]): readonly Row[] {
   const out: Row[] = [];
   for (const row of rows) {
-    if (!isRow(row)) throw new LiveRowUnidentifiedError({ query, keys: Object.keys(row) });
-    out.push(row);
+    const id: unknown = (row as { id?: unknown }).id;
+    const candidate =
+      typeof id === 'number' && Number.isSafeInteger(id) ? { ...row, id: String(id) } : row;
+    if (!isRow(candidate)) {
+      throw new LiveRowUnidentifiedError({
+        query,
+        keys: Object.keys(row),
+        ...(id === undefined || id === null ? {} : { idType: typeof id }),
+      });
+    }
+    out.push(candidate);
   }
   return out;
 }

package/src/live-fanout.ts

@@ -8,7 +8,7 @@ import type { ChangeEvent } from './changefeed';
 import { advance, type LiveCursor, makeCursor, type ResumeSource } from './cursor';
 import type { Row, RowPatch } from './json';
 import type { LiveSubscription } from './live-contract';
-import { applyToWindow, bridgeChange } from './matcher-bridge';
+import { applyToWindow, bridgeChange, type Projection, projectionOf } from './matcher-bridge';
 import { type QueryEntry, refillWindowInLane } from './query-window';
 import { type Subscriber, type SubscriberGate, windowIndex } from './subscriber-gate';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
@@ -50,6 +50,8 @@ export async function fanoutChange(
   const reread = entry.stale;
   if (reread) {
     await refillWindowInLane(entry);
+    // What was retained before this read has a hole exactly where the staleness came from.
+    deps.source.floorAt?.(entry.qid, entry.lsn, { exclusive: true });
     // Every subscriber was fed from the rows this read just replaced, so each is owed a snapshot —
     // not only the ones `invalidate()` marked: a read that failed or timed out stales the window
     // and marks nobody.
@@ -72,19 +74,26 @@ export async function fanoutChange(
   if (!bridged) return { sent: reread ? await resnapshotAll(deps, entry) : 0, stale: 0 };
   // Keyed ONCE, here, before the retained window stores them: a resume replays the same key.
   const result = { ...bridged, patches: keyPatches(entry, change, bridged.patches) };
+  // Asked of the window as it stood BEFORE this change: the partial row must not teach it a shape.
+  const partial = lacksOmitted(change, result.patches, projectionOf(entry.rows));
   entry.lsn = change.lsn;
   entry.rows = applyToWindow(entry.rows, result.patches);
-  // The window lost its tail, so what it holds is a guess — the next delivery re-reads it rather
-  // than patching a guess, and every subscriber below is re-snapshotted out of what that returns.
-  if (result.refill) entry.stale = true;
-  // The retained window holds the pre-policy patch; resume re-filters it per subscriber.
-  for (const patch of result.patches) deps.source.append(entry.qid, patch);
+  // The window lost its tail — or adopted a row the change could not carry whole — so what it
+  // holds is a guess: the next delivery re-reads it rather than patching a guess, and every
+  // subscriber below is re-snapshotted out of what that returns.
+  const guessed = result.refill || partial;
+  if (guessed) entry.stale = true;
+  // The retained window holds the pre-policy patch; resume re-filters it per subscriber. A partial
+  // row is never retained: replayed, it is the same missing column on a resuming client.
+  if (!partial) for (const patch of result.patches) deps.source.append(entry.qid, patch);
+  // And the ring says so now, not at the re-read: a resume in between got a delta lacking it.
+  else deps.source.floorAt?.(entry.qid, change.lsn, { exclusive: true });
 
   let sent = 0;
   // Indexed once for every subscriber below, never searched per subscriber per patch.
   const index = windowIndex(entry.rows);
   for (const subscription of entry.subscribers.values()) {
-    if (result.refill) {
+    if (guessed) {
       // The window lost its tail: guessing is how a sync engine silently diverges. Checked BEFORE
       // the mark, because a repair reads `entry.rows` — which this fanout has just declared a
       // guess — and then CLEARS the mark. A subscriber already diverged would be recorded as
@@ -139,6 +148,32 @@ export async function fanoutChange(
   return { sent, stale: 0 };
 }
 
+/**
+ * Whether a row ENTERS the window without a column the change did not carry
+ * (`ChangeEvent.omitted`: an unchanged out-of-line value Postgres logged no bytes for). An update
+ * patch is safe — it merges onto a window row that already holds the column — but an add adopts
+ * the row as the whole row, into the window, every later snapshot and the retained ring. An
+ * unread projection (an empty window) cannot rule a column out, so every omitted one counts.
+ */
+function lacksOmitted(
+  change: ChangeEvent,
+  patches: readonly RowPatch[],
+  projection: Projection,
+): boolean {
+  const omitted = change.omitted;
+  if (omitted === undefined || omitted.length === 0) return false;
+  return patches.some(
+    (patch) =>
+      patch.op === 'insert' &&
+      patch.row !== null &&
+      omitted.some(
+        (column) =>
+          (projection === undefined || projection.has(column)) &&
+          !Object.hasOwn(patch.row ?? {}, column),
+      ),
+  );
+}
+
 /**
  * Every row of a relation this window reads is gone. There is nothing to patch from — a truncate
  * names no row — so the window is re-read now, in the lane, and every subscriber is re-snapshotted
@@ -153,6 +188,7 @@ async function truncated(
   if (!entry.shape.entities.includes(change.entity)) return { sent: 0, stale: 0 };
   await refillWindowInLane(entry);
   if (change.lsn > entry.lsn) entry.lsn = change.lsn;
+  deps.source.floorAt?.(entry.qid, entry.lsn, { exclusive: true });
   for (const subscription of entry.subscribers.values()) {
     subscription.socket.markDesynced(subscription.sid);
   }

package/src/live-floor.ts

@@ -0,0 +1,35 @@
+// What a window read that just returned owes the retained ring, and the position the subscriber it
+// serves is told. The rule itself is `change-buffer.ts`'s (`Ring`); this is its one caller for a
+// read, split from `live-query.ts` at that file's size ceiling.
+
+import type { ResumeSource } from './cursor';
+import type { FilledWindow, QueryEntry } from './query-window';
+
+export interface NodePosition {
+  /** The newest change this node has received; `''` before the first. */
+  readonly lastLsn: string;
+  /** This node's own mark for a read with no position behind it. Sorts below every real lsn. */
+  readonly origin: string;
+}
+
+/**
+ * Synchronous on purpose: the caller awaits a policy pass next, and the position has to be the
+ * one these ROWS were read at — read after that await, a change folded in meanwhile would be
+ * claimed by a snapshot that does not hold it.
+ */
+export function floorAfterRead(
+  source: ResumeSource,
+  entry: QueryEntry,
+  window: FilledWindow,
+  node: NodePosition,
+): string {
+  // Served out of a window that was already filled: its patch history is still true.
+  if (window.landed === null) return window.lsn;
+  // A read with no position behind it is marked with this node's own origin, so the cursor it
+  // mints is one no other node could have issued.
+  const lsn = window.lsn === '' ? node.origin : window.lsn;
+  if (entry.lsn === '') entry.lsn = lsn;
+  if (window.landed === 'forced') source.floorAt?.(entry.qid, lsn, { exclusive: true });
+  else source.floorAt?.(entry.qid, lsn, { sole: node.lastLsn === '' || window.lsn === '' });
+  return lsn;
+}

package/src/live-query-options.ts

@@ -0,0 +1,38 @@
+// What a `LiveQueryRegistry` is built from, and the one ceiling it defaults. Split from
+// `live-query.ts` at that file's size ceiling: the registry owns behaviour, this owns its knobs.
+
+import type { Actor, Clock } from '@ultimat3/core';
+import type { ReconnectBudget, ResumeSource } from './cursor';
+import type { SubscriberGateOptions } from './subscriber-gate';
+import type { Scheduler } from './thundering-herd';
+
+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;

package/src/live-query.ts

@@ -6,54 +6,26 @@
 // 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 { type LiveCursor, makeCursor, type ReconnectBudget, type ResumeSource } 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 } from './sync-protocol';
-import type { Scheduler } from './thundering-herd';
 
-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>();
@@ -67,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) {
@@ -166,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.
@@ -223,7 +208,10 @@ export class LiveQueryRegistry {
     // 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.
-    if (args.cursor && args.cursor.qid === qid) {
+    //
+    // 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(
         {
@@ -319,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;
         }
@@ -433,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;
   }
@@ -495,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/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-transport.ts

@@ -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);
+      }
+    }
   }
 
   /**

package/src/offline-queue.ts

@@ -11,6 +11,7 @@
 
 import { renderThrowable, stringField } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
+import { OfflineQueueAbandonedError } from './page-errors';
 import type { WireError } from './sync-protocol';
 
 export type MutationStatus = 'pending' | 'inflight' | 'acked' | 'failed';
@@ -91,6 +92,8 @@ export class OfflineQueue {
    * is parked inside `send`. Bumped by every loss so a pass that resumes afterwards claims nothing.
    */
   #epoch = 0;
+  /** Set by `abandon`, never cleared: this queue's principal is gone. */
+  #abandoned = false;
 
   private constructor(store: QueueStore, state: QueueState) {
     this.#store = store;
@@ -103,8 +106,10 @@ export class OfflineQueue {
    *
    * An `inflight` entry on disk belonged to a page that is gone, so it goes back to `pending`. Left
    * as it was, `#sendable` skipped it forever — no ack was coming to a page that no longer exists —
-   * and every later write overtook it. The replay carries its idempotency key, so a write the old
-   * page did get through is answered from the action's idempotency store, never applied twice.
+   * and every later write overtook it. The replay carries its idempotency key, and a `mutator()`
+   * is REQUIRED to declare `idempotent: true` (`X_MUTATOR_NOT_IDEMPOTENT` at declaration), so a
+   * 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());
@@ -119,6 +124,7 @@ export class OfflineQueue {
    * other pass can have one on the wire.
    */
   async reload(): Promise<void> {
+    if (this.#abandoned) return;
     const state = await this.#store.load();
     this.#mutations = state.mutations.map((mutation) => ({ ...mutation }));
     this.#nextSeq = Math.max(this.#nextSeq, state.nextSeq);
@@ -167,6 +173,17 @@ export class OfflineQueue {
     input: JsonValue;
     at?: number;
   }): Promise<QueuedMutation> {
+    // Read BEFORE the key is looked up, never between the lookup and the push: with the await in
+    // between, two enqueues of one key both found nothing and both pushed — one intent, two
+    // entries under one sequence number. Another tab of the same user may have taken sequence
+    // numbers since this one loaded, which is what the read is for.
+    //
+    // An abandoned queue REFUSES, before the read and after it (the principal can leave during
+    // it): a write accepted here would sit in memory, shown as queued, with nothing to send it.
+    if (this.#abandoned) throw new OfflineQueueAbandonedError({ name: args.name });
+    const floor = (await this.#store.load()).nextSeq;
+    if (this.#abandoned) throw new OfflineQueueAbandonedError({ name: args.name });
+    this.#nextSeq = Math.max(this.#nextSeq, floor);
     const existing = this.find(args.key);
     if (existing && existing.status !== 'failed') {
       this.#collapsed += 1;
@@ -178,8 +195,6 @@ export class OfflineQueue {
     // 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);
-    // Another tab of the same user may have taken sequence numbers since this one loaded.
-    this.#nextSeq = Math.max(this.#nextSeq, (await this.#store.load()).nextSeq);
     const mutation: QueuedMutation = {
       key: args.key,
       seq: this.#nextSeq,
@@ -248,6 +263,22 @@ export class OfflineQueue {
     return returned;
   }
 
+  /**
+   * The principal this queue belongs to is gone (`page-outbox.ts` calls it on a `rescope`), and it
+   * is final: nothing more is SENT, WRITTEN or ACCEPTED (`enqueue` refuses). The epoch bump stops a pass parked
+   * inside `send` before its next entry — which would otherwise leave under the next principal's
+   * session — and the flag stops a pass that starts later, and every write-back: the store was
+   * wiped for this principal, and a pass that then saved what it touched put the writes back.
+   */
+  abandon(): void {
+    this.#epoch += 1;
+    this.#abandoned = true;
+  }
+
+  get abandoned(): boolean {
+    return this.#abandoned;
+  }
+
   /** Server acknowledged: the mutation leaves the queue and its rebase entry can be committed. */
   async ack(key: string): Promise<void> {
     const mutation = this.find(key);
@@ -294,7 +325,7 @@ export class OfflineQueue {
   /** One drain pass. Never called concurrently with itself — `drain` owns that. */
   async #pass(send: MutationSender): Promise<DrainReport> {
     const epoch = this.#epoch;
-    const sendable = this.#sendable();
+    const sendable = this.#abandoned ? [] : this.#sendable();
     // Nothing to do: a pass chained behind one that already sent everything must not rewrite the
     // durable state for the privilege of reporting zero.
     if (sendable.length === 0) {
@@ -326,6 +357,12 @@ export class OfflineQueue {
         // `WebSocket.send` on a CLOSING socket discards it and returns normally — so calling that
         // an ack drops the mutation on exactly the socket death this queue exists to survive.
         // Only `ack`/`fail` (the server) or `requeueInflight` (a lost connection) moves it on.
+        //
+        // A sender may settle the write itself before it returns — the page outbox does, over
+        // HTTP. One it REFUSED keeps the error `fail` just recorded and is not counted as sent:
+        // clearing it here put `{ status: 'failed', error: null }` on disk and reported a refused
+        // write as a sent one.
+        if (statusOf(mutation) === 'failed') continue;
         mutation.error = null;
         sent += 1;
       } catch (error) {
@@ -364,6 +401,7 @@ export class OfflineQueue {
    * queue: a second tab's entries are not this tab's to overwrite or delete.
    */
   async #persist(puts: readonly QueuedMutation[], deletes: readonly string[] = []): Promise<void> {
+    if (this.#abandoned) return;
     await this.#store.write({
       puts: puts.map((mutation) => ({ ...mutation })),
       deletes,
@@ -372,6 +410,11 @@ export class OfflineQueue {
   }
 }
 
+/** Read through a call: `send` awaited in between, and the compiler still narrows to `inflight`. */
+function statusOf(mutation: QueuedMutation): MutationStatus {
+  return mutation.status;
+}
+
 /** A thrown value as the queue records it — `code`, `cause`, `fix`, never a throw of its own. */
 export function toQueueError(error: unknown): WireError {
   return {

package/src/page-errors.ts

@@ -93,6 +93,23 @@ export class LocalStoreUnavailableError extends RealtimeError {
   }
 }
 
+/**
+ * A write reached a queue whose principal is gone: the page signed out, or in as someone else,
+ * while the write was being queued. It is not stored and never sent — a write issued under one
+ * session must not leave under the next — and it is RAISED, because a user's write dropped in
+ * silence is a loss nobody is told about. `name` is the mutator's registered name; the write's
+ * idempotency key is deliberately not rendered.
+ */
+export class OfflineQueueAbandonedError extends RealtimeError {
+  constructor(args: { name: string }) {
+    super({
+      code: 'X_OFFLINE_QUEUE_ABANDONED',
+      cause: `the write "${args.name}" was queued after its page changed principal, so it was not stored and will not be sent — call the mutation again under the current session`,
+      fix: 'x errors explain X_OFFLINE_QUEUE_ABANDONED --json',
+    });
+  }
+}
+
 /**
  * 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