@spooky-sync/core 0.0.1-canary.322 → 0.0.1-canary.324

package/src/modules/crdt/mirror.ts

@@ -0,0 +1,37 @@
+import type { Container, LoroDoc, LoroList, LoroMap } from 'loro-crdt';
+
+/**
+ * The plain text a `@crdt` field shows as its column value, rendered the same
+ * way the SSP fold renders it (`packages/ssp-node/src/crdt/mirror.rs`).
+ */
+
+export type CrdtKind = 'text' | 'prosemirror';
+
+const PM_ROOT = 'doc';
+const PM_NODE_NAME = 'nodeName';
+const PM_CHILDREN = 'children';
+const PM_LINE_BREAKS = new Set(['hard_break', 'hardBreak']);
+
+export function renderText(doc: LoroDoc, field: string, kind: CrdtKind): string {
+  return kind === 'text' ? doc.getText(field).toString() : nodeText(doc.getMap(PM_ROOT));
+}
+
+/** A node holding text runs is inline content (its children concatenate); a
+ *  node holding only nodes is a block container (its children are lines). */
+function nodeText(node: LoroMap): string {
+  const name = node.get(PM_NODE_NAME);
+  if (typeof name === 'string' && PM_LINE_BREAKS.has(name)) return '\n';
+  const children = node.get(PM_CHILDREN) as Container | undefined;
+  if (!children || children.kind() !== 'List') return '';
+  const list = children as LoroList;
+  const parts: Array<{ text: boolean; value: string }> = [];
+  for (let i = 0; i < list.length; i++) {
+    const child = list.get(i) as Container | unknown;
+    if (!child || typeof child !== 'object' || !('kind' in child)) continue;
+    const c = child as Container;
+    if (c.kind() === 'Text') parts.push({ text: true, value: c.toString() });
+    else if (c.kind() === 'Map') parts.push({ text: false, value: nodeText(c as LoroMap) });
+  }
+  const inline = parts.some((p) => p.text);
+  return parts.map((p) => p.value).join(inline ? '' : '\n');
+}

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

@@ -80,6 +80,22 @@ describe('drain', () => {
     expect(out.dispatched.at(-1)).toEqual({ type: 'SyncOutcome', ok: true, error: undefined });
   });
 
+  it('a CRDT edit-log CREATE that finds its row already there is acked, any other duplicate rolls back', async () => {
+    const logEnv = defaultEnv({ tables: [{ name: 'thing', columns: {} }, { name: 'doc__crdt_log', columns: {} }] } as any, { outboxBatchSize: 2 });
+    const out = await runPure(drain(logEnv), {
+      state: stateWith([1, 2]),
+      handlers: {
+        'local.query': (e: any) =>
+          e.sql === 'SELECT * FROM $ids'
+            ? [[pendingRow(1, 'create', { tableName: 'doc__crdt_log', recordId: 'doc__crdt_log:1' }), pendingRow(2)]]
+            : [],
+        'remote.query': () => [err('Database record `doc__crdt_log:1` already exists'), err('Database record `thing:2` already exists')],
+      },
+    });
+    expect(out.state.outbox.find((i) => i.id === '_00_pending_mutations:m1')?.status).toBe('acked');
+    expect(out.state.outbox.some((i) => i.id === '_00_pending_mutations:m2')).toBe(false);
+  });
+
   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]),

package/src/mutation/push.saga.ts

