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

package/src/modules/ref-tables.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { ANON_USER_ID, bucketIdForUser, listRefTableFor, sanitizeUserId } from './ref-tables';
+
+describe('listRefTableFor', () => {
+  it('returns global table in single mode regardless of user', () => {
+    expect(listRefTableFor('single', 'user:abc')).toBe('_00_list_ref');
+    expect(listRefTableFor('single', null)).toBe('_00_list_ref');
+    expect(listRefTableFor('single', undefined)).toBe('_00_list_ref');
+  });
+
+  it('returns per-user table in dedicated mode with valid user id', () => {
+    expect(listRefTableFor('dedicated', 'user:abc')).toBe(
+      '_00_list_ref_user_abc'
+    );
+  });
+
+  it('accepts a RecordId object in dedicated mode', () => {
+    const rid = new RecordId('user', 'def');
+    expect(listRefTableFor('dedicated', rid)).toBe('_00_list_ref_user_def');
+  });
+
+  it('falls back to global in dedicated mode when user id is missing', () => {
+    expect(listRefTableFor('dedicated', null)).toBe('_00_list_ref');
+    expect(listRefTableFor('dedicated', undefined)).toBe('_00_list_ref');
+  });
+
+  it('falls back to global in dedicated mode when user id has invalid chars', () => {
+    // SurrealDB table identifiers only accept alphanumerics + underscore.
+    expect(listRefTableFor('dedicated', 'user:abc-with-dash')).toBe(
+      '_00_list_ref'
+    );
+    expect(listRefTableFor('dedicated', 'user:abc.dot')).toBe('_00_list_ref');
+  });
+
+  it('routes the anon sentinel to the shared anon table in both modes', () => {
+    expect(listRefTableFor('dedicated', ANON_USER_ID)).toBe('_00_list_ref_anon');
+    expect(listRefTableFor('single', ANON_USER_ID)).toBe('_00_list_ref_anon');
+    // A real user whose id sanitizes to "anon" still carries the user: prefix,
+    // so it never collides with the bare sentinel.
+    expect(listRefTableFor('dedicated', 'user:anon')).toBe(
+      '_00_list_ref_user_anon'
+    );
+  });
+});
+
+describe('sanitizeUserId', () => {
+  it('strips the user: prefix', () => {
+    expect(sanitizeUserId('user:abc123')).toBe('abc123');
+  });
+
+  it('accepts plain ids without the user: prefix', () => {
+    expect(sanitizeUserId('abc123')).toBe('abc123');
+  });
+
+  it('accepts RecordId objects', () => {
+    expect(sanitizeUserId(new RecordId('user', 'xyz'))).toBe('xyz');
+  });
+
+  it('returns null for invalid id shapes', () => {
+    expect(sanitizeUserId(null)).toBeNull();
+    expect(sanitizeUserId(undefined)).toBeNull();
+    expect(sanitizeUserId('user:')).toBeNull();
+    expect(sanitizeUserId('user:has-dash')).toBeNull();
+  });
+});
+
+describe('bucketIdForUser', () => {
+  it('routes signed-out sessions to the anon bucket', () => {
+    expect(bucketIdForUser(null)).toBe(ANON_USER_ID);
+    expect(bucketIdForUser(undefined)).toBe(ANON_USER_ID);
+    expect(bucketIdForUser(ANON_USER_ID)).toBe(ANON_USER_ID);
+  });
+
+  it('uses the sanitized id for valid users', () => {
+    expect(bucketIdForUser('user:abc123')).toBe('abc123');
+    expect(bucketIdForUser(new RecordId('user', 'xyz'))).toBe('xyz');
+  });
+
+  it('gives unsanitizable ids a deterministic per-user bucket, never anon', () => {
+    const a = bucketIdForUser('user:has-dash');
+    const b = bucketIdForUser('user:has-dash');
+    const c = bucketIdForUser('user:other-dash');
+    // Falling back to the shared anon bucket here would recreate the
+    // cross-user local-cache leak this helper exists to prevent.
+    expect(a).not.toBe(ANON_USER_ID);
+    expect(a).toBe(b);
+    expect(a).not.toBe(c);
+    expect(a).toMatch(/^u[0-9a-f]+$/);
+  });
+});

