@spooky-sync/core 0.0.1-canary.283 → 0.0.1-canary.287

package/src/services/database/landed-body-clear.integration.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import { RecordId, Surreal } from 'surrealdb';
+import { landChunk } from '../../query/fetch.saga';
+import { defaultEnv } from '../../query/env';
+import { runPure } from '../../testing/run-pure';
+import { buildState } from '../../testing/build';
+import type { Vars } from '../../kernel/effects';
+import type { SealedQuery } from '../../utils/surql';
+import { SqliteCacheEngine } from './sqlite-cache-engine';
+import { stubTransport } from './sqlite-transport.fixture';
+import type { Row } from './cache-engine';
+
+/**
+ * Integration: a field cleared on the server (`UPDATE broadcast:x UNSET club`)
+ * is ABSENT from the body the server returns, and the body is landed with
+ * MERGE, which keeps every key it does not name. These land real bodies
+ * through `landChunk` and run the exact transaction it emits on BOTH local
+ * engines: a real in-memory SQLite (the worker's @sqlite.org/sqlite-wasm
+ * build) behind the SqliteCacheEngine, and a real SurrealDB-WASM `mem://`
+ * store provisioned with a typed schema, as the local migrator does.
+ *
+ * On each: the cleared optional field is gone, local `_00_*` bookkeeping
+ * survives (still a MERGE, not a REPLACE), and a required field the body
+ * lacks is kept rather than cleared.
+ */
+
+const env = defaultEnv({
+  tables: [
+    {
+      name: 'broadcast',
+      columns: {
+        title: { type: 'string', optional: false },
+        secret: { type: 'string', optional: false },
+        club: { type: 'string', recordId: true, optional: true },
+        note: { type: 'string', optional: true },
+      },
+    },
+  ],
+} as any);
+
+type Exec = (query: SealedQuery<unknown>, vars: Vars) => Promise<unknown>;
+
+/** Land `rows` at `version` through the real saga, executing its write with `exec`. */
+async function land(
+  exec: Exec,
+  rows: Array<Record<string, unknown>>,
+  version: number
+): Promise<void> {
+  const ids = rows.map((r) => String(r.id));
+  const out = await runPure(
+    landChunk(env, ids, rows, new Map(ids.map((id) => [id, version] as const)), buildState(), 0),
+    {
+      handlers: {
+        'local.execute': (e: any) => exec(e.query, e.vars),
+        'ssp.ingest': () => undefined,
+      },
+    }
+  );
+  expect(out.emitted).not.toContainEqual(expect.objectContaining({ message: 'body write failed' }));
+  expect(out.result).toBe(true);
+}
+
+const x = new RecordId('broadcast', 'x');
+const fresh = new RecordId('broadcast', 'fresh');
+const club = new RecordId('club', 'c1');
+
+const noop = () => {};
+
+// ==================== SQLite ====================
+
+describe('landed body clears an absent optional field: SQLite engine', () => {
+  let db: any;
+
+  function realEngine(): SqliteCacheEngine {
+    const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+    logger.child = () => logger;
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, logger);
+    stubTransport(engine, (type, payload: any) => {
+      switch (type) {
+        case 'open':
+          return { persisted: true };
+        case 'exec':
+          return {
+            rows: db.exec({
+              sql: payload.sql,
+              bind: payload.bind,
+              rowMode: 'object',
+              returnValue: 'resultRows',
+            }),
+          };
+        case 'run':
+          db.exec({ sql: payload.sql, bind: payload.bind });
+          return {};
+        case 'batch':
+          for (const stmt of payload as { sql: string; bind?: unknown[] }[])
+            db.exec({ sql: stmt.sql, bind: stmt.bind });
+          return {};
+        default:
+          return {};
+      }
+    });
+    return engine;
+  }
+
+  beforeAll(async () => {
+    const sqlite3: any = await sqlite3InitModule();
+    db = new sqlite3.oo1.DB(':memory:', 'c');
+  });
+
+  afterAll(() => db?.close());
+
+  it('removes the cleared key on the batched fast path, keeps _00_* and required fields', async () => {
+    const engine = realEngine();
+    await engine.connect('anon');
+    const exec: Exec = (q, v) => engine.execute(q, v);
+
+    await land(exec, [{ id: x, title: 't1', secret: 's', club, note: 'n' }], 1);
+    await engine.upsert('broadcast', x, { _00_local: 'keep' }, 'merge');
+    const before = (await engine.getById('broadcast', x)) as Row;
+    expect(before.club).toBeDefined();
+
+    // The server unset `club`; `secret` is hidden from this reader (required,
+    // so its absence is not a clear).
+    await land(exec, [{ id: x, title: 't2', note: 'n' }], 2);
+    const after = (await engine.getById('broadcast', x)) as Row;
+    expect('club' in after).toBe(false);
+    expect(after).toMatchObject({
+      id: 'broadcast:x',
+      title: 't2',
+      note: 'n',
+      secret: 's',
+      _00_local: 'keep',
+      _00_rv: 2,
+    });
+
+    // A fresh row stores no placeholder for the cleared key.
+    await land(exec, [{ id: fresh, title: 'f', secret: 's' }], 1);
+    const inserted = (await engine.getById('broadcast', fresh)) as Row;
+    expect(Object.keys(inserted).toSorted()).toEqual(['_00_rv', 'id', 'secret', 'title']);
+  });
+
+  it('removes the cleared key on the single-statement merge path too', async () => {
+    const engine = realEngine();
+    await engine.connect('anon');
+
+    const y = new RecordId('broadcast', 'y');
+    await engine.query('UPSERT ONLY $id MERGE $c', {
+      id: y,
+      c: { club, note: 'n2', _00_local: 'keep' },
+    });
+    expect((await engine.getById('broadcast', y))?.club).toBeDefined();
+    await engine.query('UPSERT ONLY $id MERGE $c', { id: y, c: { club: undefined, note: 'n3' } });
+    const row = (await engine.getById('broadcast', y)) as Row;
+    expect('club' in row).toBe(false);
+    expect(row.note).toBe('n3');
+    expect(row._00_local).toBe('keep');
+  });
+});
+
+// ==================== SurrealDB-WASM ====================
+
+describe('landed body clears an absent optional field: SurrealDB-WASM engine', () => {
+  let db: Surreal;
+
+  beforeAll(async () => {
+    // The wasm engine loads its binary with `fetch(new URL(..., import.meta.url))`,
+    // and Node's fetch has no `file:` scheme: serve that one read from disk.
+    const realFetch = globalThis.fetch;
+    vi.stubGlobal('fetch', async (input: unknown, init?: RequestInit) => {
+      const url = input instanceof URL ? input : new URL(String(input));
+      if (url.protocol === 'file:') return new Response(await readFile(fileURLToPath(url)));
+      return realFetch(input as RequestInfo, init);
+    });
+    const { createWasmEngines } = await import('@surrealdb/wasm');
+    db = new Surreal({ engines: createWasmEngines() });
+    await db.connect('mem://');
+    await db.use({ namespace: 'n', database: 'd' });
+    await db.query(`
+      DEFINE TABLE club SCHEMAFULL;
+      DEFINE TABLE broadcast SCHEMAFULL;
+      DEFINE FIELD title ON broadcast TYPE string;
+      DEFINE FIELD secret ON broadcast TYPE string;
+      DEFINE FIELD club ON broadcast TYPE option<record<club>>;
+      DEFINE FIELD note ON broadcast TYPE option<string>;
+      DEFINE FIELD _00_rv ON broadcast TYPE option<int>;
+      DEFINE FIELD _00_local ON broadcast TYPE option<string>;
+    `);
+  }, 60_000);
+
+  afterAll(async () => {
+    await db?.close();
+    vi.unstubAllGlobals();
+  });
+
+  const exec: Exec = (q, v) => db.query(q.sql, v) as unknown as Promise<unknown>;
+  const read = async (id: RecordId<string>): Promise<Record<string, unknown>> => {
+    const [row] = (await db.query('SELECT * FROM ONLY $id', { id })) as [Record<string, unknown>];
+    return row;
+  };
+
+  it('the undefined clear reaches SurrealDB as NONE and the MERGE removes the field', async () => {
+    await land(exec, [{ id: x, title: 't1', secret: 's', club, note: 'n' }], 1);
+    await db.query("UPDATE $id SET _00_local = 'keep'", { id: x });
+    expect(String((await read(x)).club)).toBe('club:c1');
+
+    // Would fail the whole transaction if the clear were NULL (a coercion error
+    // on `option<record<club>>`) or named the required `secret` as NONE.
+    await land(exec, [{ id: x, title: 't2', note: 'n' }], 2);
+    const after = await read(x);
+    expect('club' in after).toBe(false);
+    expect(after).toMatchObject({
+      title: 't2',
+      note: 'n',
+      secret: 's',
+      _00_local: 'keep',
+      _00_rv: 2,
+    });
+
+    await land(exec, [{ id: fresh, title: 'f', secret: 's' }], 1);
+    expect(Object.keys(await read(fresh)).toSorted()).toEqual(['_00_rv', 'id', 'secret', 'title']);
+  });
+
+  it('why the clear is NONE on optional columns only: NULL and a required NONE both fail', async () => {
+    const z = new RecordId('broadcast', 'z');
+    await db.query('CREATE $id CONTENT $c', { id: z, c: { title: 't', secret: 's', club } });
+    await expect(
+      db.query('UPSERT ONLY $id MERGE $c', { id: z, c: { club: null } })
+    ).rejects.toThrow(/club/);
+    await expect(
+      db.query('UPSERT ONLY $id MERGE $c', { id: z, c: { secret: undefined } })
+    ).rejects.toThrow(/secret/);
+  });
+});

