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

package/dist/index.d.ts

@@ -303,6 +303,10 @@ 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;

package/dist/index.js

@@ -2188,8 +2188,8 @@ function trimHistory(history, cap) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.322";
-const WASM_VERSION = "0.0.1-canary.322";
+const CORE_VERSION = "0.0.1-canary.323";
+const WASM_VERSION = "0.0.1-canary.323";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	version = CORE_VERSION;
@@ -9627,6 +9627,84 @@ var PortSqliteTransport = class extends BaseTransport {
 	}
 };
 
+//#endregion
+//#region src/services/database/sqlite-column-reset.ts
+/**
+* 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. */
+const COLUMNS_ROW_ID = "columns";
+/**
+* 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.
+*/
+function columnFingerprints(tables) {
+	const out = {};
+	for (const t of tables) out[t.name] = Object.keys(t.columns).sort().join(",");
+	return out;
+}
+const sameSets = (a, b) => {
+	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.
+*/
+function planColumnReset(stored, current, existingTables, keep) {
+	if (sameSets(stored, current)) return {
+		changed: [],
+		statements: []
+	};
+	const keepByTable = /* @__PURE__ */ new Map();
+	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 = [];
+	const statements = [];
+	for (const [table, set] of Object.entries(current)) {
+		if (stored && stored[table] === set) continue;
+		if (!existingTables.has(table)) continue;
+		changed.push(table);
+		const reset = `UPDATE ${`"${table.replace(/"/g, "\"\"")}"`} 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
+	};
+}
+
 //#endregion
 //#region src/services/database/sqlite-cache-engine.ts
 /**
@@ -10259,6 +10337,28 @@ var SqliteCacheEngine = class {
 		}
 		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, keep) {
+		const { rows } = await this.call("exec", {
+			sql: `SELECT data FROM "_00_schema" WHERE id = ?`,
+			bind: [COLUMNS_ROW_ID]
+		});
+		let stored = null;
+		try {
+			const raw = rows?.[0]?.data;
+			if (typeof raw === "string") stored = JSON.parse(raw);
+		} catch {
+			stored = null;
+		}
+		const { rows: tables } = await this.call("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) {
 		const { rows } = await this.call("exec", {
 			sql: `SELECT id, data FROM "${SNAPSHOT_TABLE}" WHERE id IN (?, ?)`,
@@ -10955,6 +11055,19 @@ var StreamProcessorService = class {
 		const epoch = this.db.epoch;
 		const alive = () => this.processor === processor && generation === this.stateGeneration && epoch === this.db.epoch;
 		const t0 = performance.now();
+		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 && typeof this.db.getSnapshot === "function" && typeof processor.load_store_state === "function") {
 			const snapshot = await this.db.getSnapshot(CIRCUIT_SNAPSHOT_KEY);
@@ -14865,7 +14978,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.322",
+			coreVersion: "0.0.1-canary.323",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -15005,6 +15118,7 @@ function createAdapters(config, s, host, lateModules) {
 			],
 			schemaHash: String(hash53(config.schemaSurql)),
 			pendingIds: new Set(pendingIds),
+			columnFingerprints: columnFingerprints(config.schema.tables),
 			onVersions: (_table, entries) => host.dispatch({
 				type: "VersionsPrimed",
 				entries

package/dist/types.d.ts

@@ -451,6 +451,16 @@ 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/package.json

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

package/src/client/services.ts

@@ -21,6 +21,7 @@ import { TabsCoordinator, type CoordinatorHooks } from '../services/tabs/coordin
 import type { LeaderSyncHub, SyncForwarder } from '../services/tabs/coordinator';
 import { computeTabsFingerprint, hash53 } from '../services/tabs/protocol';
 import type { SqliteCacheEngine } from '../services/database/sqlite-cache-engine';
+import { columnFingerprints } from '../services/database/sqlite-column-reset';
 import type { BlobCache } from '../services/blobs/index';
 import { MemoryBlobStore, createBlobCache, resolveBlobBudget } from '../services/blobs/index';
 import type { Adapters } from '../kernel/interpreter';
@@ -308,6 +309,7 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
         tables: [...config.schema.tables.map((t) => t.name), '_00_user_feature', '_00_app_release'],
         schemaHash: String(hash53(config.schemaSurql)),
         pendingIds: new Set(pendingIds),
+        columnFingerprints: columnFingerprints(config.schema.tables),
         onVersions: (_table, entries) => host.dispatch({ type: 'VersionsPrimed', entries }),
       }),
     'ssp.reset': () => s.streamProcessor.reset(),

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/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';
 
@@ -898,6 +899,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();