package/src/modules/ref-tables.ts

@@ -0,0 +1,88 @@
+// Client-side mirror of `packages/ssp-protocol/src/lib.rs`'s
+// `query_table_for` / `list_ref_table_for`. Same naming convention so
+// the LIVE subscription, the initial-fetch read, and the SSP's writes
+// all land on the same table.
+//
+// The mode is currently hardcoded to `dedicated` because that's the
+// only mode the e2e suite exercises and threading the value through
+// codegen wasn't necessary to land the cross-session fix. If single
+// mode ever needs to be exposed from the TS client too, the SSP server
+// already reads it from `SPKY_SSP_REF_MODE`; add a matching codegen
+// export then.
+
+import { cyrb53 } from '@spooky-sync/query-builder';
+
+export type RefMode = 'single' | 'dedicated';
+
+/**
+ * Sentinel user id for unauthenticated clients when anonymous live queries are
+ * enabled. Mirrors `ssp_protocol::ANON_AUTH_ID`. It carries no `user:` prefix
+ * so it can never collide with a real user id (those arrive as `user:<id>`);
+ * both sides resolve it to the shared `_00_list_ref_anon` table.
+ */
+export const ANON_USER_ID = 'anon';
+
+/**
+ * Default ref-storage mode for this client build. Mirrors the SSP's
+ * default (`RefMode::Dedicated`) so cross-session sync works out of the
+ * box.
+ */
+export const DEFAULT_REF_MODE: RefMode = 'dedicated';
+
+/**
+ * Sanitize a user record id (e.g. `"user:abc"`) into the segment that
+ * goes into a dedicated table name (e.g. `"abc"`). Returns `null` if
+ * the id is missing the `user:` prefix or contains characters that
+ * aren't valid in a SurrealDB table identifier — the server-side
+ * `ssp_protocol::sanitize_user_id` uses the same predicate.
+ *
+ * Accepts both string ids (`"user:abc"`) and SurrealDB `RecordId`
+ * objects (which only stringify cleanly via `.toString()`), since
+ * `AuthService` passes the record-id object as-is to its subscribers.
+ */
+export function sanitizeUserId(userId: unknown): string | null {
+  if (userId === null || userId === undefined) return null;
+  const asString =
+    typeof userId === 'string'
+      ? userId
+      : typeof (userId as { toString?: unknown }).toString === 'function'
+        ? (userId as { toString: () => string }).toString()
+        : null;
+  if (!asString) return null;
+  const raw = asString.startsWith('user:') ? asString.slice('user:'.length) : asString;
+  if (raw.length === 0) return null;
+  if (!/^[A-Za-z0-9_]+$/.test(raw)) return null;
+  return raw;
+}
+
+/**
+ * Resolve the LOCAL storage bucket id for a user. Every user gets their own
+ * IndexedDB-backed local store (`indxdb://sp00ky-<bucketId>`) so cached rows,
+ * query state, and the mutation outbox never leak across accounts on a shared
+ * device. Signed-out sessions share the `anon` bucket.
+ *
+ * An id that fails sanitization still gets a DETERMINISTIC per-user bucket
+ * (cyrb53 hex of the raw id) — falling back to `anon` here would put an
+ * authenticated user in the shared bucket and recreate the cross-user leak.
+ */
+export function bucketIdForUser(userId: unknown): string {
+  if (userId === null || userId === undefined || userId === ANON_USER_ID) return ANON_USER_ID;
+  const uid = sanitizeUserId(userId);
+  if (uid) return uid;
+  return `u${cyrb53(String(userId)).toString(16)}`;
+}
+
+/**
+ * Returns the `_00_list_ref` table name for `(mode, userId)`. Falls
+ * back to the global `_00_list_ref` when sanitization fails or in
+ * single mode.
+ */
+export function listRefTableFor(mode: RefMode, userId: unknown): string {
+  // Anonymous clients (flag-enabled) share one dedicated table in both modes —
+  // checked before the mode split so it never lands on the per-user or the
+  // auth-gated global table. Matches `ssp_protocol::list_ref_table_for`.
+  if (userId === ANON_USER_ID) return '_00_list_ref_anon';
+  if (mode === 'single') return '_00_list_ref';
+  const uid = sanitizeUserId(userId);
+  return uid ? `_00_list_ref_user_${uid}` : '_00_list_ref';
+}