package/src/services/database/sqlite-cache-engine.ts

@@ -6,6 +6,7 @@ import {
   renderOrderSql,
   renderWhereSql,
   reviveRow,
+  serializeMergeRow,
   serializeRow,
   project,
   projectedDataSql,
@@ -947,11 +948,12 @@ export class SqliteCacheEngine implements LocalStore {
     if (mode === 'merge') {
       // Merge in-SQL via json_patch (RFC7396 = MERGE semantics): on insert store
       // the row, on conflict shallow-merge. Serialize once, reuse for VALUES and
-      // the patch. No read-modify-write round-trip. (RFC7396: null deletes key.)
-      const full = serializeRow({ ...data, id: key });
+      // the patch. No read-modify-write round-trip. (RFC7396: null deletes key,
+      // which is how a key holding `undefined` clears the stored field.)
+      const { insert, patch } = serializeMergeRow({ ...data, id: key });
       await this.call('run', {
         sql: `INSERT INTO "${table}"(id, data) VALUES(?, ?) ON CONFLICT(id) DO UPDATE SET data = json_patch(data, ?)`,
-        bind: [key, full, full],
+        bind: [key, insert, patch],
       });
       return;
     }
@@ -1191,10 +1193,12 @@ export class SqliteCacheEngine implements LocalStore {
           // Serialize ONCE and reuse for both VALUES (fresh insert) and the
           // json_patch (merge). Patching with `id` is a harmless no-op set, so
           // the full row doubles as the delta — halves per-row stringify cost.
-          const full = serializeRow({ ...op.data, id: key });
+          // A key holding `undefined` (a field cleared upstream) rides in the
+          // delta as a `null` member, which json_patch removes.
+          const { insert, patch } = serializeMergeRow({ ...op.data, id: key });
           stmts.push({
             sql: `INSERT INTO "${t}"(id, data) VALUES(?, ?) ON CONFLICT(id) DO UPDATE SET data = json_patch(data, ?)`,
-            bind: [key, full, full],
+            bind: [key, insert, patch],
           });
         } else {
           stmts.push({

package/src/services/database/sqlite-plan-sql.test.ts

@@ -6,6 +6,7 @@ import {
   renderOrderSql,
   scalar,
   serializeRow,
+  serializeMergeRow,
   reviveRow,
   project,
 } from './sqlite-plan-sql';
@@ -102,3 +103,37 @@ describe('project', () => {
     expect(project({ id: 'a', x: 1, y: 2 }, ['x', 'missing'])).toEqual({ id: 'a', x: 1 });
   });
 });
+
+describe('serializeMergeRow', () => {
+  it('reuses one string for insert and patch when nothing is cleared', () => {
+    const row = { id: 't:1', a: 1, b: null };
+    const { insert, patch } = serializeMergeRow(row);
+    expect(insert).toBe(serializeRow(row));
+    expect(patch).toBe(insert);
+  });
+
+  // json_patch (RFC 7396) removes a member whose patch value is null; JSON drops
+  // an undefined one, which is how a cleared field used to survive the MERGE.
+  it('carries a top-level undefined as a null member in the patch only', () => {
+    const { insert, patch } = serializeMergeRow({ id: 't:1', a: 1, club: undefined, 'we"ird': undefined });
+    expect(JSON.parse(insert)).toStrictEqual({ id: 't:1', a: 1 });
+    expect(JSON.parse(patch)).toStrictEqual({ id: 't:1', a: 1, club: null, 'we"ird': null });
+  });
+
+  it('handles a row with nothing but cleared keys', () => {
+    const { insert, patch } = serializeMergeRow({ club: undefined });
+    expect(insert).toBe('{}');
+    expect(JSON.parse(patch)).toStrictEqual({ club: null });
+  });
+
+  it('leaves nested undefined dropped (only top-level keys clear)', () => {
+    const { patch } = serializeMergeRow({ id: 't:1', meta: { x: undefined, y: 1 } });
+    expect(JSON.parse(patch)).toStrictEqual({ id: 't:1', meta: { y: 1 } });
+  });
+
+  it('does not append to a root the replacer collapsed to a scalar', () => {
+    const { insert, patch } = serializeMergeRow({ tb: 'user', id: 'u1', gone: undefined });
+    expect(insert).toBe('"user:u1"');
+    expect(patch).toBe(insert);
+  });
+});

package/src/services/database/sqlite-plan-sql.ts

@@ -70,6 +70,32 @@ export function serializeRow(row: Row): string {
   });
 }
 
+/**
+ * Serialize a MERGE row ONCE for both halves of the merge upsert: the row a
+ * fresh INSERT stores and the RFC 7396 delta `json_patch` applies on conflict.
+ *
+ * A top-level own key holding `undefined` means "clear this field", which is
+ * what SurrealDB's MERGE does with it (the SDK sends it as NONE). JSON drops
+ * such a key, so a patch built by {@link serializeRow} alone never mentioned
+ * it and the stored value survived every merge: a field cleared on the server
+ * stayed set locally. The patch therefore carries each one as a `null` member,
+ * which `json_patch` removes; the insert row simply lacks it, exactly as
+ * before. Appended to the already-serialized text, so the common case costs no
+ * second stringify. Nested `undefined` stays dropped (never a clear here).
+ */
+export function serializeMergeRow(row: Row): { insert: string; patch: string } {
+  const insert = serializeRow(row);
+  const cleared: string[] = [];
+  for (const key of Object.keys(row)) {
+    if (row[key] === undefined) cleared.push(`${JSON.stringify(key)}:null`);
+  }
+  // Not an object text (the replacer collapsed the root): nothing to append to.
+  if (cleared.length === 0 || insert[0] !== '{') return { insert, patch: insert };
+  const members = cleared.join(',');
+  const patch = insert === '{}' ? `{${members}}` : `${insert.slice(0, -1)},${members}}`;
+  return { insert, patch };
+}
+
 export function reviveRow(json: string): Row {
   // Fast path: the per-key reviver is only needed to rebuild `Uint8Array`s from
   // `{__u8}` tags. Most rows (e.g. game bodies) have none — a plain parse avoids

package/src/state/client-state.ts

@@ -126,6 +126,12 @@ export interface ClientState {
   readonly membershipReread: ReadonlyMap<QueryHash, number>;
   /** Local body versions (`_00_rv`) by encoded record id. */
   readonly versions: ReadonlyMap<string, number>;
+  /**
+   * What each durable `_00_view` row vouches for, by view key: its members
+   * and subquery children. A body no row names is an orphan: it never paints
+   * before the server answers and the GC deletes it.
+   */
+  readonly views: ReadonlyMap<string, ReadonlyArray<string>>;
   readonly outbox: ReadonlyArray<OutboxItem>;
   readonly pendingWrites: ReadonlyMap<string, PendingWrite>;
   readonly failedCount: number;
@@ -169,6 +175,7 @@ export function emptyState(init: { tabId: string }): ClientState {
     registering: new Set(),
     membershipReread: new Map(),
     versions: new Map(),
+    views: new Map(),
     outbox: [],
     pendingWrites: new Map(),
     failedCount: 0,

package/src/state/reducers.test.ts

@@ -281,3 +281,22 @@ describe('identity / connection / compose', () => {
     expect(s6.failedCount).toBe(3);
   });
 });
+
+describe('durable view index', () => {
+  it('commit and children keep a view key in step with its `_00_view` row; cold children are not indexed', () => {
+    let s = buildState([e('a', { def: { viewKey: 'va' }, lifecycle: { phase: 'cold' }, subqueryRemoteArray: [['c:1', 1]] })]);
+    s = R.setSubqueryRemoteArray('a', [['c:1', 1], ['c:2', 1]])(s);
+    expect(s.views.size).toBe(0);
+    s = R.commitMembership('a', [['t:1', 1], ['c:1', 1]], true)(s);
+    expect(s.views.get('va')).toEqual(['t:1', 'c:1', 'c:2']);
+    s = R.setSubqueryRemoteArray('a', [['c:3', 1]])(s);
+    expect(s.views.get('va')).toEqual(['t:1', 'c:1', 'c:3']);
+    expect(R.setSubqueryRemoteArray('zz', [['c:9', 1]])(s)).toBe(s);
+    expect(R.clearBucketState()(s).views.size).toBe(0);
+  });
+  it('a reload takes the store, except entries of queries in state', () => {
+    const s = R.compose(R.commitMembership('a', [['t:new', 1]], true))(buildState([e('a', { def: { viewKey: 'va' } }), e('b', { def: { viewKey: 'vb' } })]));
+    const reloaded = R.reloadViews(new Map([['va', ['t:old']], ['vb', ['t:b']], ['vc', ['t:c']]]))(s);
+    expect(reloaded.views).toEqual(new Map([['va', ['t:new']], ['vb', ['t:b']], ['vc', ['t:c']]]));
+  });
+});

package/src/state/reducers.ts

@@ -90,6 +90,33 @@ export const setServerState =
  * set names: membership has caught up with the write, the overlay's job is
  * done (invariant I7).
  */
+/** What a `_00_view` row holding these arrays vouches for. */
+const vouchedIds = (members: RecordVersionArray, children: RecordVersionArray): string[] => [
+  ...new Set([...members.map(([id]) => id), ...children.map(([id]) => id)]),
+];
+
+const withView = (s: ClientState, viewKey: string, ids: ReadonlyArray<string>): ClientState => {
+  const views = new Map(s.views);
+  views.set(viewKey, ids);
+  return { ...s, views };
+};
+
+/**
+ * Replace the durable view index with a fresh `_00_view` read (boot, bucket
+ * switch, GC). An entry of a query in state is kept: its commits update the
+ * index as they write the row, so it is never older than the read.
+ */
+export const reloadViews =
+  (fromStore: ReadonlyMap<string, ReadonlyArray<string>>): Reducer =>
+  (s) => {
+    const views = new Map(fromStore);
+    for (const e of s.queries.values()) {
+      const held = s.views.get(e.def.viewKey);
+      if (held) views.set(e.def.viewKey, held);
+    }
+    return { ...s, views };
+  };
+
 export const commitMembership =
   (hash: QueryHash, remoteArray: RecordVersionArray, present: boolean): Reducer =>
   (s) => {
@@ -99,9 +126,11 @@ export const commitMembership =
       lifecycle: transition(e.lifecycle, { type: 'membership-applied', present }),
     }));
     if (withArray === s) return s;
