@spooky-sync/core 0.0.1-canary.288 → 0.0.1-canary.289

package/src/kernel/events.ts

@@ -21,6 +21,8 @@ export type RuntimeEvent =
   | { type: 'GcTick' }
   | { type: 'Drain' }
   | { type: 'FlushWrite'; key: string }
+  | { type: 'FlushPendingWrites' }
+  | { type: 'AdoptPendingWrites' }
   | { type: 'PollTick' }
   | { type: 'SelfHealTick' }
   | { type: 'HeartbeatNow' }

package/src/mutation/pending-writes.integration.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import { RecordId, Surreal } from 'surrealdb';
+import { defaultEnv } from '../query/env';
+import { runPure } from '../testing/run-pure';
+import { buildState } from '../testing/build';
+import type { ClientState } from '../state/client-state';
+import type { SealedQuery } from '../utils/surql';
+import type { Vars } from '../kernel/effects';
+import { SqliteCacheEngine } from '../services/database/sqlite-cache-engine';
+import { stubTransport } from '../services/database/sqlite-transport.fixture';
+import { PENDING_WRITE_ORPHAN_MS } from '../kernel/constants';
+import { loadPendingRows, parsePendingRow } from './rows';
+import { mintMutationId } from './mutation-id';
+import { adoptPendingWrites, flushWrite, write } from './write.saga';
+
+/**
+ * Integration: a debounced update must survive the page going away inside its
+ * delay. These run the real sagas and execute their transactions on BOTH local
+ * engines: a real in-memory SQLite behind the SqliteCacheEngine, and a real
+ * SurrealDB-WASM `mem://` store whose `_00_pending_writes` table was never
+ * defined (a store provisioned before the table existed).
+ *
+ * On each: the patch is mirrored to `_00_pending_writes` beside the row; a
+ * timely flush moves it into the outbox; and when the page died first, a fresh
+ * page (empty memory) adopts the mirror into a replayable outbox row.
+ */
+
+const env = defaultEnv({ tables: [{ name: 'doc', columns: { title: { type: 'string', optional: true } } }] } as any);
+const doc = new RecordId('doc', 'd1');
+
+interface Engine {
+  query(sql: string, vars?: Vars): Promise<unknown>;
+  execute(query: SealedQuery<unknown>, vars: Vars): Promise<unknown>;
+}
+
+const run = <R>(engine: Engine, saga: Generator<any, R, any>, state: ClientState, now: number) =>
+  runPure(saga, {
+    state,
+    now,
+    handlers: {
+      'local.query': (e: any) => engine.query(e.sql, e.vars),
+      'local.execute': (e: any) => engine.execute(e.query, e.vars),
+      'ssp.ingest': () => undefined,
+      id: () => mintMutationId(state.tabId),
+    },
+  });
+
+async function scenario(engine: Engine, readRow: () => Promise<Record<string, unknown> | null>): Promise<void> {
+  const typed = async (title: string, state: ClientState, now: number) =>
+    run(engine, write(env, { kind: 'update', recordId: 'doc:d1', data: { title }, options: { debounced: { delay: 1_000 } } }), state, now);
+  const mirrors = async () => ((await engine.query('SELECT * FROM _00_pending_writes')) as unknown[][])[0] ?? [];
+  const outbox = async () => (((await engine.query(loadPendingRows())) as unknown[][])[0] ?? []).map(parsePendingRow);
+
+  // Booting with nothing to adopt is a no-op, even before the table exists.
+  const boot = await run(engine, adoptPendingWrites(), buildState(), 0);
+  expect(boot.dispatched).toEqual([]);
+
+  // Typing inside the delay: the row changes at once, the patch is mirrored beside it.
+  const a = await typed('He', buildState(), 1_000);
+  const b = await typed('Hello', a.state, 1_100);
+  expect((await readRow())?.title).toBe('Hello');
+  expect(await mirrors()).toHaveLength(1);
+  expect(await outbox()).toEqual([]);
+
+  // The timer fires: the patch moves into the outbox, the mirror is gone.
+  const flushed = await run(engine, flushWrite(env, 'doc:d1::title'), b.state, 2_100);
+  expect(await mirrors()).toEqual([]);
+  expect(await outbox()).toEqual([expect.objectContaining({ mutationType: 'update', recordId: 'doc:d1', data: { title: 'Hello' } })]);
+  await engine.query('DELETE _00_pending_mutations');
+
+  // Typing again, then the page dies before the flush: memory is gone, the mirror is not.
+  await typed('Hello world', flushed.state, 3_000);
+  const reloaded = { ...buildState(), tabId: 'tab-after-reload' };
+  const early = await run(engine, adoptPendingWrites(), reloaded, 3_100);
+  expect(early.timers.get('adopt-writes')).toEqual({ ms: 4_000 + PENDING_WRITE_ORPHAN_MS - 3_100, event: { type: 'AdoptPendingWrites' } });
+  expect(await outbox()).toEqual([]);
+
+  const adopted = await run(engine, adoptPendingWrites(), reloaded, 4_000 + PENDING_WRITE_ORPHAN_MS);
+  expect(adopted.dispatched).toEqual([{ type: 'Drain' }]);
+  expect(await mirrors()).toEqual([]);
+  const rows = await outbox();
+  expect(rows).toEqual([expect.objectContaining({ mutationType: 'update', recordId: 'doc:d1', data: { title: 'Hello world' } })]);
+  expect(adopted.state.outbox.map((i) => i.id)).toEqual([rows[0]!.id]);
+  expect((await readRow())?.title).toBe('Hello world');
+}
+
+const noop = () => {};
+
+describe('debounced writes survive a dead page: SQLite engine', () => {
+  let db: any;
+
+  beforeAll(async () => {
+    const sqlite3: any = await sqlite3InitModule();
+    db = new sqlite3.oo1.DB(':memory:', 'c');
+  });
+
+  afterAll(() => db?.close());
+
+  it('mirrors, flushes, and adopts', async () => {
+    const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+    logger.child = () => logger;
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, logger);
+    stubTransport(engine, (type, payload: any) => {
+      switch (type) {
+        case 'open':
+          // As the worker does: system tables exist from the open on.
+          for (const t of payload.systemTables as string[]) db.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+          return { persisted: true };
+        case 'exec':
+          return { rows: db.exec({ sql: payload.sql, bind: payload.bind, rowMode: 'object', returnValue: 'resultRows' }) };
+        case 'run':
+          db.exec({ sql: payload.sql, bind: payload.bind });
+          return {};
+        case 'batch':
+          for (const stmt of payload as { sql: string; bind?: unknown[] }[]) db.exec({ sql: stmt.sql, bind: stmt.bind });
+          return {};
+        default:
+          return {};
+      }
+    });
+    await engine.connect('anon');
+    await engine.upsert('doc', doc, { title: '' }, 'replace');
+    await scenario(
+      { query: (sql, vars) => engine.query(sql, vars), execute: (q, v) => engine.execute(q, v) },
+      async () => ((await engine.getById('doc', doc)) as Record<string, unknown>) ?? null
+    );
+  });
+});
+
+describe('debounced writes survive a dead page: SurrealDB-WASM engine', () => {
+  let db: Surreal;
+
+  beforeAll(async () => {
+    // The wasm engine loads its binary with `fetch(new URL(..., import.meta.url))`,
+    // and Node's fetch has no `file:` scheme: serve that one read from disk.
+    const realFetch = globalThis.fetch;
+    vi.stubGlobal('fetch', async (input: unknown, init?: RequestInit) => {
+      const url = input instanceof URL ? input : new URL(String(input));
+      if (url.protocol === 'file:') return new Response(await readFile(fileURLToPath(url)));
+      return realFetch(input as RequestInfo, init);
+    });
+    const { createWasmEngines } = await import('@surrealdb/wasm');
+    db = new Surreal({ engines: createWasmEngines() });
+    await db.connect('mem://');
+    await db.use({ namespace: 'n', database: 'd' });
+    await db.query(`
+      DEFINE TABLE doc SCHEMAFULL;
+      DEFINE FIELD title ON doc TYPE option<string>;
+      DEFINE FIELD _00_rv ON doc TYPE option<int>;
+      DEFINE TABLE _00_pending_mutations SCHEMALESS;
+      CREATE doc:d1 SET title = '';
+    `);
+  }, 60_000);
+
+  afterAll(async () => {
+    await db?.close();
+    vi.unstubAllGlobals();
+  });
+
+  it('mirrors, flushes, and adopts', async () => {
+    await scenario(
+      {
+        query: (sql, vars) => db.query(sql, vars) as unknown as Promise<unknown>,
+        execute: async (q, v) => q.extract((await db.query(q.sql, v)) as unknown[]),
+      },
+      async () => {
+        const [row] = (await db.query('SELECT * FROM ONLY $id', { id: doc })) as [Record<string, unknown>];
+        return row ?? null;
+      }
+    );
+  });
+});

