@spooky-sync/core 0.0.1-canary.202 → 0.0.1-canary.204

package/dist/sqlite-open.js

@@ -170,6 +170,33 @@ function reviveRow(json) {
 		return v;
 	});
 }
+/**
+* SELECT-clause expression yielding the row's `data` narrowed to `fields` (plus
+* `id`), so SQLite never returns — and neither side ever parses — the fields the
+* caller did not ask for. On a game list that is every row's `pgn`, which was
+* being read, parsed and thrown away 50 rows at a time for eight rendered fields.
+*
+* Byte-identical to running {@link project} over the fully-parsed row, which is
+* what both paths did before, and verified so against real SQLite:
+* `json_each` walks the keys the row ACTUALLY has, so an ABSENT key stays absent
+* rather than becoming an explicit null — the difference `json_object`/
+* `json_extract` would have introduced. A stored null, nested objects and
+* arrays, and `{__u8}` blob tags all round-trip unchanged, because
+* `json_group_object` understands `json_each`'s `value` column as JSON rather
+* than as text. `COALESCE` covers a row sharing none of the requested keys,
+* where the subquery yields NULL and `reviveRow` would throw.
+*
+* Deliberately unaliased, so the emitted statement keeps the exact shape the
+* callers already produce (`FROM "t" WHERE id IN (…)`).
+*
+* Binds one parameter per key, pushed onto `bind` — these land in the SELECT
+* clause, so they must be bound BEFORE any WHERE parameters.
+*/
+function projectedDataSql(fields, bind) {
+	const keys = ["id", ...fields];
+	for (const k of keys) bind.push(k);
+	return `COALESCE((SELECT json_group_object(je.key, je.value) FROM json_each(data) je WHERE je.key IN (${keys.map(() => "?").join(", ")})), '{}') AS data`;
+}
 function project(row, fields) {
 	const out = {};
 	for (const f of ["id", ...fields]) if (f in row) out[f] = row[f];
@@ -273,4 +300,4 @@ async function openDb(sqlite3, dbName, useOpfs, opts = {}) {
 }
 
 //#endregion
-export { renderWhereSql as a, resolveRelations as c, renderOrderSql as i, stableKey as l, openDb as n, reviveRow as o, project as r, serializeRow as s, PROMOTION_OPEN_OPTIONS as t };
+export { renderOrderSql as a, serializeRow as c, projectedDataSql as i, resolveRelations as l, openDb as n, renderWhereSql as o, project as r, reviveRow as s, PROMOTION_OPEN_OPTIONS as t, stableKey as u };

package/dist/sqlite-worker.js

@@ -1,4 +1,4 @@
-import { a as renderWhereSql, c as resolveRelations, i as renderOrderSql, l as stableKey, n as openDb, o as reviveRow, r as project } from "./sqlite-open.js";
+import { a as renderOrderSql, i as projectedDataSql, l as resolveRelations, n as openDb, o as renderWhereSql, r as project, s as reviveRow, u as stableKey } from "./sqlite-open.js";
 import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
 
 //#region src/services/database/sqlite-select.ts
@@ -16,14 +16,18 @@ function selectByIds(db, table, ids, opts) {
 	if (ids.length === 0) return [];
 	ensureTable(db, table);
 	const keys = ids.map(stableKey);
-	let sql = `SELECT data FROM "${table}" WHERE id IN (${keys.map(() => "?").join(", ")})`;
+	const placeholders = keys.map(() => "?").join(", ");
+	const bind = [];
+	const dataCol = opts?.select ? projectedDataSql(opts.select, bind) : "data";
+	bind.push(...keys);
+	let sql = `SELECT ${dataCol} FROM "${table}" WHERE id IN (${placeholders})`;
 	if (opts?.orderBy && opts.orderBy.length > 0) sql += renderOrderSql(opts.orderBy);
-	let rows = execRows(db, sql, keys);
+	let rows = execRows(db, sql, bind);
 	if (!opts?.orderBy || opts.orderBy.length === 0) {
 		const pos = new Map(keys.map((k, i) => [k, i]));
 		rows = rows.sort((a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0));
 	}
-	return opts?.select ? rows.map((r) => project(r, opts.select)) : rows;
+	return rows;
 }
 /** Mirrors the engine's `fetchRelation` SQL exactly. */
 function fetchRelation(db, req) {
@@ -57,17 +61,16 @@ async function executeSelect(plan, params, db) {
 	}
 	ensureTable(db, plan.table);
 	const bind = [];
-	let sql = `SELECT data FROM "${plan.table}"`;
+	let sql = `SELECT ${plan.select ? projectedDataSql(plan.select, bind) : "data"} FROM "${plan.table}"`;
 	if (plan.where && plan.where.length > 0) sql += ` WHERE ${renderWhereSql(plan.where, bind, params)}`;
 	if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderSql(plan.orderBy);
 	else sql += ` ORDER BY id`;
 	if (plan.limit !== void 0) sql += ` LIMIT ${Number(plan.limit)}`;
 	if (plan.offset !== void 0) sql += ` OFFSET ${Number(plan.offset)}`;
 	const rows = execRows(db, sql, bind);
-	const projected = plan.select ? rows.map((r) => project(r, plan.select)) : rows;
-	await resolveRelations(projected, plan.relations, fetcher);
+	await resolveRelations(rows, plan.relations, fetcher);
 	return {
-		rows: projected,
+		rows,
 		relationFetches: counter.n
 	};
 }

package/dist/types.d.ts

@@ -654,6 +654,12 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * `0` disables. Defaults to `30_000`.
    */
   pushTimeoutMs?: number;
+  /**
+   * Max time a single down event (`register`/`sync`/`cleanup`) may take before
+   * it is retried. Mirror of {@link pushTimeoutMs} for the read side.
+   * Defaults to 30000; `0` disables the timeout.
+   */
+  downTimeoutMs?: number;
 }
 /** Tunables for sync-health reporting. See {@link Sp00kyConfig.syncHealth}. */
 interface SyncHealthConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.202",
