@syncular/client 0.30.12 → 0.30.14

package/dist/failed-overlay.d.ts

@@ -10,6 +10,9 @@ export declare function retainedBaseWrite(db: ClientDatabase, table: CompiledCli
 export declare function retainFailedRows(db: ClientDatabase, commit: OutboxCommit, images: readonly OutboxBeforeImage[], commitSeq?: number): void;
 /** Match declared keys through SQLite, preserving index affinity and NULL semantics. */
 export declare function uniqueConflicts(db: ClientDatabase, table: CompiledClientTable, values: Readonly<Record<string, RowValue>>): NonNullable<RetainedCommitRow['uniqueConflicts']>;
-export declare function restoreFailedBases(db: ClientDatabase, schema: CompiledClientSchema, absentIntent?: boolean, rowKeys?: readonly string[]): boolean;
-export declare function failedOverlayCommits(db: ClientDatabase, acknowledged?: boolean, rowKeys?: readonly string[]): OutboxCommit[];
-export declare function dropFailedRows(db: ClientDatabase, matches: (table: string, values: Readonly<Record<string, JsonRowValue>>) => boolean): OutboxCommit[];
+/** Exact row keys are JSON [table,id]; table scopes include unique-key peers. */
+export type OverlayScope = readonly string[];
+export declare function overlayScopePredicate(table: string, id: string): string;
+export declare function restoreFailedBases(db: ClientDatabase, schema: CompiledClientSchema, scope?: OverlayScope): boolean;
+export declare function failedOverlayCommits(db: ClientDatabase, acknowledged?: boolean, scope?: OverlayScope, schema?: CompiledClientSchema): OutboxCommit[];
+export declare function dropFailedRows(db: ClientDatabase, schema: CompiledClientSchema, matches: (table: string, values: Readonly<Record<string, JsonRowValue>>) => boolean): OutboxCommit[];

package/dist/failed-overlay.js

@@ -1,3 +1,6 @@
+import { hasUniqueIndex } from './schema.js';
+import { OUTCOMES_TABLE } from './outcomes.js';
+import { OUTBOX_TABLE } from './outbox.js';
 export const RETAINED_ROWS = '_syncular_failed_rows';
 import { ClientSyncError } from './errors.js';
 import { mapRowValues, fromSqlValue, jsonToRowValue, quoteIdent, rowValueToJson, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
@@ -17,7 +20,7 @@ export function retainedBaseWrite(db, table, rowId, values, version) {
         table.name,
         rowId,
     ]);
-    if (!table.indexes.some((index) => index.unique))
+    if (!hasUniqueIndex(table))
         return;
     for (const retained of db.query(`SELECT commit_id,idx,intent,unique_conflicts FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq IS NULL`, [table.name])) {
         const prior = retained.unique_conflicts === null
@@ -87,28 +90,54 @@ export function uniqueConflicts(db, table, values) {
         serverVersion: Number(row[SYNC_VERSION_COLUMN]),
     })));
 }