+    const entry = withArray.queries.get(hash)!;
     const named = new Set(remoteArray.map(([id]) => id));
     const outbox = withArray.outbox.filter((item) => !(item.status === 'acked' && named.has(item.recordId)));
-    return { ...withArray, outbox, dirty: addAll(withArray.dirty, [hash]) };
+    const indexed = withView(withArray, entry.def.viewKey, vouchedIds(remoteArray, entry.subqueryRemoteArray));
+    return { ...indexed, outbox, dirty: addAll(withArray.dirty, [hash]) };
   };
 
 export const setLocalArray =
@@ -111,10 +140,18 @@ export const setLocalArray =
     return next === s ? s : { ...next, dirty: addAll(next.dirty, [hash]) };
   };
 
+/**
+ * Replace a query's subquery child set. A query past `cold` has a `_00_view`
+ * row, which records the children too (see `applySubqueryChildren`).
+ */
 export const setSubqueryRemoteArray =
   (hash: QueryHash, subqueryRemoteArray: RecordVersionArray): Reducer =>
-  (s) =>
-    withEntry(s, hash, (e) => ({ ...e, subqueryRemoteArray }));
+  (s) => {
+    const next = withEntry(s, hash, (e) => ({ ...e, subqueryRemoteArray }));
+    const entry = next.queries.get(hash);
+    if (!entry || entry.lifecycle.phase === 'cold') return next;
+    return withView(next, entry.def.viewKey, vouchedIds(entry.remoteArray, subqueryRemoteArray));
+  };
 
 export const setRecords =
   (hash: QueryHash, records: ReadonlyArray<Row>, changed: boolean, materializeMs: number | null): Reducer =>
