@syncular/client 0.30.10 → 0.30.12

package/dist/schema.d.ts

@@ -93,6 +93,7 @@ export declare const OPTIMISTIC_VERSION = -1;
  * pass through this filter.
  */
 export declare function stripSyncColumns(rows: SqlRow[]): SqlRow[];
+export declare function matchesLocalScopes(table: CompiledClientTable, scopes: Readonly<Record<string, readonly string[]>>, values: Readonly<Record<string, JsonRowValue>>): boolean;
 export declare function quoteIdent(name: string): string;
 /**
  * §5.11: the app-side type of a column for local (plaintext) storage. For an
@@ -160,3 +161,5 @@ export type JsonRowValue = string | number | boolean | null | {
 export declare function hexToBytes(hex: string): Uint8Array;
 export declare function rowValueToJson(value: RowValue): JsonRowValue;
 export declare function jsonToRowValue(value: JsonRowValue): RowValue;
+/** Convert each column value without changing the row's presence set. */
+export declare function mapRowValues<T, U>(values: Readonly<Record<string, T>>, convert: (value: T) => U): Record<string, U>;

package/dist/schema.js

@@ -10,41 +10,41 @@ const ALLOWED_FTS_TOKENIZERS = new Set([
     'porter unicode61',
     'trigram',
 ]);
