@ultimat3/realtime 21.0.0 → 22.1.0

package/src/cursor.ts

@@ -161,6 +161,11 @@ export function advance(
   lsn: string,
   now: number,
 ): LiveCursor {
+  // An update moves no id in or out, and it is the common change: the ids are reused as they are,
+  // so a fan-out to N subscribers of a W-row window is not N rebuilds of a W-id set per change.
+  if (!patches.some((patch) => patch.op !== 'update')) {
+    return { qid: cursor.qid, lsn, ids: cursor.ids, at: now };
+  }
   const ids = new Set(cursor.ids);
   for (const patch of patches) {
     if (patch.op === 'delete') ids.delete(patch.id);

package/src/errors.ts

@@ -33,6 +33,9 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_LIVE_REPLICA_IDENTITY',
   'X_SOCKET_UNAUTHENTICATED',
   'X_SOCKET_AUTH_UNAVAILABLE',
+  'X_REALTIME_TOPOLOGY',
+  'X_REPLICATION_TLS',
+  'X_SOCKET_ORIGIN_REFUSED',
 ] as const;
 
 /**
@@ -137,9 +140,12 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_LIVE_SERVER_RENDER: 'a browser-only live operation ran during a server render',
   X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
   X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
-  X_LIVE_REPLICA_IDENTITY: 'a replicated table sends a key-only row on delete',
+  X_LIVE_REPLICA_IDENTITY: 'a replicated table has no replica identity',
   X_SOCKET_UNAUTHENTICATED: 'the sync upgrade carried no credential this app accepts',
   X_SOCKET_AUTH_UNAVAILABLE: 'the sync node could not decide who a connecting socket is',
+  X_REALTIME_TOPOLOGY: 'a sync node boots on a real database with no reachable change feed',
+  X_REPLICATION_TLS: 'the replication connection failed TLS',
+  X_SOCKET_ORIGIN_REFUSED: 'the websocket upgrade came from another origin',
 };
 
 // One unconditional call, so a second package claiming one of realtime's codes throws
@@ -170,6 +176,7 @@ export {
   ReplicaIdentityError,
   ReplicationFailedError,
   ReplicationProtocolError,
+  ReplicationTlsError,
   ReplicatorSlotHeldError,
 } from './replication-errors';
 
@@ -255,6 +262,25 @@ export class TransportUnavailableError extends RealtimeError {
   }
 }
 
+/**
+ * A `sync` node that can hear no change: a real database, the in-process bus, and no replicator in
+ * this process. A replicator in another process publishes into ITS in-process bus, so every live
+ * query and channel here is silent, with no error on either side. Refused at boot, where the
+ * topology is known, rather than discovered as a live feature that never updates.
+ */
+export class RealtimeTopologyError extends RealtimeError {
+  constructor() {
+    super({
+      code: 'X_REALTIME_TOPOLOGY',
+      cause:
+        'role sync runs on an external database over the in-process transport with no replicator in this process, so no committed change can reach it',
+      // Since 22.0.0 NATS_URL alone selects nothing: `realtime.transport` does, and a set NATS_URL
+      // under `'memory'` is refused, so the fix has to name both halves.
+      fix: "set realtime: { transport: 'nats', urlEnv: 'NATS_URL' } in app.config.ts and NATS_URL for every realtime role (web, sync, replicator), or run ROLE=sync with the replicator in one process: x dev --role sync,replicator",
+    });
+  }
+}
+
 /**
  * The bytes on the bus socket are not the protocol we speak: an unknown NATS verb, a header block
  * that is not `NATS/1.0`, a JetStream reply in a shape the API never produces. Always a version or
@@ -330,6 +356,22 @@ export class SocketUnauthenticatedError extends RealtimeError {
   }
 }
 
+/**
+ * A browser page on another origin asked for a socket. No CORS applies to a websocket and the
+ * session cookie rides it, so admitting the upgrade would open a socket AS the visitor for a page
+ * that is not this app — cross-site websocket hijacking. Decided before `authenticate` and before
+ * the accept budget, so a hostile page costs neither.
+ */
+export class SocketOriginRefusedError extends RealtimeError {
+  constructor(args: { reason: string }) {
+    super({
+      code: 'X_SOCKET_ORIGIN_REFUSED',
+      cause: `the websocket upgrade was refused: ${args.reason}`,
+      fix: 'export APP_URL="https://www.example.com"   # on the sync role: the origin the page is served on (or createSyncNode({ allowedOrigins }))',
+    });
+  }
+}
+
 /**
  * `authenticate` raised instead of deciding. The same rule the row gate follows: a failure is not a
  * denial, so the client is told to come back rather than told it may not connect — a token service

package/src/idb-fake.ts

@@ -13,6 +13,11 @@ type Tables = Map<string, Map<string, unknown>>;
 export interface FakeIdbOptions {
   /** `open` fails, as it does in a private window or with storage blocked. */
   readonly blocked?: boolean;
+  /**
+   * Every write ABORTS its transaction, as a quota refusal does: `abort` fires and nothing else —
+   * no `complete`, no transaction `error` event. Read at write time, so a test can flip it.
+   */
+  quotaExceeded?: boolean;
 }
 
 /** A fresh, empty database server. Share one instance to simulate a reload over the same disk. */
