@ultimat3/realtime 20.2.1 → 21.0.0

package/src/live-definition.ts

@@ -14,6 +14,7 @@ import { type AnyQuery, queryHash, queryName } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
 import type { LiveQueryDefinition, SnapshotResult } from './live-contract';
+import { liveRecords } from './live-record-type';
 import { type IncrementalMatcher, matcherFor, type Projection } from './matcher-bridge';
 import { authorizeWithPolicy, visibleWithPolicy } from './policy-gate';
 
@@ -47,6 +48,8 @@ interface SharedWindow {
   readonly matcher: IncrementalMatcher;
   /** The compiled shape's root entity — the client's identity scope for every row of this read. */
   readonly rowEntity: string;
+  /** Its projection's record key; `null` for a plain table keyed by `id`. */
+  readonly rowKey: ((row: Row) => string) | null;
   read(): Promise<readonly Row[]>;
 }
 
@@ -109,11 +112,14 @@ export function liveQueryDefinition(
     // a second subject-less copy — which is what this did — paid for the parse and the `sql()`
     // twice per query id and left two descriptions of one read that agreed only by luck.
     const projection = learnProjection();
+    const records = liveRecords(live.shape.entity);
     const built: SharedWindow = {
       matcher: matcherFor(live, projection.read),
-      // `assertMatchable` already refused a shape without one, so this is the entity the matcher
-      // patches rows of — the same name `ChangeEvent.entity` and `tx.<table>` use.
-      rowEntity: live.shape.entity,
+      // `assertMatchable` already refused a shape without one. The shape names the TABLE (what a
+      // `ChangeEvent` carries); the client store keys records by ENTITY name, so the snapshot tells
+      // it the record type, and every frame carries the key the entity's projection renders.
+      rowEntity: records.type,
+      rowKey: records.key,
       read: async () => {
         const rows = rowsOf(name, await live.execute());
         projection.teach(rows);
@@ -142,6 +148,7 @@ export function liveQueryDefinition(
     // Read off the same resolved window as the matcher, so the scope the client keys rows under and
     // the entity the matcher patches them from can never be two different names.
     rowEntity: (input) => windows.get(queryHash(name, input))?.rowEntity ?? null,
+    rowKey: (input) => windows.get(queryHash(name, input))?.rowKey ?? null,
     // The two per-subscriber gates, both through the package's one authz seam. Neither result is
     // memoised anywhere: `authorize` runs on every subscribe, `visible` on every row of every
     // delivery, and there is no key here an actor could share with another actor.

package/src/live-fanout.ts

@@ -44,8 +44,10 @@ export async function fanoutChange(
   // that arrived behind the snapshot that already included it — rewound every subscriber's cursor
   // to it and asked them to fold state they had already folded over newer rows.
   if (entry.lsn !== '' && change.lsn <= entry.lsn) return { sent: 0, stale: 1 };
-  const result = bridgeChange(entry.shape, entry.matcher, change, entry.rows);
-  if (!result) return { sent: 0, stale: 0 };
+  const bridged = bridgeChange(entry.shape, entry.matcher, change, entry.rows);
+  if (!bridged) return { sent: 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) };
   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
@@ -138,7 +140,11 @@ async function resnapshot(
   return true;
 }
 
-/** The one place a snapshot frame is built, so the identity scope cannot be told to one caller only. */
+/**
+ * The one place a snapshot frame is built, so the identity scope and the record keys cannot be
+ * told to one caller only. `keys` rides only when some key differs from its row's `id` — an entity
+ * keyed by `id` sends the frame it always sent.
+ */
 export function snapshotFrame(
   entry: QueryEntry,
   sid: string,
@@ -146,5 +152,25 @@ export function snapshotFrame(
   cursor: LiveCursor,
 ): Frame {
   const base = { type: 'snapshot', v: PROTOCOL_VERSION, sid, rows, cursor } as const;
-  return entry.rowEntity === null ? base : { ...base, entity: entry.rowEntity };
+  const scoped = entry.rowEntity === null ? base : { ...base, entity: entry.rowEntity };
+  const keyOf = entry.rowKey;
+  if (keyOf === null) return scoped;
+  const keys = rows.map((row) => keyOf(row));
+  return keys.every((key, index) => key === rows[index]?.id) ? scoped : { ...scoped, keys };
+}
+
+/**
+ * A patch's record key, from the change's WHOLE row — an update patch carries only the changed
+ * columns, and a key needs every primary-key column. Only stamped where it differs from `id`.
+ */
+function keyPatches(
+  entry: QueryEntry,
+  change: ChangeEvent,
+  patches: readonly RowPatch[],
+): readonly RowPatch[] {
+  const keyOf = entry.rowKey;
+  const whole = change.after ?? change.before;
+  if (keyOf === null || whole === null) return patches;
+  const key = keyOf(whole);
+  return patches.map((patch) => (key === patch.id ? patch : { ...patch, key }));
 }

package/src/live-record-type.ts

@@ -0,0 +1,19 @@
+// Which record type a live query's rows are, and the key each row travels under. A changefeed and
+// a snapshot speak TABLES; the page store keys records by the entity's NAME and PRIMARY KEY. Both
+// come from the entity's own projection here, on the server — the browser never derives a key.
+
+import type { Row } from '@ultimat3/core/page';
+import { recordProjectionForTable } from '@ultimat3/entity/record';
+
+export interface LiveRecords {
+  /** The entity name — or the table itself when no registered entity owns it. */
+  readonly type: string;
+  /** The row's record key, or `null` for a plain table, whose rows are keyed by `id`. */
+  readonly key: ((row: Row) => string) | null;
+}
+
+export function liveRecords(table: string): LiveRecords {
+  const projection = recordProjectionForTable(table);
+  if (projection === undefined) return { type: table, key: null };
+  return { type: projection.type, key: (row) => projection.key(row) };
+}

package/src/live-rows.ts

@@ -1,90 +1,101 @@
-// One live subscription's window, projected out of the identity map. The registration owns the
-// ORDER (its ids) and the map owns the VALUES — which is what makes post #7 one object however
-// many queries returned it, and what makes a write through any of them reach all of them.
+// One live subscription's window over the page's record store. The registration owns the ORDER
+// (its ids) and the store owns the VALUES — which is what makes post #7 one object however many
+// queries returned it, and what makes a write through any of them reach all of them.
 
+import type { Row } from '@ultimat3/core/page';
 import { orderAfterPatches } from './apply-patches';
 import type { LiveCursor } from './cursor';
-import { type IdentityMap, type RowKey, type RowScope, rowKey } from './identity-map';
-import type { JsonValue, Row, RowPatch } from './json';
+import type { JsonValue, RowPatch } from './json';
+import { type RecordKey, type RecordStore, recordKey } from './record-store';
 
-export type LiveState = 'loading' | 'live' | 'stale' | 'offline';
+export type LiveState = 'loading' | 'live' | 'stale' | 'offline' | 'failed';
 
 /** One live query this client holds. Mutable: the ids and cursor a frame advances live here. */
 export interface Registration {
   readonly sid: string;
   readonly name: string;
   readonly input: JsonValue;
-  readonly setRows: (rows: readonly Row[]) => void;
-  readonly setState: (state: LiveState) => void;
-  readonly setCursor: (cursor: LiveCursor | null) => void;
-  /** Where this window's rows live in the map: the entity the server named, or a private scope. */
-  scope: RowScope;
-  /** Membership and order. The values are the map's — never a second copy of them. */
+  /** The record type the server named for this window; `unnamedType(name)` until it does. */
+  type: string;
+  /** Membership and order. The values are the store's — never a second copy of them. */
   ids: readonly string[];
   cursor: LiveCursor | null;
+  state: LiveState;
+  /** What the node answered when it refused this subscription. Set with `state: 'failed'`. */
+  error: unknown;
+  /** Called after anything a reader of this window renders has moved. */
+  readonly notify: () => void;
 }
 
 /**
- * Every open window over one identity map. It is the only writer of `Registration.ids`, so the
- * retain/release pairs that keep the map from growing without end cannot be forgotten by a caller.
+ * Where a window's rows live when the server named no record type: `?` starts no entity name, so
+ * two unnamed windows sharing an id never merge two entities' rows. Not a record type — only a
+ * snapshot from a node that cannot name the entity lands here.
+ */
+export function unnamedType(queryName: string): string {
+  return `?query:${queryName}`;
+}
+
+/**
+ * Every open window over the one store. It is the only writer of `Registration.ids`, so the
+ * retain/release pairs that keep the store from growing without end cannot be forgotten.
  */
 export class RowWindows {
-  readonly #identity: IdentityMap;
-  /** The window a write is running for, so its own listener does not emit the same rows twice. */
+  readonly #store: RecordStore;
+  /** The window a write is running for, so its own listener does not notify it twice. */
   #writing: Registration | null = null;
 
-  constructor(identity: IdentityMap) {
-    this.#identity = identity;
+  constructor(store: RecordStore) {
+    this.#store = store;
   }
 
-  /**
-   * Start rendering this registration out of the map. The returned close releases its rows and
-   * drops its listener — an unsubscribed component must stop holding rows and stop hearing about
-   * them in the same call, or one of the two outlives the other.
-   */
+  /** Render this registration out of the store; the returned close releases every row it held. */
   open(registration: Registration): () => void {
-    const unsubscribe = this.#identity.subscribe((changed) => {
+    const unsubscribe = this.#store.subscribe((changed) => {
       if (this.#writing === registration) return;
-      if (!holds(registration, changed)) return;
-      this.#emit(registration);
+      if (holds(registration, changed)) registration.notify();
     });
     return () => {
       unsubscribe();
-      this.#identity.batch(() => {
-        for (const id of registration.ids) this.#identity.release(registration.scope, id);
+      this.#store.batch(() => {
+        for (const id of registration.ids) this.#store.release(registration.type, id);
         registration.ids = [];
       });
     };
   }
 
-  /**
-   * A snapshot: server truth for the whole window. `entity` is the scope the server named for this
-   * subscription — the first one that arrives upgrades a private scope to the shared one, which is
-   * what lets two different queries over one entity meet on the same row.
-   */
-  snapshot(registration: Registration, entity: string | null, rows: readonly Row[]): void {
-    const scope = entity ?? registration.scope;
+  /** A snapshot: server truth for the whole window, under the record type the server named. */
+  snapshot(
+    registration: Registration,
+    type: string | null,
+    rows: readonly Row[],
+    keys?: readonly string[],
+  ): void {
+    const next = type ?? registration.type;
+    // The server's record key where it sent one; a row's `id` IS its key everywhere else.
+    const keyed = rows.map((row, index) => [keys?.[index] ?? String(row['id']), row] as const);
     this.#reseat(
       registration,
-      scope,
-      rows.map((row) => row.id),
-      (held) => {
-        for (const row of rows) {
-          if (held.has(row.id)) this.#identity.merge(scope, row.id, row);
-        }
+      next,
+      keyed.map(([id]) => id),
+      () => {
+        for (const [id, row] of keyed) this.#store.merge(next, id, row);
       },
     );
   }
 
-  /** A patch list: values merged into the map, membership and order folded over the ids. */
-  patch(registration: Registration, patches: readonly RowPatch[]): void {
-    const scope = registration.scope;
-    // A `delete` is this window losing the row, never the map losing it: another window holding
-    // the same row keeps it until its own delete arrives.
-    this.#reseat(registration, scope, orderAfterPatches(registration.ids, patches), (held) => {
+  /** A patch list: values merged into the store, membership and order folded over the ids. */
+  patch(registration: Registration, sent: readonly RowPatch[]): void {
+    const type = registration.type;
+    // A window holds RECORD keys: a patch the server keyed is folded under its key, not its id.
+    const patches = sent.map((patch) =>
+      patch.key === undefined ? patch : { ...patch, id: patch.key },
+    );
+    // A `delete` is this window losing the row, never the store losing it: another holder keeps it.
+    this.#reseat(registration, type, orderAfterPatches(registration.ids, patches), (held) => {
       for (const patch of patches) {
         if (patch.op === 'delete' || patch.row === null) continue;
-        if (held.has(patch.id)) this.#identity.merge(scope, patch.id, patch.row);
+        if (held.has(patch.id)) this.#store.merge(type, patch.id, patch.row);
       }
     });
   }
@@ -93,51 +104,43 @@ export class RowWindows {
   rows(registration: Registration): readonly Row[] {
     const out: Row[] = [];
     for (const id of registration.ids) {
-      const row = this.#identity.peek(registration.scope, id);
+      const row = this.#store.peek(registration.type, id);
       if (row !== undefined) out.push(row);
     }
     return out;
   }
 
   /**
-   * Move the window to `nextIds` under `scope`, writing values in between. One batch per frame,
-   * and one emit for the window that caused it.
-   *
+   * Move the window to `nextIds` under `type`, writing values in between — one batch, one notify.
    * The retain comes before the write and the release after it, so a row this window keeps across
-   * the move never reaches zero holds and gets dropped out from under the value it is about to be
-   * given. `write` only touches ids the window ends up holding — a value nobody holds is a value
-   * no release will ever reclaim.
+   * the move never reaches zero holds and is evicted out from under the value it is being given.
    */
   #reseat(
     registration: Registration,
-    scope: RowScope,
+    type: string,
     nextIds: readonly string[],
     write: (held: ReadonlySet<string>) => void,
   ): void {
     const previous = this.#writing;
     this.#writing = registration;
     try {
-      this.#identity.batch(() => {
-        for (const id of nextIds) this.#identity.retain(scope, id);
+      this.#store.batch(() => {
+        for (const id of nextIds) this.#store.retain(type, id);
         write(new Set(nextIds));
-        for (const id of registration.ids) this.#identity.release(registration.scope, id);
-        registration.scope = scope;
+        for (const id of registration.ids) this.#store.release(registration.type, id);
+        registration.type = type;
         registration.ids = nextIds;
       });
     } finally {
       this.#writing = previous;
     }
-    this.#emit(registration);
-  }
-
-  #emit(registration: Registration): void {
-    registration.setRows(this.rows(registration));
+    registration.notify();
   }
 }
 