+function invalidSchema(message) {
+    throw new Error(message);
+}
 export function compileClientSchema(schema) {
     const tables = new Map();
     const schemaObjectNames = new Set();
     for (const table of schema.tables) {
+        const tableLabel = `table ${table.name}`;
         if (tables.has(table.name)) {
-            throw new Error(`duplicate table ${JSON.stringify(table.name)}`);
+            invalidSchema(`duplicate table ${JSON.stringify(table.name)}`);
         }
         if (schemaObjectNames.has(table.name)) {
-            throw new Error(`table ${JSON.stringify(table.name)} conflicts with an index or FTS projection`);
+            invalidSchema(`table ${JSON.stringify(table.name)} conflicts with an index or FTS projection`);
         }
         schemaObjectNames.add(table.name);
         const columnIndex = new Map();
         table.columns.forEach((column, index) => {
             if (columnIndex.has(column.name)) {
-                throw new Error(`table ${table.name}: duplicate column ${JSON.stringify(column.name)}`);
+                invalidSchema(`${tableLabel}: duplicate column ${JSON.stringify(column.name)}`);
             }
             columnIndex.set(column.name, index);
         });
         const primaryKeyIndex = columnIndex.get(table.primaryKey);
         if (primaryKeyIndex === undefined) {
-            throw new Error(`table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} is not a column`);
+            invalidSchema(`${tableLabel}: primary key ${JSON.stringify(table.primaryKey)} is not a column`);
         }
         // §2.4 primary-key eligibility: a primary key MUST render to a `rowId`
         // string every implementation produces identically and local storage
         // resolves without deferring to a SQLite build.
         const primaryKeyColumn = table.columns[primaryKeyIndex];
-        if (primaryKeyColumn !== undefined &&
-            primaryKeyColumn.type !== 'string' &&
-            primaryKeyColumn.type !== 'integer' &&
-            primaryKeyColumn.type !== 'boolean' &&
-            primaryKeyColumn.type !== 'json') {
-            throw new Error(`table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} has an ineligible column type (§2.4); a primary key must be string, integer, boolean, or json`);
+        if (!['string', 'integer', 'boolean', 'json'].includes(primaryKeyColumn.type)) {
+            invalidSchema(`${tableLabel}: primary key ${JSON.stringify(table.primaryKey)} has an ineligible type (§2.4)`);
         }
         if (table.scopes.length === 0) {
-            throw new Error(`table ${table.name}: every synced table declares at least one scope pattern (§3.1)`);
+            invalidSchema(`${tableLabel}: every synced table declares at least one scope pattern (§3.1)`);
         }
         const scopeColumnByVariable = new Map();
         const scopePrefixByVariable = new Map();
@@ -52,17 +52,17 @@ export function compileClientSchema(schema) {
             const pattern = typeof spec === 'string' ? spec : spec.pattern;
             const match = PATTERN_RE.exec(pattern);
             if (match === null || match[1] === undefined || match[2] === undefined) {
-                throw new Error(`table ${table.name}: scope pattern ${JSON.stringify(pattern)} must be 'prefix:{variable}'`);
+                invalidSchema(`${tableLabel}: scope pattern ${JSON.stringify(pattern)} must be 'prefix:{variable}'`);
             }
             const prefix = match[1];
             const variable = match[2];
             const column = typeof spec === 'string' ? variable : spec.column;
             if (!columnIndex.has(column)) {
-                throw new Error(`table ${table.name}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`);
+                invalidSchema(`${tableLabel}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`);
             }
             const existing = scopeColumnByVariable.get(variable);
             if (existing !== undefined && existing !== column) {
-                throw new Error(`table ${table.name}: variable ${JSON.stringify(variable)} maps to two different columns (§3.1)`);
+                invalidSchema(`${tableLabel}: variable ${JSON.stringify(variable)} maps to two different columns (§3.1)`);
             }
             scopeColumnByVariable.set(variable, column);
             scopePrefixByVariable.set(variable, prefix);
@@ -83,43 +83,28 @@ export function compileClientSchema(schema) {
         for (const alias of ambiguous)
             columnIndexByCamel.delete(alias);
         const indexes = table.indexes ?? [];
-        for (const index of indexes) {
-            if (schemaObjectNames.has(index.name)) {
-                throw new Error(`table ${table.name}: index ${JSON.stringify(index.name)} conflicts with another schema object`);
-            }
-            schemaObjectNames.add(index.name);
-            for (const column of index.columns) {
-                if (!columnIndex.has(column)) {
-                    throw new Error(`table ${table.name}: index ${JSON.stringify(index.name)} names unknown column ${JSON.stringify(column)}`);
-                }
-            }
-        }
         const ftsIndexes = table.ftsIndexes ?? [];
-        for (const index of ftsIndexes) {
-            if (schemaObjectNames.has(index.name)) {
-                throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} conflicts with another schema object`);
-            }
+        for (const index of [...indexes, ...ftsIndexes]) {
+            const fts = 'tokenize' in index;
+            const label = `${tableLabel}: ${fts ? 'FTS projection' : 'index'} ${JSON.stringify(index.name)}`;
+            if (schemaObjectNames.has(index.name))
+                invalidSchema(`${label} conflicts with another schema object`);
             schemaObjectNames.add(index.name);
-            if (index.columns.length === 0 || index.columns.length > 32) {
-                throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} needs between 1 and 32 columns`);
-            }
-            const seenColumns = new Set();
-            for (const columnName of index.columns) {
-                if (seenColumns.has(columnName)) {
-                    throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} repeats column ${JSON.stringify(columnName)}`);
-                }
-                seenColumns.add(columnName);
-                const column = table.columns.find((candidate) => candidate.name === columnName);
-                if (column === undefined) {
-                    throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} names unknown column ${JSON.stringify(columnName)}`);
-                }
-                if (localColumnType(column) !== 'string') {
-                    throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} column ${JSON.stringify(columnName)} must have string type`);
-                }
-            }
-            if (!ALLOWED_FTS_TOKENIZERS.has(index.tokenize)) {
-                throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} tokenizer ${JSON.stringify(index.tokenize)} is not allowlisted`);
+            if (fts && (!index.columns.length || index.columns.length > 32))
+                invalidSchema(`${label} needs between 1 and 32 columns`);
+            const seen = new Set();
+            for (const name of index.columns) {
+                if (fts && seen.has(name))
+                    invalidSchema(`${label} repeats column ${JSON.stringify(name)}`);
+                seen.add(name);
+                const column = table.columns[columnIndex.get(name) ?? -1];
+                if (!column)
+                    invalidSchema(`${label} names unknown column ${JSON.stringify(name)}`);
+                if (fts && localColumnType(column) !== 'string')
+                    invalidSchema(`${label} column ${JSON.stringify(name)} must have string type`);
             }
+            if (fts && !ALLOWED_FTS_TOKENIZERS.has(index.tokenize))
+                invalidSchema(`${label} tokenizer ${JSON.stringify(index.tokenize)} is not allowlisted`);
         }
         tables.set(table.name, {
             name: table.name,
@@ -171,6 +156,14 @@ export function stripSyncColumns(rows) {
         return copy;
     });
 }
+export function matchesLocalScopes(table, scopes, values) {
+    const entries = Object.entries(scopes);
+    return (entries.length > 0 &&
+        entries.every(([variable, allowed]) => {
+            const column = table.scopeColumnByVariable.get(variable);
+            return column !== undefined && allowed.includes(String(values[column]));
+        }));
+}
 export function quoteIdent(name) {
     return `"${name.replaceAll('"', '""')}"`;
 }
@@ -216,7 +209,7 @@ function createSyncedTable(db, table) {
         return `${quoteIdent(column.name)} ${sqlType(column)}${notNull}${pk}`;
     });
     columns.push(`${quoteIdent(SYNC_VERSION_COLUMN)} INTEGER NOT NULL DEFAULT 0`);
