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

package/dist/index.d.ts

@@ -696,6 +696,13 @@ declare class DataModule<S extends SchemaStructure> {
   private resolveMembership;
   private readonly settledWrites;
   private readonly settledDeletes;
+  private pendingIds;
+  private pendingIdsAt;
+  private pendingIdsInflight;
+  private static readonly PENDING_IDS_TTL_MS;
+  /** Drop the cached outbox ids. Cheap; call it on anything that could change
+   *  `_00_pending_mutations`. */
+  private invalidatePendingIds;
   /**
    * 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
@@ -841,6 +848,9 @@ declare class DataModule<S extends SchemaStructure> {
     writes: Set<string>;
     deletes: Set<string>;
   }>;
+  /** The uncached read. Also the reload path after an invalidation, so the ids
+   *  still survive a reload exactly as before. */
+  private readPendingRecordIds;
   /** True while ≥1 live subscriber is watching this query (refcount guard). */
   hasSubscribers(hash: string): boolean;
   /**
@@ -1079,6 +1089,15 @@ interface Sp00kySyncOptions {
    * up-queue for the session. Defaults to 30000; `0` disables the timeout.
    */
   pushTimeoutMs?: number;
+  /**
+   * Max time a single down event (`register`/`sync`/`cleanup`) may take before
+   * it is treated as a network failure and retried. The mirror of
+   * {@link pushTimeoutMs} for the read side, which had no such guard: a
+   * `fn::query::register` that never settled held its slot in the down drain,
+   * and every later registration behind it, for the rest of the session.
+   * Defaults to 30000; `0` disables the timeout.
+   */
+  downTimeoutMs?: number;
   /**
    * Transport supervisor. Sync reads its state to report `connection` in
    * {@link SyncHealth} so a UI can show "reconnecting…" the instant the socket
@@ -1148,6 +1167,7 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private readonly degradeAfterFailures;
   /** Per-push RPC deadline; see {@link withPushTimeout}. */
   private readonly pushTimeoutMs;
+  private readonly downTimeoutMs;
   private consecutiveSyncFailures;
   private syncHealthStatus;
   private lastSyncErrorKind;
@@ -1378,6 +1398,8 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private handleMutationSettled;
   private handleRollback;
   private processDownEvent;
+  private withDownTimeout;
+  private runDownEvent;
   /**
    * Synchronizes a specific query by hash.
    * Compares local and remote version arrays and fetches differences.

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as renderWhereSql, c as resolveRelations, i as renderOrderSql, l as stableKey, o as reviveRow, r as project, s as serializeRow, t as PROMOTION_OPEN_OPTIONS } from "./sqlite-open.js";
+import { a as renderOrderSql, c as serializeRow, i as projectedDataSql, l as resolveRelations, o as renderWhereSql, r as project, s as reviveRow, t as PROMOTION_OPEN_OPTIONS, u as stableKey } from "./sqlite-open.js";
 import { DateTime, Duration, RecordId, Surreal, Uuid, applyDiagnostics, createRemoteEngines } from "surrealdb";
 import { QueryBuilder, RecordId as RecordId$1, cyrb53 } from "@spooky-sync/query-builder";
 import pino from "pino";
@@ -2658,16 +2658,15 @@ var SqliteCacheEngine = class {
 		}
 		await this.ensureTable(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 = await this.execRows(sql, bind);
-		const projected = plan.select ? rows.map((r) => project(r, plan.select)) : rows;
-		await resolveRelations(projected, plan.relations, this);
-		return projected;
+		await resolveRelations(rows, plan.relations, this);
+		return rows;
 	}
 	async fetchRelation(req) {
 		getStats().relationFetches++;
@@ -2686,14 +2685,18 @@ var SqliteCacheEngine = class {
 		if (ids.length === 0) return [];
 		await this.ensureTable(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 = await this.execRows(sql, keys);
+		let rows = await this.execRows(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;
 	}
 	async getById(table, id) {
 		await this.ensureTable(table);
@@ -3586,6 +3589,15 @@ var DataModule = class DataModule {
 	}
 	settledWrites = /* @__PURE__ */ new Map();
 	settledDeletes = /* @__PURE__ */ new Map();
+	pendingIds = null;
+	pendingIdsAt = 0;
+	pendingIdsInflight = null;
+	static PENDING_IDS_TTL_MS = 250;
+	/** Drop the cached outbox ids. Cheap; call it on anything that could change
+	*  `_00_pending_mutations`. */
+	invalidatePendingIds() {
+		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
@@ -3604,6 +3616,7 @@ var DataModule = class DataModule {
 	* disappear immediately, which is what makes this safe.
 	*/
 	noteWriteSettled(recordId, mutationType) {
+		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);
@@ -3989,6 +4002,24 @@ var DataModule = class DataModule {
 	* briefly hide an optimistic write but never resurrects a deleted row.
 	*/
 	async getPendingRecordIds() {
+		const now = Date.now();
+		const cached = this.pendingIds;
+		if (cached && now - this.pendingIdsAt < DataModule.PENDING_IDS_TTL_MS) return {
+			writes: new Set(cached.writes),
+			deletes: new Set(cached.deletes)
+		};
+		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. */
+	async readPendingRecordIds() {
 		const writes = /* @__PURE__ */ new Set();
 		const deletes = /* @__PURE__ */ new Set();
 		try {
@@ -4004,7 +4035,16 @@ var DataModule = class DataModule {
 				err,
 				Category: "sp00ky-client::DataModule::getPendingRecordIds"
 			}, "Failed to read pending mutations; optimistic writes may be briefly hidden");
+			return {
+				writes,
+				deletes
+			};
 		}
+		this.pendingIds = {
+			writes,
+			deletes
+		};
+		this.pendingIdsAt = Date.now();
 		return {
 			writes,
 			deletes
@@ -4321,6 +4361,7 @@ var DataModule = class DataModule {
 			record: target,
 			tableName
 		};
+		this.invalidatePendingIds();
 		for (const callback of this.mutationCallbacks) callback([mutationEvent]);
 		this.logger.debug({
 			id,
@@ -4374,6 +4415,7 @@ var DataModule = class DataModule {
 			beforeRecord: beforeRecord || void 0,
 			options: pushEventOptions
 		};
+		this.invalidatePendingIds();
 		for (const callback of this.mutationCallbacks) callback([mutationEvent]);
 		this.logger.debug({
 			id,
@@ -4419,6 +4461,7 @@ var DataModule = class DataModule {
 			mutation_id: mutationId,
 			record_id: rid
 		};
+		this.invalidatePendingIds();
 		for (const callback of this.mutationCallbacks) callback([mutationEvent]);
 		this.logger.debug({
 			id,
@@ -5071,9 +5114,43 @@ var DownQueue = class {
 	}
 	async next(fn) {
 		const event = this.queue.shift();
-		if (event) try {
+		if (!event) return;
+		const error = await this.run(event, fn);
+		if (error !== void 0) throw error;
+	}
+	/**
+	* The next event whose hash is NOT already being processed, or `undefined`
+	* when every remaining event is blocked on a busy hash.
+	*
+	* Ordering only ever mattered PER HASH — a `cleanup` must not overtake the
+	* `register` for the same query — but the queue enforced it globally, so one
+	* registration RPC at a time was the ceiling for the whole client. An event
+	* for a busy hash keeps its place here (it is skipped, not reordered), so
+	* per-hash ordering is preserved exactly while independent hashes proceed
+	* concurrently.
+	*/
+	takeNext(busy) {
+		for (let i = 0; i < this.queue.length; i++) {
+			const event = this.queue[i];
+			if (busy.has(event.payload.hash)) continue;
+			this.queue.splice(i, 1);
+			return event;
+		}
+	}
+	/**
+	* Process one event, applying the re-head / rotate failure policy.
+	*
+	* NEVER rejects: it RETURNS the error instead (`undefined` on success). A
+	* concurrent drain has other work in flight when one event fails, and a
+	* rejection would either take that work down with it or have to be caught at
+	* every call site. `next` reinstates the throwing contract for the serial
+	* callers that still want it.
+	*/
+	async run(event, fn) {
+		try {
 			await fn(event);
 			this.failures.delete(event);
+			return;
 		} catch (error) {
 			const attempts = (this.failures.get(event) ?? 0) + 1;
 			this.failures.set(event, attempts);
@@ -5087,7 +5164,7 @@ var DownQueue = class {
 				rotated: starvingOthers,
 				Category: "sp00ky-client::DownQueue::next"
 			}, "Failed to process query");
-			throw error;
+			return error;
 		}
 	}
 };
@@ -5452,6 +5529,17 @@ var SyncEngine = class {
 */
 /** Backoff for re-draining a queue that halted on an error. */
 const RETRY_BASE_MS = 500;
+/**
+* How many down events may be in flight at once.
+*
+* The down queue was strictly serial: one `register`/`sync`/`cleanup` RPC at a
+* time for the WHOLE client. Measured in production that drained at roughly one
+* event per 8.8s, so a list that registers a query per scrolled-to window took
+* minutes to fill — the rows were already cached, only the registration lagged.
+* Ordering is a per-hash requirement, not a global one (see `takeNext`), so
+* independent hashes can go in parallel. Bounded to stay polite to the SSP.
+*/
+const MAX_CONCURRENT_DOWN = 4;
 const RETRY_MAX_MS = 15e3;
 var SyncScheduler = class {
 	isSyncingUp = false;
@@ -5593,14 +5681,35 @@ var SyncScheduler = class {
 		}
 		this.isSyncingDown = true;
 		let processedAny = false;
+		const busy = /* @__PURE__ */ new Set();
+		const inFlight = /* @__PURE__ */ new Set();
+		let failure;
 		try {
-			while (this.downQueue.size > 0 && !this.paused) {
-				if (this.upQueue.size > 0) break;
-				await this.downQueue.next(this.onProcessDown);
-				processedAny = true;
+			for (;;) {
+				if (this.paused) break;
+				const yieldToUp = this.upQueue.size > 0;
+				while (failure === void 0 && !yieldToUp && inFlight.size < MAX_CONCURRENT_DOWN) {
+					const event = this.downQueue.takeNext(busy);
+					if (!event) break;
+					const hash = event.payload.hash;
+					busy.add(hash);
+					processedAny = true;
+					const task = this.downQueue.run(event, this.onProcessDown).then((error) => {
+						if (error !== void 0 && failure === void 0) failure = error;
+					}).finally(() => {
+						busy.delete(hash);
+						inFlight.delete(task);
+					});
+					inFlight.add(task);
+				}
+				if (inFlight.size === 0) break;
+				await Promise.race(inFlight);
+				if (yieldToUp && inFlight.size === 0) break;
 			}
+			if (failure !== void 0) throw failure;
 			if (processedAny) this.onSyncOutcome?.(true);
 			this.downRetryAttempt = 0;
+			if (this.downQueue.size > 0) this.scheduleDownRetry(RETRY_BASE_MS);
 		} catch (error) {
 			this.onSyncOutcome?.(false, error);
 			this.scheduleDownRetry();
@@ -5691,6 +5800,7 @@ var Sp00kySync = class Sp00kySync {
 	degradeAfterFailures;
 	/** Per-push RPC deadline; see {@link withPushTimeout}. */
 	pushTimeoutMs;
+	downTimeoutMs;
 	consecutiveSyncFailures = 0;
 	syncHealthStatus = "healthy";
 	lastSyncErrorKind;
@@ -5862,6 +5972,7 @@ var Sp00kySync = class Sp00kySync {
 		this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
 		this.degradeAfterFailures = Math.max(0, options?.degradeAfterConsecutiveFailures ?? 3);
 		this.pushTimeoutMs = Math.max(0, options?.pushTimeoutMs ?? 3e4);
+		this.downTimeoutMs = Math.max(0, options?.downTimeoutMs ?? 3e4);
 		this.connectionSupervisor = options?.connectionSupervisor;
 	}
 	/**
@@ -6544,6 +6655,12 @@ var Sp00kySync = class Sp00kySync {
 			event,
 			Category: "sp00ky-client::Sp00kySync::processDownEvent"
 		}, "Processing down event");
+		return this.withDownTimeout(this.runDownEvent(event), `${event.type} ${event.payload.hash}`);
+	}
+	withDownTimeout(promise, label) {
+		return withTimeout(promise, this.downTimeoutMs, `Down event timed out after ${this.downTimeoutMs}ms (${label})`);
+	}
+	async runDownEvent(event) {
 		switch (event.type) {
 			case "register": return this.registerQuery(event.payload.hash);
 			case "sync": return this.syncQuery(event.payload.hash);
@@ -7094,8 +7211,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.203";
-const WASM_VERSION = "0.0.1-canary.203";
+const CORE_VERSION = "0.0.1-canary.204";
+const WASM_VERSION = "0.0.1-canary.204";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -11718,6 +11835,7 @@ var Sp00kyClient = class {
 			anonymousLiveQueries: this.config.enableAnonymousLiveQueries,
 			degradeAfterConsecutiveFailures: this.config.syncHealth === false ? 0 : this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3,
 			pushTimeoutMs: this.config.pushTimeoutMs,
+			downTimeoutMs: this.config.downTimeoutMs,
 			connectionSupervisor: this.connectionSupervisor
 		});
 		this.featureFlags = new FeatureFlagModule({
@@ -11772,7 +11890,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.203",
+				coreVersion: "0.0.1-canary.204",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,

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.203",
+  "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.203",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.203",
+    "@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/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']);
+  });
+});