package/src/mutation/jobs.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { buildJobRecord } from './jobs';
+
+const schema = {
+  tables: [],
+  backends: {
+    api: { outboxTable: '_00_job_api', routes: { hello: { args: { name: { optional: false }, tone: { optional: true } } } } },
+    bare: { routes: { x: { args: {} } } },
+  },
+} as any;
+
+describe('buildJobRecord', () => {
+  it('builds a pending job row with the route payload and option overrides', () => {
+    const { tableName, record } = buildJobRecord(schema, 'api', 'hello', { name: 'a', extra: 1 }, { max_retries: 5, retry_strategy: 'exponential', timeout: 9, delay: 100, assignedTo: 'w1' });
+    expect(tableName).toBe('_00_job_api');
+    expect(record).toEqual({ path: 'hello', payload: JSON.stringify({ name: 'a', tone: undefined }), status: 'pending', max_retries: 5, retry_strategy: 'exponential', timeout: 9, delay: 100, assigned_to: 'w1' });
+    expect(buildJobRecord(schema, 'api', 'hello', { name: 'a' }).record).toMatchObject({ max_retries: 3, retry_strategy: 'linear' });
+  });
+  it('rejects unknown routes, missing outbox tables and missing required args', () => {
+    expect(() => buildJobRecord(schema, 'api', 'nope', {})).toThrow('Route api.nope not found');
+    expect(() => buildJobRecord(schema, 'bare', 'x', {})).toThrow('Outbox table for backend bare not found');
+    expect(() => buildJobRecord(schema, 'api', 'hello', {})).toThrow('Missing required argument name');
+    expect(() => buildJobRecord({ tables: [] } as any, 'api', 'hello', {})).toThrow('Route api.hello not found');
+  });
+});

package/src/mutation/jobs.ts

@@ -0,0 +1,41 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { RunOptions } from '../types';
+
+/**
+ * Build the outbox job record for a backend route and resolve its table.
+ * Every job is a single execution; recurring work is declared server-side.
+ */
+export function buildJobRecord(
+  schema: SchemaStructure,
+  backend: string,
+  path: string,
+  data: Record<string, unknown>,
+  options?: RunOptions
+): { tableName: string; record: Record<string, unknown> } {
+  const backends = (schema as { backends?: Record<string, { outboxTable?: string; routes?: Record<string, { args: Record<string, { optional: boolean }> }> }> }).backends;
+  const route = backends?.[backend]?.routes?.[path];
+  if (!route) throw new Error(`Route ${backend}.${path} not found`);
+  const tableName = backends?.[backend]?.outboxTable;
+  if (!tableName) throw new Error(`Outbox table for backend ${backend} not found`);
+
+  const payload: Record<string, unknown> = {};
+  for (const argName of Object.keys(route.args)) {
+    const arg = route.args[argName];
+    if (data[argName] === undefined && arg.optional === false) throw new Error(`Missing required argument ${argName}`);
+    payload[argName] = data[argName];
+  }
+
+  const record: Record<string, unknown> = {
+    path,
+    payload: JSON.stringify(payload),
+    // Explicit: the schema's server-side DEFAULT does not apply to an
+    // optimistic local create, and in-flight indicators key on `pending`.
+    status: 'pending',
+    max_retries: options?.max_retries ?? 3,
+    retry_strategy: options?.retry_strategy ?? 'linear',
+  };
+  if (options?.timeout != null) record.timeout = options.timeout;
+  if (options?.delay != null) record.delay = options.delay;
+  if (options?.assignedTo) record.assigned_to = options.assignedTo;
+  return { tableName, record };
+}