-    db.exec(`CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)} (${columns.join(', ')})`);
+    db.exec(`CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)}(${columns.join(', ')})`);
     // Local secondary indexes (CREATE INDEX subset). Created here so both the
     // initial ensureLocalSchema and the §7.4.3 drop-and-recreate reset path
     // materialize them. IF NOT EXISTS keeps it idempotent; the DROP TABLE in the
@@ -224,7 +217,7 @@ function createSyncedTable(db, table) {
     for (const index of table.indexes) {
         const unique = index.unique ? 'UNIQUE ' : '';
         const cols = index.columns.map((c) => quoteIdent(c)).join(', ');
-        db.exec(`CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(index.name)} ON ${quoteIdent(table.name)} (${cols})`);
+        db.exec(`CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(index.name)} ON ${quoteIdent(table.name)}(${cols})`);
     }
 }
 const FTS_SOURCE_ID_COLUMN = '_syncular_source_id';
@@ -245,18 +238,21 @@ const FTS_SOURCE_ID_COLUMN = '_syncular_source_id';
  * comment below for the full rationale.
  */
 function createFtsProjection(db, table, index) {
+    const projection = quoteIdent(index.name);
+    const sourceTable = quoteIdent(table.name);
+    const primaryKey = quoteIdent(table.primaryKey);
     const existed = db.query("SELECT 1 AS present FROM sqlite_master WHERE type='table' AND name=?", [index.name]).length > 0;
     const indexedColumns = index.columns.map(quoteIdent);
     const tokenizer = index.tokenize.replaceAll("'", "''");
-    db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS ${quoteIdent(index.name)} USING fts5(${quoteIdent(FTS_SOURCE_ID_COLUMN)} UNINDEXED, ${indexedColumns.join(', ')}, tokenize='${tokenizer}')`);
+    db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS ${projection} USING fts5(${quoteIdent(FTS_SOURCE_ID_COLUMN)} UNINDEXED,${indexedColumns.join(', ')},tokenize='${tokenizer}')`);
     const mapping = quoteIdent(`_syncular_fts_${index.name}`);
     const mapped = db.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", [
         `_syncular_fts_${index.name}`,
     ]).length > 0;