-function retainedRows(db, rowKeys) {
-    return db.query(`SELECT * FROM ${RETAINED_ROWS} WHERE ?1 IS NULL OR json_array(tbl,id) IN(SELECT value FROM json_each(?1)) ORDER BY commit_seq,at,commit_id,idx`, [rowKeys ? JSON.stringify(rowKeys) : null]);
+export function overlayScopePredicate(table, id) {
+    return `?1 IS NULL OR json_array(${table},${id}) IN(SELECT value FROM json_each(?1)) OR json_array(${table}) IN(SELECT value FROM json_each(?1))`;
 }
-export function restoreFailedBases(db, schema, absentIntent = false, rowKeys) {
+function retainedRows(db, scope, acknowledged) {
+    return db.query(`SELECT * FROM ${RETAINED_ROWS} WHERE (${overlayScopePredicate('tbl', 'id')})${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`, [scope ? JSON.stringify(scope) : null]);
+}
+function retainedTable(schema, name) {
+    const table = schema.tables.get(name);
+    if (!table)
+        throw new ClientSyncError('sync.unknown_table', 'retained table is unknown');
+    return table;
+}
+export function restoreFailedBases(db, schema, scope) {
     const seen = new Set();
-    for (const row of retainedRows(db, rowKeys)) {
+    for (const row of retainedRows(db, scope)) {
         const key = JSON.stringify([row.tbl, row.id]);
-        if (!absentIntent && seen.has(key))
+        if (seen.has(key))
             continue;
         seen.add(key);
-        const table = schema.tables.get(row.tbl);
-        if (!table)
-            throw new ClientSyncError('sync.unknown_table', 'retained table is unknown');
-        const json = absentIntent ? row.intent : row.base;
-        if (absentIntent && row.intent !== null) {
-            const values = JSON.parse(row.intent);
-            const conflicts = uniqueConflicts(db, table, mapRowValues(values, jsonToRowValue));
-            // Hydrate a pre-0.30.11 failure after its winner was already imported.
-            // Pending and retained overlays cannot supply authoritative row evidence.
-            if (row.commit_seq === null && row.unique_conflicts === null) {
-                const authorized = conflicts.filter((conflict) => conflict.serverVersion >= 0 &&
-                    !db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM _syncular_outbox,json_each(operations)WHERE json_extract(json_each.value,'$.table')=? AND json_extract(json_each.value,'$.rowId')=? LIMIT 1`, [table.name, conflict.rowId, table.name, conflict.rowId]).length);
+        const table = retainedTable(schema, row.tbl);
+        if (row.base === null)
+            deleteLocalRow(db, table, row.id, false);
+        else {
+            const values = JSON.parse(String(row.base));
+            upsertLocalRow(db, table, table.columns.map((column) => jsonToRowValue(values[column.name] ?? null)), (row.version ?? -1), false);
+        }
+    }
+    return seen.size > 0;
+}
+export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
+    const commits = new Map();
+    for (const row of retainedRows(db, scope, acknowledged)) {
+        const id = row.commit_id;
+        let operation = JSON.parse(row.op);
+        if (schema && operation.op === 'upsert') {
+            const table = retainedTable(schema, operation.table);
+            if (acknowledged) {
+                if (!db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [operation.rowId]).length)
+                    operation = {
+                        ...operation,
+                        values: JSON.parse(row.intent),
+                    };
+            }
+            else if (row.unique_conflicts === null && row.intent !== null) {
+                // Hydrate legacy failure evidence from authoritative unique-key peers.
+                const values = JSON.parse(row.intent);
+                const authorized = uniqueConflicts(db, table, mapRowValues(values, jsonToRowValue)).filter((conflict) => conflict.serverVersion >= 0 &&
+                    !db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_TABLE},json_each(operations)WHERE json_extract(json_each.value,'$.table')=? AND json_extract(json_each.value,'$.rowId')=? LIMIT 1`, [table.name, conflict.rowId, table.name, conflict.rowId]).length);
                 if (authorized.length)
                     db.exec(`UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`, [
                         JSON.stringify(authorized.map((conflict) => ({
@@ -119,35 +148,7 @@ export function restoreFailedBases(db, schema, absentIntent = false, rowKeys) {
                         row.idx,
                     ]);
             }
-            if (conflicts.length)
-                continue;
-        }
-        if (absentIntent &&
-            (json === null ||
-                db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [row.id]).length))
-            continue;
-        if (json === null)
-            deleteLocalRow(db, table, row.id, false);
-        else {
-            const values = JSON.parse(String(json));
-            if (absentIntent) {
-                const operation = JSON.parse(row.op);
-                if (row.commit_seq === null &&
-                    !table.columns.every((column) => Object.hasOwn(operation.values ?? {}, column.name)))
-                    continue;
-            }
-            upsertLocalRow(db, table, table.columns.map((column) => jsonToRowValue(values[column.name] ?? null)), (row.version ?? -1), false);
         }
-    }
-    return seen.size > 0;
-}
-export function failedOverlayCommits(db, acknowledged = false, rowKeys) {
-    const commits = new Map();
-    for (const row of retainedRows(db, rowKeys)) {
-        if ((row.commit_seq !== null) !== acknowledged)
-            continue;
-        const id = row.commit_id;
-        const operation = JSON.parse(row.op);
         const prior = commits.get(id);
         if (prior)
             prior.operations.push(operation);
@@ -161,7 +162,7 @@ export function failedOverlayCommits(db, acknowledged = false, rowKeys) {
     }
     return [...commits.values()];
 }
-export function dropFailedRows(db, matches) {
+export function dropFailedRows(db, schema, matches) {
     const ids = new Set();
     for (const row of retainedRows(db)) {
         for (const json of [row.intent, row.base]) {
@@ -176,9 +177,10 @@ export function dropFailedRows(db, matches) {
         ...failedOverlayCommits(db),
         ...failedOverlayCommits(db, true),
     ].filter((commit) => ids.has(commit.clientCommitId));
+    restoreFailedBases(db, schema, dropped.flatMap((commit) => commit.operations.map((op) => JSON.stringify([op.table, op.rowId]))));
     for (const id of ids) {
         db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [id]);
-        db.exec("UPDATE _syncular_commit_outcomes SET operations=NULL,results='[]' WHERE client_commit_id=?", [id]);
+        db.exec(`UPDATE ${OUTCOMES_TABLE} SET operations=NULL,results='[]' WHERE client_commit_id=?`, [id]);
     }
     return dropped;
 }

package/dist/outbox.d.ts

@@ -1,3 +1,6 @@
+export declare const OUTBOX_TABLE = "_syncular_outbox";
+export declare const OUTBOX_IMAGES = "_syncular_outbox_before_images";
+import { type OverlayScope } from './failed-overlay.js';
 /**
  * The durable outbox (SPEC.md §7.1) with encode-at-send (the §0 binary-push
  * outbox rule): local mutations are persisted in a schema-agnostic JSON
@@ -40,7 +43,7 @@ export interface OutboxBeforeImage {
 }
 export declare function appendOutboxCommit(db: ClientDatabase, clientCommitId: string, operations: readonly OutboxOperation[], nowMs: number, beforeImages?: readonly OutboxBeforeImage[]): void;
 /** Pending commits in FIFO creation order (§7.1). Full reads serve replay and the public listing. */
-export declare function listOutbox(db: ClientDatabase, rowKeys?: readonly string[]): OutboxCommit[];
+export declare function listOutbox(db: ClientDatabase, scope?: OverlayScope): OutboxCommit[];
 /** Keyset pages bound staging; laziness decodes only commits consumed by the encoder. */
 export declare function iterateOutbox(db: ClientDatabase, throughSeq: number): Generator<OutboxCommit>;
 /** Routine status reads never load operation bodies. */

package/dist/outbox.js

@@ -1,3 +1,7 @@
+import { BLOB_COMMIT_REFS } from './blob.js';
+export const OUTBOX_TABLE = '_syncular_outbox';
+export const OUTBOX_IMAGES = '_syncular_outbox_before_images';
+import { overlayScopePredicate } from './failed-overlay.js';
 /**
  * The durable outbox (SPEC.md §7.1) with encode-at-send (the §0 binary-push
  * outbox rule): local mutations are persisted in a schema-agnostic JSON
@@ -12,15 +16,15 @@ export function appendOutboxCommit(db, clientCommitId, operations, nowMs, before
     if (operations.length === 0) {
         throw new ClientSyncError('sync.empty_commit', 'a local commit must carry at least one operation (§6.1)');
     }
-    db.exec('INSERT INTO _syncular_outbox(client_commit_id,created_at_ms,operations)VALUES(?,?,?)', [clientCommitId, nowMs, JSON.stringify(operations)]);
+    db.exec(`INSERT INTO ${OUTBOX_TABLE}(client_commit_id,created_at_ms,operations)VALUES(?,?,?)`, [clientCommitId, nowMs, JSON.stringify(operations)]);
     replaceOutboxBeforeImages(db, clientCommitId, beforeImages);
 }
 /** Pending commits in FIFO creation order (§7.1). Full reads serve replay and the public listing. */
-export function listOutbox(db, rowKeys) {
+export function listOutbox(db, scope) {
     return db
-        .query(rowKeys === undefined
-        ? 'SELECT seq, client_commit_id, created_at_ms, operations FROM _syncular_outbox ORDER BY seq ASC'
-        : "SELECT * FROM _syncular_outbox WHERE EXISTS(SELECT 1 FROM json_each(operations) WHERE json_array(json_extract(value,'$.table'),json_extract(value,'$.rowId')) IN(SELECT value FROM json_each(?))) ORDER BY seq", rowKeys && [JSON.stringify(rowKeys)])
+        .query(scope === undefined
+        ? `SELECT * FROM ${OUTBOX_TABLE} ORDER BY seq ASC`
+        : `SELECT * FROM ${OUTBOX_TABLE} WHERE EXISTS(SELECT 1 FROM json_each(operations) WHERE ${overlayScopePredicate("json_extract(value,'$.table')", "json_extract(value,'$.rowId')")}) ORDER BY seq`, scope && [JSON.stringify(scope)])
         .map(decodeOutboxRow);
 }
 function decodeOutboxRow(row) {
@@ -35,7 +39,7 @@ function decodeOutboxRow(row) {
 export function* iterateOutbox(db, throughSeq) {
     let afterSeq = 0;
     while (afterSeq < throughSeq) {
-        const rows = db.query('SELECT seq, client_commit_id, created_at_ms, operations FROM _syncular_outbox WHERE seq > ? AND seq <= ? ORDER BY seq ASC LIMIT 32', [afterSeq, throughSeq]);
+        const rows = db.query(`SELECT * FROM ${OUTBOX_TABLE} WHERE seq > ? AND seq <= ? ORDER BY seq ASC LIMIT 32`, [afterSeq, throughSeq]);
         if (rows.length === 0)
             return;
         for (const row of rows) {
@@ -47,21 +51,23 @@ export function* iterateOutbox(db, throughSeq) {
 }
 /** Routine status reads never load operation bodies. */
 export function countOutbox(db) {
-    return db.query('SELECT COUNT(*)AS count FROM _syncular_outbox')[0]
+    return db.query(`SELECT COUNT(*)AS count FROM ${OUTBOX_TABLE}`)[0]
         .count;
 }
 export function deleteOutboxCommit(db, clientCommitId) {
-    db.exec('DELETE FROM _syncular_blob_commit_refs WHERE commit_id=?', [
+    db.exec(`DELETE FROM ${BLOB_COMMIT_REFS} WHERE commit_id=?`, [
         clientCommitId,
     ]);
-    db.exec('DELETE FROM _syncular_outbox_before_images WHERE client_commit_id=?', [clientCommitId]);
-    db.exec('DELETE FROM _syncular_outbox WHERE client_commit_id=?', [
+    db.exec(`DELETE FROM ${OUTBOX_IMAGES} WHERE client_commit_id=?`, [
+        clientCommitId,
+    ]);
+    db.exec(`DELETE FROM ${OUTBOX_TABLE} WHERE client_commit_id=?`, [
         clientCommitId,
     ]);
 }
 export function listOutboxBeforeImages(db, clientCommitId) {
     return db
-        .query('SELECT op_index,existed,sync_version,values_json,delivery_seq FROM _syncular_outbox_before_images WHERE client_commit_id=? ORDER BY op_index', [clientCommitId])
+        .query(`SELECT op_index,existed,sync_version,values_json,delivery_seq FROM ${OUTBOX_IMAGES} WHERE client_commit_id=? ORDER BY op_index`, [clientCommitId])
         .map((row) => ({
         opIndex: row.op_index,
         existed: row.existed === 1,
@@ -80,7 +86,7 @@ export function listOutboxBeforeImages(db, clientCommitId) {
 }
 export function replaceOutboxBeforeImages(db, clientCommitId, replacements) {
     for (const image of replacements) {
-        db.exec('INSERT INTO _syncular_outbox_before_images(client_commit_id,op_index,existed,sync_version,values_json)VALUES(?,?,?,?,?) ON CONFLICT(client_commit_id,op_index)DO UPDATE SET existed=excluded.existed,sync_version=excluded.sync_version,values_json=excluded.values_json', [
+        db.exec(`INSERT INTO ${OUTBOX_IMAGES}(client_commit_id,op_index,existed,sync_version,values_json)VALUES(?,?,?,?,?) ON CONFLICT(client_commit_id,op_index)DO UPDATE SET existed=excluded.existed,sync_version=excluded.sync_version,values_json=excluded.values_json`, [
             clientCommitId,
             image.opIndex,
             image.existed ? 1 : 0,

package/dist/outcomes.d.ts

@@ -1,3 +1,4 @@
+export declare const OUTCOMES_TABLE = "_syncular_commit_outcomes";
 /**
  * Durable per-client commit outcomes.
  *

package/dist/outcomes.js

@@ -1,3 +1,5 @@
+export const OUTCOMES_TABLE = '_syncular_commit_outcomes';
+const SELECT_OUTCOME = `SELECT * FROM ${OUTCOMES_TABLE}`;
 import { RETAINED_ROWS } from './failed-overlay.js';
 import { ClientSyncError } from './errors.js';
 import { mapRowValues, jsonToRowValue, rowValueToJson, } from './schema.js';
@@ -74,7 +76,7 @@ function parseOutcome(db, row) {
     };
 }
 export function recordCommitOutcome(db, outcome) {
-    db.exec("INSERT INTO _syncular_commit_outcomes(client_commit_id,status,recorded_at_ms,results,operations,resolution)VALUES(?,?,?,?,?,'active')", [
+    db.exec(`INSERT INTO ${OUTCOMES_TABLE}(client_commit_id,status,recorded_at_ms,results,operations,resolution)VALUES(?,?,?,?,?,'active')`, [
         outcome.clientCommitId,
         outcome.status,
         outcome.recordedAtMs,
@@ -86,7 +88,9 @@ export function recordCommitOutcome(db, outcome) {
     return commitOutcome(db, outcome.clientCommitId);
 }
 export function commitOutcome(db, clientCommitId) {
-    const row = db.query('SELECT seq,client_commit_id,status,recorded_at_ms,results,operations,resolution,resolved_at_ms,replacement_client_commit_id FROM _syncular_commit_outcomes WHERE client_commit_id=?', [clientCommitId])[0];
+    const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
+        clientCommitId,
+    ])[0];
     return row === undefined ? undefined : parseOutcome(db, row);
 }
 export function listCommitOutcomes(db, query = {}) {
@@ -97,11 +101,11 @@ export function listCommitOutcomes(db, query = {}) {
     const where = query.activeOnly
         ? "WHERE resolution = 'active' AND status IN ('conflict', 'rejected')"
         : '';
-    const rows = db.query(`SELECT seq,client_commit_id,status,recorded_at_ms,results,operations,resolution,resolved_at_ms,replacement_client_commit_id FROM _syncular_commit_outcomes ${where} ORDER BY seq DESC${limit === undefined ? '' : ' LIMIT ?'}`, limit === undefined ? [] : [limit]);
+    const rows = db.query(`${SELECT_OUTCOME} ${where} ORDER BY seq DESC${limit === undefined ? '' : ' LIMIT ?'}`, limit === undefined ? [] : [limit]);
     return rows.map((row) => parseOutcome(db, row));
 }
 export function persistCommitOutcomeResolution(db, input, nowMs) {
-    db.exec("UPDATE _syncular_commit_outcomes SET resolution=?,resolved_at_ms=?,replacement_client_commit_id=? WHERE client_commit_id=? AND resolution='active'", [
+    db.exec(`UPDATE ${OUTCOMES_TABLE} SET resolution=?,resolved_at_ms=?,replacement_client_commit_id=? WHERE client_commit_id=? AND resolution='active'`, [
         input.resolution,
         nowMs,
         input.replacementClientCommitId ?? null,
@@ -117,13 +121,14 @@ export function pruneCommitOutcomes(db, maxEntries) {
     if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
         throw new ClientSyncError('sync.invalid_request', 'outcome retention maxEntries must be a positive safe integer');
     }
-    const count = db.query('SELECT COUNT(*) AS count FROM _syncular_commit_outcomes')[0]?.count;
+    const count = db.query(`SELECT COUNT(*) AS count FROM ${OUTCOMES_TABLE}`)[0]
+        ?.count;
     const excess = Math.max(0, (count ?? 0) - maxEntries);
     if (excess === 0)
         return 0;
-    const candidates = db.query("SELECT seq FROM _syncular_commit_outcomes WHERE status IN('applied','cached')OR resolution !='active' ORDER BY seq ASC LIMIT ?", [excess]);
+    const candidates = db.query(`SELECT seq FROM ${OUTCOMES_TABLE} WHERE status IN('applied','cached')OR resolution !='active' ORDER BY seq ASC LIMIT ?`, [excess]);
     for (const candidate of candidates) {
-        db.exec('DELETE FROM _syncular_commit_outcomes WHERE seq=?', [
+        db.exec(`DELETE FROM ${OUTCOMES_TABLE} WHERE seq=?`, [
             candidate.seq,
         ]);
     }

package/dist/previous-version.js

@@ -1,7 +1,7 @@
 import { ClientSyncError } from './errors.js';
 import { INVALID_HOST_RESPONSE_CODE } from './local-rebootstrap.js';
 import { fromSqlValue, jsonToRowValue, localColumnType, quoteIdent, rowValueToJson, } from './schema.js';
-import { getMeta, setMeta } from './state.js';
+import { getMeta, setMeta, META_TABLE } from './state.js';
 /** `_syncular_meta` key holding the persisted {@link LocalSchemaDescriptor}. */
 const LOCAL_SCHEMA_DESCRIPTOR_KEY = 'localSchemaDescriptor';
 /**
@@ -441,7 +441,7 @@ export function writePreviousVersionRefusal(db, reason, measurement) {
 }
 /** Delete the durable refusal. Part of the orphan sweep and of a successful capture. */
 export function clearPreviousVersionRefusal(db) {
-    db.exec('DELETE FROM _syncular_meta WHERE key=?', [
+    db.exec(`DELETE FROM ${META_TABLE} WHERE key=?`, [
         PREVIOUS_VERSION_CONTEXT_KEY,
     ]);
 }
@@ -575,7 +575,7 @@ export function writePreviousVersionAudit(db, audit) {
 }
 /** Delete the advisory audit. Part of a discard, never of a normal bump. */
 export function clearPreviousVersionAudit(db) {
-    db.exec('DELETE FROM _syncular_meta WHERE key=?', [
+    db.exec(`DELETE FROM ${META_TABLE} WHERE key=?`, [
         PREVIOUS_VERSION_AUDIT_KEY,
     ]);
 }

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 hasUniqueIndex(table: CompiledClientTable): boolean;
 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;
 /**

package/dist/schema.js

@@ -1,3 +1,9 @@
+import { BLOB_COMMIT_REFS } from './blob.js';
+import { PENDING_EVICTIONS } from './window.js';
+import { WINDOWS_TABLE } from './window.js';
+import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox.js';
+import { OUTCOMES_TABLE } from './outcomes.js';
+import { SUBSCRIPTIONS_TABLE, META_TABLE } from './state.js';
 import { ensureFailedOverlaySchema } from './failed-overlay.js';
 import { invalidRequest } from './errors.js';
 import { snakeToCamel } from './naming.js';
@@ -156,6 +162,9 @@ export function stripSyncColumns(rows) {
         return copy;
     });
 }
+export function hasUniqueIndex(table) {
+    return table.indexes.some((index) => index.unique);
+}
 export function matchesLocalScopes(table, scopes, values) {
     const entries = Object.entries(scopes);
     return (entries.length > 0 &&
@@ -361,34 +370,34 @@ export function ensureLocalBookkeepingSchema(db) {
     db.transaction(() => {
         ensureFailedOverlaySchema(db);
         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')");
-        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(META_TABLE, 'key TEXT PRIMARY KEY,value TEXT NOT NULL');
+        createTable(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 ${BLOB_COMMIT_REFS}_body ON ${BLOB_COMMIT_REFS}(blob_id)`);
+        db.exec(`INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`);
+        createTable(OUTBOX_TABLE, 'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL');
+        createTable(OUTBOX_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)')
+            .query(`PRAGMA table_info(${OUTBOX_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");
+            db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN delivery_seq INTEGER`);
+        createTable(OUTCOMES_TABLE, "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 {
-            db.exec('ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations TEXT');
+            db.exec(`ALTER TABLE ${OUTCOMES_TABLE} ADD COLUMN operations TEXT`);
         }
         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)');
-        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");
+        db.exec(`CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`);
+        createTable(SUBSCRIPTIONS_TABLE, "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).
-        createTable('_syncular_windows', 'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)');
+        createTable(WINDOWS_TABLE, '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.
-        createTable('_syncular_window_pending_evict', 'sub_id TEXT PRIMARY KEY,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL');
+        createTable(PENDING_EVICTIONS, 'sub_id TEXT PRIMARY KEY,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL');
     });
 }
 /** Create both application and protected bookkeeping tables. */

package/dist/state.d.ts

@@ -1,3 +1,5 @@
+export declare const META_TABLE = "_syncular_meta";
+export declare const SUBSCRIPTIONS_TABLE = "_syncular_subscriptions";
 /**
  * Durable client sync state: per-subscription cursor, bootstrap resume
  * token (round-tripped opaquely, §4.7), and the last-echoed effective

package/dist/state.js

@@ -1,3 +1,7 @@
+export const META_TABLE = '_syncular_meta';
+import { PENDING_EVICTIONS } from './window.js';
+import { WINDOWS_TABLE } from './window.js';
+export const SUBSCRIPTIONS_TABLE = '_syncular_subscriptions';
 export const LOCAL_REVISION_KEY = 'localRevision';
 const MAX_U64 = 18446744073709551615n;
 function rowToRecord(row) {
@@ -23,17 +27,17 @@ function rowToRecord(row) {
 }
 export function loadSubscriptions(db) {
     return db
-        .query('SELECT * FROM _syncular_subscriptions ORDER BY rowid ASC')
+        .query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} ORDER BY rowid ASC`)
         .map(rowToRecord);
 }
 export function getSubscription(db, id) {
-    const row = db.query('SELECT * FROM _syncular_subscriptions WHERE id=?', [
+    const row = db.query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} 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 ${SUBSCRIPTIONS_TABLE}(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)`, [
         record.id,
         record.table,
         JSON.stringify(record.scopes),
@@ -48,7 +52,7 @@ export function saveSubscription(db, record) {
     ]);
 }
 export function deleteSubscription(db, id) {
-    db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
+    db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
 }
 /**
  * §7.4.3 reset: keep compatible subscription REGISTRATIONS (id, table,
@@ -58,7 +62,7 @@ export function deleteSubscription(db, id) {
  * 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 ${SUBSCRIPTIONS_TABLE} SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL`);
 }
 /** Persist declarations separately from the previous-version row descriptor. */
 export function saveSubscriptionScopeSchema(db, schema) {
@@ -108,7 +112,7 @@ export function pruneUnknownSubscriptions(db, subscriptions, schema, bump = fals
         .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')) {
+    for (const row of db.query(`SELECT sub_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`)) {
         if (!compatible({
             table: String(row.tbl),
             scopes: JSON.parse(String(row.effective_scopes)),
@@ -119,23 +123,19 @@ export function pruneUnknownSubscriptions(db, subscriptions, schema, bump = fals
         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=?', [
-                id,
-            ]);
-            db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
+            db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
+            db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id=?`, [id]);
+            db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
         }
     });
     return retained;
 }
 export function getMeta(db, key) {
-    const row = db.query('SELECT value FROM _syncular_meta WHERE key=?', [
-        key,
-    ])[0];
+    const row = db.query(`SELECT value FROM ${META_TABLE} 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 ${META_TABLE}(key,value)VALUES(?,?)`, [
         key,
         value,
     ]);

package/dist/window.d.ts

@@ -1,3 +1,5 @@
+export declare const PENDING_EVICTIONS = "_syncular_window_pending_evict";
+export declare const WINDOWS_TABLE = "_syncular_windows";
 /**
  * Windowed subscriptions (SPEC.md §4.8).
  *

package/dist/window.js

@@ -1,3 +1,5 @@
+export const PENDING_EVICTIONS = '_syncular_window_pending_evict';
+export const WINDOWS_TABLE = '_syncular_windows';
 /**
  * Windowed subscriptions (SPEC.md §4.8).
  *
@@ -88,12 +90,12 @@ export async function deriveSubId(base, unit) {
 /** Live units for a base, ordered by unit value. */
 export function loadWindowUnits(db, baseKey) {
     return db
-        .query('SELECT unit, sub_id FROM _syncular_windows WHERE base = ? ORDER BY unit ASC', [baseKey])
+        .query(`SELECT unit,sub_id FROM ${WINDOWS_TABLE} WHERE base=? ORDER BY unit`, [baseKey])
         .map((row) => ({ unit: row.unit, subId: row.sub_id }));
 }
 /** Registry lookup used to emit exact completion changes for a sub id. */
 export function getWindowUnitBySubId(db, subId) {
-    const row = db.query(`SELECT base, unit, sub_id FROM _syncular_windows
+    const row = db.query(`SELECT base, unit, sub_id FROM ${WINDOWS_TABLE}
       WHERE sub_id = ? LIMIT 1`, [subId])[0];
     return row === undefined
         ? undefined
@@ -104,30 +106,31 @@ export function getWindowUnitBySubId(db, subId) {
         };
 }
 export function insertWindowUnit(db, baseKey, unit, subId) {
-    db.exec('INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?, ?, ?)', [baseKey, unit, subId]);
+    db.exec(`INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`, [baseKey, unit, subId]);
 }
 export function deleteWindowUnit(db, baseKey, unit) {
-    db.exec('DELETE FROM _syncular_windows WHERE base = ? AND unit = ?', [
+    db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE base=? AND unit=?`, [
         baseKey,
         unit,
     ]);
 }
 /** Is a single scope value windowed-in for this base? (the oracle, I3) */
 export function isUnitLive(db, baseKey, unit) {
-    return (db.query('SELECT 1 FROM _syncular_windows WHERE base = ? AND unit = ? LIMIT 1', [baseKey, unit]).length > 0);
+    return (db.query(`SELECT 1 FROM ${WINDOWS_TABLE} WHERE base=? AND unit=? LIMIT 1`, [
+        baseKey,
+        unit,
+    ]).length > 0);
 }
 export function savePendingEviction(db, subId, table, effective) {
-    db.exec(`INSERT OR REPLACE INTO _syncular_window_pending_evict(sub_id, tbl, effective_scopes)
+    db.exec(`INSERT OR REPLACE INTO ${PENDING_EVICTIONS}(sub_id, tbl, effective_scopes)
        VALUES (?, ?, ?)`, [subId, table, JSON.stringify(effective)]);
 }
 export function deletePendingEviction(db, subId) {
-    db.exec('DELETE FROM _syncular_window_pending_evict WHERE sub_id = ?', [
-        subId,
-    ]);
+    db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id = ?`, [subId]);
 }
 export function loadPendingEvictions(db) {
     return db
-        .query('SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict')
+        .query(`SELECT sub_id, tbl, effective_scopes FROM ${PENDING_EVICTIONS}`)
         .map((row) => ({
         subId: row.sub_id,
         table: row.tbl,