-function holds(registration: Registration, changed: ReadonlySet<RowKey>): boolean {
+function holds(registration: Registration, changed: ReadonlySet<RecordKey>): boolean {
   for (const id of registration.ids) {
-    if (changed.has(rowKey(registration.scope, id))) return true;
+    if (changed.has(recordKey(registration.type, id))) return true;
   }
   return false;
 }

package/src/local-store-idb.ts

@@ -0,0 +1,250 @@
+/**
+ * The page's durable client store: persisted records and the one outbox, in IndexedDB, every entry
+ * keyed by the principal it belongs to so one principal's cache can never restore into another's.
+ * IndexedDB blocked (a private window, storage disabled) falls back to memory with ONE warning,
+ * `X_LOCAL_STORE_UNAVAILABLE` — a page never breaks because it cannot remember.
+ */
+
+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 { LocalStoreUnavailableError } from './page-errors';
+
+/** One persisted row, by record type and record key. */
+export interface PersistedRow {
+  readonly type: string;
+  readonly key: string;
+  readonly row: Row;
+}
+
+export interface LocalStore {
+  readonly kind: 'indexeddb' | 'memory';
+  /** Every persisted row of one scope: record type -> record key -> row. */
+  rows(scope: string): Promise<ReadonlyMap<string, RecordRows>>;
+  write(
+    scope: string,
+    puts: readonly PersistedRow[],
+    deletes: readonly Omit<PersistedRow, 'row'>[],
+  ): Promise<void>;
+  queue(scope: string): Promise<QueueState | undefined>;
+  saveQueue(scope: string, state: QueueState): Promise<void>;
+  /** Everything of one scope — its rows AND its outbox. Sign-out, or any principal change. */
+  wipe(scope: string): Promise<void>;
+  /**
+   * Everything of every scope but `keep` — rows and outboxes. The page boot's answer to a sign-out
+   * by full navigation, which never calls `rescope()` and so never reaches `wipe`.
+   */
+  wipeOthers(keep: string): Promise<void>;
+}
+
+/**
+ * The storage key of a principal, or `undefined` for an UNSCOPED page (rendered for nobody):
+ * nothing is persisted there, because there is no principal to key it by. Prefixed so a principal
+ * spelled `anon` can never share the anonymous visitor's rows.
+ */
+export function scopeKey(principal: ClientScope['principal']): string | undefined {
+  if (principal === undefined) return undefined;
+  return principal === null ? 'anon' : `p:${principal}`;
+}
+
+const RECORDS = 'records';
+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]);
+
+/** 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>();
+
+  async rows(scope: string): Promise<ReadonlyMap<string, RecordRows>> {
+    return group([...this.#rows.values()].filter((entry) => entry.scope === scope));
+  }
+  async write(
+    scope: string,
+    puts: readonly PersistedRow[],
+    deletes: readonly Omit<PersistedRow, 'row'>[],
+  ): Promise<void> {
+    for (const { type, key } of deletes) this.#rows.delete(rowKey(scope, type, key));
+    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);
+  }
+  async saveQueue(scope: string, state: QueueState): Promise<void> {
+    this.#queues.set(scope, structuredClone(state));
+  }
+  async wipe(scope: string): Promise<void> {
+    for (const [key, entry] of this.#rows) if (entry.scope === scope) this.#rows.delete(key);
+    this.#queues.delete(scope);
+  }
+  async wipeOthers(keep: string): Promise<void> {
+    for (const [key, entry] of this.#rows) if (entry.scope !== keep) this.#rows.delete(key);
+    for (const scope of [...this.#queues.keys()]) if (scope !== keep) this.#queues.delete(scope);
+  }
+}
+
+class IdbLocalStore implements LocalStore {
+  readonly kind = 'indexeddb';
+  constructor(private readonly db: IdbDatabaseLike) {}
+
+  async rows(scope: string): Promise<ReadonlyMap<string, RecordRows>> {
+    const tx = this.db.transaction(RECORDS, 'readonly');
+    const store = tx.objectStore(RECORDS);
+    const [keys, values] = await Promise.all([answer(store.getAllKeys()), answer(store.getAll())]);
+    const found: PersistedRow[] = [];
+    keys.forEach((raw, index) => {
+      const parts: unknown = typeof raw === 'string' ? JSON.parse(raw) : undefined;
+      const row = values[index];
+      if (!Array.isArray(parts) || parts[0] !== scope || !isJsonObject(row)) return;
+      found.push({ type: String(parts[1]), key: String(parts[2]), row });
+    });
+    return group(found);
+  }
+  async write(
+    scope: string,
+    puts: readonly PersistedRow[],
+    deletes: readonly Omit<PersistedRow, 'row'>[],
+  ): Promise<void> {
+    const tx = this.db.transaction(RECORDS, 'readwrite');
+    const store = tx.objectStore(RECORDS);
+    for (const { type, key } of deletes) store.delete(rowKey(scope, type, key));
+    for (const put of puts) store.put(put.row, rowKey(scope, put.type, put.key));
+    await done(tx);
+  }
+  async queue(scope: string): Promise<QueueState | undefined> {
+    const tx = this.db.transaction(OUTBOX, 'readonly');
+    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);
+  }
+  async saveQueue(scope: string, state: QueueState): Promise<void> {
+    const tx = this.db.transaction(OUTBOX, 'readwrite');
+    tx.objectStore(OUTBOX).put(state, scope);
+    await done(tx);
+  }
+  async wipe(scope: string): Promise<void> {
+    const tx = this.db.transaction([RECORDS, OUTBOX], 'readwrite');
+    const records = tx.objectStore(RECORDS);
+    const keys = await answer(records.getAllKeys());
+    for (const raw of keys) {
+      if (typeof raw !== 'string') continue;
+      const parts: unknown = JSON.parse(raw);
+      if (Array.isArray(parts) && parts[0] === scope) records.delete(raw);
+    }
+    tx.objectStore(OUTBOX).delete(scope);
+    await done(tx);
+  }
+  async wipeOthers(keep: string): Promise<void> {
+    const tx = this.db.transaction([RECORDS, OUTBOX], 'readwrite');
+    const records = tx.objectStore(RECORDS);
+    const outbox = tx.objectStore(OUTBOX);
+    const [rowKeys, queueKeys] = await Promise.all([
+      answer(records.getAllKeys()),
+      answer(outbox.getAllKeys()),
+    ]);
+    for (const raw of rowKeys) {
+      if (typeof raw !== 'string') continue;
+      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);
+    }
+    await done(tx);
+  }
+}
+
+export interface OpenLocalStoreOptions {
+  /** Default `globalThis.indexedDB`, read at call time. */
+  readonly indexedDB?: IdbFactoryLike | undefined;
+  /** Where the one fallback warning goes. Default `console.warn`. */
+  readonly warn?: ((error: UltimateError) => void) | undefined;
+  readonly name?: string | undefined;
+}
+
+/** IndexedDB when the page has it and it opens; memory, warned once, when it does not. */
+export async function openLocalStore(options: OpenLocalStoreOptions = {}): Promise<LocalStore> {
+  // The browser's `IDBFactory` IS this shape at runtime; its DOM typings (event-typed handlers)
+  // are wider than the slice `idb-types.ts` declares, so the ambient value is narrowed once here.
+  const ambient: unknown = Reflect.get(globalThis, 'indexedDB');
+  const factory = options.indexedDB ?? (ambient as IdbFactoryLike | undefined);
+  const warn = options.warn ?? ((error: UltimateError) => console.warn(error));
+  if (factory === undefined) {
+    warn(new LocalStoreUnavailableError({ reason: 'this runtime has no indexedDB' }));
+    return new MemoryLocalStore();
+  }
+  try {
+    return new IdbLocalStore(await openDatabase(factory, options.name ?? 'ultimate-client'));
+  } catch (error) {
+    warn(
+      new LocalStoreUnavailableError({
+        reason: `indexedDB.open failed: ${renderThrowable(error)}`,
+      }),
+    );
+    return new MemoryLocalStore();
+  }
+}
+
+function openDatabase(factory: IdbFactoryLike, name: string): Promise<IdbDatabaseLike> {
+  return new Promise((resolve, reject) => {
+    const request = factory.open(name, 1);
+    request.onupgradeneeded = (): void => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(RECORDS)) db.createObjectStore(RECORDS);
+      if (!db.objectStoreNames.contains(OUTBOX)) db.createObjectStore(OUTBOX);
+    };
+    request.onsuccess = (): void => resolve(request.result);
+    request.onerror = (): void => reject(request.error);
+    request.onblocked = (): void => reject(request.error ?? 'blocked by another open tab');
+  });
+}
+
+function answer<T>(request: IdbRequestLike<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = (): void => resolve(request.result);
+    request.onerror = (): void => reject(request.error);
+  });
+}
+
+function done(tx: {
+  oncomplete: (() => void) | null;
+  onerror: (() => void) | null;
+  error: unknown;
+}): Promise<void> {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = (): void => resolve();
+    tx.onerror = (): void => reject(tx.error);
+  });
+}
+
+function group(entries: readonly PersistedRow[]): ReadonlyMap<string, RecordRows> {
+  const out = new Map<string, Record<string, Row>>();
+  for (const { type, key, row } of entries) {
+    const rows = out.get(type) ?? (Object.create(null) as Record<string, Row>);
+    Object.defineProperty(rows, key, { value: row, enumerable: true });
+    out.set(type, rows);
+  }
+  return out;
+}
+
+const PAGE_KEY: unique symbol = Symbol.for('ultimate.local-store');
+type PageHost = { [PAGE_KEY]?: Promise<LocalStore> };
+
+/**
+ * The page's ONE durable store, opened once per tab whichever island asks first — the persister and
+ * the outbox share it, so a wipe on a principal change reaches both. On `globalThis`, like the
+ * record store, because every island bundle carries its own copy of this module.
+ */
+export function pageLocalStore(): Promise<LocalStore> {
+  const host = globalThis as PageHost;
+  const existing = host[PAGE_KEY];
+  if (existing !== undefined) return existing;
+  const opened = openLocalStore();
+  Object.defineProperty(host, PAGE_KEY, { value: opened, configurable: true });
+  return opened;
+}