-    db.exec(`CREATE TABLE IF NOT EXISTS ${mapping} (id INTEGER PRIMARY KEY, source_id TEXT NOT NULL UNIQUE)`);
-    const sourceId = `CAST(${quoteIdent(table.primaryKey)} AS TEXT)`;
-    const newSourceId = `CAST(new.${quoteIdent(table.primaryKey)} AS TEXT)`;
-    const oldSourceId = `CAST(old.${quoteIdent(table.primaryKey)} AS TEXT)`;
+    db.exec(`CREATE TABLE IF NOT EXISTS ${mapping}(id INTEGER PRIMARY KEY,source_id TEXT NOT NULL UNIQUE)`);
+    const sourceId = `CAST(${primaryKey} AS TEXT)`;
+    const newSourceId = `CAST(new.${primaryKey} AS TEXT)`;
+    const oldSourceId = `CAST(old.${primaryKey} AS TEXT)`;
     const projectionColumns = [
         quoteIdent(FTS_SOURCE_ID_COLUMN),
         ...indexedColumns,
@@ -265,9 +261,9 @@ function createFtsProjection(db, table, index) {
         newSourceId,
         ...index.columns.map((column) => `new.${quoteIdent(column)}`),
     ].join(', ');
-    const deleteFor = (value) => `DELETE FROM ${quoteIdent(index.name)} WHERE rowid = (SELECT id FROM ${mapping} WHERE source_id = ${value}); DELETE FROM ${mapping} WHERE source_id = ${value}`;
-    const deleteDisplaced = (select) => `DELETE FROM ${quoteIdent(index.name)} WHERE rowid IN (SELECT id FROM ${mapping} WHERE source_id IN (${select})); DELETE FROM ${mapping} WHERE source_id IN (${select})`;
-    const insertNew = `INSERT INTO ${mapping}(source_id) VALUES (${newSourceId}); INSERT INTO ${quoteIdent(index.name)} (rowid, ${projectionColumns}) VALUES ((SELECT id FROM ${mapping} WHERE source_id = ${newSourceId}), ${newValues})`;
+    const deleteFor = (value) => `DELETE FROM ${projection} WHERE rowid=(SELECT id FROM ${mapping} WHERE source_id=${value});DELETE FROM ${mapping} WHERE source_id=${value}`;
+    const deleteDisplaced = (select) => `DELETE FROM ${projection} WHERE rowid IN (SELECT id FROM ${mapping} WHERE source_id IN (${select}));DELETE FROM ${mapping} WHERE source_id IN (${select})`;
+    const insertNew = `INSERT INTO ${mapping}(source_id)VALUES(${newSourceId});INSERT INTO ${projection}(rowid,${projectionColumns})VALUES((SELECT id FROM ${mapping} WHERE source_id=${newSourceId}),${newValues})`;
     // A clean insert cannot already have a projection row because the source
     // primary key is unique. Keep clean inserts linear by moving replacement
     // cleanup behind indexed source-table existence checks. SQLite does not
@@ -295,7 +291,7 @@ function createFtsProjection(db, table, index) {
     for (const suffix of ['bi', 'ai', 'ad', 'au', 'bu']) {
         db.exec(`DROP TRIGGER IF EXISTS ${quoteIdent(`${index.name}_${suffix}`)}`);
     }
-    const replacementExists = `EXISTS (SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = new.${quoteIdent(table.primaryKey)})`;
+    const replacementExists = `EXISTS (SELECT 1 FROM ${sourceTable} WHERE ${primaryKey} = new.${primaryKey})`;
     // Per secondary UNIQUE index: the different-PK rows about to be displaced
     // via that unique key. `=` makes NULL unique values match nothing, which is
     // exactly SQLite's unique-index semantics (NULLs never conflict).
@@ -304,7 +300,7 @@ function createFtsProjection(db, table, index) {
         const match = spec.columns
             .map((column) => `${quoteIdent(column)} = new.${quoteIdent(column)}`)
             .join(' AND ');
-        return `SELECT ${sourceId} FROM ${quoteIdent(table.name)} WHERE ${match} AND ${quoteIdent(table.primaryKey)} != new.${quoteIdent(table.primaryKey)}`;
+        return `SELECT ${sourceId} FROM ${sourceTable} WHERE ${match} AND ${primaryKey} !=new.${primaryKey}`;
     });
     const insertGuardCondition = [
         replacementExists,
@@ -314,10 +310,11 @@ function createFtsProjection(db, table, index) {
         deleteFor(newSourceId),
         ...displacedByUnique.map(deleteDisplaced),
     ].join('; ');
-    db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_bi`)} BEFORE INSERT ON ${quoteIdent(table.name)} WHEN ${insertGuardCondition} BEGIN ${insertGuardBody}; END`);
-    db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_ai`)} AFTER INSERT ON ${quoteIdent(table.name)} BEGIN ${insertNew}; END`);
-    db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_ad`)} AFTER DELETE ON ${quoteIdent(table.name)} BEGIN ${deleteFor(oldSourceId)}; END`);
-    db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_au`)} AFTER UPDATE ON ${quoteIdent(table.name)} BEGIN ${deleteFor(oldSourceId)}; ${deleteFor(newSourceId)}; ${insertNew}; END`);
+    const createTrigger = (suffix, timing, body, when = '') => db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_${suffix}`)} ${timing} ON ${sourceTable}${when ? ` WHEN ${when}` : ''} BEGIN ${body};END`);
+    createTrigger('bi', 'BEFORE INSERT', insertGuardBody, insertGuardCondition);
+    createTrigger('ai', 'AFTER INSERT', insertNew);
+    createTrigger('ad', 'AFTER DELETE', deleteFor(oldSourceId));
+    createTrigger('au', 'AFTER UPDATE', `${deleteFor(oldSourceId)}; ${deleteFor(newSourceId)}; ${insertNew}`);
     // BEFORE UPDATE guard for `UPDATE OR REPLACE`: clear the projection of any
     // different-PK row about to be displaced through a secondary unique index by
     // the new values. Only meaningful when the table has a unique index; with