@@ -67,6 +67,14 @@ export function* refreshFailedCount(): Saga<void> {
 
 const ERR = (r: StatementResult | undefined): string | null => (r && r.status === 'ERR' ? r.error : null);
 
+/**
+ * A CRDT edit-log row (`<table>__crdt_log`) is written once and never changes,
+ * so a CREATE retried after its first attempt committed (and only the answer
+ * was lost) finds it already there: that is a success, not a rejection.
+ */
+const isRepeatedLogCreate = (row: { mutationType: string; tableName: string }, err: string): boolean =>
+  row.mutationType === 'create' && row.tableName.endsWith('__crdt_log') && /already exists/i.test(err);
+
 /**
  * Drain the outbox: one serial lane, FIFO, up to `outboxBatchSize` statements
  * per request, per-statement outcome. Accepted rows are acked (they stay in
@@ -127,7 +135,7 @@ export function* drain(env: SagaEnv): Saga<void> {
         break;
       }
       const err = ERR(r);
-      if (err === null) {
+      if (err === null || isRepeatedLogCreate(row, err)) {
         const del = deletePendingRow(row.id);
         try {
           yield fx.local.query(del.sql, del.vars);

package/src/query/anon-query-isolation.integration.test.ts

@@ -449,6 +449,37 @@ describe('anonymous _00_query isolation (real SurrealDB)', () => {
     expect(await heartbeatFound(g, qg)).toBe(true);
   });
 
+  // Without `anonymousLiveQueries` the SSP stores a signed-out registration
+  // with no identity at all (`auth_id = ''`). The rule admitted only `'anon'`
+  // rows to their subscribers, so such a page could not read its own row back
+  // and its preload never settled.
+  it("a signed-out view stored with no identity (anonymous live queries off) answers to its own session, and to nobody else", async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [a, sidA] = await guest();
+    const [b] = await guest();
+    const [u] = await member('alice');
+    const qa = viewId();
+    await register(qa, sidA, '');
+    expect((await row(qa))?.auth_id).toBe('');
+
+    expect(await readBack(a, qa)).toEqual({ rowCount: 3, state: 'ready' });
+    expect(await heartbeatFound(a, qa)).toBe(true);
+
+    const before = await row(qa);
+    for (const other of [b, u]) {
+      expect(await readBack(other, qa)).toBeNull();
+      expect(await heartbeatFound(other, qa)).toBe(false);
+      expect(await other.query('SELECT id FROM _00_query')).toEqual([[]]);
+      await other.query('DELETE $id', { id: qa });
+    }
+    expect(await row(qa)).toEqual(before);
+
+    expect(await a.query('RETURN fn::query::unsubscribe($id)', { id: qa })).toEqual([
+      { released: true, remaining: 0 },
+    ]);
+    expect(await row(qa)).toBeUndefined();
+  });
+
   it('the owning guest can still release its view', async (ctx) => {
     if (!reachable) ctx.skip();
     const [a, sidA] = await guest();

package/src/query/env.ts

@@ -49,6 +49,15 @@ export function listRefTable(env: SagaEnv, s: ClientState): string {
   return listRefTableFor(env.refMode, userId);
 }
 
+/**
+ * Whether this session can be sent a view's membership at all. A signed-out
+ * session reads edges only from `_00_list_ref_anon`, and only with
+ * `enableAnonymousLiveQueries`: without it the SSP files its views under no
+ * identity in `_00_list_ref`, whose rule shows those edges to no caller. Such
+ * a view can register and report its row count, but never its rows.
+ */
+export const receivesMembership = (env: SagaEnv, s: ClientState): boolean => s.userId !== null || env.anonLive;
+
 export function columnsFor(env: SagaEnv, table: string): Record<string, unknown> | null {
   const found = env.schema.tables.find((t) => t.name === table);
   if (found) return found.columns as Record<string, unknown>;

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

@@ -151,6 +151,16 @@ export interface LocalStore extends LocalCacheEngine {
    * without it boots the circuit empty, as before.
    */
   scanVersions?(tables: string[]): Promise<Record<string, [string, number][]>>;
+  /**
+   * Reset the cached `_00_rv` of every table whose column set (`fingerprints`,
+   * see `columnFingerprints`) changed since the store last recorded it, except
+   * the rows in `keep`, and record the new sets. Returns the tables reset.
+   * For engines that keep bodies across schema changes: a body landed under an
+   * older schema lacks the columns it did not know, at the server's version,
+   * and would never be fetched again. OPTIONAL: an engine that rebuilds its
+   * store on a schema change (SurrealDB) does not need it.
+   */
+  resetChangedTables?(fingerprints: Record<string, string>, keep: Set<string>): Promise<string[]>;
   /**
    * Circuit snapshot storage, keyed. Lives in the same durable store as the
    * rows (OPFS SQLite), so it is per-bucket by construction, atomic, and

package/src/services/database/local-migrator.ts

@@ -17,10 +17,11 @@ export const sha1 = async (str: string): Promise<string> => {
 
 /**
  * Local-only state a schema change must not throw away: the outbox, the
- * failed-mutation tray and debounced patches not yet in the outbox. Cached
- * rows refill from the server; these exist nowhere else.
+ * failed-mutation tray, debounced patches not yet in the outbox and CRDT
+ * documents with edits not yet sent. Cached rows refill from the server;
+ * these exist nowhere else.
  */
-const KEPT_TABLES = ['_00_pending_mutations', '_00_failed_mutations', '_00_pending_writes'] as const;
+const KEPT_TABLES = ['_00_pending_mutations', '_00_failed_mutations', '_00_pending_writes', '_00_crdt_local'] as const;
 
 export class LocalMigrator {
   private logger: Logger;
@@ -59,6 +60,7 @@ export class LocalMigrator {
       DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
       DEFINE TABLE IF NOT EXISTS _00_pending_writes SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
       DEFINE TABLE IF NOT EXISTS _00_blob SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
+      DEFINE TABLE IF NOT EXISTS _00_crdt_local SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
     `;
     const fullSchema = schemaSurql + '\n' + systemSchema;
 

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

@@ -30,6 +30,7 @@ import {
   type SqliteTransport,
 } from './sqlite-transport';
 import { PROMOTION_OPEN_OPTIONS } from './sqlite-open';
+import { COLUMNS_ROW_ID, planColumnReset } from './sqlite-column-reset';
 import type { EngineTx, Id, LocalStore, OrderBy, RelationFetch, Row } from './cache-engine';
 import type { EngineStorageDiagnostics } from '../../modules/devtools/storage-info';
 
@@ -72,6 +73,8 @@ const SYSTEM_TABLES = [
   // asks for the ids it found in OPFS), so it has to exist up front like the
   // rest — otherwise the very first reconcile throws and the cache runs cold.
   '_00_blob',
+  // CRDT documents per open field, with edits not yet in the outbox.
+  '_00_crdt_local',
   // Server-written, synced-down meta tables (see meta_tables_client.surql).
   // DEFINE is a noop on this engine, so without seeding them here their synced
   // rows have no local table to land in: feature flags silently fall back to
@@ -898,6 +901,31 @@ export class SqliteCacheEngine implements LocalStore {
     return out;
   }
 
+  /**
+   * Reset the cached `_00_rv` of every table whose column set changed since
+   * the last boot, so its rows are fetched again whole. See
+   * `sqlite-column-reset.ts`. Returns the tables reset.
+   */
+  async resetChangedTables(fingerprints: Record<string, string>, keep: Set<string>): Promise<string[]> {
+    const { rows } = await this.call<{ rows: { data: unknown }[] }>('exec', {
+      sql: `SELECT data FROM "_00_schema" WHERE id = ?`,
+      bind: [COLUMNS_ROW_ID],
+    });
+    let stored: Record<string, string> | null = null;
+    try {
+      const raw = rows?.[0]?.data;
+      if (typeof raw === 'string') stored = JSON.parse(raw) as Record<string, string>;
+    } catch {
+      stored = null;
+    }
+    const { rows: tables } = await this.call<{ rows: { name: string }[] }>('exec', {
+      sql: `SELECT name FROM sqlite_master WHERE type = 'table'`,
+    });
+    const plan = planColumnReset(stored, fingerprints, new Set((tables ?? []).map((t) => t.name)), keep);
+    if (plan.statements.length > 0) await this.call('batch', plan.statements);
+    return plan.changed;
+  }
+
   async getSnapshot(key: string): Promise<StoredSnapshot | null> {
     const { rows } = await this.call<{ rows: { id: string; data: unknown }[] }>('exec', {
       sql: `SELECT id, data FROM "${SNAPSHOT_TABLE}" WHERE id IN (?, ?)`,

package/src/services/database/sqlite-column-reset.integration.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import { COLUMNS_ROW_ID, columnFingerprints, planColumnReset } from './sqlite-column-reset';
+
+/**
+ * A body landed under an older schema lacks the columns that schema did not
+ * know, at the server's version. Without a reset the next build never fetches
+ * it again (WhitePawn's puzzles stuck on "Preparing" for want of `layout`).
+ * These run the planned statements against a REAL in-memory SQLite, the same
+ * build the worker loads.
+ */
+
+let db: any;
+
+const rows = (sql: string, bind?: unknown[]) =>
+  db.exec({ sql, bind, rowMode: 'object', returnValue: 'resultRows' }) as Record<string, unknown>[];
+
+const versions = (table: string) =>
+  Object.fromEntries(
+    rows(`SELECT id, json_extract(data, '$._00_rv') AS rv FROM "${table}"`).map((r) => [r.id, r.rv])
+  );
+
+const storedSets = () => {
+  const r = rows(`SELECT data FROM "_00_schema" WHERE id = ?`, [COLUMNS_ROW_ID]);
+  return r[0] ? (JSON.parse(r[0].data as string) as Record<string, string>) : null;
+};
+
+const existing = () => new Set(rows(`SELECT name FROM sqlite_master WHERE type = 'table'`).map((r) => r.name as string));
+
+function run(current: Record<string, string>, keep: string[] = []) {
+  const plan = planColumnReset(storedSets(), current, existing(), keep);
+  db.exec({ sql: 'BEGIN' });
+  for (const s of plan.statements) db.exec({ sql: s.sql, bind: s.bind });
+  db.exec({ sql: 'COMMIT' });
+  return plan;
+}
+
+beforeEach(async () => {
+  const sqlite3: any = await sqlite3InitModule();
+  db = new sqlite3.oo1.DB(':memory:', 'c');
+  for (const t of ['_00_schema', 'puzzle', 'game']) {
+    db.exec({ sql: `CREATE TABLE "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+  }
+  const put = (t: string, id: string, body: object) =>
+    db.exec({ sql: `INSERT INTO "${t}"(id, data) VALUES(?, ?)`, bind: [id, JSON.stringify(body)] });
+  // Landed by the old build: no `layout`, at the server's version 6.
+  put('puzzle', 'puzzle:a', { title: 'A', _00_rv: 6 });
+  put('puzzle', 'puzzle:b', { title: 'B', _00_rv: 6 });
+  put('game', 'game:1', { white: 'x', _00_rv: 3 });
+});
+
+afterEach(() => db?.close());
+
+const OLD = { puzzle: 'title', game: 'white' };
+const NEW = { puzzle: 'layout,title', game: 'white' };
+
+describe('column reset on the SQLite cache', () => {
+  it('fingerprints are the sorted declared columns', () => {
+    expect(columnFingerprints([{ name: 'puzzle', columns: { title: {}, layout: {} } }])).toEqual({
+      puzzle: 'layout,title',
+    });
+  });
+
+  it('first boot with no recorded sets resets every cached table once', () => {
+    const plan = run(NEW);
+    expect(plan.changed.sort()).toEqual(['game', 'puzzle']);
+    expect(versions('puzzle')).toEqual({ 'puzzle:a': 0, 'puzzle:b': 0 });
+    expect(versions('game')).toEqual({ 'game:1': 0 });
+    expect(storedSets()).toEqual(NEW);
+    // Bodies stay: they keep rendering until the refetch lands.
+    expect(rows(`SELECT data FROM puzzle WHERE id = 'puzzle:a'`)[0].data).toContain('"title":"A"');
+
+    // The next boot of the same build changes nothing.
+    const again = run(NEW);
+    expect(again.statements).toEqual([]);
+  });
+
+  it('a new column resets only that table', () => {
+    run(OLD);
+    db.exec({ sql: `UPDATE puzzle SET data = json_set(data, '$._00_rv', 6)` });
+    db.exec({ sql: `UPDATE game SET data = json_set(data, '$._00_rv', 3)` });
+
+    const plan = run(NEW);
+    expect(plan.changed).toEqual(['puzzle']);
+    expect(versions('puzzle')).toEqual({ 'puzzle:a': 0, 'puzzle:b': 0 });
+    expect(versions('game')).toEqual({ 'game:1': 3 });
+  });
+
+  it('keeps the version of a row with an unsettled local write', () => {
+    const plan = run(NEW, ['puzzle:b', 'game:9']);
+    expect(plan.changed).toContain('puzzle');
+    expect(versions('puzzle')).toEqual({ 'puzzle:a': 0, 'puzzle:b': 6 });
+  });
+
+  it('records a table the store has no rows for without touching it', () => {
+    const plan = run({ ...NEW, puzzle_chapter: 'puzzle,sort,title' });
+    expect(plan.changed).not.toContain('puzzle_chapter');
+    expect(storedSets()).toEqual({ ...NEW, puzzle_chapter: 'puzzle,sort,title' });
+  });
+});

package/src/services/database/sqlite-column-reset.ts

@@ -0,0 +1,91 @@
+/**
+ * Cached bodies outlive a schema change on the SQLite engine, and that loses
+ * columns for good.
+ *
+ * A body is landed through `cleanRecord`, which keeps only the columns the
+ * running app's schema declares, and is stored at the server's `_00_rv`. The
+ * engine is schemaless (no migrator, nothing is recreated when the schema
+ * changes), so a tab on an older build that fetched a row after the server
+ * added and backfilled a column stored it WITHOUT that column at the new
+ * version. The next build knows the column, but its local version equals the
+ * server's, so the fetch plan never asks for the row again and the column
+ * stays missing until something else bumps the row. (WhitePawn, 2026-10-11:
+ * every puzzle read as unconverted because `layout` never arrived.)
+ *
+ * So the store remembers each table's column set (`_00_schema`, row
+ * `columns`). On boot, before the prime reads the versions, a table whose set
+ * changed, or every table when no set was recorded yet, gets its cached
+ * `_00_rv` reset to 0. The bodies stay and keep rendering; any view that names
+ * one of those rows sees it as stale and fetches it again, whole. Rows with an
+ * unsettled local write keep their version: their echo is a newer body anyway.
+ */
+
+/** `_00_schema` row holding the recorded column sets. */
+export const COLUMNS_ROW_ID = 'columns';
+
+export interface ColumnResetPlan {
+  /** Tables with cached rows whose versions are reset. */
+  changed: string[];
+  /** One transaction: the resets, then the new column sets. Empty when nothing changed. */
+  statements: { sql: string; bind?: unknown[] }[];
+}
+
+/**
+ * The column set of every table, as `cleanRecord` sees it: the sorted declared
+ * column names. Plain names rather than a hash, so a stored set says what it is.
+ */
+export function columnFingerprints(
+  tables: readonly { name: string; columns: Record<string, unknown> }[]
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const t of tables) out[t.name] = Object.keys(t.columns).sort().join(',');
+  return out;
+}
+
+const sameSets = (a: Record<string, string> | null, b: Record<string, string>): boolean => {
+  if (!a) return false;
+  const ka = Object.keys(a);
+  return ka.length === Object.keys(b).length && ka.every((k) => a[k] === b[k]);
+};
+
+/**
+ * What to run for the column sets `current`, given the `stored` ones (null when
+ * none were recorded), the tables that exist in the store, and the encoded ids
+ * (`table:id`) with an unsettled local write.
+ */
+export function planColumnReset(
+  stored: Record<string, string> | null,
+  current: Record<string, string>,
+  existingTables: ReadonlySet<string>,
+  keep: Iterable<string>
+): ColumnResetPlan {
+  if (sameSets(stored, current)) return { changed: [], statements: [] };
+
+  const keepByTable = new Map<string, string[]>();
+  for (const id of keep) {
+    const table = id.slice(0, id.indexOf(':'));
+    if (!keepByTable.has(table)) keepByTable.set(table, []);
+    keepByTable.get(table)!.push(id);
+  }
+
+  const changed: string[] = [];
+  const statements: ColumnResetPlan['statements'] = [];
+  for (const [table, set] of Object.entries(current)) {
+    if (stored && stored[table] === set) continue;
+    if (!existingTables.has(table)) continue;
+    changed.push(table);
+    const quoted = `"${table.replace(/"/g, '""')}"`;
+    const reset = `UPDATE ${quoted} SET data = json_set(data, '$._00_rv', 0) WHERE json_extract(data, '$._00_rv') != 0`;
+    const kept = keepByTable.get(table);
+    statements.push(
+      kept
+        ? { sql: `${reset} AND id NOT IN (SELECT value FROM json_each(?))`, bind: [JSON.stringify(kept)] }
+        : { sql: reset }
+    );
+  }
+  statements.push({
+    sql: `INSERT OR REPLACE INTO "_00_schema"(id, data) VALUES (?, ?)`,
+    bind: [COLUMNS_ROW_ID, JSON.stringify(current)],
+  });
+  return { changed, statements };
+}

package/src/services/stream-processor/index.ts

@@ -87,6 +87,10 @@ export interface CircuitPrimeContext {
   /** Encoded ids with an unsettled local mutation (their `_00_rv` was bumped
    *  locally and may exceed the server's next version). */
   pendingIds: Set<string>;
+  /** Each table's client column set (`columnFingerprints`). An engine that
+   *  keeps bodies across schema changes resets the versions of a table whose
+   *  set changed before they are read, so its rows are fetched again whole. */
+  columnFingerprints?: Record<string, string>;
   /** Receives every `(id, rv)` the prime put into the circuit, per table, so
    *  the sync layer can skip re-downloading bodies it already has. */
   onVersions?: (table: string, entries: [string, number][]) => void;
@@ -507,6 +511,26 @@ export class StreamProcessorService {
       this.processor === processor && generation === this.stateGeneration && epoch === this.db.epoch;
     const t0 = performance.now();
 
+    // Before anything reads a version: a table whose columns changed since its
+    // bodies were cached reads as stale from here on (see sqlite-column-reset).
+    if (ctx.columnFingerprints && typeof this.db.resetChangedTables === 'function') {
+      try {
+        const reset = await this.db.resetChangedTables(ctx.columnFingerprints, ctx.pendingIds);
+        if (!alive()) return;
+        if (reset.length > 0) {
+          this.logger.info(
+            { tables: reset, Category: 'sp00ky-client::StreamProcessorService::primeFromLocal' },
+            'Columns changed since these rows were cached; they will be fetched again'
+          );
+        }
+      } catch (e) {
+        this.logger.warn(
+          { error: e, Category: 'sp00ky-client::StreamProcessorService::primeFromLocal' },
+          'Column change check failed; cached versions kept'
+        );
+      }
+    }
+
     let restored = false;
     if (
       this.persistCircuit &&

package/src/services/stream-processor/stream-processor.prime.test.ts

@@ -106,6 +106,42 @@ describe('StreamProcessorService.primeFromLocal', () => {
     await expect(service.whenPrimed()).resolves.toBeUndefined();
   });
 
+  it('resets tables whose columns changed BEFORE reading the versions it reports', async () => {
+    const { service, db } = makeService();
+    const order: string[] = [];
+    // The engine zeroes `thing`'s cached versions (a column was added).
+    const reset = vi.fn(async () => {
+      order.push('reset');
+      db.scanVersions.mockImplementation(async (tables: string[]) => {
+        order.push('scan');
+        return Object.fromEntries(tables.map((t) => [t, t === 'thing' ? [['thing:a', 0], ['thing:b', 0]] : [['other:x', 5]]]));
+      });
+      return ['thing'];
+    });
+    (db as any).resetChangedTables = reset;
+    await service.init();
+    const c = { ...ctx(), pendingIds: new Set(['thing:b']), columnFingerprints: { thing: 'layout,title', other: 'title' } };
+    await service.primeFromLocal(c);
+    expect(reset).toHaveBeenCalledWith({ thing: 'layout,title', other: 'title' }, new Set(['thing:b']));
+    expect(order).toEqual(['reset', 'scan']);
+    // Reported as stale, so the fetch plan pulls the bodies again.
+    expect(c.onVersions).toHaveBeenCalledWith('thing', [['thing:a', 0]]);
+  });
+
+  it('keeps priming when the column check fails', async () => {
+    const { service, db } = makeService();
+    (db as any).resetChangedTables = vi.fn(async () => {
+      throw new Error('worker gone');
+    });
+    await service.init();
+    const c = { ...ctx(), columnFingerprints: { thing: 'title' } };
+    await service.primeFromLocal(c);
+    expect(c.onVersions).toHaveBeenCalledWith('thing', [
+      ['thing:a', 1],
+      ['thing:b', 2],
+    ]);
+  });
+
   it('with a snapshot, restores it under the registered views and only fetches what reconcile asks for', async () => {
     const { service, db, received } = makeService({ snapshot: { bytes: new Uint8Array([7]), meta: goodMeta } });
     await service.init();

package/src/testing/fake-services.ts

@@ -37,7 +37,7 @@ export function fakeServiceBundle<S extends SchemaStructure>(over: Partial<Servi
     persistence: { set: async () => undefined, get: async () => null, remove: async () => undefined },
     streamProcessor: { addReceiver: (r: unknown) => void receivers.push(r), checkpoint: async () => undefined, dispose: noop } as any,
     migrator: {} as any,
-    crdt: { closeAll: noop, dispose: noop, open: async () => 'field', close: noop } as any,
+    crdt: { attach: noop, setSessionId: noop, closeAll: noop, dispose: noop, open: async () => 'field', close: async () => {} } as any,
     auth: { subscribe: (cb: (u: string | null) => void) => (authListeners.push(cb), noop), subscribeImpersonation: () => noop, onBeforeSignOut: () => noop, currentUser: null, isAuthenticated: false, token: null, impersonation: null, eventSystem: { subscribe: noop } } as any,
     tabs: null,
     tabsUnsupportedReason: 'test',

package/src/types.ts

@@ -259,11 +259,11 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
   streamDebounceTime?: number;
   /**
    * Debounce time in milliseconds for syncing collaborative (CRDT) field
-   * changes to the remote database. Local writes happen immediately on
-   * every keystroke (so reload/offline works), but the remote UPSERT is
-   * coalesced over this window. Lower = snappier remote propagation +
-   * more network traffic; higher = less traffic + more lag for other
-   * collaborators. Defaults to 500ms.
+   * edits to the server. Local state is kept on every change (so reload and
+   * offline work), but a field's own new ops go out as one edit-log row per
+   * pause of this length (at most 2 s apart while typing continues).
+   * Lower = snappier propagation and more rows; higher = fewer rows and more
+   * lag for other collaborators. Defaults to 300ms.
    */
   crdtDebounceMs?: number;
   /**
@@ -321,7 +321,8 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * page gets live `useQuery` updates over world-readable tables. Requires the
    * server to be deployed with `anonymousLiveQueries: true` in `sp00ky.yml`
    * (this flag must match it). Defaults to `false`: anonymous clients can read
-   * one-shot but never sync live.
+   * one-shot but never sync live, and a `preload` made while signed out returns
+   * at once rather than wait for membership that never comes.
    */
   enableAnonymousLiveQueries?: boolean;
   /**

package/src/utils/surql.ts

@@ -120,10 +120,9 @@ export const surql: SurqlHelper = {
     return `UPSERT ONLY $${idVar} REPLACE $${dataVar}`;
   },
 
-  // Use this for sync-down ingestion: the remote payload omits local-only
-  // fields injected by the CLI's local-schema setup (`_00_crdt`,
-  // `_00_cursor`), and REPLACE would wipe them on every round-trip and
-  // break offline reload of CRDT state.
+  // Use this for sync-down ingestion: the remote payload can omit local-only
+  // fields injected by the CLI's local-schema setup, and REPLACE would wipe
+  // them on every round-trip.
   upsertMerge(idVar: string, dataVar: string) {
     return `UPSERT ONLY $${idVar} MERGE $${dataVar}`;
   },