@spooky-sync/core 0.0.1-canary.38 → 0.0.1-canary.381

package/src/mutation/rows.ts

@@ -0,0 +1,515 @@
+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';
+/** 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). */
+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.name}:${String(id.id)}`;
+  const rid = parseStoredRecordId(String(id));
+  return `${rid.table.name}:${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;
+  }
+}
+
+/**
+ * A row read back from the store at boot, bucket switch or leader takeover.
+ * The session that queued it may have sent it and died before the answer (a
+ * closed tab, a killed app, a lost leader), so its outcome is in doubt.
+ */
+export const toOutboxItem = (row: PendingMutationRow): OutboxItem => ({
+  id: row.id,
+  type: row.mutationType,
+  recordId: row.recordId,
+  table: row.tableName,
+  status: 'pending',
+  ackedAt: null,
+  attempts: 0,
+  inDoubt: true,
+});
+
+/**
+ * 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 ------------------------------------------------
+
+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,
+    },
+  };
+}
+
+/**
+ * A channel peer's create: the row alone, no outbox entry (the peer's own
+ * client pushes it). Result index 0 is the row.
+ */
+export function planPeerCreateTx(input: { recordId: RecordId<string>; data: Record<string, unknown> }): LocalTx {
+  const keys = Object.keys(input.data).map((key) => ({ key, variable: `data_${key}` }));
+  const vars: Vars = { id: input.recordId };
+  for (const { key, variable } of keys) vars[variable] = input.data[key];
+  return { query: surql.seal<unknown>(surql.tx([surql.createSet('id', keys)]), { resultIndex: 0 }), vars };
+}
+
+/** Undo a peer's create the server never confirmed: the row alone, no outbox entry. */
+export function planPeerUndoTx(recordId: RecordId<string>): LocalTx {
+  return { query: surql.seal<unknown>(surql.tx([surql.delete('id')])), vars: { id: recordId } };
+}
+
+/**
+ * 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(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. 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(statements)),
+    vars: {
+      id: input.recordId,
+      mid: input.mutationId,
+      table: input.table,
+      createdAt: input.now,
+      data: input.data ?? {},
+      before: input.before ?? null,
+      ...(input.mirrorId ? { wid: input.mirrorId } : {}),
+    },
+  };
+}
+
+// ---- remote push -------------------------------------------------------------
+
+export interface RemoteBatch {
+  sql: string;
+  vars: Vars;
+}
+
+/**
+ * What a statement of a `remoteBatch` throws instead of running, because an
+ * earlier statement in the same request failed.
+ */
+export const BATCH_SKIPPED = 'sp00ky: not run, an earlier statement in this batch failed';
+
+/** A CRDT edit-log row (`<table>__crdt_log`): written once under a fresh id, never changed. */
+const isLogTable = (table: string): boolean => table.endsWith('__crdt_log');
+
+/**
+ * Which fields of the row already on the server must equal the payload of the
+ * CREATE at `i` for that row to count as this CREATE's own earlier commit, or
+ * `null` when the CREATE must not tolerate an existing row at all.
+ *
+ * Only a CREATE whose outcome is in doubt tolerates one: elsewhere "already
+ * exists" means someone else holds the id, a rejection as before. The check
+ * is every payload field except those a later in-doubt row of the same
+ * record, which may have committed in the same lost round, could have changed
+ * since; those rows run again after it and set them anyway. A later in-doubt
+ * DELETE or CREATE of the record may have replaced the row, so then existence
+ * is all that is checked. Rows that are not in doubt never ran.
+ *
+ * A CRDT log row's id is fresh and the row immutable, so its existence is
+ * proof enough, in doubt or not.
+ */
+function matchFields(rows: ReadonlyArray<PendingMutationRow>, i: number, inDoubt: ReadonlySet<string>): string[] | null {
+  const row = rows[i];
+  if (isLogTable(row.tableName)) return [];
+  if (!inDoubt.has(row.id)) return null;
+  const changed = new Set<string>();
+  for (const later of rows.slice(i + 1)) {
+    if (later.recordId !== row.recordId || !inDoubt.has(later.id)) continue;
+    if (later.mutationType !== 'update') return [];
+    for (const key of Object.keys(later.data ?? {})) changed.add(key);
+  }
+  return Object.keys(row.data ?? {}).filter((key) => !changed.has(key));
+}
+
+function remoteStatement(rows: ReadonlyArray<PendingMutationRow>, i: number, vars: Vars, inDoubt: ReadonlySet<string>): string {
+  const row = rows[i];
+  vars[`id${i}`] = parseRecordIdString(row.recordId);
+  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}`;
+      });
+      const create = `CREATE ONLY $id${i} SET ${sets.join(', ')}`;
+      const match = matchFields(rows, i, inDoubt);
+      if (!match) return create;
+      // The CREATE runs unless the row is there and matches; on a mismatch it
+      // fails with SurrealDB's own "already exists", a rejection as before.
+      const differs = [`($was${i} = NONE)`, ...match.map((key) => `($was${i}.${key} != $d${i}_${key})`)];
+      return `LET $was${i} = (SELECT * FROM ONLY $id${i}); IF ${differs.join(' OR ')} { ${create} }`;
+    }
+    case 'update':
+      vars[`data${i}`] = row.data ?? {};
+      return `UPDATE $id${i} MERGE $data${i}`;
+    case 'delete':
+      return `DELETE $id${i}`;
+  }
+}
+
+/**
+ * Many outbox rows as ONE multi-statement request. Statement i answers row i
+ * and is its own transaction on the server, as before, but the statements are
+ * chained: statement i binds `$ok<i>` only when it commits, and statement i+1
+ * throws `BATCH_SKIPPED` without touching anything unless `$ok<i>` is bound
+ * (a LET lives for one request only). So the server stops at the first
+ * failure: everything before it is committed, nothing after it ran.
+ *
+ * Without the chain, statements after a failed one ran anyway. A retryable
+ * failure at i left the rows after i queued although they had committed; the
+ * re-sent CREATE then read "already exists", was taken for a rejection and
+ * rolled back locally while the server kept the row. Acking them instead
+ * would have let a later write land before an earlier one it may depend on.
+ *
+ * The chain cannot help when the answer itself is lost: the request may have
+ * committed any prefix of the batch. Rows named in `inDoubt` (mutation ids)
+ * are such rows. An UPDATE MERGE or a DELETE is safe to run twice, a CREATE
+ * is not, so an in-doubt CREATE checks the row already there first (see
+ * `matchFields`) and is a no-op when it is its own: the batch goes on in
+ * order, with no "already exists" to cut it.
+ */
+export function remoteBatch(rows: ReadonlyArray<PendingMutationRow>, inDoubt: ReadonlySet<string> = new Set()): RemoteBatch {
+  const vars: Vars = {};
+  const stmts = rows.map((_, i) => {
+    const guard = i === 0 ? '' : `IF !$ok${i - 1} { THROW "${BATCH_SKIPPED}" }; `;
+    return `LET $ok${i} = { ${guard}${remoteStatement(rows, i, vars, inDoubt)}; true }`;
+  });
+  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;
+}