@syncular/client 0.30.10 → 0.30.11

package/dist/schema.js

@@ -14,6 +14,7 @@ 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)}`);
         }
@@ -24,13 +25,13 @@ export function compileClientSchema(schema) {
         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)}`);
+                throw new Error(`${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`);
+            throw new Error(`${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
@@ -41,10 +42,10 @@ export function compileClientSchema(schema) {
             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`);
+            throw new Error(`${tableLabel}: primary key ${JSON.stringify(table.primaryKey)} has an ineligible column type (§2.4); a primary key must be string, integer, boolean, or json`);
         }
         if (table.scopes.length === 0) {
-            throw new Error(`table ${table.name}: every synced table declares at least one scope pattern (§3.1)`);
+            throw new Error(`${tableLabel}: every synced table declares at least one scope pattern (§3.1)`);
         }
         const scopeColumnByVariable = new Map();
         const scopePrefixByVariable = new Map();
@@ -52,17 +53,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}'`);
+                throw new Error(`${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)}`);
+                throw new Error(`${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)`);
+                throw new Error(`${tableLabel}: variable ${JSON.stringify(variable)} maps to two different columns (§3.1)`);
             }
             scopeColumnByVariable.set(variable, column);
             scopePrefixByVariable.set(variable, prefix);
@@ -85,40 +86,41 @@ export function compileClientSchema(schema) {
         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`);
+                throw new Error(`${tableLabel}: 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)}`);
+                    throw new Error(`${tableLabel}: index ${JSON.stringify(index.name)} names unknown column ${JSON.stringify(column)}`);
                 }
             }
         }
         const ftsIndexes = table.ftsIndexes ?? [];
         for (const index of ftsIndexes) {
+            const projectionLabel = `${tableLabel}: FTS projection ${JSON.stringify(index.name)}`;
             if (schemaObjectNames.has(index.name)) {
-                throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} conflicts with another schema object`);
+                throw new Error(`${projectionLabel} 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`);
+                throw new Error(`${projectionLabel} 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)}`);
+                    throw new Error(`${projectionLabel} 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)}`);
+                    throw new Error(`${projectionLabel} 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`);
+                    throw new Error(`${projectionLabel} 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`);
+                throw new Error(`${projectionLabel} tokenizer ${JSON.stringify(index.tokenize)} is not allowlisted`);
             }
         }
         tables.set(table.name, {
@@ -216,7 +218,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 +226,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';
@@ -248,12 +250,12 @@ function createFtsProjection(db, table, index) {
     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 ${quoteIdent(index.name)} 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)`);
+    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)`;
@@ -265,9 +267,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 ${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})`;
     // 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
@@ -304,7 +306,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 ${quoteIdent(table.name)} WHERE ${match} AND ${quoteIdent(table.primaryKey)} !=new.${quoteIdent(table.primaryKey)}`;
     });
     const insertGuardCondition = [
         replacementExists,
@@ -314,10 +316,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 ${quoteIdent(table.name)}${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 +330,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 ${quoteIdent(index.name)}(${projectionColumns})SELECT ${sourceId},${indexedColumns.join(', ')} FROM ${quoteIdent(table.name)}`);
     }
     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 ${quoteIdent(index.name)}`);
     }
 }
 /**
@@ -363,35 +366,14 @@ 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)');
+        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 +382,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 +413,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))}`);
     }
@@ -584,3 +545,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,
     ]);

package/dist/wasm-database.js

@@ -22,6 +22,7 @@
  * `ClientDatabase`. Browser-only — exercised by the demo, never imported
  * by bun tests (subpath export `@syncular/client/wasm`).
  */
+import { webLocksLeaderLock } from './leader-lock.js';
 import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
 import { assertImageAlias, runTransaction, } from './database.js';
 import { ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, STORAGE_UNAVAILABLE_CODE, } from './errors.js';
@@ -37,6 +38,7 @@ class WasmClientDatabase {
     #sqlite3;
     /** RFC 0005: present only for a persistent OPFS database. */
     #sah;
+    #closed = false;
     #tx = { depth: 0 };
     constructor(db, sqlite3, sah) {
         this.#db = db;
@@ -128,7 +130,14 @@ class WasmClientDatabase {
         }
     }
     close() {
+        if (this.#closed)
+            return;
         this.#db.close();
+        // DB.close() leaves the SAH pool live. Close siblings first, then pause the
+        // VFS without deleting files, before releasing this worker's physical lock.
+        this.#sah?.util.pauseVfs();
+        this.#closed = true;
+        void this.#sah?.lease.release();
     }
 }
 let sqlite3Init;
@@ -249,35 +258,42 @@ export async function openPersistentWasmDatabase(name, options) {
             'requires OPFS (~2023+ browsers). There is no IndexedDB or ' +
             'in-memory fallback for persistent mode.');
     }
-    const sqlite3 = await initSqlite3();
-    const directory = options?.directory ?? `.syncular/${name}`;
-    let pool = sahPools.get(directory);
-    if (pool === undefined) {
-        pool = sqlite3
-            .installOpfsSAHPoolVfs({
-            // VFS registration names must be unique per directory.
-            name: `syncular-sahpool-${directory.replace(/[^A-Za-z0-9]+/g, '-')}`,
-            directory,
-            // sqlite-wasm caches a rejected initialization promise by VFS name.
-            // Syncular removes its own rejected entry below, so allow a later
-            // open in the same worker to make a real attempt as well.
-            forceReinitIfPreviouslyFailed: true,
-            initialCapacity: Math.max(options?.initialCapacity ?? SAH_POOL_DEFAULT_CAPACITY, SAH_POOL_MIN_CAPACITY),
-        })
-            .catch((error) => {
-            sahPools.delete(directory);
-            throw opfsSahPoolError(error, directory);
-        });
-        sahPools.set(directory, pool);
+    if (!navigator.locks) {
+        throw new ClientSyncError(STORAGE_UNAVAILABLE_CODE, 'Persistent OPFS storage requires Web Locks');
     }
-    const util = await pool;
-    const db = new util.OpfsSAHPoolDb(`/${name}.db`);
+    const directory = (options?.directory ?? `.syncular/${name}`).replace(/^\/+|\/+$/g, '');
+    // The document's leader lease can end before its worker's SAHs close. This
+    // worker-owned lock has exactly the same lifetime as the physical pool.
+    const lease = await webLocksLeaderLock().acquire(`syncular-opfs/${directory}`);
+    let util;
+    let db;
     try {
+        const sqlite3 = await initSqlite3();
+        let pool = sahPools.get(directory);
+        if (pool === undefined) {
+            pool = sqlite3
+                .installOpfsSAHPoolVfs({
+                name: `syncular-sahpool-${directory.replace(/[^A-Za-z0-9]+/g, '-')}`,
+                directory,
+                forceReinitIfPreviouslyFailed: true,
+                initialCapacity: Math.max(options?.initialCapacity ?? SAH_POOL_DEFAULT_CAPACITY, SAH_POOL_MIN_CAPACITY),
+            })
+                .catch((error) => {
+                sahPools.delete(directory);
+                throw opfsSahPoolError(error, directory);
+            });
+            sahPools.set(directory, pool);
+        }
+        util = await pool;
+        await util.unpauseVfs();
+        db = new util.OpfsSAHPoolDb(`/${name}.db`);
         configureSahCrashRecovery(db, sqlite3);
-        return new WasmClientDatabase(db, sqlite3, { util });
+        return new WasmClientDatabase(db, sqlite3, { util, lease });
     }
     catch (error) {
-        db.close();
+        db?.close();
+        util?.pauseVfs();
+        await lease.release();
         throw error;
     }
 }