@@ -28,7 +33,7 @@ export function fakeIndexedDb(options: FakeIdbOptions = {}): IdbFactoryLike {
         }
         const known = databases.get(name) ?? { version: 0, tables: new Map() };
         databases.set(name, known);
-        const db = database(known.tables);
+        const db = database(known.tables, options);
         request.result = db;
         if (known.version < version) {
           known.version = version;
@@ -41,7 +46,7 @@ export function fakeIndexedDb(options: FakeIdbOptions = {}): IdbFactoryLike {
   };
 }
 
-function database(tables: Tables): IdbDatabaseLike {
+function database(tables: Tables, options: FakeIdbOptions): IdbDatabaseLike {
   return {
     objectStoreNames: { contains: (name: string): boolean => tables.has(name) },
     createObjectStore: (name: string): void => {
@@ -49,13 +54,20 @@ function database(tables: Tables): IdbDatabaseLike {
     },
     transaction(names: string | readonly string[]) {
       let open = 0;
-      const failed = false;
+      let failed = false;
       const tx = {
         oncomplete: null as (() => void) | null,
         onerror: null as (() => void) | null,
+        onabort: null as (() => void) | null,
         error: null as unknown,
         objectStore: (name: string): IdbStoreLike => store(name),
       };
+      const abort = (): void => {
+        if (failed) return;
+        failed = true;
+        tx.error = new DOMException('The quota has been exceeded.', 'QuotaExceededError');
+        queueMicrotask(() => tx.onabort?.());
+      };
       const settleLater = (): void => {
         queueMicrotask(() => {
           if (open > 0 || failed) return;
@@ -82,7 +94,15 @@ function database(tables: Tables): IdbDatabaseLike {
         const sorted = (): [string, unknown][] =>
           [...table].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
         return {
-          put: (value, key) => run(() => void table.set(key, structuredClone(value))),
+          get: (key) => run(() => structuredClone(table.get(key))),
+          put: (value, key) =>
+            run(() => {
+              if (options.quotaExceeded === true) {
+                abort();
+                return;
+              }
+              table.set(key, structuredClone(value));
+            }),
           delete: (key) => run(() => void table.delete(key)),
           getAll: () => run(() => sorted().map(([, value]) => structuredClone(value))),
           getAllKeys: () => run(() => sorted().map(([key]) => key)),

package/src/idb-types.ts

@@ -14,6 +14,7 @@ export interface IdbRequestLike<T> {
 }
 
 export interface IdbStoreLike {
+  get(key: string): IdbRequestLike<unknown>;
   put(value: unknown, key: string): IdbRequestLike<unknown>;
   delete(key: string): IdbRequestLike<unknown>;
   getAll(): IdbRequestLike<unknown[]>;
@@ -23,6 +24,12 @@ export interface IdbStoreLike {
 export interface IdbTransactionLike {
   oncomplete: (() => void) | null;
   onerror: (() => void) | null;
+  /**
+   * A transaction the browser ABORTED — a quota refusal is the ordinary one — fires `abort` and
+   * nothing else: no `complete`, and no `error` on the transaction. Unlistened, every write awaiting
+   * it hung forever.
+   */
+  onabort: (() => void) | null;
   error: unknown;
   objectStore(name: string): IdbStoreLike;
 }

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   ReplicaIdentityError,
   ReplicationFailedError,
   ReplicationProtocolError,
+  ReplicationTlsError,
   ReplicatorSlotHeldError,
   ServerRenderLiveError,
   SubscriptionLimitError,
@@ -158,7 +159,6 @@ export {
 export {
   type BackoffPolicy,
   BROWSER_RECONNECT_MAX_MS,
-  backoffDelay,
   browserBackoff,
   defaultBackoff,
   type JitterMode,

package/src/live-definition.ts

@@ -142,7 +142,11 @@ export function liveQueryDefinition(
     },
     snapshot: async ({ input }): Promise<SnapshotResult> => {
       const window = await resolve(input);
-      return { rows: await window.read(), lsn: options.lsn?.() ?? '' };
+      // 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.
+      const lsn = options.lsn?.() ?? '';
+      return { rows: await window.read(), lsn };
     },
     matcher: (input) => windows.get(queryHash(name, input))?.matcher ?? UNRESOLVED,
     // Read off the same resolved window as the matcher, so the scope the client keys rows under and

package/src/live-fanout.ts

@@ -10,7 +10,7 @@ import type { Row, RowPatch } from './json';
 import type { LiveSubscription } from './live-contract';
 import { applyToWindow, bridgeChange } from './matcher-bridge';
 import { type QueryEntry, refillWindowInLane } from './query-window';
-import type { Subscriber, SubscriberGate } from './subscriber-gate';
+import { type Subscriber, type SubscriberGate, windowIndex } from './subscriber-gate';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
 
 export interface FanoutDeps {
@@ -38,6 +38,15 @@ export async function fanoutChange(
 ): Promise<FanoutResult> {
   // A window that missed a change must be replaced before it is patched again, and it can only be
   // replaced here — a fanout holds this entry's lane, and `fillWindow` takes the same one.
+  // No read has landed in this window yet: there is nothing to patch, and a patch folded into the
+  // empty rows would move `entry.lsn` past the read in flight and get that read discarded as older
+  // than the window — every row but the patched one lost, permanently. Marked stale instead, so the
+  // read that lands is applied and followed by one that includes this change.
+  if (entry.applied === 0) {
+    entry.stale = true;
+    return { sent: 0, stale: 0 };
+  }
+  if (change.op === 'truncate') return await truncated(deps, entry, change);
   if (entry.stale) await refillWindowInLane(entry);
   // The consume-side twin of the replicator's own duplicate guard, which had none. `entry.lsn =
   // change.lsn` was unconditional, so a change the window already holds — a redelivery, or one
@@ -57,6 +66,8 @@ export async function fanoutChange(
   for (const patch of result.patches) deps.source.append(entry.qid, patch);
 
   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) {
       // The window lost its tail: guessing is how a sync engine silently diverges. Checked BEFORE
@@ -84,7 +95,8 @@ export async function fanoutChange(
         entry,
         who,
         result.patches,
-        new Set(subscription.cursor.ids),
+        heldBy(subscription.cursor),
+        index,
       );
     } catch {
       // Already counted and reported as a gate failure. Degrade this one subscriber the way a
@@ -112,6 +124,43 @@ export async function fanoutChange(
   return { sent, stale: 0 };
 }
 
+/**
+ * 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
+ * out of what came back: a window that kept the truncated rows until its next change would serve
+ * them to every new subscriber in the meantime.
+ */
+async function truncated(
+  deps: FanoutDeps,
+  entry: QueryEntry,
+  change: ChangeEvent,
+): Promise<FanoutResult> {
+  if (!entry.shape.entities.includes(change.entity)) return { sent: 0, stale: 0 };
+  await refillWindowInLane(entry);
+  if (change.lsn > entry.lsn) entry.lsn = change.lsn;
+  let sent = 0;
+  for (const subscription of entry.subscribers.values()) {
+    subscription.socket.markDesynced(subscription.sid);
+    if (await resnapshot(deps, entry, subscription)) sent += 1;
+  }
+  return { sent, stale: 0 };
+}
+
+/**
+ * A cursor's ids as a set, built once per ids ARRAY rather than once per subscriber per change.
+ * `advance` hands an update's cursor the same array it had (an update moves no id), so the cache
+ * holds across the common change and dies with the array; an insert or delete makes a new one.
+ */
+const heldSets = new WeakMap<readonly string[], ReadonlySet<string>>();
+
+function heldBy(cursor: LiveCursor): ReadonlySet<string> {
+  const cached = heldSets.get(cursor.ids);
+  if (cached !== undefined) return cached;
+  const held = new Set(cursor.ids);
+  heldSets.set(cursor.ids, held);
+  return held;
+}
+
 /**
  * The repair for one diverged subscriber, out of the window the lane is already holding — no DB
  * read, one frame. Its cursor is rebuilt from what this subscriber may actually see, exactly as

package/src/live-query.ts

@@ -70,6 +70,7 @@ export class LiveQueryRegistry {
   readonly #maxEntries: number;
   /** What one lane needs, and nothing this class holds beyond it. */
   readonly #fanout: FanoutDeps;
+  #lastLsn = '';
   #staleChanges = 0;
 
   constructor(options: LiveQueryRegistryOptions) {
@@ -363,7 +364,17 @@ export class LiveQueryRegistry {
    * never per node — awaiting one entry before entering the next made one slow policy pass the
    * whole node's pace, and let a lane that threw skip every entry behind it with nobody desynced.
    */
+  /**
+   * The newest change position this registry has been handed. What a node's snapshot may claim
+   * (`liveQueryDefinition`'s `lsn`): a read begun after it holds at least that change, and every
+   * later change is above it. `''` before the first.
+   */
+  get lastLsn(): string {
+    return this.#lastLsn;
+  }
+
   async deliver(change: ChangeEvent): Promise<number> {
+    if (change.lsn > this.#lastLsn) this.#lastLsn = change.lsn;
     const lanes = [...this.#entries.values()].map(async (entry) => {
       try {
         const result = await entry.lock.run(() => fanoutChange(this.#fanout, entry, change));

package/src/live-replicator.ts

@@ -0,0 +1,160 @@
+// The in-process replicator: committed row changes in, `ChangeEvent`s out, fanned into the node.
+//
+// Production decodes the write-ahead log. PGlite has no walsender and the memory driver has no log,
+// so a test process had no change source at all — which is what left the `subscribe` fixture with
+// no driver, and its five tests in `examples/dummy` asserting against a snapshot that never moved.
+//
+// WHAT IS REAL HERE, and it is everything downstream of the decoder: the matcher, the shared window,
+// the per-subscriber `visible` gate, the cursor, the frames. This substitutes for the WAL DECODER
+// and for nothing else — `@ultimat3/entity`'s `setRowObserver` reports what a repository wrote, in
+// this process, and the events are shaped exactly as `PgLogicalReplicationFeed` shapes them.
+//
+// WHAT IS NOT: a write another process made is invisible, because nothing here reads a log. That is
+// the honest bound, and it is why `selectChangeFeed` never picks it — the boot that installs it
+// decides, and only under an embedded database.
+//
+// Lives in `@ultimat3/realtime/server` since 2026-09-23: it imports only `entity` and `realtime`,
+// so it is a second change source beside the WAL decoder, and `x dev` booting it out of
+// `@ultimat3/testing` put the test harness in every dev process's graph. `@ultimat3/testing`
+// re-exports it until 22.0.0.
+//
+// `x dev` is the one boot that installs it outside a test, `As of 2026-09-05` (`@ultimat3/cli`'s
+// `dev-live-feed.ts`), and only under the EMBEDDED database: PGlite has no walsender, every role
+// runs in that one process, so the bound above holds by construction — and a real `DATABASE_URL`
+// gets the decoder instead, never both.
+
+import type { RowBulkChange, RowChange, RowObserver } from '@ultimat3/entity';
+import type { ChangeEvent, ChangeOp } from './changefeed';
+import type { Row } from './json';
+import type { LiveQueryRegistry } from './live-query';
+
+/** What a caller does with a change nobody could deliver. */
+export interface LiveReplicatorOptions {
+  readonly registry: LiveQueryRegistry;
+  /**
+   * The node's declared channels, fed the same `ChangeEvent` — what a real node's change
+   * subscription does beside `registry.deliver` (`sync-node.ts`). Without it a channel's `records`
+   * frames never carried a write made under `x dev`, and every other tab stayed on the old row.
+   */
+  readonly channels?: { deliverChange(change: ChangeEvent): unknown };
+  /** Tenant column, hoisted out of the row so fanout filters without parsing it. */
+  readonly tenantColumn?: string;
+  readonly onError?: (error: unknown) => void;
+}
+
+export interface LiveReplicator {
+  /** Resolves when every change observed so far has been fanned out. Never a sleep. */
+  settled(): Promise<void>;
+  /** Changes this replicator has delivered — the number a test asserts a patch count against. */
+  readonly delivered: number;
+  stop(): void;
+}
+
+/**
+ * A `ChangeEvent` row is `Row` — a JSON object carrying an `id`. Every row a repository stores has
+ * one; the cast is what says so to a compiler that only sees `Record<string, unknown>`, and a row
+ * that genuinely has none fails downstream in `idOf`, with the entity named, exactly as a row off
+ * the wire would.
+ */
+const asRow = (value: Readonly<Record<string, unknown>> | null): Row | null =>
+  value === null ? null : (value as unknown as Row);
+
+/**
+ * Lexicographically comparable, which is the whole contract of an lsn — `formatLsn` in
+ * `@ultimat3/realtime` produces the same shape from a real WAL position. A counter is enough here
+ * because one process observes its own writes in the order it made them.
+ */
+const lsnOf = (position: number): string => position.toString(16).padStart(16, '0');
+
+/**
+ * Install the replicator for the length of one test. It takes over the process row observer and
+ * hands back whatever was installed before, because `bun test` shares one process across files and
+ * an unconditional clear would take an outer harness's observer with it.
+ */
+export async function startLiveReplicator(options: LiveReplicatorOptions): Promise<LiveReplicator> {
+  // Awaited BEFORE the observer exists, so installation is the last thing this function does and
+  // no write between the call and the install can slip past unobserved.
+  const entity = await import('@ultimat3/entity');
+  const { registry } = options;
+  const tenant = options.tenantColumn ?? 'orgId';
+  let position = 0;
+  let delivered = 0;
+  // One promise chain, because ORDERING is the guarantee the whole pipeline is built on — the same
+  // reason `InMemoryChangeFeed` serializes its deliveries rather than firing them concurrently.
+  let tail: Promise<void> = Promise.resolve();
+  let stopped = false;
+
+  const enqueue = (work: () => Promise<void>): void => {
+    tail = tail.then(work).catch((error: unknown) => {
+      // Never rethrown into the chain: one failed fanout must not silence every change behind it,
+      // and a rejection with nobody to hand it to ends the Bun process.
+      options.onError?.(error);
+    });
+  };
+
+  const observer: RowObserver = {
+    onChange(change: RowChange): void {
+      if (stopped) return;
+      position += 1;
+      const at = position;
+      const row = change.after ?? change.before;
+      const orgId = typeof row?.[tenant] === 'string' ? (row[tenant] as string) : null;
+      const event: ChangeEvent = {
+        entity: change.entity,
+        // A repository's three row ops are three of the feed's four; a truncate never comes this way.
+        op: change.op satisfies ChangeOp,
+        before: asRow(change.before),
+        after: asRow(change.after),
+        lsn: lsnOf(at),
+        txid: String(at),
+        orgId,
+        // Deliberately not a clock read: the preload freezes `Date.now()`, and a change's commit
+        // time is not something any assertion in this repo reads. `at` keeps it monotonic anyway.
+        at,
+        // The keyed write it belongs to, read off the request scope — what the WAL decoder reads
+        // off the transaction's opening message — so a channel frame names it here as it would there.
+        ...(change.write === undefined ? {} : { write: change.write }),
+      };
+      enqueue(async () => {
+        // Channels first, as the node does: a live query's fanout that throws must not also cost
+        // every declared channel the change.
+        options.channels?.deliverChange(event);
+        delivered += await registry.deliver(event);
+      });
+    },
+
+    /**
+     * 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.
+     */
+    onBulk(_change: RowBulkChange): void {
+      if (stopped) return;
+      registry.invalidate();
+    },
+  };
+
+  const previous = entity.setRowObserver(observer);
+
+  return {
+    get delivered() {
+      return delivered;
+    },
+    settled: async () => {
+      // Twice: a fanout can enqueue nothing, but the writes that produced these changes may still
+      // be resolving their own promises when a test asks. Awaiting the chain, letting the
+      // microtask queue drain, then awaiting it again covers a change observed in between.
+      await tail;
+      for (let turn = 0; turn < 8; turn += 1) await Promise.resolve();
+      await tail;
+    },
+    stop: () => {
+      stopped = true;
+      // Restored, never cleared: one process runs every test file, and an outer harness's observer
+      // must survive an inner fixture finishing.
+      entity.setRowObserver(previous);
+    },
+  };
+}

package/src/local-store-idb.ts

@@ -8,7 +8,7 @@
 import type { ClientScope, RecordRows, Row } from '@ultimat3/core/page';
 import { isJsonObject, renderThrowable, type UltimateError } from '@ultimat3/core/page';
 import type { IdbDatabaseLike, IdbFactoryLike, IdbRequestLike } from './idb-types';
-import type { QueueState } from './offline-queue';
+import type { QueueChange, QueuedMutation, QueueState } from './offline-queue';
 import { LocalStoreUnavailableError } from './page-errors';
 
 /** One persisted row, by record type and record key. */
@@ -28,7 +28,12 @@ export interface LocalStore {
     deletes: readonly Omit<PersistedRow, 'row'>[],
   ): Promise<void>;
   queue(scope: string): Promise<QueueState | undefined>;
-  saveQueue(scope: string, state: QueueState): Promise<void>;
+  /**
+   * One change to one scope's outbox, BY KEY (`QueueChange`). It was `saveQueue(scope, state)`,
+   * a whole-queue save — and two tabs of one user each saved their own copy, so the last save won
+   * and the other tab's queued write was erased.
+   */
+  writeQueue(scope: string, change: QueueChange): Promise<void>;
   /** Everything of one scope — its rows AND its outbox. Sign-out, or any principal change. */
   wipe(scope: string): Promise<void>;
   /**
@@ -53,12 +58,26 @@ const OUTBOX = 'outbox';
 /** JSON, never a joined string: a principal is opaque and may hold any separator. */
 const rowKey = (scope: string, type: string, key: string): string =>
   JSON.stringify([scope, type, key]);
+/** One queued mutation, and one scope's sequence floor — the outbox's two record shapes. */
+const mutationKey = (scope: string, key: string): string => JSON.stringify([scope, 'm', key]);
+const seqSlot = (scope: string): string => JSON.stringify([scope, 'seq']);
+
+/** The scope an outbox key belongs to: `[scope, …]`, or a pre-22.0.0 whole-queue record `scope`. */
+function outboxScopeOf(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined;
+  if (!raw.startsWith('[')) return raw;
+  const parts: unknown = JSON.parse(raw);
+  return Array.isArray(parts) && typeof parts[0] === 'string' ? parts[0] : undefined;
+}
+
+const byQueueOrder = (a: QueuedMutation, b: QueuedMutation): number =>
+  a.seq - b.seq || a.enqueuedAt - b.enqueuedAt || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
 
 /** Memory: tests, SSR, and the fallback when IndexedDB is unavailable. */
 export class MemoryLocalStore implements LocalStore {
   readonly kind = 'memory';
   readonly #rows = new Map<string, PersistedRow & { readonly scope: string }>();
-  readonly #queues = new Map<string, QueueState>();
+  readonly #queues = new Map<string, { mutations: Map<string, QueuedMutation>; nextSeq: number }>();
 
   async rows(scope: string): Promise<ReadonlyMap<string, RecordRows>> {
     return group([...this.#rows.values()].filter((entry) => entry.scope === scope));
@@ -72,10 +91,19 @@ export class MemoryLocalStore implements LocalStore {
     for (const put of puts) this.#rows.set(rowKey(scope, put.type, put.key), { ...put, scope });
   }
   async queue(scope: string): Promise<QueueState | undefined> {
-    return this.#queues.get(scope);
+    const held = this.#queues.get(scope);
+    if (held === undefined) return undefined;
+    return {
+      mutations: structuredClone([...held.mutations.values()]).sort(byQueueOrder),
+      nextSeq: held.nextSeq,
+    };
   }
-  async saveQueue(scope: string, state: QueueState): Promise<void> {
-    this.#queues.set(scope, structuredClone(state));
+  async writeQueue(scope: string, change: QueueChange): Promise<void> {
+    const held = this.#queues.get(scope) ?? { mutations: new Map(), nextSeq: 1 };
+    for (const key of change.deletes) held.mutations.delete(key);
+    for (const put of change.puts) held.mutations.set(put.key, structuredClone(put));
+    held.nextSeq = Math.max(held.nextSeq, change.nextSeq);
+    this.#queues.set(scope, held);
   }
   async wipe(scope: string): Promise<void> {
     for (const [key, entry] of this.#rows) if (entry.scope === scope) this.#rows.delete(key);
@@ -116,15 +144,52 @@ class IdbLocalStore implements LocalStore {
     await done(tx);
   }
   async queue(scope: string): Promise<QueueState | undefined> {
-    const tx = this.db.transaction(OUTBOX, 'readonly');
+    // Read-WRITE: a pre-22.0.0 whole-queue record for this scope is converted in the same
+    // transaction, so an upgrade keeps the writes a user queued on the previous version.
+    const tx = this.db.transaction(OUTBOX, 'readwrite');
     const store = tx.objectStore(OUTBOX);
-    const [keys, values] = await Promise.all([answer(store.getAllKeys()), answer(store.getAll())]);
-    const at = keys.indexOf(scope);
-    return at === -1 ? undefined : (values[at] as QueueState);
+    // Both issued before either is awaited, and awaited one by one: the conversion below writes in
+    // this transaction, and it must still be open when the reads land.
+    const asked = [answer(store.getAllKeys()), answer(store.getAll())] as const;
+    const keys = await asked[0];
+    const values = await asked[1];
+    const mutations = new Map<string, QueuedMutation>();
+    let nextSeq = 1;
+    let found = false;
+    let converted = false;
+    keys.forEach((raw, index) => {
+      if (outboxScopeOf(raw) !== scope) return;
+      found = true;
+      const value = values[index];
+      if (raw === scope) {
+        const legacy = value as QueueState;
+        for (const mutation of legacy.mutations) {
+          mutations.set(mutation.key, mutation);
+          store.put(mutation, mutationKey(scope, mutation.key));
+        }
+        nextSeq = Math.max(nextSeq, legacy.nextSeq);
+        store.put(nextSeq, seqSlot(scope));
+        store.delete(scope);
+        converted = true;
+      } else if (raw === seqSlot(scope)) {
+        nextSeq = Math.max(nextSeq, typeof value === 'number' ? value : 1);
+      } else {
+        const mutation = value as QueuedMutation;
+        mutations.set(mutation.key, mutation);
+      }
+    });
+    // Awaited only when something was written: a transaction that issued nothing after its reads
+    // has already completed, and a listener attached now would wait for an event that is gone.
+    if (converted) await done(tx);
+    return found ? { mutations: [...mutations.values()].sort(byQueueOrder), nextSeq } : undefined;
   }
-  async saveQueue(scope: string, state: QueueState): Promise<void> {
+  async writeQueue(scope: string, change: QueueChange): Promise<void> {
     const tx = this.db.transaction(OUTBOX, 'readwrite');
-    tx.objectStore(OUTBOX).put(state, scope);
+    const store = tx.objectStore(OUTBOX);
+    const floor = await answer(store.get(seqSlot(scope)));
+    for (const key of change.deletes) store.delete(mutationKey(scope, key));
+    for (const put of change.puts) store.put(put, mutationKey(scope, put.key));
+    store.put(Math.max(typeof floor === 'number' ? floor : 1, change.nextSeq), seqSlot(scope));
     await done(tx);
   }
   async wipe(scope: string): Promise<void> {
@@ -136,7 +201,10 @@ class IdbLocalStore implements LocalStore {
       const parts: unknown = JSON.parse(raw);
       if (Array.isArray(parts) && parts[0] === scope) records.delete(raw);
     }
-    tx.objectStore(OUTBOX).delete(scope);
+    const outbox = tx.objectStore(OUTBOX);
+    for (const raw of await answer(outbox.getAllKeys())) {
+      if (outboxScopeOf(raw) === scope && typeof raw === 'string') outbox.delete(raw);
+    }
     await done(tx);
   }
   async wipeOthers(keep: string): Promise<void> {
@@ -152,8 +220,9 @@ class IdbLocalStore implements LocalStore {
       const parts: unknown = JSON.parse(raw);
       if (Array.isArray(parts) && parts[0] !== keep) records.delete(raw);
     }
-    for (const scope of queueKeys) {
-      if (typeof scope === 'string' && scope !== keep) outbox.delete(scope);
+    for (const raw of queueKeys) {
+      const scope = outboxScopeOf(raw);
+      if (typeof raw === 'string' && scope !== undefined && scope !== keep) outbox.delete(raw);
     }
     await done(tx);
   }
@@ -214,11 +283,16 @@ function answer<T>(request: IdbRequestLike<T>): Promise<T> {
 function done(tx: {
   oncomplete: (() => void) | null;
   onerror: (() => void) | null;
+  onabort: (() => void) | null;
   error: unknown;
 }): Promise<void> {
   return new Promise((resolve, reject) => {
     tx.oncomplete = (): void => resolve();
     tx.onerror = (): void => reject(tx.error);
+    // A quota refusal ABORTS the transaction and fires nothing else, so a store that listened only
+    // for `complete` and `error` left `write`, `writeQueue`, `flush` and `enqueue` pending forever.
+    tx.onabort = (): void =>
+      reject(tx.error ?? new DOMException('the transaction was aborted', 'AbortError'));
   });
 }