package/src/mutation/mutation-id.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { mintMutationId, mutationOwnerTabId } from './mutation-id';
+
+describe('mutationOwnerTabId (raw ids)', () => {
+  it('mints with the fallback tab id when none is given', () => {
+    const id = mintMutationId();
+    expect(id.startsWith('_00_pending_mutations:')).toBe(true);
+    expect(mutationOwnerTabId(id)).toMatch(/^[a-z0-9]+$/);
+  });
+  it('accepts an id without the table prefix', () => {
+    expect(mutationOwnerTabId('1700000000000_0001_tab9')).toBe('tab9');
+    expect(mutationOwnerTabId('1700000000000')).toBeNull();
+  });
+});
+
+// The old `_00_pending_mutations:${Date.now()}` collided within a millisecond
+// (guaranteed once multiple tabs share a store) and never actually ordered the
+// drain. These pin the new id's three properties: unique, sortable, routable.
+describe('mutation ids', () => {
+  it('never collides within a burst', () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => mintMutationId('tabx')));
+    expect(ids.size).toBe(1000);
+  });
+
+  it('sorts lexicographically in mint order (ORDER BY id is chronological)', () => {
+    const ids = Array.from({ length: 200 }, () => mintMutationId('tabx'));
+    expect([...ids].sort()).toEqual(ids);
+  });
+
+  it('routes back to the owning tab', () => {
+    expect(mutationOwnerTabId(mintMutationId('tab-abc'))).toBe('tab-abc');
+  });
+
+  it('returns null for a legacy numeric id instead of misrouting', () => {
+    expect(mutationOwnerTabId('_00_pending_mutations:1753875000000')).toBeNull();
+  });
+});

package/src/mutation/mutation-id.ts

@@ -0,0 +1,35 @@
+/**
+ * Outbox mutation ids. Previously `_00_pending_mutations:${Date.now()}`, which
+ * (a) collides when two mutations land in the same millisecond, a real case
+ * once multiple tabs share one store, and (b) never actually ordered the
+ * drain, because `loadFromDatabase` sorted by a `created_at` field that does
+ * not exist on the table. The new shape is sortable AND collision-free:
+ *
+ *   <13-digit zero-padded ms timestamp>_<4-digit base36 seq>_<tabId>
+ *
+ * Lexicographic order == chronological order (per tab; cross-tab within-ms
+ * ordering is arbitrary, which matches reality), so `ORDER BY id` in the
+ * drain is now meaningful. The tabId suffix also routes rollbacks back to the
+ * tab that owns the mutation in shared-tabs mode.
+ */
+
+let seq = 0;
+
+/** Tab identity for mutation ids in SOLO mode, minted once per session. In
+ *  shared-tabs mode the coordinator's tabId is passed in instead. */
+const FALLBACK_TAB_ID = Math.random().toString(36).slice(2, 8);
+
+export function mintMutationId(tabId?: string): string {
+  const ts = Date.now().toString().padStart(13, '0');
+  const n = (seq = (seq + 1) % 36 ** 4).toString(36).padStart(4, '0');
+  return `_00_pending_mutations:${ts}_${n}_${tabId ?? FALLBACK_TAB_ID}`;
+}
+
+/** The tab that created the mutation, or null for a legacy numeric id. */
+export function mutationOwnerTabId(mutationId: string): string | null {
+  const raw = mutationId.startsWith('_00_pending_mutations:')
+    ? mutationId.slice('_00_pending_mutations:'.length)
+    : mutationId;
+  const parts = raw.split('_');
+  return parts.length >= 3 ? parts[parts.length - 1] : null;
+}

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

