@syncular/client 0.30.13 → 0.30.15

package/dist/client.js

@@ -1,3 +1,7 @@
+import { BLOB_COMMIT_REFS } from './blob.js';
+import { hasUniqueIndex } from './schema.js';
+import { OUTCOMES_TABLE } from './outcomes.js';
+import { OUTBOX_TABLE } from './outbox.js';
 import { RETAINED_ROWS } from './failed-overlay.js';
 import { dropFailedRows, failedOverlayCommits, retainFailedRows, restoreFailedBases, uniqueConflicts, } from './failed-overlay.js';
 import { ProgressEmitter, } from './progress.js';
@@ -126,6 +130,7 @@ function realtimeErrorCode(error) {
 }
 export class SyncClient {
     #config;
+    #authorityReads;
     #db;
     #schema;
     /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
@@ -233,6 +238,8 @@ export class SyncClient {
         this.#retainFailedCommits = config.retainFailedCommits === true;
         this.#db = config.database;
         this.#schema = compileClientSchema(config.schema);
+        this.#authorityReads = config.authorityReads;
+        this.#authorityReads?.validate(this.#schema);
         const realtimePolicy = config.realtimePolicy ?? 'optional';
         if (realtimePolicy !== 'required' &&
             realtimePolicy !== 'optional' &&
@@ -478,6 +485,13 @@ export class SyncClient {
     }
     /** §2.1 reset after the server reports a different log continuity. */
     #runLogEpochReset(logEpoch) {
+        if (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined) {
+            this.#applyBatch(() => setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch));
+            this.#setSyncNeeded(true);
+            this.#emitSyncNeeded('startup');
+            this.#emitSyncIntent({ kind: 'interactive' });
+            return [];
+        }
         const subscriptions = loadSubscriptions(this.#db);
         const pending = listOutbox(this.#db);
         this.#setUpgrading(true);
@@ -530,6 +544,7 @@ export class SyncClient {
         });
     }
     async close() {
+        this.#started = false;
         this.#emitSyncIntent({ kind: 'none' });
         this.#devtoolsUnregister?.();
         this.#devtoolsUnregister = undefined;
@@ -537,7 +552,6 @@ export class SyncClient {
         this.#abortPendingRound('client closed mid-round');
         await this.#lease?.release();
         this.#lease = undefined;
-        this.#started = false;
         this.#progress.clear();
         this.#syncNeededListeners.clear();
         this.#syncIntentListeners.clear();
@@ -685,6 +699,13 @@ export class SyncClient {
         this.#requireStarted();
         return getLocalRevision(this.#db);
     }
+    /** Read the creation-time plain authority policy, including preflight. */
+    authoritySnapshot() {
+        this.#requireStarted();
+        if (!this.#authorityReads || arguments.length)
+            throw new ClientSyncError('client.authority_read_forbidden', 'authority read denied');
+        return this.#authorityReads.snapshot(this.#db, this.#schema);
+    }
     /**
      * Read rows, window answerability, and revision from one SQLite snapshot.
      * Reactive integrations use this instead of composing `query()` and
@@ -703,24 +724,13 @@ export class SyncClient {
                 const missing = [];
                 for (const requested of spec.coverage ?? []) {
                     const baseKey = windowBaseKey(requested.base);
-                    const live = new Map(loadWindowUnits(this.#db, baseKey).map((entry) => [
-                        entry.unit,
-                        entry.subId,
-                    ]));
+                    const state = this.windowState(requested.base);
                     for (const unit of new Set(requested.units)) {
-                        const subId = live.get(unit);
                         const ref = { baseKey, unit };
-                        if (subId === undefined) {
+                        if (!state.units.includes(unit))
                             missing.push(ref);
-                            continue;
-                        }
-                        const sub = getSubscription(this.#db, subId);
-                        if (sub === undefined ||
-                            sub.status !== 'active' ||
-                            sub.cursor < 0 ||
-                            sub.bootstrapState !== undefined) {
+                        else if (state.pending.includes(unit))
                             pending.push(ref);
-                        }
                     }
                 }
                 return {
@@ -1033,7 +1043,7 @@ export class SyncClient {
                 item.id.length === 0 ||
                 typeof item.table !== 'string' ||
                 item.table.length === 0) {
-                throw invalidRequest('diagnosticsSnapshot expected subscriptions require non-empty id and table strings');
+                throw invalidRequest('diagnosticsSnapshot needs subscription id and table');
             }
             const registeredSubscription = subscriptions.get(item.id);
             if (registeredSubscription !== undefined &&
@@ -1128,8 +1138,8 @@ export class SyncClient {
         try {
             const pageCount = Number(this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0);
             const pageSize = Number(this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0);
-            const outboxBytes = Number(this.#db.query('SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM _syncular_outbox')[0]?.bytes ?? 0);
-            const outcome = this.#db.query('SELECT COUNT(*)AS entries,COALESCE(SUM(LENGTH(results)+ COALESCE(LENGTH(operations),0)),0)AS bytes FROM _syncular_commit_outcomes')[0];
+            const outboxBytes = Number(this.#db.query(`SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM ${OUTBOX_TABLE}`)[0]?.bytes ?? 0);
+            const outcome = this.#db.query(`SELECT COUNT(*)AS entries,COALESCE(SUM(LENGTH(results)+ COALESCE(LENGTH(operations),0)),0)AS bytes FROM ${OUTCOMES_TABLE}`)[0];
             const blobBytes = this.#hasBlobs
                 ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length),0)AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
                 : 0;
@@ -1925,7 +1935,7 @@ export class SyncClient {
                         catch {
                             continue;
                         }
-                        this.#db.exec('INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id,blob_id)SELECT ?,? WHERE EXISTS(SELECT 1 FROM _syncular_blobs WHERE blob_id=?)', [clientCommitId, blobId, blobId]);
+                        this.#db.exec(`INSERT OR IGNORE INTO ${BLOB_COMMIT_REFS}(commit_id,blob_id)SELECT ?,? WHERE EXISTS(SELECT 1 FROM _syncular_blobs WHERE blob_id=?)`, [clientCommitId, blobId, blobId]);
                     }
                 }
                 try {
@@ -2143,7 +2153,7 @@ export class SyncClient {
             };
         }
         if (this.#schemaFloor !== undefined) {
-            throw invalidRequest('local rebootstrap cannot bypass an active schema-floor stop; update the application first');
+            throw invalidRequest('local rebootstrap needs a schema-floor update');
         }
         const pending = listOutbox(this.#db);
         const resetSubscriptions = loadSubscriptions(this.#db).length;
@@ -2250,7 +2260,7 @@ export class SyncClient {
     async #encodeOutboxForPush() {
         // Pin before the first encryption await: mutations can append while a
         // round is encoding, and belong to the next request.
-        const bounds = this.#db.query('SELECT COUNT(*)AS count,MAX(seq)AS last_seq FROM _syncular_outbox')[0];
+        const bounds = this.#db.query(`SELECT COUNT(*)AS count,MAX(seq)AS last_seq FROM ${OUTBOX_TABLE}`)[0];
         const pendingCount = bounds.count;
         const throughSeq = bounds.last_seq ?? 0;
         const pushFrames = [];
@@ -3140,14 +3150,7 @@ export class SyncClient {
             }
         }
         finally {
-            try {
-                // §7.1: local reads see outbox state applied optimistically — replay
-                // the still-pending commits on top of the freshly applied server state.
-                this.#replayOutbox();
-            }
-            finally {
-                this.#endDiagnosticsDeferral();
-            }
+            this.#endDiagnosticsDeferral();
         }
         if (errorFrame !== undefined)
             throw errorFrame;
@@ -3276,13 +3279,16 @@ export class SyncClient {
             if (this.#retainFailedCommits)
                 retainFailedRows(this.#db, commit, listOutboxBeforeImages(this.#db, commit.clientCommitId));
             this.#rollbackFailedCommit(commit, batch);
+            this.#replayOutbox(commit.operations.map((operation) => JSON.stringify(hasUniqueIndex(this.#table(operation.table))
+                ? [operation.table]
+                : [operation.table, operation.rowId])));
         });
         batch.status();
         summary.rejected.push(frame.clientCommitId);
         return true;
     }
     #outboxCommitExists(clientCommitId) {
-        return (this.#db.query('SELECT 1 FROM _syncular_outbox WHERE client_commit_id=? LIMIT 1', [clientCommitId]).length > 0);
+        return (this.#db.query(`SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`, [clientCommitId]).length > 0);
     }
     #decodeServerRow(tableName, payload) {
         if (tableName === undefined)
@@ -3320,7 +3326,7 @@ export class SyncClient {
         await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
             this.#recordCommitChanges(batch, frame);
             const result = fn();
-            this.#replayOutbox(result);
+            this.#replayOutbox(result, false);
             return result;
         }));
         summary.commitsApplied += 1;
@@ -3381,7 +3387,7 @@ export class SyncClient {
                     (clearFirst && this.#scopedRowsExist(table, effective)))
                     batch.table(table.name);
                 const result = fn();
-                this.#replayOutbox();
+                this.#replayOutbox(result, false);
                 return result;
             }),
         };
@@ -3513,11 +3519,12 @@ export class SyncClient {
                         return matchesLocalScopes(table, effective, values);
                     }));
                     if (covered.length) {
-                        restoreFailedBases(this.#db, this.#schema);
+                        const scope = covered.map((row) => JSON.stringify([sub.table, String(row.id)]));
+                        restoreFailedBases(this.#db, this.#schema, scope);
                         for (const row of covered)
                             this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [sub.table, String(row.id), nextCursor]);
                         batch.table(sub.table);
-                        this.#replayOutbox();
+                        this.#replayOutbox(scope, false);
                     }
                 }
                 if (completed && registered !== undefined) {
@@ -3560,9 +3567,11 @@ export class SyncClient {
             if (lastEffective !== undefined &&
                 Object.keys(lastEffective).length > 0) {
                 try {
-                    restoreFailedBases(this.#db, this.#schema);
-                    this.#dropRetainedRows(batch, (name, values) => name === table.name &&
-                        matchesLocalScopes(table, lastEffective, values));
+                    const scope = [
+                        JSON.stringify([table.name]),
+                        ...this.#dropRetainedRows(batch, (name, values) => name === table.name &&
+                            matchesLocalScopes(table, lastEffective, values)),
+                    ];
                     deleteScopedRows(this.#db, table, lastEffective);
                     batch.scopeMap(table, lastEffective);
                     const pendingById = new Map(listOutbox(this.#db).map((commit) => [
@@ -3600,6 +3609,7 @@ export class SyncClient {
                         batch.rejections();
                         batch.outcomes();
                     }
+                    this.#replayOutbox(scope);
                     this.#deleteUnreferencedBlobs();
                 }
                 catch (error) {
@@ -3772,7 +3782,7 @@ export class SyncClient {
                 ? OPTIMISTIC_VERSION
                 : local[SYNC_VERSION_COLUMN];
             if (replay &&
-                table.indexes.some((index) => index.unique) &&
+                hasUniqueIndex(table) &&
                 uniqueConflicts(this.#db, table, Object.fromEntries(table.columns.map((column, index) => [
                     column.name,
                     values[index] ?? null,
@@ -3786,33 +3796,35 @@ export class SyncClient {
         this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
     }
     #dropRetainedRows(batch, matches) {
-        for (const commit of dropFailedRows(this.#db, matches)) {
+        const scope = [];
+        for (const commit of dropFailedRows(this.#db, this.#schema, matches)) {
             batch.conflicts();
             batch.rejections();
             batch.outcomes();
             this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== commit.clientCommitId);
             this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== commit.clientCommitId);
-            for (const op of commit.operations)
+            for (const op of commit.operations) {
                 batch.table(op.table);
+                scope.push(JSON.stringify([op.table, op.rowId]));
+            }
         }
+        return scope;
     }
-    #replayOutbox(rowKeys) {
-        const acknowledged = failedOverlayCommits(this.#db, true, rowKeys);
-        const pending = [
-            ...failedOverlayCommits(this.#db, false, rowKeys),
-            ...listOutbox(this.#db, rowKeys),
-        ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
-        if (pending.length === 0 && acknowledged.length === 0)
+    #replayOutbox(scope, restoreBases = true) {
+        if (scope?.length === 0)
             return;
         this.#applyBatch((batch) => {
-            this.#db.transaction(() => {
-                restoreFailedBases(this.#db, this.#schema, false, rowKeys);
-                restoreFailedBases(this.#db, this.#schema, true, rowKeys);
-                for (const commit of [...acknowledged, ...pending])
-                    this.#applyOperationsLocally(rowKeys === undefined
-                        ? commit.operations
-                        : commit.operations.filter((op) => rowKeys.includes(JSON.stringify([op.table, op.rowId]))), batch, true);
-            });
+            if (restoreBases)
+                restoreFailedBases(this.#db, this.#schema, scope);
+            const acknowledged = failedOverlayCommits(this.#db, true, scope, this.#schema);
+            const pending = [
+                ...failedOverlayCommits(this.#db, false, scope, this.#schema),
+                ...listOutbox(this.#db, scope),
+            ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
+            for (const commit of [...acknowledged, ...pending])
+                this.#applyOperationsLocally(commit.operations.filter((op) => scope === undefined ||
+                    scope.includes(JSON.stringify([op.table, op.rowId])) ||
+                    scope.includes(JSON.stringify([op.table]))), batch, true);
         });
     }
     #deleteUnreferencedBlobs() {
@@ -3830,13 +3842,13 @@ export class SyncClient {
     }
     #requireStarted() {
         if (!this.#started) {
-            throw invalidRequest('call SyncClient.start() first');
+            throw invalidRequest('call start() first');
         }
     }
     #requireActive() {
         this.#requireStarted();
         if (this.#securityLifecycle === 'preflight') {
-            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'security preflight must complete before accessing protected data; call activateSecurity');
+            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'protected reads require activateSecurity');
         }
     }
 }

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/index.d.ts

@@ -8,6 +8,7 @@
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
  */
+export { defineAuthorityReads, type AuthorityReadPolicy, type AuthorityReadDeclaration, type AuthoritySnapshot, } from './authority.js';
 export * from './apply.js';
 export * from './availability.js';
 export * from './blob.js';

package/dist/index.js

@@ -8,6 +8,7 @@
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
  */
+export { defineAuthorityReads, } from './authority.js';
 export * from './apply.js';
 export * from './availability.js';
 export * from './blob.js';

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,
         ]);
     }