@spooky-sync/core 0.0.1-canary.29 → 0.0.1-canary.290

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

@@ -0,0 +1,316 @@
+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 { 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');
+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' })] } });
+  });
+
+  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);
+  });
+});

package/src/mutation/write.saga.ts

@@ -0,0 +1,268 @@
+import { RecordId } from 'surrealdb';
+import type { MutationEventType, UpdateOptions } from '../types';
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import type { ClientState, PendingWrite } from '../state/client-state';
+import * as R from '../state/reducers';
+import { parseParams } from '../utils/parser';
+import { extractTablePart, parseRecordIdString } from '../utils/index';
+import type { SagaEnv } from '../query/env';
+import { columnsFor } from '../query/env';
+import { PENDING_WRITE_ORPHAN_MS } from '../kernel/constants';
+import {
+  loadPendingWriteRows,
+  parsePendingWriteRow,
+  pendingWriteId,
+  planCreateTx,
+  planDeferredOutboxRowTx,
+  planDeleteTx,
+  planLocalOnlyUpdateTx,
+  planUpdateTx,
+  type LocalTx,
+  type PendingWriteRow,
+} from './rows';
+
+export interface WriteInput {
+  kind: MutationEventType;
+  recordId: string;
+  data?: Record<string, unknown>;
+  options?: UpdateOptions;
+}
+
+export interface WriteResult {
+  mutationId: string;
+  record: Record<string, unknown> | null;
+}
+
+const debounceKey = (input: WriteInput): string | null => {
+  const d = input.options?.debounced;
+  if (!d) return null;
+  const opts = d === true ? {} : d;
+  const keyMode = opts.key ?? 'recordId_x_fields';
+  return keyMode === 'recordId'
+    ? input.recordId
+    : `${input.recordId}::${Object.keys(input.data ?? {}).sort().join(',')}`;
+};
+const debounceDelay = (input: WriteInput): number => {
+  const d = input.options?.debounced;
+  return d && d !== true && typeof d.delay === 'number' ? d.delay : 300;
+};
+const flushOnHide = (input: WriteInput): boolean => {
+  const d = input.options?.debounced;
+  return !(d && d !== true && d.flushOnHide === false);
+};
+
+/**
+ * One optimistic write: read the previous row (update/delete), run the local
+ * transaction that writes the row AND its outbox entry, publish the outbox
+ * item (which puts the id into the overlay and dirties the table's queries),
+ * feed the circuit, and start a drain. A debounced update applies locally at
+ * once but accumulates into one outbox row written on flush.
+ */
+export function* write(env: SagaEnv, input: WriteInput): Saga<WriteResult> {
+  const table = extractTablePart(input.recordId);
+  const columns = columnsFor(env, table);
+  if (!columns) throw new Error(`Table ${table} not found`);
+  const rid = parseRecordIdString(input.recordId);
+  const params = input.data ? parseParams(columns as never, input.data) : undefined;
+  const key = input.kind === 'update' ? debounceKey(input) : null;
+  if (key !== null) return yield* debouncedUpdate(input, key, rid, table, params ?? {});
+  const mutationId = (yield fx.id('mutation')) as string;
+  const now = (yield fx.now()) as number;
+  let before: Record<string, unknown> | null = null;
+  if (input.kind !== 'create') before = yield* readBefore(rid);
+  const tx = planTx(input.kind, { recordId: rid, mutationId: parseRecordIdString(mutationId), table, data: params, before, now });
+  return yield* commitWrite(input.kind, tx, { mutationId, recordId: input.recordId, table, before, now });
+}
+
+function planTx(kind: MutationEventType, planInput: Parameters<typeof planCreateTx>[0]): LocalTx {
+  if (kind === 'create') return planCreateTx(planInput);
+  if (kind === 'update') return planUpdateTx(planInput);
+  return planDeleteTx(planInput);
+}
+
+function* readBefore(rid: RecordId<string>): Saga<Record<string, unknown> | null> {
+  const res = (yield fx.local.query('SELECT * FROM ONLY $id', { id: rid })) as unknown[];
+  const row = Array.isArray(res) ? res[0] : null;
+  return row && typeof row === 'object' && !Array.isArray(row) ? (row as Record<string, unknown>) : null;
+}
+
+interface CommitCtx {
+  mutationId: string;
+  recordId: string;
+  table: string;
+  before: Record<string, unknown> | null;
+  now: number;
+}
+
+function* commitWrite(kind: MutationEventType, tx: LocalTx, ctx: CommitCtx): Saga<WriteResult> {
+  const result = (yield fx.local.execute(tx.query, tx.vars)) as unknown;
+  const target = kind === 'update' ? (result as { target?: unknown } | undefined)?.target : result;
+  const record = kind === 'delete' || !target || typeof target !== 'object' ? null : (target as Record<string, unknown>);
+  yield fx.state.update(
+    R.outboxPush({ id: ctx.mutationId, type: kind, recordId: ctx.recordId, table: ctx.table, status: 'pending', ackedAt: null, attempts: 0 })
+  );
+  const version = kind === 'create' ? 1 : typeof record?._00_rv === 'number' ? (record._00_rv as number) : ((ctx.before?._00_rv as number) ?? 0) + 1;
+  const circuitRecord = kind === 'delete' ? (ctx.before ?? {}) : { ...record, _00_rv: version };
+  const circuitTuple = { table: ctx.table, op: kind.toUpperCase() as 'CREATE' | 'UPDATE' | 'DELETE', id: ctx.recordId, record: circuitRecord };
+  try {
+    yield fx.ssp.ingest([circuitTuple]);
+    if (kind === 'delete') yield fx.state.update(R.deleteVersions([ctx.recordId]));
+    else yield fx.state.update(R.setVersions([[ctx.recordId, version]]));
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'error', message: 'circuit ingest failed after a local write', data: { recordId: ctx.recordId, error } });
+  }
+  yield fx.emit({
+    type: 'mutation:event',
+    event: { type: kind, mutation_id: parseRecordIdString(ctx.mutationId), record_id: parseRecordIdString(ctx.recordId), data: tx.vars.data, record, beforeRecord: ctx.before ?? undefined, tableName: ctx.table },
+  });
+  const role = (yield fx.state.read((s) => s.tabRole)) as ClientState['tabRole'];
+  if (role !== 'solo') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'ingest', records: [circuitTuple] } });
+  if (role === 'follower') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId: ctx.mutationId } });
+  else yield fx.dispatch({ type: 'Drain' });
+  return { mutationId: ctx.mutationId, record };
+}
+
+/**
+ * Apply locally now, remember the merged patch, write the outbox row on flush.
+ * With `flushOnHide` (the default) the merged patch is also mirrored to
+ * `_00_pending_writes` in the same transaction, so a reload or a closed tab
+ * inside the delay cannot lose it.
+ */
+function* debouncedUpdate(
+  input: WriteInput,
+  key: string,
+  rid: RecordId<string>,
+  table: string,
+  params: Record<string, unknown>
+): Saga<WriteResult> {
+  const existing = (yield fx.state.read((s) => s.pendingWrites.get(key))) as PendingWrite | undefined;
+  const now = (yield fx.now()) as number;
+  const before = existing ? existing.before : yield* readBefore(rid);
+  const mirrorId = existing?.mirrorId ?? (flushOnHide(input) ? pendingWriteId((yield fx.id('mutation')) as string) : null);
+  const delay = debounceDelay(input);
+  const mirror = mirrorId
+    ? { id: parseRecordIdString(mirrorId), row: { recordId: rid, tableName: table, data: { ...existing?.data, ...params }, beforeRecord: before, flushBy: now + delay } }
+    : undefined;
+  const local = planLocalOnlyUpdateTx({ recordId: rid, data: params, mirror });
+  const res = (yield fx.local.execute(local.query, local.vars)) as { target?: Record<string, unknown> } | undefined;
+  const record = res?.target ?? null;
+  yield fx.state.update(R.mergePendingWrite({ key, table, recordId: input.recordId, data: params, before, firstAt: existing?.firstAt ?? now, mirrorId }));
+  yield fx.state.update(R.markTableDirty(table));
+  const version = typeof record?._00_rv === 'number' ? (record._00_rv as number) : 0;
+  const tuple = { table, op: 'UPDATE' as const, id: input.recordId, record: { ...record, _00_rv: version } };
+  try {
+    yield fx.ssp.ingest([tuple]);
+    yield fx.state.update(R.setVersions([[input.recordId, version]]));
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'error', message: 'circuit ingest failed after a local write', data: { recordId: input.recordId, error } });
+  }
+  const role = (yield fx.state.read((s) => s.tabRole)) as ClientState['tabRole'];
+  if (role !== 'solo') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'ingest', records: [tuple] } });
+  yield fx.timer.set(`debounce:${key}`, delay, { type: 'FlushWrite', key });
+  return { mutationId: '', record };
+}
+
+/** Timer target: turn the accumulated patch into one outbox row and drain. */
+export function* flushWrite(env: SagaEnv, key: string): Saga<void> {
+  const pending = (yield fx.state.read((s) => s.pendingWrites.get(key))) as PendingWrite | undefined;
+  if (!pending) return;
+  yield fx.state.update(R.clearPendingWrite(key));
+  const mutationId = (yield fx.id('mutation')) as string;
+  const now = (yield fx.now()) as number;
+  const rid = parseRecordIdString(pending.recordId);
+  const insert = planDeferredOutboxRowTx({
+    recordId: rid,
+    mutationId: parseRecordIdString(mutationId),
+    table: pending.table,
+    data: { ...pending.data },
+    before: pending.before,
+    now,
+    mirrorId: pending.mirrorId ? parseRecordIdString(pending.mirrorId) : undefined,
+  });
+  try {
+    yield fx.local.execute(insert.query, insert.vars);
+  } catch (error) {
+    // The patch is no longer in memory; a mirrored one is still in the store.
+    if (pending.mirrorId) yield fx.timer.set('adopt-writes', PENDING_WRITE_ORPHAN_MS, { type: 'AdoptPendingWrites' });
+    throw error;
+  }
+  yield fx.state.update(R.outboxPush({ id: mutationId, type: 'update', recordId: pending.recordId, table: pending.table, status: 'pending', ackedAt: null, attempts: 0 }));
+  yield fx.emit({
+    type: 'mutation:event',
+    event: { type: 'update', mutation_id: parseRecordIdString(mutationId), record_id: rid, data: { ...pending.data }, beforeRecord: pending.before ?? undefined, tableName: pending.table },
+  });
+  const role = (yield fx.state.read((s) => s.tabRole)) as ClientState['tabRole'];
+  if (role === 'follower') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId } });
+  else yield fx.dispatch({ type: 'Drain' });
+}
+
+/**
+ * The page is being hidden (tab switch, reload, close, backgrounded): flush
+ * every mirrored pending write now rather than when its timer fires. On a
+ * reload or close this races the teardown; whatever does not make it stays
+ * in `_00_pending_writes` for the next boot.
+ */
+export function* flushPendingWrites(): Saga<void> {
+  const keys = (yield fx.state.read((s) => [...s.pendingWrites.values()].filter((w) => w.mirrorId !== null).map((w) => w.key))) as string[];
+  for (const key of keys) {
+    yield fx.timer.clear(`debounce:${key}`);
+    yield fx.dispatch({ type: 'FlushWrite', key });
+  }
+}
+
+/**
+ * Move abandoned `_00_pending_writes` rows into the outbox: rows no pending
+ * write of this tab holds, `PENDING_WRITE_ORPHAN_MS` past their due flush. That
+ * is a tab that reloaded or closed inside the delay, or a flush of ours that
+ * failed. A row not yet overdue may still be live in another tab and is looked
+ * at again once it would be. A follower only nudges the leader, so a single
+ * tab adopts and a patch is never queued twice.
+ */
+export function* adoptPendingWrites(): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  let raw: unknown[] = [];
+  try {
+    const res = (yield fx.local.query(loadPendingWriteRows())) as unknown[];
+    raw = Array.isArray(res?.[0]) ? (res[0] as unknown[]) : [];
+  } catch {
+    return; // An older store may not have the table yet: nothing to adopt.
+  }
+  const held = new Set([...state.pendingWrites.values()].map((w) => w.mirrorId));
+  const rows = raw.map(parsePendingWriteRow).filter((r): r is PendingWriteRow => r !== null && !held.has(r.id));
+  if (rows.length === 0) return;
+  if (state.tabRole === 'follower') {
+    yield fx.emit({ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId: '' } });
+    return;
+  }
+  const now = (yield fx.now()) as number;
+  let recheckAt = Infinity;
+  let adopted = 0;
+  for (const row of rows) {
+    const due = row.flushBy + PENDING_WRITE_ORPHAN_MS;
+    if (now < due) {
+      recheckAt = Math.min(recheckAt, due);
+      continue;
+    }
+    const mutationId = (yield fx.id('mutation')) as string;
+    const move = planDeferredOutboxRowTx({
+      recordId: parseRecordIdString(row.recordId),
+      mutationId: parseRecordIdString(mutationId),
+      table: row.tableName,
+      data: row.data,
+      before: row.beforeRecord,
+      now,
+      mirrorId: parseRecordIdString(row.id),
+    });
+    try {
+      yield fx.local.execute(move.query, move.vars);
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'warn', message: 'could not move an abandoned debounced write into the outbox', data: { id: row.id, error } });
+      continue;
+    }
+    yield fx.state.update(R.outboxPush({ id: mutationId, type: 'update', recordId: row.recordId, table: row.tableName, status: 'pending', ackedAt: null, attempts: 0 }));
+    adopted += 1;
+  }
+  if (adopted > 0) yield fx.dispatch({ type: 'Drain' });
+  if (recheckAt !== Infinity) yield fx.timer.set('adopt-writes', recheckAt - now, { type: 'AdoptPendingWrites' });
+}