@@ -441,6 +478,7 @@ export const rebindQuery =
 export const clearBucketState = (): Reducer => (s) => ({
   ...s,
   versions: new Map(),
+  views: new Map(),
   outbox: [],
   pendingWrites: new Map(),
   dirty: new Set(),

package/src/state/selectors.test.ts

@@ -147,3 +147,21 @@ describe('phaseTimings', () => {
     expect(t.registration.parseMs).toBeNull();
   });
 });
+
+describe('view index selectors', () => {
+  it('vouched is the union of every view row, memoized on the index', () => {
+    const s = R.reloadViews(new Map([['v1', ['t:1', 't:2']], ['v2', ['t:2', 'c:1']]]))(buildState());
+    expect([...S.vouched(s)]).toEqual(['t:1', 't:2', 'c:1']);
+    expect(S.vouched({ ...s, dirty: new Set(['x']) })).toBe(S.vouched(s));
+  });
+  it('retained: vouched, held in memory (members, children), in the outbox or a debounced write, or bookkeeping', () => {
+    const s = R.compose(
+      R.reloadViews(new Map([['v', ['t:vouched']]])),
+      R.outboxReplace([buildOutboxItem({ recordId: 't:outbox' })]),
+      (st) => ({ ...st, pendingWrites: new Map([['k', { key: 'k', table: 't', recordId: 't:debounced', data: {}, before: null, firstAt: 0 }]]) })
+    )(buildState([e('a', { remoteArray: [['t:member', 1]], subqueryRemoteArray: [['t:child', 1]] })]));
+    const keep = S.retained(s);
+    for (const id of ['t:vouched', 't:member', 't:child', 't:outbox', 't:debounced', '_00_view:x']) expect(keep(id)).toBe(true);
+    expect(keep('t:orphan')).toBe(false);
+  });
+});