+  "version": "0.0.1-canary.204",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.202",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.202",
+    "@spooky-sync/query-builder": "0.0.1-canary.204",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.204",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/modules/auth/auth.local-first.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi } from 'vitest';
+import { AuthService } from './index';
+
+// A SurrealDB record-access JWT carries the access method as `AC` and the
+// `$auth.id` record id as `ID`. Only the payload matters here - nothing in the
+// client verifies the signature, the server does.
+function jwt(claims: Record<string, unknown>): string {
+  const b64 = Buffer.from(JSON.stringify(claims)).toString('base64url');
+  return `header.${b64}.signature`;
+}
+
+const silentLogger = () =>
+  ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), child: () => silentLogger() }) as any;
+
+function makeAuth(opts: { token?: string | null; query?: any; authenticate?: any } = {}) {
+  const store = new Map<string, unknown>();
+  if (opts.token) store.set('sp00ky_auth_token', opts.token);
+  const persistence = {
+    get: vi.fn(async (k: string) => store.get(k) ?? null),
+    set: vi.fn(async (k: string, v: unknown) => void store.set(k, v)),
+    remove: vi.fn(async (k: string) => void store.delete(k)),
+  } as any;
+  const remote = {
+    query: opts.query ?? vi.fn(async () => [[]]),
+    getClient: () => ({ authenticate: opts.authenticate ?? vi.fn(async () => undefined) }),
+  } as any;
+  return { auth: new AuthService({} as any, remote, persistence, silentLogger()), remote, persistence, store };
+}
+
+describe('restoreSessionFromToken', () => {
+  it('restores the session from the cached token with NO network', async () => {
+    const { auth, remote } = makeAuth({ token: jwt({ AC: 'account', ID: 'user:abc' }) });
+
+    const userId = await auth.restoreSessionFromToken();
+
+    expect(userId).toBe('user:abc');
+    expect(auth.isAuthenticated).toBe(true);
+    expect(auth.currentUser?.id).toBe('user:abc');
+    expect(auth.access).toBe('account');
+    // The whole point: this is what makes a warm/offline boot paint.
+    expect(remote.query).not.toHaveBeenCalled();
+  });
+
+  it('notifies subscribers so query routing can be set before any registration', async () => {
+    const { auth } = makeAuth({ token: jwt({ AC: 'account', ID: 'user:abc' }) });
+    const seen: (string | null)[] = [];
+    auth.subscribe((uid) => seen.push(uid));
+
+    await auth.restoreSessionFromToken();
+
+    expect(seen).toContain('user:abc');
+  });
+
+  it('returns null when there is no token, and when the token carries no id', async () => {
+    expect(await makeAuth().auth.restoreSessionFromToken()).toBeNull();
+    const noId = makeAuth({ token: jwt({ AC: 'account' }) });
+    expect(await noId.auth.restoreSessionFromToken()).toBeNull();
+    expect(noId.auth.isAuthenticated).toBe(false);
+  });
+
+  it('survives a malformed token rather than throwing', async () => {
+    const { auth } = makeAuth({ token: 'not-a-jwt' });
+    expect(await auth.restoreSessionFromToken()).toBeNull();
+  });
+});
+
+describe('check() error handling', () => {
+  const token = jwt({ AC: 'account', ID: 'user:abc' });
+
+  it('KEEPS the cached session when the server is unreachable', async () => {
+    const { auth, persistence, store } = makeAuth({
+      token,
+      authenticate: vi.fn(async () => {
+        throw new Error('There was a problem with the underlying connection');
+      }),
+    });
+    await auth.restoreSessionFromToken();
+
+    await auth.check();
+
+    // A blip must not log the user out - that is what makes offline possible.
+    expect(auth.isAuthenticated).toBe(true);
+    expect(store.get('sp00ky_auth_token')).toBe(token);
+    expect(persistence.remove).not.toHaveBeenCalled();
+  });
+
+  it('signs out for real when the server REJECTS the token', async () => {
+    const { auth, store } = makeAuth({
+      token,
+      authenticate: vi.fn(async () => {
+        throw new Error('There was a problem with the database: Invalid token');
+      }),
+    });
+    await auth.restoreSessionFromToken();
+
+    await auth.check();
+
+    expect(auth.isAuthenticated).toBe(false);
+    expect(store.get('sp00ky_auth_token')).toBeUndefined();
+  });
+});