@@ -327,14 +324,14 @@ function createFtsProjection(db, table, index) {
             .map((select) => `EXISTS (${select})`)
             .join(' OR ');
         const updateGuardBody = displacedByUnique.map(deleteDisplaced).join('; ');
-        db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_bu`)} BEFORE UPDATE ON ${quoteIdent(table.name)} WHEN ${updateGuardCondition} BEGIN ${updateGuardBody}; END`);
+        createTrigger('bu', 'BEFORE UPDATE', updateGuardBody, updateGuardCondition);
     }
     if (!existed) {
-        db.exec(`INSERT INTO ${quoteIdent(index.name)} (${projectionColumns}) SELECT ${sourceId}, ${indexedColumns.join(', ')} FROM ${quoteIdent(table.name)}`);
+        db.exec(`INSERT INTO ${projection}(${projectionColumns})SELECT ${sourceId},${indexedColumns.join(', ')} FROM ${sourceTable}`);
     }
     if (!mapped || !existed) {
         db.exec(`DELETE FROM ${mapping}`);
-        db.exec(`INSERT INTO ${mapping}(id, source_id) SELECT rowid, ${quoteIdent(FTS_SOURCE_ID_COLUMN)} FROM ${quoteIdent(index.name)}`);
+        db.exec(`INSERT INTO ${mapping}(id,source_id)SELECT rowid,${quoteIdent(FTS_SOURCE_ID_COLUMN)} FROM ${projection}`);
     }
 }
 /**
@@ -363,35 +360,18 @@ export function ensureLocalSyncedSchema(db, schema) {
 export function ensureLocalBookkeepingSchema(db) {
     db.transaction(() => {
         ensureFailedOverlaySchema(db);
-        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
-      key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
-        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
-      commit_id TEXT NOT NULL, blob_id TEXT NOT NULL, PRIMARY KEY(commit_id, blob_id))`);
+        const createTable = (name, columns) => db.exec(`CREATE TABLE IF NOT EXISTS ${name}(${columns})`);
+        createTable('_syncular_meta', 'key TEXT PRIMARY KEY,value TEXT NOT NULL');
+        createTable('_syncular_blob_commit_refs', 'commit_id TEXT NOT NULL,blob_id TEXT NOT NULL,PRIMARY KEY(commit_id,blob_id)');
         db.exec('CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body ON _syncular_blob_commit_refs(blob_id)');
-        db.exec(`INSERT OR IGNORE INTO _syncular_meta(key, value) VALUES ('localRevision', '0')`);
-        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_outbox(
-      seq INTEGER PRIMARY KEY AUTOINCREMENT,
-      client_commit_id TEXT NOT NULL UNIQUE,
-      created_at_ms INTEGER NOT NULL,
-      operations TEXT NOT NULL)`);
-        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_outbox_before_images(
-      client_commit_id TEXT NOT NULL,
-      op_index INTEGER NOT NULL,
-      existed INTEGER NOT NULL CHECK(existed IN (0, 1)),
-      sync_version INTEGER,
-      values_json TEXT,
-      PRIMARY KEY(client_commit_id, op_index))`);
-        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes(
-      seq INTEGER PRIMARY KEY AUTOINCREMENT,
-      client_commit_id TEXT NOT NULL UNIQUE,
-      status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
-      recorded_at_ms INTEGER NOT NULL,
-      results TEXT NOT NULL,
-      operations TEXT,
-      resolution TEXT NOT NULL DEFAULT 'active'
-        CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
-      resolved_at_ms INTEGER,
-      replacement_client_commit_id TEXT)`);
+        db.exec("INSERT OR IGNORE INTO _syncular_meta(key,value)VALUES('localRevision','0')");
+        createTable('_syncular_outbox', 'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL');
+        createTable('_syncular_outbox_before_images', 'client_commit_id TEXT NOT NULL,op_index INTEGER NOT NULL,existed INTEGER NOT NULL CHECK(existed IN (0,1)),sync_version INTEGER,values_json TEXT,PRIMARY KEY(client_commit_id,op_index)');
+        if (!db
+            .query('PRAGMA table_info(_syncular_outbox_before_images)')
+            .some((row) => row.name === 'delivery_seq'))
+            db.exec('ALTER TABLE _syncular_outbox_before_images ADD COLUMN delivery_seq INTEGER');
+        createTable('_syncular_commit_outcomes', "seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,status TEXT NOT NULL CHECK(status IN ('applied','cached','conflict','rejected')),recorded_at_ms INTEGER NOT NULL,results TEXT NOT NULL,operations TEXT,resolution TEXT NOT NULL DEFAULT 'active' CHECK(resolution IN ('active','resolved_keep_server','superseded','dismissed')),resolved_at_ms INTEGER,replacement_client_commit_id TEXT");
         // Outcomes created before durable aggregate recovery retain no commit
         // envelope. New failed outcomes store it in the protected client DB.
         try {
@@ -400,32 +380,15 @@ export function ensureLocalBookkeepingSchema(db) {
         catch {
             // column already exists — the CREATE above included it
         }
-        db.exec(`CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
-      ON _syncular_commit_outcomes(resolution, seq)`);
-        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_subscriptions(
-      id TEXT PRIMARY KEY,
-      tbl TEXT NOT NULL,
-      requested_scopes TEXT NOT NULL,
-      params TEXT,
-      cursor INTEGER NOT NULL DEFAULT -1,
-      bootstrap_state TEXT,
-      effective_scopes TEXT,
-      status TEXT NOT NULL DEFAULT 'active',
-      reason_code TEXT)`);
+        db.exec('CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq ON _syncular_commit_outcomes(resolution,seq)');
+        createTable('_syncular_subscriptions', "id TEXT PRIMARY KEY,tbl TEXT NOT NULL,requested_scopes TEXT NOT NULL,params TEXT,cursor INTEGER NOT NULL DEFAULT -1,bootstrap_state TEXT,effective_scopes TEXT,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT");
         // §4.8 window registry: which units (scope values) of a window base are
         // live locally — the completeness oracle (I3) and the shrink driver
         // (a unit's omission from the next pull unregisters it, §4.1).
-        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_windows(
-      base TEXT NOT NULL,
-      unit TEXT NOT NULL,
-      sub_id TEXT NOT NULL,
-      PRIMARY KEY (base, unit))`);
+        createTable('_syncular_windows', 'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)');
         // §4.8 E1: units that left the window but still had outbox-pinned rows.
         // Retried when the outbox drains; cancelled if the unit re-enters.
-        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_window_pending_evict(
-      sub_id TEXT PRIMARY KEY,
-      tbl TEXT NOT NULL,
-      effective_scopes TEXT NOT NULL)`);
+        createTable('_syncular_window_pending_evict', 'sub_id TEXT PRIMARY KEY,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL');
     });
 }
 /** Create both application and protected bookkeeping tables. */
