@syncular/client 0.30.13 → 0.30.14

package/dist/apply.d.ts

@@ -1,3 +1,4 @@
+import { type OverlayScope } from './failed-overlay.js';
 /**
  * Local application of server data: `COMMIT` frames (§4.5), rows segments
  * (§5.2, §5.6), and the scope-matched delete shared by the §3.3 purge
@@ -8,7 +9,7 @@ import type { ClientDatabase } from './database.js';
 import type { EncryptionConfig } from './encryption.js';
 import { type CompiledClientSchema, type CompiledClientTable } from './schema.js';
 /** Lets the client wrap the physical write in its revision transaction. */
-export type ApplyTransaction = <T>(fn: () => T) => T;
+export type ApplyTransaction = (fn: () => OverlayScope) => unknown;
 export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, serverWrite?: boolean): void;
 export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string, serverWrite?: boolean): void;
 /**
@@ -23,7 +24,7 @@ export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClient
  * (`client.decrypt_failed`) aborts before any local write, so the commit
  * never half-applies.
  */
-export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledClientSchema, frame: CommitFrame, encryption?: EncryptionConfig, transaction?: (fn: () => readonly string[] | undefined) => unknown): Promise<void>;
+export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledClientSchema, frame: CommitFrame, encryption?: EncryptionConfig, transaction?: (fn: () => OverlayScope) => unknown): Promise<void>;
 /**
  * §5.2: the segment's column table must match the generated schema for
  * (table, schemaVersion) — order, names, types, nullability. A mismatch is

package/dist/apply.js

@@ -1,3 +1,5 @@
+import { hasUniqueIndex } from './schema.js';
+import { OUTBOX_TABLE, OUTBOX_IMAGES, countOutbox } from './outbox.js';
 import { RETAINED_ROWS } from './failed-overlay.js';
 import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
 /**
@@ -76,13 +78,13 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
         });
     }
     transaction(() => {
-        const rowKeys = frame.tables.some((name) => schema.tables.get(name)?.indexes.some((index) => index.unique))
-            ? undefined
-            : frame.changes.map((change) => JSON.stringify([frame.tables[change.tableIndex], change.rowId]));
-        restoreFailedBases(db, schema, false, rowKeys);
+        const scope = resolved.map((change, index) => JSON.stringify(hasUniqueIndex(change.table)
+            ? [change.table.name]
+            : [change.table.name, frame.changes[index].rowId]));
+        restoreFailedBases(db, schema, scope);
         for (const [index, change] of resolved.entries()) {
             const rowId = frame.changes[index].rowId;
-            db.exec("UPDATE _syncular_outbox_before_images SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE (client_commit_id,op_index) IN(SELECT client_commit_id,json_each.key FROM _syncular_outbox,json_each(operations) WHERE json_extract(value,'$.table')=? AND json_extract(value,'$.rowId')=?)", [frame.commitSeq, change.table.name, rowId]);
+            db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE (client_commit_id,op_index) IN(SELECT client_commit_id,json_each.key FROM ${OUTBOX_TABLE},json_each(operations) WHERE json_extract(value,'$.table')=? AND json_extract(value,'$.rowId')=?)`, [frame.commitSeq, change.table.name, rowId]);
             db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [change.table.name, rowId, frame.commitSeq]);
             if (change.op === 'delete') {
                 deleteLocalRow(db, change.table, change.rowId);
@@ -91,7 +93,7 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
                 upsertLocalRow(db, change.table, change.values, change.rowVersion);
             }
         }
-        return rowKeys;
+        return scope;
     });
 }
 /**
@@ -147,12 +149,27 @@ export function localScopePredicate(table, effective) {
         .join(' AND ');
     return { sql, params };
 }
+function scopedRows(db, table, scope) {
+    return scope
+        ? db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${scope.sql}`, scope.params)
+        : [];
+}
+function bootstrapScope(db, table, effective) {
+    const rows = scopedRows(db, table, localScopePredicate(table, effective));
+    rows.push(...db
+        .query(`SELECT id,base,intent FROM ${RETAINED_ROWS} WHERE tbl=?`, [
+        table.name,
+    ])
+        .filter((row) => [row.base, row.intent].some((json) => json !== null &&
+        matchesLocalScopes(table, effective, JSON.parse(json)))));
+    return rows.map((row) => JSON.stringify([table.name, String(row.id)]));
+}
 export function deleteScopedRows(db, table, effective) {
     const scope = localScopePredicate(table, effective);
     if (!scope)
         return;
     const { sql, params } = scope;
-    for (const row of db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${sql}`, params)) {
+    for (const row of scopedRows(db, table, scope)) {
         retainedBaseWrite(db, table, String(row.id));
     }
     db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${sql}`, params);
@@ -287,18 +304,37 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
                 predicates.push(`${primaryKey} <= ?`);
                 params.push(boundary);
             }
+            const replay = countOutbox(db) ||
+                db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [
+                    table.name,
+                ]).length;
+            const rows = replay
+                ? db.query(`SELECT * FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}`, params)
+                : [];
             (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
-                restoreFailedBases(db, schema);
+                const scope = !replay
+                    ? []
+                    : hasUniqueIndex(table)
+                        ? [JSON.stringify([table.name])]
+                        : [
+                            ...(after === undefined && options.clearFirst
+                                ? bootstrapScope(db, table, options.effective)
+                                : []),
+                            ...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
+                        ];
+                const protectedRows = restoreFailedBases(db, schema, scope);
                 if (after === undefined && options.clearFirst)
                     deleteScopedRows(db, table, options.effective);
                 db.exec(`INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${predicates.join(' AND ') || 'true'} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates}`, params);
                 applied += Number(db.query('SELECT changes()AS n')[0]?.n ?? 0);
-                for (const row of db.query(`SELECT * FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}`, params)) {
-                    retainedBaseWrite(db, table, String(row[table.primaryKey]), Object.fromEntries(table.columns.map((column) => [
-                        column.name,
-                        rowValueToJson(row[column.name]),
-                    ])), Number(row._syncular_version));
-                }
+                if (protectedRows)
+                    for (const row of rows) {
+                        retainedBaseWrite(db, table, String(row[table.primaryKey]), Object.fromEntries(table.columns.map((column) => [
+                            column.name,
+                            rowValueToJson(row[column.name]),
+                        ])), Number(row._syncular_version));
+                    }
+                return scope;
             });
             options.onProgress?.(applied);
             await yieldToHost();
@@ -347,7 +383,18 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
         if (!clearThisBlock && rows.length === 0)
             continue;
         (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
-            const protectedRows = restoreFailedBases(db, schema);
+            const scope = hasUniqueIndex(table)
+                ? [JSON.stringify([table.name])]
+                : [
+                    ...(clearThisBlock
+                        ? bootstrapScope(db, table, options.effective)
+                        : []),
+                    ...rows.map((row) => JSON.stringify([
+                        table.name,
+                        String(row.values[table.primaryKeyIndex]),
+                    ])),
+                ];
+            const protectedRows = restoreFailedBases(db, schema, scope);
             if (clearThisBlock) {
                 deleteScopedRows(db, table, options.effective);
             }
@@ -357,6 +404,7 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
                 if (applied % 1024 === 0)
                     options.onProgress?.(applied);
             }
+            return scope;
         });
         options.onProgress?.(applied);
         await yieldToHost();

package/dist/blob.d.ts

@@ -1,3 +1,4 @@
+export declare const BLOB_COMMIT_REFS = "_syncular_blob_commit_refs";
 /**
  * Client-side blob cache + transport (SPEC.md §5.9.7).
  *

package/dist/blob.js

@@ -1,3 +1,4 @@
+export const BLOB_COMMIT_REFS = '_syncular_blob_commit_refs';
 /**
  * Client-side blob cache + transport (SPEC.md §5.9.7).
  *
@@ -70,7 +71,7 @@ export function enforceBlobCacheCap(db, schema, maxBytes) {
     if (total <= maxBytes)
         return [];
     // Oldest eligible body first, with blob ID as a stable tie.
-    const candidates = db.query(`SELECT blob_id,byte_length FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM _syncular_blob_commit_refs)AND blob_id NOT IN(${visibleBlobIdsSql(schema)})ORDER BY created_at_ms ASC,blob_id ASC`);
+    const candidates = db.query(`SELECT blob_id,byte_length FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${visibleBlobIdsSql(schema)})ORDER BY created_at_ms ASC,blob_id ASC`);
     const evicted = [];
     db.transaction(() => {
         for (const row of candidates) {
@@ -86,7 +87,7 @@ export function enforceBlobCacheCap(db, schema, maxBytes) {
 }
 export function listPendingUploads(db) {
     return db
-        .query('SELECT blob_id,media_type FROM(SELECT blob_id,media_type,created_at_ms FROM _syncular_blob_uploads UNION ALL SELECT DISTINCT r.blob_id,b.media_type,9223372036854775807 AS created_at_ms FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id=r.blob_id WHERE NOT EXISTS(SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id=r.blob_id))ORDER BY created_at_ms,blob_id')
+        .query(`SELECT blob_id,media_type FROM(SELECT blob_id,media_type,created_at_ms FROM _syncular_blob_uploads UNION ALL SELECT DISTINCT r.blob_id,b.media_type,9223372036854775807 AS created_at_ms FROM ${BLOB_COMMIT_REFS} r LEFT JOIN _syncular_blobs b ON b.blob_id=r.blob_id WHERE NOT EXISTS(SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id=r.blob_id))ORDER BY created_at_ms,blob_id`)
         .map((row) => {
         if (typeof row.blob_id !== 'string' ||
             (row.media_type !== null && typeof row.media_type !== 'string')) {
@@ -138,6 +139,6 @@ function visibleBlobIdsSql(schema) {
         : selects.join(' UNION ');
 }
 export function deleteUnreferencedCachedBlobs(db, schema) {
-    db.exec(`DELETE FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM _syncular_blob_commit_refs)AND blob_id NOT IN(${visibleBlobIdsSql(schema)})`);
+    db.exec(`DELETE FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${visibleBlobIdsSql(schema)})`);
 }
 export { parseBlobRef, serializeBlobRef };

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';
@@ -478,6 +482,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);
@@ -1128,8 +1139,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 +1936,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 {
@@ -2250,7 +2261,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 +3151,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 +3280,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 +3327,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 +3388,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 +3520,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 +3568,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 +3610,7 @@ export class SyncClient {
                         batch.rejections();
                         batch.outcomes();
                     }
+                    this.#replayOutbox(scope);
                     this.#deleteUnreferencedBlobs();
                 }
                 catch (error) {
@@ -3772,7 +3783,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 +3797,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() {

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. */