package/src/modules/auth/index.ts

@@ -9,6 +9,7 @@ import type { Logger } from '../../services/logger/index';
 export * from './events/index';
 import { AuthEventTypes, createAuthEventSystem } from './events/index';
 import type { PersistenceClient } from '../../types';
+import { classifySyncError } from '../../utils/error-classification';
 
 // Helper to pretty print types
 type Prettify<T> = {
@@ -36,28 +37,41 @@ type ExtractAccessParams<
     : never;
 
 /**
- * Read the `AC` (access-method name) claim from a SurrealDB record-access
- * JWT without verifying it — we only need the claim, the server enforces the
- * token. Returns null on any malformed input. The in-browser SSP needs this
- * to resolve `$access` in table permission predicates (mirrors the session's
- * `$access` that the server's `fn::query::register` reads).
+ * Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
+ * server still enforces the token on every request; this is only so the client
+ * can act on what it already holds before a round trip completes.
+ *
+ * `AC` is the access-method name — the in-browser SSP needs it to resolve
+ * `$access` in table permission predicates (mirrors the session's `$access`
+ * that the server's `fn::query::register` reads). `ID` is the `$auth.id` record
+ * id, which is what lets a warm boot restore a session locally.
+ *
+ * Returns nulls on any malformed input.
  */
-function decodeAccessFromToken(token: string): string | null {
+function decodeTokenClaims(token: string): { access: string | null; userId: string | null } {
   try {
     const payload = token.split('.')[1];
-    if (!payload) return null;
+    if (!payload) return { access: null, userId: null };
     let b64 = payload.replace(/-/g, '+').replace(/_/g, '/');
     b64 += '='.repeat((4 - (b64.length % 4)) % 4);
     const json =
       typeof atob === 'function' ? atob(b64) : Buffer.from(b64, 'base64').toString('binary');
     const claims = JSON.parse(json) as Record<string, unknown>;
     const ac = claims.AC ?? claims.ac;
-    return typeof ac === 'string' ? ac : null;
+    const id = claims.ID ?? claims.id;
+    return {
+      access: typeof ac === 'string' ? ac : null,
+      userId: typeof id === 'string' ? id : null,
+    };
   } catch {
-    return null;
+    return { access: null, userId: null };
   }
 }
 
+function decodeAccessFromToken(token: string): string | null {
+  return decodeTokenClaims(token).access;
+}
+
 export class AuthService<S extends SchemaStructure> {
   // State
   public token: string | null = null;
@@ -115,6 +129,44 @@ export class AuthService<S extends SchemaStructure> {
     this.events.emit(AuthEventTypes.AuthStateChanged, userId);
   }
 
+  /**
+   * Restore a session from the locally cached JWT, with NO network.
+   *
+   * This is what makes a warm boot paint instantly and what makes an offline
+   * boot possible at all: the token is in local storage, and it already carries
+   * both the access method and the `$auth.id` record id. Everything the client
+   * needs to route queries (`setCurrentUserId`) and to satisfy `$auth`-gated
+   * permission predicates in the in-browser SSP (`setSessionAuth`) is therefore
+   * available before a socket exists.
+   *
+   * The session is OPTIMISTIC: the token is unverified here. `check()` runs
+   * afterwards in the background and downgrades to a real sign-out if the
+   * server rejects it. Nothing is trusted that the server has not also seen -
+   * the local store only ever holds rows the server previously sent.
+   *
+   * Returns the restored user id, or null when there is no usable token.
+   */
+  async restoreSessionFromToken(): Promise<string | null> {
+    const token = await this.persistenceClient.get<string>('sp00ky_auth_token');
+    if (!token) return null;
+    const { access, userId } = decodeTokenClaims(token);
+    if (!userId) return null;
+
+    this.token = token;
+    // Only the id: the full row is not in the token. It lands from the local
+    // cache when the app's own `user` query paints, and is replaced wholesale
+    // by `check()` once the server answers.
+    this.currentUser = { id: userId };
+    this.isAuthenticated = true;
+    this.access = access ?? this.defaultAccessName();
+    this.notifyListeners();
+    this.logger.debug(
+      { userId, Category: 'sp00ky-client::AuthService::restoreSessionFromToken' },
+      'Session restored optimistically from cached token'
+    );
+    return userId;
+  }
+
   /**
    * Check for existing session and validate
    */
@@ -180,11 +232,23 @@ export class AuthService<S extends SchemaStructure> {
         }
       }
     } catch (error) {
-      this.logger.error(
-        { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
-        'Auth check failed'
-      );
-      await this.signOut();
+      // A REACHABILITY failure is not a rejected token. This catch used to call
+      // signOut() unconditionally, which deletes `sp00ky_auth_token` - so a
+      // blip on boot silently logged the user out, and an offline boot could
+      // never stay signed in. Only an application error (the server answered,
+      // and the answer was "no") ends the session.
+      if (classifySyncError(error) === 'network') {
+        this.logger.warn(
+          { error, Category: 'sp00ky-client::AuthService::check' },
+          'Auth check unreachable; keeping the cached session and retrying later'
+        );
+      } else {
+        this.logger.error(
+          { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
+          'Auth check failed'
+        );
+        await this.signOut();
+      }
     } finally {
       this.isLoading = false;
     }

package/src/modules/cache/index.ts

@@ -151,17 +151,18 @@ export class CacheModule implements StreamUpdateReceiver {
           )
         );
 
-        const params = populatedRecords.reduce(
-          (acc, record, i) => {
-            const { id, ...content } = record.record;
-            return {
-              ...acc,
-              [`id${i}`]: id,
-              [`content${i}`]: content,
-            };
-          },
-          {} as Record<string, any>
-        );
+        // Filled in place, NOT with a spread-per-iteration reduce: spreading the
+        // accumulator copies every key written so far on each record, which is
+        // O(n^2) in the batch size. On a cold start that batches thousands of
+        // rows (a game library, a player-name registry) it was the single
+        // biggest main-thread cost of the whole boot - ~36% of samples, seconds
+        // of blocking - for a loop that does no real work.
+        const params: Record<string, any> = {};
+        for (let i = 0; i < populatedRecords.length; i++) {
+          const { id, ...content } = populatedRecords[i].record;
+          params[`id${i}`] = id;
+          params[`content${i}`] = content;
+        }
 
         await this.local.execute(query, params, { epoch });
       }

package/src/modules/data/data.pending-ids.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DataModule } from './index';
+
+/**
+ * `getPendingRecordIds` used to run a full `SELECT ... FROM
+ * _00_pending_mutations` on EVERY materialization of EVERY query — a round trip
+ * down the local engine's single-flight op queue, paid tens of times per ingest
+ * against an outbox that is usually empty. It is now cached, invalidated when
+ * the outbox actually changes, with a short TTL as a backstop.
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+/** DataModule over a local store that counts outbox reads and can be told what
+ *  to return. */
+function makeModule(rows: { recordId: RecordId<string>; mutationType: string }[] = []) {
+  const state = { rows, reads: 0 };
+  const local = {
+    query: vi.fn(async () => {
+      state.reads++;
+      return [state.rows];
+    }),
+  };
+  const dm = new DataModule(
+    {} as any,
+    local as any,
+    { tables: [] } as any,
+    makeLogger(),
+    100
+  );
+  return { dm, state };
+}
+
+const pending = (id: string, mutationType = 'update') => ({
+  recordId: new RecordId('game', id),
+  mutationType,
+});
+
+describe('DataModule pending-id cache', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('reads the outbox once for repeated calls', async () => {
+    const { dm, state } = makeModule([pending('a')]);
+    await dm.getPendingRecordIds();
+    await dm.getPendingRecordIds();
+    await dm.getPendingRecordIds();
+    expect(state.reads).toBe(1);
+  });
+
+  it('collapses a burst of CONCURRENT calls into one read', async () => {
+    // The real shape: one ingest fans out to many queries materializing at once.
+    const { dm, state } = makeModule([pending('a')]);
+    await Promise.all([
+      dm.getPendingRecordIds(),
+      dm.getPendingRecordIds(),
+      dm.getPendingRecordIds(),
+      dm.getPendingRecordIds(),
+    ]);
+    expect(state.reads).toBe(1);
+  });
+
+  it('hands out COPIES, so a caller mutating the sets cannot poison the cache', async () => {
+    // buildRenderIds merges the settled-write ids into what it gets back.
+    const { dm } = makeModule([pending('a')]);
+    const first = await dm.getPendingRecordIds();
+    first.writes.add('game:injected');
+    const second = await dm.getPendingRecordIds();
+    expect(second.writes.has('game:injected')).toBe(false);
+    expect([...second.writes]).toEqual(['game:a']);
+  });
+
+  it('re-reads after a mutation settles (its outbox row is gone)', async () => {
+    const { dm, state } = makeModule([pending('a')]);
+    await dm.getPendingRecordIds();
+    expect(state.reads).toBe(1);
+
+    state.rows = [];
+    dm.noteWriteSettled('game:a', 'update');
+    const after = await dm.getPendingRecordIds();
+
+    expect(state.reads).toBe(2);
+    expect(after.writes.size).toBe(0);
+  });
+
+  it('re-reads once the TTL backstop lapses', async () => {
+    // Covers any path that removes an outbox row without telling us: staleness
+    // is bounded to a tick rather than lasting the session.
+    const { dm, state } = makeModule([pending('a')]);
+    await dm.getPendingRecordIds();
+    expect(state.reads).toBe(1);
+
+    vi.setSystemTime(Date.now() + 1_000);
+    await dm.getPendingRecordIds();
+    expect(state.reads).toBe(2);
+  });
+
+  it('does NOT cache a failed read', async () => {
+    // Empty sets are this call's fallback, not a claim that the outbox is empty.
+    const { dm, state } = makeModule([pending('a')]);
+    (dm as any).local.query = vi.fn(async () => {
+      state.reads++;
+      throw new Error('engine down');
+    });
+    const failed = await dm.getPendingRecordIds();
+    expect(failed.writes.size).toBe(0);
+    expect(state.reads).toBe(1);
+
+    await dm.getPendingRecordIds();
+    expect(state.reads).toBe(2);
+  });
+
+  it('splits writes from deletes', async () => {
+    const { dm } = makeModule([pending('a'), pending('b', 'delete')]);
+    const { writes, deletes } = await dm.getPendingRecordIds();
+    expect([...writes]).toEqual(['game:a']);
+    expect([...deletes]).toEqual(['game:b']);
+  });
+});