@@ -448,16 +411,12 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
 export function dropAndRecreateSyncedTables(db, schema) {
     // Drop virtual tables first. SQLite then removes their shadow tables as one
     // unit, so the generic discovery below never tears an FTS5 projection apart.
-    const virtualTables = db.query(`SELECT name FROM sqlite_master WHERE type = 'table'
-       AND sql LIKE 'CREATE VIRTUAL TABLE%'
-       AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%'`);
+    const virtualTables = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND sql LIKE 'CREATE VIRTUAL TABLE%' AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%'`);
     for (const row of virtualTables) {
         db.exec(`DROP TABLE IF EXISTS ${quoteIdent(`_syncular_fts_${String(row.name)}`)}`);
         db.exec(`DROP TABLE IF EXISTS ${quoteIdent(String(row.name))}`);
     }
-    const existing = db.query(`SELECT name FROM sqlite_master WHERE type = 'table'
-       AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%'
-       AND name NOT LIKE 'sqlite_%'`);
+    const existing = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%' AND name NOT LIKE 'sqlite_%'`);
     for (const row of existing) {
         db.exec(`DROP TABLE IF EXISTS ${quoteIdent(String(row.name))}`);
     }
@@ -488,14 +447,7 @@ export function fromSqlValue(column, value) {
             return value !== 0 && value !== false;
         case 'integer':
             return typeof value === 'bigint' ? Number(value) : value;
-        case 'float':
-            return value;
-        case 'bytes':
-        case 'crdt':
-            return value;
-        case 'string':
-        case 'json':
-        case 'blob_ref':
+        default:
             return value;
     }
 }
@@ -512,13 +464,13 @@ export function normalizeRecordKeys(table, record) {
         const index = table.columnIndex.get(key) ?? table.columnIndexByCamel.get(key);
         if (index === undefined) {
             if (key.startsWith('_sync_')) {
-                throw invalidRequest(`table ${table.name}: ${JSON.stringify(key)} is an internal sync column and cannot appear in mutation values — did you build this record from a raw SELECT * row? (client.query() strips _sync_* columns; rows read via client.database keep them)`);
+                throw invalidRequest(`table ${table.name}: ${JSON.stringify(key)} is an internal sync column; omit it from mutation values`);
             }
-            throw invalidRequest(`table ${table.name}: unknown column ${JSON.stringify(key)} in mutation values (snake_case and camelCase keys are accepted)`);
+            throw invalidRequest(`table ${table.name}: unknown column ${JSON.stringify(key)} in mutation values`);
         }
         const sqlName = table.columns[index].name;
         if (normalized.has(sqlName)) {
-            throw invalidRequest(`table ${table.name}: column ${JSON.stringify(sqlName)} appears twice in mutation values (as both snake_case and camelCase) — pass it once`);
+            throw invalidRequest(`table ${table.name}: column ${JSON.stringify(sqlName)} appears twice in mutation values`);
         }
         normalized.set(sqlName, value);
     }