package/src/state/selectors.ts

@@ -35,6 +35,38 @@ export function overlay(s: ClientState): Overlay {
   return { writes, deletes };
 }
 
+const vouchedCache = new WeakMap<ClientState['views'], ReadonlySet<string>>();
+
+/**
+ * Every id some durable `_00_view` row vouches for. Memoized on the index,
+ * which only changes when a view row does.
+ */
+export function vouched(s: ClientState): ReadonlySet<string> {
+  const hit = vouchedCache.get(s.views);
+  if (hit) return hit;
+  const out = new Set<string>();
+  for (const ids of s.views.values()) for (const id of ids) out.add(id);
+  vouchedCache.set(s.views, out);
+  return out;
+}
+
+/**
+ * Bodies the GC must keep: `_00_` bookkeeping, anything a durable view
+ * vouches for, anything a query in memory names (members or children), and
+ * anything a write is still in flight for.
+ */
+export function retained(s: ClientState): (id: string) => boolean {
+  const held = new Set<string>();
+  for (const e of s.queries.values()) {
+    for (const [id] of e.remoteArray) held.add(id);
+    for (const [id] of e.subqueryRemoteArray) held.add(id);
+  }
+  for (const item of s.outbox) held.add(item.recordId);
+  for (const write of s.pendingWrites.values()) held.add(write.recordId);
+  const known = vouched(s);
+  return (id) => id.startsWith('_00_') || known.has(id) || held.has(id);
+}
+
 export const pendingDeleteIds = (s: ClientState): ReadonlySet<string> =>
   new Set(s.outbox.filter((i) => i.type === 'delete').map((i) => i.recordId));
 