package/src/offline-queue.ts

@@ -9,9 +9,9 @@
 //      to a socket and nothing more, so a drained mutation is `inflight` — not `acked` — until an
 //      `ack`/`fail` frame settles it, or a lost connection returns it to the queue.
 
-import { renderThrowable, stringField } from '@ultimat3/core';
+import { renderThrowable, stringField } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
-import { type Frame, PROTOCOL_VERSION, type WireError } from './sync-protocol';
+import type { WireError } from './sync-protocol';
 
 export type MutationStatus = 'pending' | 'inflight' | 'acked' | 'failed';
 
@@ -33,7 +33,7 @@ export interface QueueState {
   readonly nextSeq: number;
 }
 
-/** Durability seam: OPFS/IndexedDB in the browser, memory in tests. */
+/** Durability seam: IndexedDB in the browser (`page-outbox.ts`), memory in tests. */
 export interface QueueStore {
   load(): Promise<QueueState>;
   save(state: QueueState): Promise<void>;
@@ -131,8 +131,8 @@ export class OfflineQueue {
     // 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.
-    if (existing)
-      this.#mutations = this.#mutations.filter((candidate) => candidate.key !== args.key);
+    // 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);
     const mutation: QueuedMutation = {
       key: args.key,
       seq: this.#nextSeq,
@@ -204,7 +204,8 @@ export class OfflineQueue {
     const mutation = this.find(key);
     if (!mutation) return;
     mutation.status = 'acked';
-    this.#mutations = this.#mutations.filter((candidate) => candidate.key !== key);
+    // 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);
     await this.#persist();
   }
 
@@ -316,18 +317,8 @@ export class OfflineQueue {
   }
 }
 
-export function mutateFrame(mutation: QueuedMutation): Frame {
-  return {
-    type: 'mutate',
-    v: PROTOCOL_VERSION,
-    key: mutation.key,
-    seq: mutation.seq,
-    name: mutation.name,
-    input: mutation.input,
-  };
-}
-
-function toQueueError(error: unknown): WireError {
+/** A thrown value as the queue records it — `code`, `cause`, `fix`, never a throw of its own. */
+export function toQueueError(error: unknown): WireError {
   return {
     // `stringField`, not `shape?.code`: the sender is a transport the app supplied, so the probe
     // for "did it throw a coded error" is itself a property read on an app value. A getter that