package/src/otel/index.ts

@@ -1,5 +1,5 @@
-import { Level } from 'pino';
-import { PinoTransmit } from '../types';
+import type { Level } from 'pino';
+import type { PinoTransmit } from '../types';
 
 // Map pino levels to OTEL severity numbers
 // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#severity-fields
@@ -74,6 +74,7 @@ export function createOtelTransmit(endpoint: string, level: Level = 'info'): Pin
   return {
     level: level,
     send: (levelLabel: string, logEvent: any) => {
+      // oxlint-disable-next-line promise/always-return
       otelReady.then((getOtelLogger) => {
         try {
           const messages = [...logEvent.messages];
@@ -81,12 +82,12 @@ export function createOtelTransmit(endpoint: string, level: Level = 'info'): Pin
 
           // Construct the message body
           let body = '';
-          const msg = messages.pop();
+          const lastMsg = messages.pop();
 
-          if (typeof msg === 'string') {
-            body = msg;
-          } else if (msg) {
-            body = JSON.stringify(msg);
+          if (typeof lastMsg === 'string') {
+            body = lastMsg;
+          } else if (lastMsg) {
+            body = JSON.stringify(lastMsg);
           }
 
           let category = 'sp00ky-client::unknown';
@@ -114,9 +115,11 @@ export function createOtelTransmit(endpoint: string, level: Level = 'info'): Pin
             timestamp: new Date(logEvent.ts),
           });
         } catch (e) {
+          // oxlint-disable-next-line no-console
           console.warn('Failed to transmit log to OTEL endpoint', e);
         }
       }).catch((e) => {
+        // oxlint-disable-next-line no-console
         console.warn('Failed to load OpenTelemetry modules', e);
       });
     },