package/src/mutation/push.saga.test.ts

@@ -267,9 +267,9 @@ describe('loadOutbox / refreshFailedCount', () => {
     expect(out.emitted).toContainEqual(expect.objectContaining({ type: 'mutation:rolled-back', mutationId: '_00_pending_mutations:bad' }));
     expect(out.emitted).toContainEqual(expect.objectContaining({ type: 'mutation:rolled-back', mutationId: '' }));
     expect(out.state.failedCount).toBe(4);
-    expect(out.dispatched).toEqual([{ type: 'Drain' }]);
+    expect(out.dispatched).toEqual([{ type: 'Drain' }, { type: 'AdoptPendingWrites' }]);
     const empty = await runPure(loadOutbox(env), { state: buildState(), handlers: { 'local.query': () => [] } });
-    expect(empty.dispatched).toEqual([]);
+    expect(empty.dispatched).toEqual([{ type: 'AdoptPendingWrites' }]);
     const missingTable = await runPure(refreshFailedCount(), {
       state: R.setFailedCount(2)(buildState()),
       handlers: {

package/src/mutation/push.saga.ts

@@ -26,6 +26,7 @@ import {
 /**
  * Boot / bucket switch: mirror the outbox table into state. Rows that can
  * never be replayed (a create without its payload) go straight to the tray.
+ * Debounced patches a dead page left in `_00_pending_writes` are adopted next.
  */
 export function* loadOutbox(env: SagaEnv): Saga<void> {
   const res = (yield fx.local.query(loadPendingRows())) as unknown[];
@@ -51,6 +52,7 @@ export function* loadOutbox(env: SagaEnv): Saga<void> {
   }
   yield* refreshFailedCount();
   if (items.length > 0) yield fx.dispatch({ type: 'Drain' });
+  yield fx.dispatch({ type: 'AdoptPendingWrites' });
 }
 
 export function* refreshFailedCount(): Saga<void> {

package/src/mutation/rows.test.ts

@@ -103,6 +103,36 @@ describe('debounced update transactions', () => {
     expect(deferred.query.sql).toBe("BEGIN TRANSACTION;\nCREATE ONLY $mid SET mutationType = 'update', recordId = $id, tableName = $table, createdAt = $createdAt, v = 2, data = $data, beforeRecord = $before;\nCOMMIT TRANSACTION;");
     expect(rows.planDeferredOutboxRowTx({ recordId: rid('thing', '1'), mutationId: rid('_00_pending_mutations', 'm'), table: 'thing', now: 3 }).vars).toMatchObject({ data: {}, before: null });
   });
+
+  it('with a mirror: the patch is upserted beside the row, and the flush moves it in one transaction', () => {
+    const wrow = { recordId: rid('thing', '1'), tableName: 'thing', data: { a: 1, b: 2 }, beforeRecord: null, flushBy: 9 };
+    const local = rows.planLocalOnlyUpdateTx({ recordId: rid('thing', '1'), data: { b: 2 }, mirror: { id: rid('_00_pending_writes', 'w'), row: wrow } });
+    expect(local.query.sql).toBe(
+      'BEGIN TRANSACTION;\nUPDATE $id SET _00_rv += 1;LET $updated = (UPDATE ONLY $id MERGE $data);UPSERT ONLY $wid REPLACE $wrow;RETURN {target: $updated};\nCOMMIT TRANSACTION;'
+    );
+    expect(local.vars).toEqual({ id: rid('thing', '1'), data: { b: 2 }, wid: rid('_00_pending_writes', 'w'), wrow });
+    expect(local.query.extract([null, 1, 2, 3, { target: 'x' }])).toEqual({ target: 'x' });
+    const moved = rows.planDeferredOutboxRowTx({ recordId: rid('thing', '1'), mutationId: rid('_00_pending_mutations', 'm'), table: 'thing', data: { a: 1 }, now: 3, mirrorId: rid('_00_pending_writes', 'w') });
+    expect(moved.query.sql).toContain('beforeRecord = $before;DELETE $wid;\nCOMMIT');
+    expect(moved.vars.wid).toEqual(rid('_00_pending_writes', 'w'));
+  });
+
+  it('pending write ids and rows', () => {
+    expect(rows.pendingWriteId('_00_pending_mutations:0000000000001_0001_tab')).toBe('_00_pending_writes:0000000000001_0001_tab');
+    expect(rows.pendingWriteId('mutation-1')).toBe('_00_pending_writes:mutation-1');
+    expect(rows.parsePendingWriteRow({ id: '_00_pending_writes:⟨w-1⟩', recordId: rid('thing', '1'), data: { a: 1 }, beforeRecord: { a: 0 }, flushBy: 5 })).toEqual({
+      id: '_00_pending_writes:w-1',
+      recordId: 'thing:1',
+      tableName: 'thing',
+      data: { a: 1 },
+      beforeRecord: { a: 0 },
+      flushBy: 5,
+    });
+    expect(rows.parsePendingWriteRow({ id: 'w', recordId: 'thing:1', tableName: 'thing', data: {} })).toMatchObject({ beforeRecord: null, flushBy: 0 });
+    expect(rows.parsePendingWriteRow({ id: 'w', recordId: 'thing:1' })).toBeNull();
+    expect(rows.parsePendingWriteRow({ id: 'w', data: {} })).toBeNull();
+    expect(rows.parsePendingWriteRow('junk')).toBeNull();
+  });
 });
 
 describe('remoteBatch', () => {

package/src/mutation/rows.ts

@@ -10,6 +10,8 @@ import { parseQueryParams } from '../utils/parser';
 
 export const PENDING_TABLE = '_00_pending_mutations';
 export const FAILED_TABLE = '_00_failed_mutations';
+/** Debounced patches still inside their delay (see `DebounceOptions.flushOnHide`). */
+export const PENDING_WRITES_TABLE = '_00_pending_writes';
 export const PENDING_ROW_VERSION = 2;
 
 /** One `_00_pending_mutations` row as this client writes it (v2). */
@@ -117,7 +119,42 @@ export const toOutboxItem = (row: PendingMutationRow): OutboxItem => ({
   attempts: 0,
 });
 
+/**
+ * One `_00_pending_writes` row: the merged patch of a debounced update that
+ * has not reached the outbox yet. `flushBy` is when the writing tab's timer
+ * is due to move it there.
+ */
+export interface PendingWriteRow {
+  id: string;
+  recordId: string;
+  tableName: string;
+  data: Record<string, unknown>;
+  beforeRecord: Record<string, unknown> | null;
+  flushBy: number;
+}
+
+/** The `_00_pending_writes` id for a minted mutation id (same suffix). */
+export const pendingWriteId = (mutationId: string): string =>
+  `${PENDING_WRITES_TABLE}:${mutationId.includes(':') ? mutationId.slice(mutationId.indexOf(':') + 1) : mutationId}`;
+
+export function parsePendingWriteRow(row: unknown): PendingWriteRow | null {
+  if (!row || typeof row !== 'object') return null;
+  const r = row as Record<string, unknown>;
+  if (typeof r.recordId !== 'string' && !(r.recordId instanceof RecordId)) return null;
+  if (!r.data || typeof r.data !== 'object') return null;
+  const recordId = typeof r.recordId === 'string' ? r.recordId : storedIdString(r.recordId);
+  return {
+    id: storedIdString(r.id),
+    recordId,
+    tableName: typeof r.tableName === 'string' ? r.tableName : extractTablePart(recordId),
+    data: r.data as Record<string, unknown>,
+    beforeRecord: r.beforeRecord && typeof r.beforeRecord === 'object' ? (r.beforeRecord as Record<string, unknown>) : null,
+    flushBy: typeof r.flushBy === 'number' ? r.flushBy : 0,
+  };
+}
+
 export const loadPendingRows = (): string => `SELECT * FROM ${PENDING_TABLE} ORDER BY id ASC`;
+export const loadPendingWriteRows = (): string => `SELECT * FROM ${PENDING_WRITES_TABLE}`;
 export const loadFailedRows = (): string => `SELECT * FROM ${FAILED_TABLE} ORDER BY failedAt ASC`;
 
 // ---- local write transactions ------------------------------------------------
@@ -199,24 +236,36 @@ export function planDeleteTx(input: WritePlanInput): LocalTx {
   };
 }
 
-/** Debounced update: bump `_00_rv` and MERGE now; the outbox row comes later. */
-export function planLocalOnlyUpdateTx(input: { recordId: RecordId<string>; data: Record<string, unknown> }): LocalTx {
+/**
+ * Debounced update: bump `_00_rv` and MERGE now; the outbox row comes later.
+ * With a `mirror`, the merged patch so far is written to `_00_pending_writes`
+ * in the same transaction, so the row never changes without a durable copy of
+ * what still has to reach the server.
+ */
+export function planLocalOnlyUpdateTx(input: {
+  recordId: RecordId<string>;
+  data: Record<string, unknown>;
+  mirror?: { id: RecordId<string>; row: Omit<PendingWriteRow, 'id' | 'recordId'> & { recordId: RecordId<string> } };
+}): LocalTx {
+  const statements = [surql.updateSet('id', [{ statement: '_00_rv += 1' }]), surql.let('updated', surql.updateMerge('id', 'data'))];
+  if (input.mirror) statements.push(surql.upsert('wid', 'wrow'));
+  statements.push(surql.returnObject([{ key: 'target', variable: 'updated' }]));
   return {
-    query: surql.seal<unknown>(
-      surql.tx([
-        surql.updateSet('id', [{ statement: '_00_rv += 1' }]),
-        surql.let('updated', surql.updateMerge('id', 'data')),
-        surql.returnObject([{ key: 'target', variable: 'updated' }]),
-      ])
-    ),
-    vars: { id: input.recordId, data: input.data },
+    query: surql.seal<unknown>(surql.tx(statements)),
+    vars: input.mirror ? { id: input.recordId, data: input.data, wid: input.mirror.id, wrow: input.mirror.row } : { id: input.recordId, data: input.data },
   };
 }
 
-/** The outbox row of a flushed debounced update, on its own. */
-export function planDeferredOutboxRowTx(input: WritePlanInput): LocalTx {
+/**
+ * The outbox row of a flushed debounced update. With `mirrorId` the
+ * `_00_pending_writes` row goes in the same transaction: the patch moves
+ * from one table to the other, it is never in both or in neither.
+ */
+export function planDeferredOutboxRowTx(input: WritePlanInput & { mirrorId?: RecordId<string> }): LocalTx {
+  const statements = [pendingInsert('update', true, true)];
+  if (input.mirrorId) statements.push(surql.delete('wid'));
   return {
-    query: surql.seal<unknown>(surql.tx([pendingInsert('update', true, true)])),
+    query: surql.seal<unknown>(surql.tx(statements)),
     vars: {
       id: input.recordId,
       mid: input.mutationId,
@@ -224,6 +273,7 @@ export function planDeferredOutboxRowTx(input: WritePlanInput): LocalTx {
       createdAt: input.now,
       data: input.data ?? {},
       before: input.before ?? null,
+      ...(input.mirrorId ? { wid: input.mirrorId } : {}),
     },
   };
 }

package/src/mutation/write.saga.test.ts

@@ -3,7 +3,8 @@ import { RecordId } from 'surrealdb';
 import { runPure } from '../testing/run-pure';
 import { buildEntry, buildState } from '../testing/build';
 import { defaultEnv } from '../query/env';
-import { flushWrite, write } from './write.saga';
+import { adoptPendingWrites, flushPendingWrites, flushWrite, write } from './write.saga';
+import * as R from '../state/reducers';
 
 const env = defaultEnv({ tables: [{ name: 'thing', columns: { a: {}, b: {} } }] } as any);
 const rid = new RecordId('thing', '1');
@@ -160,4 +161,156 @@ describe('write', () => {
     });
     expect(leaderDebounced.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'ingest', records: [expect.objectContaining({ op: 'UPDATE' })] } });
   });
+
+  it('flushOnHide (default): the merged patch is mirrored in the same tx, and the flush moves it into the outbox', async () => {
+    const now = 1_000;
+    const first = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { a: 1 }, options: { debounced: true } }), {
+      state: withQuery(),
+      now,
+      handlers: {
+        'local.query': () => [{ id: rid, a: 0, _00_rv: 1 }],
+        'local.execute': (e: any) => {
+          expect(e.query.sql).toContain('UPSERT ONLY $wid REPLACE $wrow');
+          expect(e.vars.wid).toEqual(new RecordId('_00_pending_writes', 'mutation-1'));
+          expect(e.vars.wrow).toEqual({ recordId: rid, tableName: 'thing', data: { a: 1 }, beforeRecord: { id: rid, a: 0, _00_rv: 1 }, flushBy: now + 300 });
+          return { target: { id: rid, a: 1, _00_rv: 2 } };
+        },
+        'ssp.ingest': () => undefined,
+      },
+    });
+    const key = 'thing:1::a';
+    expect(first.state.pendingWrites.get(key)!.mirrorId).toBe('_00_pending_writes:mutation-1');
+    const second = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { a: 7 }, options: { debounced: { delay: 50 } } }), {
+      state: first.state,
+      now: now + 10,
+      handlers: {
+        'local.execute': (e: any) => {
+          expect(e.vars.wid).toEqual(new RecordId('_00_pending_writes', 'mutation-1'));
+          expect(e.vars.wrow).toMatchObject({ data: { a: 7 }, flushBy: now + 60 });
+          return { target: { id: rid, a: 7, _00_rv: 3 } };
+        },
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(second.log.filter((e) => e.kind === 'id')).toHaveLength(0);
+    const flushed = await runPure(flushWrite(env, key), {
+      state: second.state,
+      handlers: {
+        'local.execute': (e: any) => {
+          expect(e.query.sql).toContain('DELETE $wid');
+          expect(e.vars).toMatchObject({ data: { a: 7 }, wid: new RecordId('_00_pending_writes', 'mutation-1') });
+        },
+      },
+    });
+    expect(flushed.state.pendingWrites.size).toBe(0);
+    expect(flushed.state.outbox).toHaveLength(1);
+    const armed: unknown[] = [];
+    const closed = runPure(flushWrite(env, key), {
+      state: second.state,
+      handlers: {
+        'local.execute': () => {
+          throw new Error('store closed');
+        },
+        'timer.set': (e: any) => void armed.push([e.key, e.ms, e.event]),
+      },
+    });
+    await expect(closed).rejects.toThrow('store closed');
+    expect(armed).toEqual([['adopt-writes', 3_000, { type: 'AdoptPendingWrites' }]]);
+  });
+
+  it('flushOnHide: false keeps the patch in memory only', async () => {
+    const out = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { a: 1 }, options: { debounced: { flushOnHide: false } } }), {
+      state: withQuery(),
+      handlers: {
+        'local.query': () => [],
+        'local.execute': (e: any) => {
+          expect(e.query.sql).not.toContain('UPSERT');
+          expect(e.vars.wid).toBeUndefined();
+        },
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(out.state.pendingWrites.get('thing:1::a')!.mirrorId).toBeNull();
+    const flushed = await runPure(flushWrite(env, 'thing:1::a'), {
+      state: out.state,
+      handlers: { 'local.execute': (e: any) => expect(e.query.sql).not.toContain('DELETE') },
+    });
+    expect(flushed.state.outbox).toHaveLength(1);
+  });
+});
+
+describe('flushPendingWrites', () => {
+  it('flushes every mirrored pending write now, leaves memory-only ones to their timer', async () => {
+    const base = { table: 'thing', recordId: 'thing:1', data: { a: 1 }, before: null, firstAt: 0 };
+    const state = R.compose(
+      R.mergePendingWrite({ ...base, key: 'k1', mirrorId: '_00_pending_writes:1' }),
+      R.mergePendingWrite({ ...base, key: 'k2', mirrorId: null }),
+      R.mergePendingWrite({ ...base, key: 'k3', mirrorId: '_00_pending_writes:3' })
+    )(buildState());
+    const out = await runPure(flushPendingWrites(), { state });
+    expect(out.log.filter((e) => e.kind === 'timer.clear').map((e: any) => e.key)).toEqual(['debounce:k1', 'debounce:k3']);
+    expect(out.dispatched).toEqual([{ type: 'FlushWrite', key: 'k1' }, { type: 'FlushWrite', key: 'k3' }]);
+    const none = await runPure(flushPendingWrites(), { state: buildState() });
+    expect(none.dispatched).toEqual([]);
+  });
+});
+
+describe('adoptPendingWrites', () => {
+  const now = 100_000;
+  const row = (id: string, flushBy: number) => ({ id: `_00_pending_writes:${id}`, recordId: rid, tableName: 'thing', data: { a: 1 }, beforeRecord: { a: 0 }, flushBy });
+  const held = R.mergePendingWrite({ key: 'k', table: 'thing', recordId: 'thing:1', data: {}, before: null, firstAt: 0, mirrorId: '_00_pending_writes:mine' })(buildState());
+
+  it('moves overdue rows nobody here holds into the outbox, re-checks rows that may still be live', async () => {
+    const moved: any[] = [];
+    const out = await runPure(adoptPendingWrites(), {
+      state: held,
+      now,
+      handlers: {
+        'local.query': (e: any) => {
+          expect(e.sql).toBe('SELECT * FROM _00_pending_writes');
+          return [[row('mine', 0), row('dead', now - 3_000), row('live', now + 500), row('other-live', now + 2_000), 'junk']];
+        },
+        'local.execute': (e: any) => {
+          moved.push(e.vars);
+        },
+      },
+    });
+    expect(moved).toHaveLength(1);
+    expect(moved[0]).toMatchObject({ id: rid, table: 'thing', data: { a: 1 }, before: { a: 0 }, createdAt: now, wid: new RecordId('_00_pending_writes', 'dead') });
+    expect(out.state.outbox).toEqual([{ id: 'mutation-1', type: 'update', recordId: 'thing:1', table: 'thing', status: 'pending', ackedAt: null, attempts: 0 }]);
+    expect(out.dispatched).toEqual([{ type: 'Drain' }]);
+    expect(out.timers.get('adopt-writes')).toEqual({ ms: 3_500, event: { type: 'AdoptPendingWrites' } });
+  });
+
+  it('a follower nudges the leader instead; a failed move is logged and skipped; no table means nothing to do', async () => {
+    const follower = await runPure(adoptPendingWrites(), { state: { ...buildState(), tabRole: 'follower' }, now, handlers: { 'local.query': () => [[row('dead', 0)]] } });
+    expect(follower.log.some((e) => e.kind === 'local.execute')).toBe(false);
+    expect(follower.emitted).toEqual([{ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId: '' } }]);
+    const quietFollower = await runPure(adoptPendingWrites(), { state: { ...held, tabRole: 'follower' }, now, handlers: { 'local.query': () => [[row('mine', 0)]] } });
+    expect(quietFollower.emitted).toEqual([]);
+    const failing = await runPure(adoptPendingWrites(), {
+      state: buildState(),
+      now,
+      handlers: {
+        'local.query': () => [[row('dead', 0)]],
+        'local.execute': () => {
+          throw new Error('closed');
+        },
+      },
+    });
+    expect(failing.state.outbox).toEqual([]);
+    expect(failing.dispatched).toEqual([]);
+    expect(failing.emitted).toContainEqual(expect.objectContaining({ type: 'log', level: 'warn' }));
+    const noTable = await runPure(adoptPendingWrites(), {
+      state: buildState(),
+      handlers: {
+        'local.query': () => {
+          throw new Error('no table');
+        },
+      },
+    });
+    expect(noTable.dispatched).toEqual([]);
+    const empty = await runPure(adoptPendingWrites(), { state: buildState(), handlers: { 'local.query': () => [[]] } });
+    expect(empty.timers.size).toBe(0);
+  });
 });