@@ -584,3 +536,7 @@ export function jsonToRowValue(value) {
     }
     return value;
 }
+/** Convert each column value without changing the row's presence set. */
+export function mapRowValues(values, convert) {
+    return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, convert(value)]));
+}

package/dist/state.d.ts

@@ -5,6 +5,7 @@
  * exactly for that purpose.
  */
 import type { ScopeMap } from '@syncular/core';
+import type { CompiledClientSchema } from './schema.js';
 import type { ClientDatabase } from './database.js';
 import type { LocalRevision } from './invalidation.js';
 export declare const LOCAL_REVISION_KEY = "localRevision";
@@ -31,21 +32,17 @@ export declare function getSubscription(db: ClientDatabase, id: string): Subscri
 export declare function saveSubscription(db: ClientDatabase, record: SubscriptionRecord): void;
 export declare function deleteSubscription(db: ClientDatabase, id: string): void;
 /**
- * §7.4.3 reset: keep every subscription REGISTRATION (id, table,
+ * §7.4.3 reset: keep compatible subscription REGISTRATIONS (id, table,
  * requested scopes, params — the app's declared intent) but discard all
  * synced state (cursor → -1, no resume token, no effective-scope map,
  * status → active), so the next round fresh-bootstraps exactly the
  * subscriptions the app still wants. Caller owns the transaction.
  */
 export declare function resetSubscriptionsForBump(db: ClientDatabase): void;
-/**
- * Remove registrations whose table no longer exists in the running schema.
- * Keeping one would make every subsequent pull fail with
- * `sync.unknown_table`. Window bookkeeping belongs to the registration and
- * is removed with it. The caller supplies its startup subscription snapshot
- * so pruning and startup-work detection stay a single read.
- */
-export declare function pruneUnknownSubscriptions(db: ClientDatabase, subscriptions: readonly SubscriptionRecord[], tableNames: ReadonlySet<string>): SubscriptionRecord[];
+/** Persist declarations separately from the previous-version row descriptor. */
+export declare function saveSubscriptionScopeSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
+/** Drop incompatible registrations and their windows; never translate scopes. */
+export declare function pruneUnknownSubscriptions(db: ClientDatabase, subscriptions: readonly SubscriptionRecord[], schema: CompiledClientSchema, bump?: boolean): SubscriptionRecord[];
 export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
 export declare function setMeta(db: ClientDatabase, key: string, value: string): void;
 /** Read the durable client-local observer revision (SPEC §7.5). */

package/dist/state.js

