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

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as renderOrderSql, c as serializeRow, i as projectedDataSql, l as resolveRelations, o as renderWhereSql, r as project, s as reviveRow, t as PROMOTION_OPEN_OPTIONS, u as stableKey } from "./sqlite-open.js";
+import { a as renderOrderSql, c as serializeMergeRow, d as stableKey, i as projectedDataSql, l as serializeRow, o as renderWhereSql, r as project, s as reviveRow, t as PROMOTION_OPEN_OPTIONS, u as resolveRelations } from "./sqlite-open.js";
 import { QueryBuilder, RecordId, baseFieldOfParam, cyrb53 } from "@spooky-sync/query-builder";
 import { DateTime, Duration, RecordId as RecordId$1, Surreal, Uuid, applyDiagnostics, createRemoteEngines } from "surrealdb";
 import pino from "pino";
@@ -448,6 +448,34 @@ function cleanRecord(tableSchema, record) {
 	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.
+*/
+function absentOptionalColumns(tableSchema, record) {
+	const cleared = {};
+	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] === void 0) cleared[key] = void 0;
+	}
+	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.
 */
@@ -1724,8 +1752,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.283";
-const WASM_VERSION = "0.0.1-canary.283";
+const CORE_VERSION = "0.0.1-canary.286";
+const WASM_VERSION = "0.0.1-canary.286";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -5485,6 +5513,7 @@ function* landChunk(env, requested, rows, versions, state, epoch) {
 		bodies.push({
 			id: rid,
 			content: {
+				...absentOptionalColumns(columns, row),
 				...content,
 				_00_rv: version
 			}
@@ -9310,7 +9339,7 @@ var SqliteCacheEngine = class {
 		await this.ensureTable(table);
 		const key = stableKey(id);
 		if (mode === "merge") {
-			const full = serializeRow({
+			const { insert, patch } = serializeMergeRow({
 				...data,
 				id: key
 			});
@@ -9318,8 +9347,8 @@ var SqliteCacheEngine = class {
 				sql: `INSERT INTO "${table}"(id, data) VALUES(?, ?) ON CONFLICT(id) DO UPDATE SET data = json_patch(data, ?)`,
 				bind: [
 					key,
-					full,
-					full
+					insert,
+					patch
 				]
 			});
 			return;
@@ -9496,7 +9525,7 @@ var SqliteCacheEngine = class {
 			const key = stableKey(op.id);
 			ensure(t);
 			if (op.mode === "merge") {
-				const full = serializeRow({
+				const { insert, patch } = serializeMergeRow({
 					...op.data,
 					id: key
 				});
@@ -9504,8 +9533,8 @@ var SqliteCacheEngine = class {
 					sql: `INSERT INTO "${t}"(id, data) VALUES(?, ?) ON CONFLICT(id) DO UPDATE SET data = json_patch(data, ?)`,
 					bind: [
 						key,
-						full,
-						full
+						insert,
+						patch
 					]
 				});
 			} else stmts.push({
@@ -13758,7 +13787,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.283",
+			coreVersion: "0.0.1-canary.286",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,

package/dist/sqlite-open.js

@@ -182,6 +182,33 @@ function serializeRow(row) {
 		return v;
 	});
 }
+/**
+* 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).
+*/
+function serializeMergeRow(row) {
+	const insert = serializeRow(row);
+	const cleared = [];
+	for (const key of Object.keys(row)) if (row[key] === void 0) cleared.push(`${JSON.stringify(key)}:null`);
+	if (cleared.length === 0 || insert[0] !== "{") return {
+		insert,
+		patch: insert
+	};
+	const members = cleared.join(",");
+	return {
+		insert,
+		patch: insert === "{}" ? `{${members}}` : `${insert.slice(0, -1)},${members}}`
+	};
+}
 function reviveRow(json) {
 	if (json.indexOf("\"__u8\"") === -1) return JSON.parse(json);
 	return JSON.parse(json, (_k, v) => {
@@ -328,4 +355,4 @@ async function openDb(sqlite3, dbName, useOpfs, opts = {}) {
 }
 
 //#endregion
-export { renderOrderSql as a, serializeRow as c, projectedDataSql as i, resolveRelations as l, openDb as n, renderWhereSql as o, project as r, reviveRow as s, PROMOTION_OPEN_OPTIONS as t, stableKey as u };
+export { renderOrderSql as a, serializeMergeRow as c, stableKey as d, projectedDataSql as i, serializeRow as l, openDb as n, renderWhereSql as o, project as r, reviveRow as s, PROMOTION_OPEN_OPTIONS as t, resolveRelations as u };

package/dist/sqlite-worker.js

@@ -1,4 +1,4 @@
-import { a as renderOrderSql, i as projectedDataSql, l as resolveRelations, n as openDb, o as renderWhereSql, r as project, s as reviveRow, u as stableKey } from "./sqlite-open.js";
+import { a as renderOrderSql, d as stableKey, i as projectedDataSql, n as openDb, o as renderWhereSql, r as project, s as reviveRow, u as resolveRelations } from "./sqlite-open.js";
 import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
 
 //#region src/services/database/sqlite-lock-verify.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.283",
+  "version": "0.0.1-canary.286",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -75,8 +75,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.283",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.283",
+    "@spooky-sync/query-builder": "0.0.1-canary.286",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.286",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/skills/sp00ky-core/SKILL.md

@@ -182,12 +182,15 @@ Backend runs let you trigger server-side HTTP operations via an **outbox pattern
 ### `db.run()` Signature
 
 ```typescript
-db.run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
-  backend: B,        // Backend name from sp00ky.yml (e.g., 'api')
-  route: R,          // Route path from OpenAPI spec (e.g., '/spookify')
-  payload: RoutePayload<S, B, R>,  // Typed args for the route
-  options?: RunOptions
-): Promise<void>
+// A method of the client: called as `db.run(backend, route, payload, options)`.
+interface Sp00kyClient<S> {
+  run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
+    backend: B, // Backend name from sp00ky.yml (e.g., 'api')
+    route: R, // Route path from OpenAPI spec (e.g., '/spookify')
+    payload: RoutePayload<S, B, R>, // Typed args for the route
+    options?: RunOptions
+  ): Promise<void>;
+}
 ```
 
 All parameters are type-safe — `backend`, `route`, and `payload` are inferred from the generated schema.

package/src/query/fetch.saga.test.ts

@@ -4,7 +4,7 @@ import { runPure } from '../testing/run-pure';
 import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
 import * as R from '../state/reducers';
 import { defaultEnv } from './env';
-import { fetchRows } from './fetch.saga';
+import { fetchRows, landChunk } from './fetch.saga';
 import type { StatementResult } from '../kernel/effects';
 
 const env = defaultEnv({ tables: [{ name: 'thing', columns: { a: {} } }] } as any);
@@ -154,3 +154,46 @@ describe('fetchRows', () => {
     expect(out.state.versions.get('thing:2')).toBe(1);
   });
 });
+
+describe('landChunk', () => {
+  const typed = defaultEnv({
+    tables: [
+      {
+        name: 'broadcast',
+        columns: {
+          title: { type: 'string', optional: false },
+          owner: { type: 'string', recordId: true, optional: false },
+          club: { type: 'string', recordId: true, optional: true },
+          note: { type: 'string', optional: true },
+        },
+      },
+    ],
+  } as any);
+
+  // `UPDATE broadcast:x UNSET club` leaves no `club` key in the body the server
+  // returns, and a MERGE that does not name it kept the stale local club.
+  it('names each optional column the body lacks as undefined so the MERGE clears it', async () => {
+    const rid = new RecordId('broadcast', 'x');
+    const out = await runPure(landChunk(typed, ['broadcast:x'], [{ id: rid, title: 't', note: 'n', _00_extra: 1 }], new Map([['broadcast:x', 4]]), buildState(), 3), {
+      handlers: { 'local.execute': () => undefined, 'ssp.ingest': () => undefined },
+    });
+    expect(out.result).toBe(true);
+    const exec = out.log.find((e) => e.kind === 'local.execute') as any;
+    expect(exec.query.sql).toContain('UPSERT ONLY $id0 MERGE $content0');
+    expect(exec.vars.content0).toStrictEqual({ club: undefined, title: 't', note: 'n', _00_extra: 1, _00_rv: 4 });
+    expect(Object.prototype.hasOwnProperty.call(exec.vars.content0, 'club')).toBe(true);
+    // A required column (`owner`) is never cleared: its absence means hidden, not unset.
+    expect(Object.prototype.hasOwnProperty.call(exec.vars.content0, 'owner')).toBe(false);
+    // The circuit record carries no clear: CREATE/UPDATE replace the circuit row.
+    const ingest = out.log.find((e) => e.kind === 'ssp.ingest') as any;
+    expect(ingest.records[0].record).toStrictEqual({ id: rid, title: 't', note: 'n', _00_extra: 1, _00_rv: 4 });
+  });
+
+  it('names nothing for a table without a schema', async () => {
+    const out = await runPure(landChunk(typed, ['other:1'], [{ id: new RecordId('other', '1'), z: 1 }], new Map([['other:1', 1]]), buildState(), 0), {
+      handlers: { 'local.execute': () => undefined, 'ssp.ingest': () => undefined },
+    });
+    const exec = out.log.find((e) => e.kind === 'local.execute') as any;
+    expect(exec.vars.content0).toStrictEqual({ z: 1, _00_rv: 1 });
+  });
+});

package/src/query/fetch.saga.ts

@@ -8,7 +8,7 @@ import type { ClientState } from '../state/client-state';
 import * as R from '../state/reducers';
 import { planFetch } from '../state/selectors';
 import { encodeRecordId, parseRecordIdString } from '../utils/index';
-import { cleanRecord } from '../utils/parser';
+import { absentOptionalColumns, cleanRecord } from '../utils/parser';
 import type { SagaEnv } from './env';
 import * as sql from './sql';
 
@@ -87,7 +87,12 @@ export function* landChunk(
     const columns = env.schema.tables.find((t) => t.name === table)?.columns;
     const cleaned = columns ? cleanRecord(columns, row) : row;
     const { id: _id, ...content } = cleaned;
-    bodies.push({ id: rid, content: { ...content, _00_rv: version } });
+    // The row is the server's whole body, so an optional column it lacks was
+    // cleared upstream: name it (as `undefined`) so the MERGE removes the local
+    // copy instead of keeping it. `_00_*` local bookkeeping is never named, so
+    // MERGE (not REPLACE) still preserves it. The circuit record below needs no
+    // such key: CREATE/UPDATE replace the circuit's row outright.
+    bodies.push({ id: rid, content: { ...absentOptionalColumns(columns, row), ...content, _00_rv: version } });
     ingest.push({ table, op: state.versions.has(id) ? 'UPDATE' : 'CREATE', id, record: { ...cleaned, _00_rv: version } });
     seen.add(id);
   }

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/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.