package/src/sync/tabs.saga.test.ts

@@ -43,6 +43,10 @@ describe('tabMessage', () => {
     expect(out.state.versions.get('other:1')).toBe(0);
     expect(out.state.versions.has('thing:1')).toBe(false);
     expect(out.state.dirty.has('a')).toBe(true);
+    // A relayed delete (another tab's GC) may drop a body this tab names: the fetch plan decides.
+    expect(out.dispatched).toEqual([{ type: 'FetchRows' }]);
+    const writesOnly = await runPure(tabMessage(env, { ...msg, records: msg.records.filter((r) => r.op !== 'DELETE') }), { state: s(), handlers: { 'ssp.ingest': () => undefined } });
+    expect(writesOnly.dispatched).toEqual([]);
     const failing = await runPure(tabMessage(env, msg), {
       state: s(),
       handlers: {

package/src/sync/tabs.saga.ts

@@ -60,6 +60,9 @@ export function* tabMessage(env: SagaEnv, raw: unknown): Saga<void> {
           ...[...new Set(msg.records.map((r) => r.table))].map((t) => R.markTableDirty(t))
         )
       );
+      // A body another tab deleted (its orphan GC) may still be one this tab
+      // names: with the version gone, the fetch plan pulls it back.
+      if (msg.records.some((r) => r.op === 'DELETE')) yield fx.dispatch({ type: 'FetchRows' });
       return;
     }
     case 'membership-dirty':

package/src/utils/parser.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { RecordId } from '@spooky-sync/query-builder';
-import { parseParams, parseQueryParams } from './parser';
+import { absentOptionalColumns, parseParams, parseQueryParams } from './parser';
 
 const columns = {
   white: { recordId: true },
@@ -52,3 +52,39 @@ describe('parseParams', () => {
     expect(parsed).toEqual({ result: '1-0' });
   });
 });
+
+describe('absentOptionalColumns', () => {
+  const schema = {
+    title: { type: 'string', optional: false },
+    club: { type: 'string', recordId: true, optional: true },
+    note: { type: 'string', optional: true },
+    _00_local: { type: 'string', optional: true },
+    id: { type: 'string', optional: true },
+  } as any;
+
+  // The bug: `UPDATE broadcast:x UNSET club` leaves no `club` key in the body,
+  // and a MERGE that does not name it keeps the stale local value.
+  it('names every optional column the row lacks, as undefined', () => {
+    const cleared = absentOptionalColumns(schema, { id: 'broadcast:x', title: 't', note: 'n' });
+    expect(cleared).toStrictEqual({ club: undefined });
+    expect(Object.prototype.hasOwnProperty.call(cleared, 'club')).toBe(true);
+  });
+
+  it('treats an explicit undefined (a decoded NONE) as absent', () => {
+    expect(absentOptionalColumns(schema, { title: 't', club: undefined, note: 'n' })).toStrictEqual(
+      { club: undefined }
+    );
+  });
+
+  it('never names a required column, id, or _00_* bookkeeping', () => {
+    expect(absentOptionalColumns(schema, {})).toStrictEqual({ club: undefined, note: undefined });
+  });
+
+  it('keeps a present value, even a falsy one', () => {
+    expect(absentOptionalColumns(schema, { club: null, note: '' })).toStrictEqual({});
+  });
+
+  it('is empty without a schema', () => {
+    expect(absentOptionalColumns(undefined, { a: 1 })).toStrictEqual({});
+  });
+});

package/src/utils/parser.ts

@@ -16,6 +16,38 @@ export function cleanRecord(
   return cleaned;
 }
 
+/**
+ * The OPTIONAL schema columns a full server row does not carry, each mapped to
+ * `undefined`, for spreading into a body that is landed with MERGE.
+ *
+ * The server omits an optional field that is unset (`UPDATE t UNSET club`
+ * leaves no `club` key in `SELECT *` or the SSP body), and MERGE keeps every
+ * key the patch does not mention, so without this the local store held on to
+ * a cleared value forever. `undefined` is the one representation both engines
+ * read as "remove": the SurrealDB SDK encodes it as NONE, which MERGE removes
+ * (NULL would be a type error on an `option<record<...>>` field), and the
+ * SQLite engine turns it into the `null` member that `json_patch` removes (see
+ * `serializeMergeRow`).
+ *
+ * Required columns are left alone. A SCHEMAFULL server cannot hold NONE in
+ * one, so its absence means the row was not readable in full (a field
+ * permission), not that it was cleared, and NONE in a typed local store is a
+ * coercion error that would fail the whole chunk's transaction. `id` and the
+ * local-only `_00_*` bookkeeping are never touched.
+ */
+export function absentOptionalColumns(
+  tableSchema: Record<string, ColumnSchema> | undefined,
+  record: Record<string, unknown>
+): Record<string, undefined> {
+  const cleared: Record<string, undefined> = {};
+  if (!tableSchema) return cleared;
+  for (const [key, column] of Object.entries(tableSchema)) {
+    if (key === 'id' || key.startsWith('_00_') || column?.optional !== true) continue;
+    if (record[key] === undefined) cleared[key] = undefined;
+  }
+  return cleared;
+}
+
 /**
  * Parse a RECORD's fields against the table schema. Anything the schema does not
  * know is dropped, which is what keeps a stray field out of a write.