@spooky-sync/core 0.0.1-canary.26 → 0.0.1-canary.260

package/src/mutation/rows.ts

@@ -0,0 +1,377 @@
+import { RecordId } from 'surrealdb';
+import type { MutationEventType } from '../types';
+import type { Vars } from '../kernel/effects';
+import type { IngestRecord } from '../services/stream-processor/index';
+import type { OutboxItem } from '../state/client-state';
+import { surql } from '../utils/surql';
+import type { SealedQuery } from '../utils/surql';
+import { extractTablePart, parseRecordIdString } from '../utils/index';
+import { parseQueryParams } from '../utils/parser';
+
+export const PENDING_TABLE = '_00_pending_mutations';
+export const FAILED_TABLE = '_00_failed_mutations';
+export const PENDING_ROW_VERSION = 2;
+
+/** One `_00_pending_mutations` row as this client writes it (v2). */
+export interface PendingMutationRow {
+  id: string;
+  mutationType: MutationEventType;
+  recordId: string;
+  tableName: string;
+  data?: Record<string, unknown>;
+  beforeRecord?: Record<string, unknown> | null;
+  createdAt: number;
+  v: number;
+}
+
+export interface FailedMutationRow {
+  id: string;
+  mutationType: MutationEventType;
+  recordId: string;
+  tableName: string;
+  data?: Record<string, unknown>;
+  beforeRecord?: Record<string, unknown> | null;
+  error: { message: string; kind: 'application' | 'unreplayable' };
+  attempts: number;
+  createdAt: number;
+  failedAt: number;
+  revert: 'full' | 'partial' | 'none';
+}
+
+/**
+ * Parse a record id READ BACK FROM THE STORE, stripping SurrealDB's `⟨⟩`
+ * escaping (outbox ids contain `_`, so they come back escaped).
+ */
+export function parseStoredRecordId(id: string): RecordId<string> {
+  const [table, ...rest] = id.split(':');
+  let raw = rest.join(':');
+  if (raw.startsWith('⟨') && raw.endsWith('⟩')) raw = raw.slice(1, -1);
+  return new RecordId(table, raw);
+}
+
+/** Stable `table:id` string for an id read from the store, escaping removed. */
+export const storedIdString = (id: unknown): string => {
+  if (id instanceof RecordId) return `${id.table}:${String(id.id)}`;
+  const rid = parseStoredRecordId(String(id));
+  return `${rid.table}:${rid.id}`;
+};
+
+/** Timestamp prefix of a v1/v2 mutation id, or `null` for a legacy numeric id. */
+export function createdAtFromId(id: string): number | null {
+  const raw = id.includes(':') ? id.slice(id.indexOf(':') + 1) : id;
+  const m = /^⟨?(\d{13})/.exec(raw);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Read any row shape this table ever had. Legacy rows (`v` missing) lack
+ * `tableName`, `createdAt` and `beforeRecord`. A create without `data` is not
+ * replayable and returns `null`.
+ */
+export function parsePendingRow(row: unknown): PendingMutationRow | null {
+  if (!row || typeof row !== 'object') return null;
+  const r = row as Record<string, unknown>;
+  const type = r.mutationType;
+  if (type !== 'create' && type !== 'update' && type !== 'delete') return null;
+  if (typeof r.recordId !== 'string' && !(r.recordId instanceof RecordId)) return null;
+  const id = storedIdString(r.id);
+  const recordId = typeof r.recordId === 'string' ? r.recordId : storedIdString(r.recordId);
+  const data = r.data && typeof r.data === 'object' ? (r.data as Record<string, unknown>) : undefined;
+  if (type === 'create' && !data) return null;
+  return {
+    id,
+    mutationType: type,
+    recordId,
+    tableName: typeof r.tableName === 'string' ? r.tableName : extractTablePart(recordId),
+    data,
+    beforeRecord:
+      r.beforeRecord && typeof r.beforeRecord === 'object' ? (r.beforeRecord as Record<string, unknown>) : undefined,
+    createdAt: typeof r.createdAt === 'number' ? r.createdAt : (createdAtFromId(id) ?? 0),
+    v: typeof r.v === 'number' ? r.v : 1,
+  };
+}
+
+/**
+ * Re-type a stored row's payload from the schema before it is pushed. The
+ * store keeps JSON, so a `record<user>` field comes back as `'user:x'` and a
+ * datetime as a string; the server coerces neither. Unknown keys stay as they
+ * are, and a payload the schema rejects is sent raw so the server's answer,
+ * not a local throw, decides its fate.
+ */
+export function hydrateRowData(row: PendingMutationRow, columns: Record<string, unknown> | null): PendingMutationRow {
+  if (!row.data || !columns) return row;
+  try {
+    return { ...row, data: parseQueryParams(columns as never, row.data) };
+  } catch {
+    return row;
+  }
+}
+
+export const toOutboxItem = (row: PendingMutationRow): OutboxItem => ({
+  id: row.id,
+  type: row.mutationType,
+  recordId: row.recordId,
+  table: row.tableName,
+  status: 'pending',
+  ackedAt: null,
+  attempts: 0,
+});
+
+export const loadPendingRows = (): string => `SELECT * FROM ${PENDING_TABLE} ORDER BY id ASC`;
+export const loadFailedRows = (): string => `SELECT * FROM ${FAILED_TABLE} ORDER BY failedAt ASC`;
+
+// ---- local write transactions ------------------------------------------------
+
+export interface LocalTx {
+  query: SealedQuery<unknown>;
+  vars: Vars;
+}
+
+const pendingInsert = (type: MutationEventType, withData: boolean, withBefore: boolean): string => {
+  const fields = [
+    `mutationType = '${type}'`,
+    'recordId = $id',
+    'tableName = $table',
+    'createdAt = $createdAt',
+    `v = ${PENDING_ROW_VERSION}`,
+  ];
+  if (withData) fields.push('data = $data');
+  if (withBefore) fields.push('beforeRecord = $before');
+  return `CREATE ONLY $mid SET ${fields.join(', ')}`;
+};
+
+export interface WritePlanInput {
+  recordId: RecordId<string>;
+  mutationId: RecordId<string>;
+  table: string;
+  data?: Record<string, unknown>;
+  before?: Record<string, unknown> | null;
+  now: number;
+}
+
+/** `CREATE` the row and its outbox entry in one transaction; result index 0 is the row. */
+export function planCreateTx(input: WritePlanInput): LocalTx {
+  const data = input.data ?? {};
+  const keys = Object.keys(data).map((key) => ({ key, variable: `data_${key}` }));
+  const vars: Vars = { id: input.recordId, mid: input.mutationId, table: input.table, createdAt: input.now, data };
+  for (const { key, variable } of keys) vars[variable] = data[key];
+  return {
+    query: surql.seal<unknown>(surql.tx([surql.createSet('id', keys), pendingInsert('create', true, false)]), {
+      resultIndex: 0,
+    }),
+    vars,
+  };
+}
+
+/** Bump `_00_rv`, MERGE the patch, write the outbox row (with `beforeRecord`); returns `{ target }`. */
+export function planUpdateTx(input: WritePlanInput): LocalTx {
+  return {
+    query: surql.seal<unknown>(
+      surql.tx([
+        surql.updateSet('id', [{ statement: '_00_rv += 1' }]),
+        surql.let('updated', surql.updateMerge('id', 'data')),
+        pendingInsert('update', true, true),
+        surql.returnObject([{ key: 'target', variable: 'updated' }]),
+      ])
+    ),
+    vars: {
+      id: input.recordId,
+      mid: input.mutationId,
+      table: input.table,
+      createdAt: input.now,
+      data: input.data ?? {},
+      before: input.before ?? null,
+    },
+  };
+}
+
+/** DELETE the row and write the outbox entry (with `beforeRecord`). */
+export function planDeleteTx(input: WritePlanInput): LocalTx {
+  return {
+    query: surql.seal<unknown>(surql.tx([surql.delete('id'), pendingInsert('delete', false, true)])),
+    vars: {
+      id: input.recordId,
+      mid: input.mutationId,
+      table: input.table,
+      createdAt: input.now,
+      before: input.before ?? null,
+    },
+  };
+}
+
+/** 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 {
+  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 },
+  };
+}
+
+/** The outbox row of a flushed debounced update, on its own. */
+export function planDeferredOutboxRowTx(input: WritePlanInput): LocalTx {
+  return {
+    query: surql.seal<unknown>(surql.tx([pendingInsert('update', true, true)])),
+    vars: {
+      id: input.recordId,
+      mid: input.mutationId,
+      table: input.table,
+      createdAt: input.now,
+      data: input.data ?? {},
+      before: input.before ?? null,
+    },
+  };
+}
+
+// ---- remote push -------------------------------------------------------------
+
+export interface RemoteBatch {
+  sql: string;
+  vars: Vars;
+}
+
+/**
+ * Many outbox rows as ONE multi-statement request. Statement i answers row i.
+ * Each statement is its own transaction on the server, as before.
+ */
+export function remoteBatch(rows: ReadonlyArray<PendingMutationRow>): RemoteBatch {
+  const vars: Vars = {};
+  const stmts = rows.map((row, i) => {
+    const rid = parseRecordIdString(row.recordId);
+    vars[`id${i}`] = rid;
+    switch (row.mutationType) {
+      case 'create': {
+        const data = row.data ?? {};
+        const sets = Object.keys(data).map((key) => {
+          vars[`d${i}_${key}`] = data[key];
+          return `${key} = $d${i}_${key}`;
+        });
+        return `CREATE ONLY $id${i} SET ${sets.join(', ')}`;
+      }
+      case 'update':
+        vars[`data${i}`] = row.data ?? {};
+        return `UPDATE $id${i} MERGE $data${i}`;
+      case 'delete':
+        return `DELETE $id${i}`;
+    }
+  });
+  return { sql: stmts.join(';\n'), vars };
+}
+
+// ---- rollback ----------------------------------------------------------------
+
+export interface RevertPlan {
+  tx: LocalTx | null;
+  circuit: IngestRecord;
+  revert: FailedMutationRow['revert'];
+}
+
+/**
+ * How to undo a rejected mutation locally. A create is deleted; an update or
+ * delete is restored from `beforeRecord` (REPLACE, so the pre-bump `_00_rv`
+ * comes back). Without a `beforeRecord` nothing can be restored.
+ */
+export function planRevert(row: PendingMutationRow, before: Record<string, unknown> | null): RevertPlan {
+  const rid = parseRecordIdString(row.recordId);
+  if (row.mutationType === 'create') {
+    return {
+      tx: { query: surql.seal<unknown>(surql.tx([surql.delete('id')])), vars: { id: rid } },
+      circuit: { table: row.tableName, op: 'DELETE', id: row.recordId, record: row.data ?? {} },
+      revert: 'full',
+    };
+  }
+  if (!before) {
+    return {
+      tx: null,
+      circuit: { table: row.tableName, op: 'UPDATE', id: row.recordId, record: {} },
+      revert: 'partial',
+    };
+  }
+  const { id: _id, ...content } = before;
+  return {
+    tx: { query: surql.seal<unknown>(surql.tx([surql.upsert('id', 'content')])), vars: { id: rid, content } },
+    circuit: {
+      table: row.tableName,
+      op: row.mutationType === 'delete' ? 'CREATE' : 'UPDATE',
+      id: row.recordId,
+      record: { ...before, id: rid },
+    },
+    revert: 'full',
+  };
+}
+
+export const failedRecordId = (mutationId: string): RecordId<string> =>
+  new RecordId(FAILED_TABLE, mutationId.slice(mutationId.indexOf(':') + 1));
+
+export function buildFailedRow(
+  row: PendingMutationRow,
+  error: { message: string; kind: 'application' | 'unreplayable' },
+  before: Record<string, unknown> | null,
+  attempts: number,
+  now: number,
+  revert: FailedMutationRow['revert']
+): FailedMutationRow {
+  return {
+    id: row.id,
+    mutationType: row.mutationType,
+    recordId: row.recordId,
+    tableName: row.tableName,
+    data: row.data,
+    beforeRecord: before,
+    error,
+    attempts,
+    createdAt: row.createdAt,
+    failedAt: now,
+    revert,
+  };
+}
+
+/** ONE transaction: write the tray row, delete the pending row. */
+export function moveToFailedTx(failed: FailedMutationRow): LocalTx {
+  const { id: _id, ...content } = failed;
+  return {
+    query: surql.seal<unknown>(surql.tx([surql.create('fid', 'failed'), surql.delete('mid')])),
+    vars: { fid: failedRecordId(failed.id), failed: content, mid: parseStoredRecordId(failed.id) },
+  };
+}
+
+export const deletePendingRow = (mutationId: string): { sql: string; vars: Vars } => ({
+  sql: 'DELETE $mid',
+  vars: { mid: parseStoredRecordId(mutationId) },
+});
+
+export const deleteFailedRow = (mutationId: string): { sql: string; vars: Vars } => ({
+  sql: 'DELETE $fid',
+  vars: { fid: failedRecordId(mutationId) },
+});
+
+export function parseFailedRow(row: unknown): FailedMutationRow | null {
+  if (!row || typeof row !== 'object') return null;
+  const r = row as Record<string, unknown>;
+  const type = r.mutationType;
+  if (type !== 'create' && type !== 'update' && type !== 'delete') return null;
+  if (typeof r.recordId !== 'string') return null;
+  const err = (r.error ?? {}) as Record<string, unknown>;
+  return {
+    id: storedIdString(r.id).replace(`${FAILED_TABLE}:`, `${PENDING_TABLE}:`),
+    mutationType: type,
+    recordId: r.recordId,
+    tableName: typeof r.tableName === 'string' ? r.tableName : extractTablePart(r.recordId),
+    data: r.data && typeof r.data === 'object' ? (r.data as Record<string, unknown>) : undefined,
+    beforeRecord:
+      r.beforeRecord && typeof r.beforeRecord === 'object' ? (r.beforeRecord as Record<string, unknown>) : null,
+    error: {
+      message: typeof err.message === 'string' ? err.message : 'unknown',
+      kind: err.kind === 'unreplayable' ? 'unreplayable' : 'application',
+    },
+    attempts: typeof r.attempts === 'number' ? r.attempts : 0,
+    createdAt: typeof r.createdAt === 'number' ? r.createdAt : 0,
+    failedAt: typeof r.failedAt === 'number' ? r.failedAt : 0,
+    revert: r.revert === 'partial' || r.revert === 'none' ? r.revert : 'full',
+  };
+}

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

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure } from '../testing/run-pure';
+import { buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { discardFailed, listFailed, retryFailed } from './tray.saga';
+
+const env = defaultEnv({ tables: [{ name: 'thing', columns: { a: {} } }] } as any);
+const failedRow = {
+  id: '_00_failed_mutations:m1',
+  mutationType: 'create',
+  recordId: 'thing:1',
+  tableName: 'thing',
+  data: { a: 1 },
+  error: { message: 'denied', kind: 'application' },
+  attempts: 1,
+  createdAt: 1,
+  failedAt: 2,
+  revert: 'full',
+};
+
+describe('tray', () => {
+  it('lists parsed rows, skipping junk', async () => {
+    const out = await runPure(listFailed(), { handlers: { 'local.query': () => [[failedRow, { nope: true }]] } });
+    expect(out.result).toEqual([expect.objectContaining({ id: '_00_pending_mutations:m1', mutationType: 'create' })]);
+    expect((await runPure(listFailed(), { handlers: { 'local.query': () => [] } })).result).toEqual([]);
+  });
+  it('retry re-applies the write with a new id, drops the tray row, updates the count; missing rows return false', async () => {
+    const out = await runPure(retryFailed(env, '_00_pending_mutations:m1'), {
+      state: R.setFailedCount(2)(buildState()),
+      handlers: {
+        'local.query': (e: any) => {
+          if (e.sql === 'SELECT * FROM $ids') {
+            expect(e.vars.ids).toEqual([new RecordId('_00_failed_mutations', 'm1')]);
+            return [[failedRow]];
+          }
+          if (e.sql === 'DELETE $fid') return [];
+          return [];
+        },
+        'local.execute': () => ({ id: new RecordId('thing', '1'), a: 1 }),
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(out.result).toBe(true);
+    expect(out.state.outbox).toEqual([expect.objectContaining({ id: 'mutation-1', type: 'create', recordId: 'thing:1' })]);
+    expect(out.state.failedCount).toBe(1);
+    expect(out.emitted).toContainEqual({ type: 'tray:changed', count: 1 });
+    expect(out.dispatched).toContainEqual({ type: 'Drain' });
+    const missing = await runPure(retryFailed(env, '_00_pending_mutations:zz'), { handlers: { 'local.query': () => [[]] } });
+    expect(missing.result).toBe(false);
+  });
+  it('discard drops the row and never goes below zero', async () => {
+    const out = await runPure(discardFailed('_00_pending_mutations:m1'), {
+      state: buildState(),
+      handlers: { 'local.query': (e: any) => (e.sql === 'SELECT * FROM $ids' ? [[failedRow]] : []) },
+    });
+    expect(out.result).toBe(true);
+    expect(out.state.failedCount).toBe(0);
+    expect(out.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'failed-mutations-changed', count: 0 } });
+    expect((await runPure(discardFailed('nope'), { handlers: { 'local.query': () => [] } })).result).toBe(false);
+  });
+});

package/src/mutation/tray.saga.ts

@@ -0,0 +1,48 @@
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import * as R from '../state/reducers';
+import type { SagaEnv } from '../query/env';
+import { deleteFailedRow, failedRecordId, loadFailedRows, parseFailedRow, type FailedMutationRow } from './rows';
+import { write } from './write.saga';
+
+/** Every rejected mutation still in the tray, oldest first. */
+export function* listFailed(): Saga<FailedMutationRow[]> {
+  const res = (yield fx.local.query(loadFailedRows())) as unknown[];
+  const raw = Array.isArray(res?.[0]) ? (res[0] as unknown[]) : [];
+  return raw.map(parseFailedRow).filter((r): r is FailedMutationRow => r !== null);
+}
+
+function* loadFailed(mutationId: string): Saga<FailedMutationRow | null> {
+  const res = (yield fx.local.query('SELECT * FROM $ids', { ids: [failedRecordId(mutationId)] })) as unknown[];
+  const raw = Array.isArray(res?.[0]) ? (res[0] as unknown[])[0] : undefined;
+  return raw ? parseFailedRow(raw) : null;
+}
+
+function* dropFailed(mutationId: string): Saga<void> {
+  const del = deleteFailedRow(mutationId);
+  yield fx.local.query(del.sql, del.vars);
+  const count = Math.max(0, ((yield fx.state.read((s) => s.failedCount)) as number) - 1);
+  yield fx.state.update(R.setFailedCount(count));
+  yield fx.emit({ type: 'tray:changed', count });
+  yield fx.emit({ type: 'tabs:broadcast', message: { type: 'failed-mutations-changed', count } });
+}
+
+/**
+ * Re-apply a rejected mutation as a NEW optimistic write (fresh mutation id,
+ * the optimistic local change comes back, the outbox drains), then drop the
+ * tray row.
+ */
+export function* retryFailed(env: SagaEnv, mutationId: string): Saga<boolean> {
+  const failed = yield* loadFailed(mutationId);
+  if (!failed) return false;
+  yield* write(env, { kind: failed.mutationType, recordId: failed.recordId, data: failed.data });
+  yield* dropFailed(mutationId);
+  return true;
+}
+
+export function* discardFailed(mutationId: string): Saga<boolean> {
+  const failed = yield* loadFailed(mutationId);
+  if (!failed) return false;
+  yield* dropFailed(mutationId);
+  return true;
+}

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

@@ -0,0 +1,163 @@
+import { describe, expect, it } from 'vitest';
+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';
+
+const env = defaultEnv({ tables: [{ name: 'thing', columns: { a: {}, b: {} } }] } as any);
+const rid = new RecordId('thing', '1');
+const withQuery = () => buildState([buildEntry({ def: { hash: 'q', tableName: 'thing' } })]);
+
+describe('write', () => {
+  it('rejects unknown tables', async () => {
+    await expect(runPure(write(env, { kind: 'create', recordId: 'nope:1', data: {} }))).rejects.toThrow('Table nope not found');
+  });
+
+  it('create: local tx, outbox item, circuit ingest, version 1, event, drain; dirties the table', async () => {
+    const out = await runPure(write(env, { kind: 'create', recordId: 'thing:1', data: { a: 1, junk: 2 } }), {
+      state: withQuery(),
+      handlers: {
+        'local.execute': (e: any) => {
+          expect(e.query.sql).toContain("mutationType = 'create'");
+          expect(e.vars.data).toEqual({ a: 1 });
+          return { id: rid, a: 1 };
+        },
+        'ssp.ingest': (e: any) => {
+          expect(e.records).toEqual([{ table: 'thing', op: 'CREATE', id: 'thing:1', record: { id: rid, a: 1, _00_rv: 1 } }]);
+        },
+      },
+    });
+    expect(out.result).toEqual({ mutationId: 'mutation-1', record: { id: rid, a: 1 } });
+    expect(out.state.outbox).toEqual([{ id: 'mutation-1', type: 'create', recordId: 'thing:1', table: 'thing', status: 'pending', ackedAt: null, attempts: 0 }]);
+    expect(out.state.versions.get('thing:1')).toBe(1);
+    expect(out.state.dirty.has('q')).toBe(true);
+    expect(out.emitted[0]).toMatchObject({ type: 'mutation:event', event: { type: 'create', tableName: 'thing' } });
+    expect(out.dispatched).toEqual([{ type: 'Drain' }]);
+    expect(out.log.filter((e) => e.kind === 'local.query')).toHaveLength(0);
+  });
+
+  it('update: reads before, tx with beforeRecord, version from the returned row; delete: before feeds the circuit', async () => {
+    const upd = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { a: 2 } }), {
+      state: withQuery(),
+      handlers: {
+        'local.query': () => [{ id: rid, a: 1, _00_rv: 4 }],
+        'local.execute': (e: any) => {
+          expect(e.vars.before).toEqual({ id: rid, a: 1, _00_rv: 4 });
+          return { target: { id: rid, a: 2, _00_rv: 5 } };
+        },
+        'ssp.ingest': (e: any) => expect(e.records[0]).toMatchObject({ op: 'UPDATE', record: { a: 2, _00_rv: 5 } }),
+      },
+    });
+    expect(upd.result.record).toEqual({ id: rid, a: 2, _00_rv: 5 });
+    expect(upd.state.versions.get('thing:1')).toBe(5);
+    expect(upd.emitted[0]).toMatchObject({ event: { beforeRecord: { a: 1 } } });
+    const noRow = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { a: 2 } }), {
+      state: withQuery(),
+      handlers: { 'local.query': () => [null], 'local.execute': () => ({ target: null }), 'ssp.ingest': () => undefined },
+    });
+    expect(noRow.result.record).toBeNull();
+    expect(noRow.state.versions.get('thing:1')).toBe(1);
+    const del = await runPure(write(env, { kind: 'delete', recordId: 'thing:1' }), {
+      state: buildState([], (s) => ({ ...s, versions: new Map([['thing:1', 3]]) })),
+      handlers: {
+        'local.query': () => [{ id: rid, a: 1, _00_rv: 3 }],
+        'local.execute': () => undefined,
+        'ssp.ingest': (e: any) => expect(e.records[0]).toEqual({ table: 'thing', op: 'DELETE', id: 'thing:1', record: { id: rid, a: 1, _00_rv: 3 } }),
+      },
+    });
+    expect(del.result.record).toBeNull();
+    expect(del.state.versions.has('thing:1')).toBe(false);
+    expect(del.state.outbox[0].type).toBe('delete');
+    const delNoRow = await runPure(write(env, { kind: 'delete', recordId: 'thing:1' }), {
+      state: buildState(),
+      handlers: {
+        'local.query': () => [[]],
+        'local.execute': () => undefined,
+        'ssp.ingest': (e: any) => expect(e.records[0].record).toEqual({}),
+      },
+    });
+    expect(delNoRow.emitted[0]).toMatchObject({ event: { beforeRecord: undefined } });
+  });
+
+  it('a failing circuit ingest is logged, the write still stands; a follower broadcasts instead of draining', async () => {
+    const out = await runPure(write(env, { kind: 'create', recordId: 'thing:1', data: {} }), {
+      state: { ...buildState(), tabRole: 'follower' },
+      handlers: {
+        'local.execute': () => ({ id: rid }),
+        'ssp.ingest': () => {
+          throw new Error('wasm');
+        },
+      },
+    });
+    expect(out.emitted.some((e) => e.type === 'log' && e.level === 'error')).toBe(true);
+    expect(out.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId: 'mutation-1' } });
+    expect(out.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'ingest', records: [expect.objectContaining({ id: 'thing:1', op: 'CREATE' })] } });
+    expect(out.dispatched).toEqual([]);
+    expect(out.state.outbox).toHaveLength(1);
+  });
+
+  it('debounced update: applies locally, merges the patch per key, arms the flush timer; flush writes one outbox row', async () => {
+    const first = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { a: 1 }, options: { debounced: true } }), {
+      state: withQuery(),
+      handlers: {
+        'local.query': () => [{ id: rid, a: 0, _00_rv: 1 }],
+        'local.execute': () => ({ target: { id: rid, a: 1, _00_rv: 2 } }),
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(first.result).toEqual({ mutationId: '', record: { id: rid, a: 1, _00_rv: 2 } });
+    expect(first.state.outbox).toEqual([]);
+    const key = 'thing:1::a';
+    expect(first.state.pendingWrites.get(key)).toMatchObject({ data: { a: 1 }, before: { a: 0 } });
+    expect(first.timers.get(`debounce:${key}`)).toEqual({ ms: 300, event: { type: 'FlushWrite', key } });
+    expect(first.state.dirty.has('q')).toBe(true);
+    const second = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { a: 5 }, options: { debounced: { delay: 50, key: 'recordId_x_fields' } } }), {
+      state: first.state,
+      handlers: {
+        'local.execute': () => ({ target: { id: rid, a: 5, _00_rv: 3 } }),
+        'ssp.ingest': () => {
+          throw new Error('wasm');
+        },
+      },
+    });
+    expect(second.log.filter((e) => e.kind === 'local.query')).toHaveLength(0);
+    expect(second.state.pendingWrites.get(key)).toMatchObject({ data: { a: 5 }, before: { a: 0 } });
+    expect(second.timers.get(`debounce:${key}`)!.ms).toBe(50);
+    const byRecord = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { b: 1 }, options: { debounced: { key: 'recordId' } } }), {
+      state: withQuery(),
+      handlers: { 'local.query': () => [], 'local.execute': () => undefined, 'ssp.ingest': () => undefined },
+    });
+    expect(byRecord.state.pendingWrites.has('thing:1')).toBe(true);
+    expect(byRecord.result.record).toBeNull();
+    const noData = await runPure(write(env, { kind: 'update', recordId: 'thing:1', options: { debounced: true } }), {
+      state: withQuery(),
+      handlers: { 'local.query': () => undefined, 'local.execute': () => undefined, 'ssp.ingest': () => undefined },
+    });
+    expect(noData.state.pendingWrites.has('thing:1::')).toBe(true);
+    const flushedNoBefore = await runPure(flushWrite(env, 'thing:1'), { state: byRecord.state, handlers: { 'local.execute': () => undefined } });
+    expect(flushedNoBefore.emitted[0]).toMatchObject({ event: { beforeRecord: undefined } });
+    const flushed = await runPure(flushWrite(env, key), {
+      state: second.state,
+      handlers: {
+        'local.execute': (e: any) => {
+          expect(e.query.sql).toContain("mutationType = 'update'");
+          expect(e.vars).toMatchObject({ data: { a: 5 }, before: { id: rid, a: 0, _00_rv: 1 }, table: 'thing' });
+        },
+      },
+    });
+    expect(flushed.state.pendingWrites.size).toBe(0);
+    expect(flushed.state.outbox).toEqual([expect.objectContaining({ id: 'mutation-1', type: 'update', recordId: 'thing:1' })]);
+    expect(flushed.emitted[0]).toMatchObject({ type: 'mutation:event', event: { type: 'update', data: { a: 5 } } });
+    expect(flushed.dispatched).toEqual([{ type: 'Drain' }]);
+    const nothing = await runPure(flushWrite(env, 'missing'), { state: buildState() });
+    expect(nothing.dispatched).toEqual([]);
+    const follower = await runPure(flushWrite(env, key), { state: { ...second.state, tabRole: 'follower' }, handlers: { 'local.execute': () => undefined } });
+    expect(follower.emitted).toContainEqual(expect.objectContaining({ type: 'tabs:broadcast' }));
+    const leaderDebounced = await runPure(write(env, { kind: 'update', recordId: 'thing:1', data: { a: 1 }, options: { debounced: true } }), {
+      state: { ...withQuery(), tabRole: 'leader' },
+      handlers: { 'local.query': () => [], 'local.execute': () => undefined, 'ssp.ingest': () => undefined },
+    });
+    expect(leaderDebounced.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'ingest', records: [expect.objectContaining({ op: 'UPDATE' })] } });
+  });
+});