@@ -27,16 +27,13 @@ export function loadSubscriptions(db) {
         .map(rowToRecord);
 }
 export function getSubscription(db, id) {
-    const row = db.query('SELECT * FROM _syncular_subscriptions WHERE id = ?', [
+    const row = db.query('SELECT * FROM _syncular_subscriptions WHERE id=?', [
         id,
     ])[0];
     return row === undefined ? undefined : rowToRecord(row);
 }
 export function saveSubscription(db, record) {
-    db.exec(`INSERT OR REPLACE INTO _syncular_subscriptions(
-       id, tbl, requested_scopes, params, cursor, bootstrap_state,
-       effective_scopes, status, reason_code)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+    db.exec('INSERT OR REPLACE INTO _syncular_subscriptions(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)', [
         record.id,
         record.table,
         JSON.stringify(record.scopes),
@@ -51,57 +48,94 @@ export function saveSubscription(db, record) {
     ]);
 }
 export function deleteSubscription(db, id) {
-    db.exec('DELETE FROM _syncular_subscriptions WHERE id = ?', [id]);
+    db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
 }
 /**
- * §7.4.3 reset: keep every subscription REGISTRATION (id, table,
+ * §7.4.3 reset: keep compatible subscription REGISTRATIONS (id, table,
  * requested scopes, params — the app's declared intent) but discard all
  * synced state (cursor → -1, no resume token, no effective-scope map,
  * status → active), so the next round fresh-bootstraps exactly the
  * subscriptions the app still wants. Caller owns the transaction.
  */
 export function resetSubscriptionsForBump(db) {
-    db.exec(`UPDATE _syncular_subscriptions
-       SET cursor = -1, bootstrap_state = NULL, effective_scopes = NULL,
-           status = 'active', reason_code = NULL`);
+    db.exec("UPDATE _syncular_subscriptions SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL");
 }
-/**
- * Remove registrations whose table no longer exists in the running schema.
- * Keeping one would make every subsequent pull fail with
- * `sync.unknown_table`. Window bookkeeping belongs to the registration and
- * is removed with it. The caller supplies its startup subscription snapshot
- * so pruning and startup-work detection stay a single read.
- */
-export function pruneUnknownSubscriptions(db, subscriptions, tableNames) {
-    const retained = subscriptions.filter((record) => tableNames.has(record.table));
-    const staleIds = subscriptions
-        .filter((record) => !tableNames.has(record.table))
-        .map((record) => record.id);
-    // A redundant subscription scan plus an empty write transaction cut the
-    // fresh-client bootstrap lane by more than half on bun:sqlite. The supplied
-    // snapshot and this branch are synchronous, so no application work can
-    // interleave before a real pruning transaction begins.
-    if (staleIds.length === 0)
+/** Persist declarations separately from the previous-version row descriptor. */
+export function saveSubscriptionScopeSchema(db, schema) {
+    const declarations = {};
+    for (const table of schema.tables.values()) {
+        declarations[table.name] = Object.fromEntries([...table.scopeColumnByVariable].map(([variable, column]) => [
+            variable,
+            [table.scopePrefixByVariable.get(variable), column],
+        ]));
+    }
+    setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
+}
+/** Drop incompatible registrations and their windows; never translate scopes. */
+export function pruneUnknownSubscriptions(db, subscriptions, schema, bump = false) {
+    const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
+    const previous = stored === undefined
+        ? undefined
+        : JSON.parse(stored);
+    const compatible = (record) => {
+        const table = schema.tables.get(record.table);
+        if (table === undefined)
+            return false;
+        const variables = Object.keys(record.scopes);
+        if (!variables.every((variable) => table.scopeColumnByVariable.has(variable)))
+            return false;
+        if (!bump)
+            return true;
+        // An old binary stored no declaration evidence. Re-registration is required
+        // at a bump: matching names cannot prove unchanged column/prefix meaning.
+        const old = previous?.[record.table];
+        if (old === undefined)
+            return false;
+        const compared = variables.length === 0
+            ? [
+                ...new Set([
+                    ...Object.keys(old),
+                    ...table.scopeColumnByVariable.keys(),
+                ]),
+            ]
+            : variables;
+        return compared.every((variable) => old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
+            old[variable]?.[1] === table.scopeColumnByVariable.get(variable));
+    };
+    const retained = subscriptions.filter(compatible);
+    const staleIds = new Set(subscriptions
+        .filter((record) => !compatible(record))
+        .map((record) => record.id));
+    // Shrinking a pinned window already removed its registration. Its deferred
+    // eviction still carries the old scope declaration and needs the same fence.
+    for (const row of db.query('SELECT sub_id,tbl,effective_scopes FROM _syncular_window_pending_evict')) {
+        if (!compatible({
+            table: String(row.tbl),
+            scopes: JSON.parse(String(row.effective_scopes)),
+        }))
+            staleIds.add(String(row.sub_id));
+    }
+    if (staleIds.size === 0)
         return retained;
     db.transaction(() => {
         for (const id of staleIds) {
-            db.exec('DELETE FROM _syncular_windows WHERE sub_id = ?', [id]);
-            db.exec('DELETE FROM _syncular_window_pending_evict WHERE sub_id = ?', [
+            db.exec('DELETE FROM _syncular_windows WHERE sub_id=?', [id]);
+            db.exec('DELETE FROM _syncular_window_pending_evict WHERE sub_id=?', [
                 id,
             ]);
-            db.exec('DELETE FROM _syncular_subscriptions WHERE id = ?', [id]);
+            db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
         }
     });
     return retained;
 }
 export function getMeta(db, key) {
-    const row = db.query('SELECT value FROM _syncular_meta WHERE key = ?', [
+    const row = db.query('SELECT value FROM _syncular_meta WHERE key=?', [
         key,
     ])[0];
     return row === undefined ? undefined : row.value;
 }
 export function setMeta(db, key, value) {
-    db.exec('INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?, ?)', [
+    db.exec('INSERT OR REPLACE INTO _syncular_meta(key,value)VALUES(?,?)', [
         key,
         value,
     ]);