package/src/modules/data/index.ts

@@ -587,6 +587,32 @@ export class DataModule<S extends SchemaStructure> {
   private readonly settledWrites = new Map<string, number>();
   private readonly settledDeletes = new Map<string, number>();
 
+  // ---- Outbox id cache -----------------------------------------------------
+  //
+  // `getPendingRecordIds` runs a full `SELECT ... FROM _00_pending_mutations`,
+  // and `buildRenderIds` calls it on EVERY materialization of EVERY query. That
+  // is a round trip down the local engine's single-flight op queue, so with tens
+  // of live queries one ingest fanned out into tens of them — in a 4-second
+  // capture, 11 of 25 local queries were that one statement, against an outbox
+  // holding zero rows.
+  //
+  // Cached, and invalidated at the two points that change the outbox: enqueueing
+  // a mutation (below) and `noteWriteSettled` (the row is deleted before it is
+  // called). The TTL is a BACKSTOP, not the mechanism: should some other path
+  // ever remove a row without telling us, this bounds the staleness to one tick
+  // instead of the session. Well under the grace windows the render set already
+  // tolerates deliberately (SETTLED_WRITE_GRACE_MS is 10s).
+  private pendingIds: { writes: Set<string>; deletes: Set<string> } | null = null;
+  private pendingIdsAt = 0;
+  private pendingIdsInflight: Promise<{ writes: Set<string>; deletes: Set<string> }> | null = null;
+  private static readonly PENDING_IDS_TTL_MS = 250;
+
+  /** Drop the cached outbox ids. Cheap; call it on anything that could change
+   *  `_00_pending_mutations`. */
+  private invalidatePendingIds(): void {
+    this.pendingIds = null;
+  }
+
   /**
    * Grace period for a settled write. Long enough to cover an SSP round trip
    * that is running slowly (seconds, not milliseconds, when the edge path is
@@ -606,6 +632,9 @@ export class DataModule<S extends SchemaStructure> {
    * disappear immediately, which is what makes this safe.
    */
   noteWriteSettled(recordId: string, mutationType: string): void {
+    // The outbox row is already gone by the time this is called — that is what
+    // makes it the delete-side invalidation point for the cache above.
+    this.invalidatePendingIds();
     const until = Date.now() + DataModule.SETTLED_WRITE_GRACE_MS;
     if (mutationType === 'delete') this.settledDeletes.set(recordId, until);
     else this.settledWrites.set(recordId, until);
@@ -1181,6 +1210,30 @@ export class DataModule<S extends SchemaStructure> {
    * briefly hide an optimistic write but never resurrects a deleted row.
    */
   async getPendingRecordIds(): Promise<{ writes: Set<string>; deletes: Set<string> }> {
+    const now = Date.now();
+    const cached = this.pendingIds;
+    if (cached && now - this.pendingIdsAt < DataModule.PENDING_IDS_TTL_MS) {
+      // COPIES: `buildRenderIds` merges the settled-write ids into these sets,
+      // and handing out the cached instances would let it grow them permanently.
+      return { writes: new Set(cached.writes), deletes: new Set(cached.deletes) };
+    }
+    // Single-flight: one ingest fans out to many queries materializing at once,
+    // and without this they all queue their own identical read behind each other.
+    if (!this.pendingIdsInflight) {
+      this.pendingIdsInflight = this.readPendingRecordIds().finally(() => {
+        this.pendingIdsInflight = null;
+      });
+    }
+    const fresh = await this.pendingIdsInflight;
+    return { writes: new Set(fresh.writes), deletes: new Set(fresh.deletes) };
+  }
+
+  /** The uncached read. Also the reload path after an invalidation, so the ids
+   *  still survive a reload exactly as before. */
+  private async readPendingRecordIds(): Promise<{
+    writes: Set<string>;
+    deletes: Set<string>;
+  }> {
     const writes = new Set<string>();
     const deletes = new Set<string>();
     try {
@@ -1198,7 +1251,12 @@ export class DataModule<S extends SchemaStructure> {
         { err, Category: 'sp00ky-client::DataModule::getPendingRecordIds' },
         'Failed to read pending mutations; optimistic writes may be briefly hidden'
       );
+      // Do NOT cache a failed read: the empty sets are a fallback for this call,
+      // not a statement that the outbox is empty.
+      return { writes, deletes };
     }
+    this.pendingIds = { writes, deletes };
+    this.pendingIdsAt = Date.now();
     return { writes, deletes };
   }
 
@@ -1685,6 +1743,8 @@ export class DataModule<S extends SchemaStructure> {
       tableName,
     };
 
+    // A new outbox row: the cached pending-id sets no longer describe it.
+    this.invalidatePendingIds();
     for (const callback of this.mutationCallbacks) {
       callback([mutationEvent]);
     }
@@ -1778,6 +1838,8 @@ export class DataModule<S extends SchemaStructure> {
       options: pushEventOptions,
     };
 
+    // A new outbox row: the cached pending-id sets no longer describe it.
+    this.invalidatePendingIds();
     for (const callback of this.mutationCallbacks) {
       callback([mutationEvent]);
     }
@@ -1853,6 +1915,8 @@ export class DataModule<S extends SchemaStructure> {
       record_id: rid,
     };
 
+    // A new outbox row: the cached pending-id sets no longer describe it.
+    this.invalidatePendingIds();
     for (const callback of this.mutationCallbacks) {
       callback([mutationEvent]);
     }