@@ -0,0 +1,285 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure } from '../testing/run-pure';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { drain, loadOutbox, refreshFailedCount, rollback } from './push.saga';
+import type { StatementResult } from '../kernel/effects';
+import type { PendingMutationRow } from './rows';
+
+const env = defaultEnv({ tables: [{ name: 'thing', columns: {} }] } as any, { outboxBatchSize: 2 });
+const ok = (result: unknown = null): StatementResult => ({ status: 'OK', result });
+const err = (error: string): StatementResult => ({ status: 'ERR', error });
+const pendingRow = (n: number, type: PendingMutationRow['mutationType'] = 'create', extra: Partial<PendingMutationRow> = {}) => ({
+  id: `_00_pending_mutations:m${n}`,
+  mutationType: type,
+  recordId: `thing:${n}`,
+  tableName: 'thing',
+  data: type === 'delete' ? undefined : { a: n },
+  beforeRecord: type === 'create' ? undefined : { id: `thing:${n}`, a: 0, _00_rv: 7 },
+  createdAt: 1,
+  v: 2,
+  ...extra,
+});
+const items = (...ns: number[]) => ns.map((n) => buildOutboxItem({ id: `_00_pending_mutations:m${n}`, recordId: `thing:${n}`, type: 'create' }));
+const stateWith = (rows: number[], ...extra: Parameters<typeof buildState>[1][]) =>
+  buildState([buildEntry({ def: { hash: 'q', tableName: 'thing' } })], R.outboxReplace(items(...rows)), ...extra);
+
+describe('drain', () => {
+  it('re-types stored payloads from the schema before pushing (a stored record field is a string)', async () => {
+    const typedEnv = defaultEnv({ tables: [{ name: 'thing', columns: { owner: { recordId: true } } }] } as any, { outboxBatchSize: 2 });
+    let vars: any = null;
+    await runPure(drain(typedEnv), {
+      state: stateWith([1]),
+      handlers: {
+        'local.query': (e: any) => (e.sql === 'SELECT * FROM $ids' ? [[pendingRow(1, 'create', { data: { owner: 'user:u1' } })]] : []),
+        'remote.query': (e: any) => ((vars = e.vars), [ok()]),
+      },
+    });
+    expect(vars.d0_owner).toEqual(new RecordId('user', 'u1'));
+  });
+
+  it('pushes batches in FIFO order, acks each accepted row, deletes its pending row, then loops', async () => {
+    const pushed: string[] = [];
+    const out = await runPure(drain(env), {
+      state: stateWith([1, 2, 3]),
+      now: 500,
+      handlers: {
+        'local.query': (e: any) => {
+          if (e.sql === 'SELECT * FROM $ids') return [e.vars.ids.map((id: RecordId) => pendingRow(Number(String(id.id).slice(1))))];
+          return [];
+        },
+        'remote.query': (e: any) => {
+          pushed.push(e.sql);
+          return e.sql.split(';\n').map(() => ok());
+        },
+      },
+    });
+    expect(pushed).toEqual(['CREATE ONLY $id0 SET a = $d0_a;\nCREATE ONLY $id1 SET a = $d1_a', 'CREATE ONLY $id0 SET a = $d0_a']);
+    expect(out.state.outbox.every((i) => i.status === 'acked' && i.ackedAt === 500)).toBe(true);
+    expect(out.log.filter((e) => e.kind === 'local.query' && (e as any).sql === 'DELETE $mid')).toHaveLength(3);
+    expect(out.emitted.filter((e) => e.type === 'mutation:settled')).toHaveLength(3);
+    expect(out.timers.get('ack-prune')).toEqual({ ms: 30_000, event: { type: 'AckPrune' } });
+    expect(out.dispatched.filter((d) => d.type === 'SyncOutcome')).toEqual([{ type: 'SyncOutcome', ok: true, error: undefined }, { type: 'SyncOutcome', ok: true, error: undefined }]);
+  });
+
+  it('a rejected statement rolls back only that row; the rest of the batch is acked', async () => {
+    const out = await runPure(drain(env), {
+      state: stateWith([1, 2]),
+      handlers: {
+        'local.query': (e: any) => (e.sql === 'SELECT * FROM $ids' ? [[pendingRow(1), pendingRow(2)]] : []),
+        'remote.query': () => [err('permission denied'), ok()],
+        'local.execute': () => undefined,
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(out.state.outbox.map((i) => [i.id, i.status])).toEqual([['_00_pending_mutations:m2', 'acked']]);
+    expect(out.state.failedCount).toBe(1);
+    expect(out.emitted).toContainEqual(expect.objectContaining({ type: 'mutation:rolled-back', mutationId: '_00_pending_mutations:m1', error: 'permission denied' }));
+    expect(out.dispatched.at(-1)).toEqual({ type: 'SyncOutcome', ok: true, error: undefined });
+  });
+
+  it('transport failures keep the tail queued behind a backoff timer (thrown, or a network ERR mid-batch, or a short result list)', async () => {
+    const thrown = await runPure(drain(env), {
+      state: stateWith([1, 2]),
+      handlers: {
+        'local.query': () => [[pendingRow(1), pendingRow(2)]],
+        'remote.query': () => {
+          throw new Error('socket closed');
+        },
+      },
+    });
+    expect(thrown.state.outbox.map((i) => i.status)).toEqual(['pending', 'pending']);
+    expect(thrown.state.outbox[0].attempts).toBe(1);
+    expect(thrown.timers.get('outbox')).toEqual({ ms: 500, event: { type: 'Drain' } });
+    expect(thrown.dispatched).toEqual([{ type: 'SyncOutcome', ok: false, error: new Error('socket closed') }]);
+    const mid = await runPure(drain(env), {
+      state: stateWith([1, 2]),
+      handlers: { 'local.query': () => [[pendingRow(1), pendingRow(2)]], 'remote.query': () => [ok(), err('connection reset')] },
+    });
+    expect(mid.state.outbox.map((i) => [i.status, i.attempts])).toEqual([['acked', 0], ['pending', 1]]);
+    expect(mid.timers.get('outbox')!.ms).toBe(500);
+    const short = await runPure(drain(env), {
+      state: stateWith([1, 2]),
+      handlers: { 'local.query': () => [[pendingRow(1), pendingRow(2)]], 'remote.query': () => [ok()] },
+    });
+    expect(short.state.outbox.map((i) => i.status)).toEqual(['acked', 'pending']);
+    const undefinedRows = await runPure(drain(env), { state: stateWith([1]), handlers: { 'local.query': () => undefined } });
+    expect(undefinedRows.state.outbox).toEqual([]);
+    const notArray = await runPure(drain(env), {
+      state: stateWith([1]),
+      handlers: { 'local.query': () => [[pendingRow(1)]], 'remote.query': () => 'nope' },
+    });
+    expect(notArray.timers.has('outbox')).toBe(true);
+  });
+
+  it('a request rejected as a whole with an application error rolls back the head and continues', async () => {
+    let calls = 0;
+    const out = await runPure(drain(env), {
+      state: stateWith([1, 2]),
+      handlers: {
+        'local.query': (e: any) => (e.sql === 'SELECT * FROM $ids' ? [e.vars.ids.map((id: RecordId) => pendingRow(Number(String(id.id).slice(1))))] : []),
+        'remote.query': () => {
+          calls++;
+          if (calls === 1) throw 'Parse error at line 1';
+          return [ok()];
+        },
+        'local.execute': () => undefined,
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(calls).toBe(2);
+    expect(out.state.failedCount).toBe(1);
+    expect(out.state.outbox.map((i) => [i.id, i.status])).toEqual([['_00_pending_mutations:m2', 'acked']]);
+    const asError = await runPure(drain(env), {
+      state: stateWith([1]),
+      handlers: {
+        'local.query': () => [[pendingRow(1)]],
+        'remote.query': () => {
+          throw new Error('Parse error at line 1');
+        },
+        'local.execute': (e: any) => {
+          if (e.vars.failed) expect(e.vars.failed.error.message).toBe('Parse error at line 1');
+        },
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(asError.state.failedCount).toBe(1);
+  });
+
+  it('skips pending rows the store no longer has, does nothing as a follower or when empty, tolerates a failed row delete', async () => {
+    const gone = await runPure(drain(env), { state: stateWith([1]), handlers: { 'local.query': () => [[]] } });
+    expect(gone.state.outbox).toEqual([]);
+    expect(gone.log.filter((e) => e.kind === 'remote.query')).toHaveLength(0);
+    const follower = await runPure(drain(env), { state: { ...stateWith([1]), tabRole: 'follower' } });
+    expect(follower.log.filter((e) => e.kind === 'local.query')).toHaveLength(0);
+    const empty = await runPure(drain(env), { state: buildState() });
+    expect(empty.log.filter((e) => e.kind === 'local.query')).toHaveLength(0);
+    const delFail = await runPure(drain(env), {
+      state: stateWith([1]),
+      handlers: {
+        'local.query': (e: any) => {
+          if (e.sql === 'DELETE $mid') throw new Error('locked');
+          return [[pendingRow(1)]];
+        },
+        'remote.query': () => [ok()],
+      },
+    });
+    expect(delFail.state.outbox[0].status).toBe('acked');
+    expect(delFail.emitted).toContainEqual(expect.objectContaining({ level: 'error' }));
+  });
+});
+
+describe('rollback', () => {
+  it('create: tray move first, local delete, circuit DELETE, version dropped, owner relay when leading', async () => {
+    const order: string[] = [];
+    const state = { ...stateWith([1]), tabRole: 'leader' as const, tabId: 'tab-a' };
+    const row = pendingRow(1, 'create', { id: '_00_pending_mutations:1700000000000_0001_tabz' });
+    const out = await runPure(rollback(env, row, { message: 'denied', kind: 'application' }), {
+      state: R.setVersions([['thing:1', 1]])(state),
+      handlers: {
+        'local.execute': (e: any) => void order.push(e.query.sql.includes('_00_failed') || e.query.sql.includes('CREATE ONLY $fid') ? 'tray' : 'revert'),
+        'ssp.ingest': (e: any) => void order.push(`circuit:${e.records[0].op}`),
+      },
+    });
+    expect(order).toEqual(['tray', 'revert', 'circuit:DELETE']);
+    expect(out.state.versions.has('thing:1')).toBe(false);
+    expect(out.state.failedCount).toBe(1);
+    expect(out.state.dirty.has('q')).toBe(true);
+    expect(out.emitted).toContainEqual({ type: 'tabs:sendTo', tabId: 'tabz', message: expect.objectContaining({ type: 'mutation-rolled-back' }) });
+    expect(out.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'ingest', records: [expect.objectContaining({ op: 'DELETE' })] } });
+    expect(out.emitted).toContainEqual({ type: 'tray:changed', count: 1 });
+    expect(out.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'failed-mutations-changed', count: 1 } });
+  });
+  it('update / delete restore beforeRecord and its version; legacy rows read the server row (or end partial)', async () => {
+    const upd = await runPure(rollback(env, pendingRow(1, 'update'), { message: 'x', kind: 'application' }), {
+      state: stateWith([1]),
+      handlers: { 'local.execute': () => undefined, 'ssp.ingest': (e: any) => expect(e.records[0].op).toBe('UPDATE') },
+    });
+    expect(upd.state.versions.get('thing:1')).toBe(7);
+    const del = await runPure(rollback(env, pendingRow(1, 'delete'), { message: 'x', kind: 'application' }), {
+      state: stateWith([1]),
+      handlers: { 'local.execute': () => undefined, 'ssp.ingest': (e: any) => expect(e.records[0].op).toBe('CREATE') },
+    });
+    expect(del.state.versions.get('thing:1')).toBe(7);
+    const legacy = await runPure(rollback(env, pendingRow(1, 'update', { beforeRecord: undefined }), { message: 'x', kind: 'application' }), {
+      state: stateWith([1]),
+      handlers: {
+        'remote.query': () => [ok({ id: new RecordId('thing', '1'), a: 9, _00_rv: 2 })],
+        'local.execute': (e: any) => {
+          if (e.query.sql.includes('CREATE ONLY $fid')) expect(e.vars.failed.revert).toBe('full');
+        },
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(legacy.state.versions.get('thing:1')).toBe(2);
+    const partial = await runPure(rollback(env, pendingRow(1, 'update', { beforeRecord: undefined }), { message: 'x', kind: 'application' }), {
+      state: stateWith([1]),
+      handlers: {
+        'remote.query': () => {
+          throw new Error('offline');
+        },
+        'local.execute': (e: any) => expect(e.vars.failed.revert).toBe('partial'),
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(partial.log.filter((e) => e.kind === 'local.execute')).toHaveLength(1);
+    const errRow = await runPure(rollback(env, pendingRow(1, 'update', { beforeRecord: undefined }), { message: 'x', kind: 'application' }), {
+      state: stateWith([1]),
+      handlers: { 'remote.query': () => [err('nope')], 'local.execute': () => undefined, 'ssp.ingest': () => undefined },
+    });
+    expect(errRow.state.failedCount).toBe(1);
+  });
+  it('every local step is best-effort: tray move, revert and circuit failures are logged', async () => {
+    const out = await runPure(rollback(env, pendingRow(1, 'update'), { message: 'x', kind: 'unreplayable' }), {
+      state: stateWith([1]),
+      handlers: {
+        'local.execute': () => {
+          throw new Error('disk');
+        },
+        'ssp.ingest': () => {
+          throw new Error('wasm');
+        },
+      },
+    });
+    expect(out.emitted.filter((e) => e.type === 'log')).toHaveLength(3);
+    expect(out.state.outbox).toEqual([]);
+  });
+});
+
+describe('loadOutbox / refreshFailedCount', () => {
+  it('mirrors pending rows, sends unreplayable ones to the tray, refreshes the count, starts a drain', async () => {
+    const out = await runPure(loadOutbox(env), {
+      state: buildState(),
+      handlers: {
+        'local.query': (e: any) => {
+          if (e.sql.startsWith('SELECT * FROM _00_pending_mutations'))
+            return [[pendingRow(1), { id: '_00_pending_mutations:bad', mutationType: 'create', recordId: 'thing:9' }, { tableName: 'thing' }, { mutationType: 'delete' }, 'junk']];
+          if (e.sql.startsWith('SELECT count()')) return [[{ count: 4 }]];
+          return [];
+        },
+        'local.execute': () => undefined,
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(out.state.outbox.map((i) => i.id)).toEqual(['_00_pending_mutations:m1']);
+    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' }]);
+    const empty = await runPure(loadOutbox(env), { state: buildState(), handlers: { 'local.query': () => [] } });
+    expect(empty.dispatched).toEqual([]);
+    const missingTable = await runPure(refreshFailedCount(), {
+      state: R.setFailedCount(2)(buildState()),
+      handlers: {
+        'local.query': () => {
+          throw new Error('no table');
+        },
+      },
+    });
+    expect(missingTable.state.failedCount).toBe(2);
+    const noRows = await runPure(refreshFailedCount(), { state: R.setFailedCount(2)(buildState()), handlers: { 'local.query': () => [[]] } });
+    expect(noRows.state.failedCount).toBe(0);
+  });
+});