@syncular/client 0.30.11 → 0.30.12

package/README.md

@@ -18,6 +18,13 @@ Ordinary commits use wire version 1 until the caller supplies an acquired
 partition `logEpoch`. Set `logEpoch` after a restore rotation requires epoch
 validation.
 
+Applied and cached acknowledgements drain the send queue while protected local
+intent stays visible until the same row's server image arrives at that commit
+sequence or later. Empty pulls and restart preserve it; later edits stack above
+it. This behavior is automatic, independent of `retainFailedCommits`. The core
+requests a following pull without relying on an origin realtime notification.
+See [optimistic writes](https://syncular.dev/concepts-conflicts/#the-optimistic-outbox).
+
 ## Client-local FTS5 projections
 
 Generated schemas may attach `ftsIndexes` to a synced table. The

package/dist/apply.d.ts

@@ -23,7 +23,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?: ApplyTransaction): Promise<void>;
+export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledClientSchema, frame: CommitFrame, encryption?: EncryptionConfig, transaction?: (fn: () => readonly string[] | undefined) => 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
@@ -37,6 +37,10 @@ export declare function validateSegmentColumns(schema: CompiledClientSchema, tab
  * (`sync.scope_revoked`) when the table has no local mapping for a key:
  * precision or nothing, never clear-the-table.
  */
+export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap): {
+    sql: string;
+    params: string[];
+} | undefined;
 export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap): void;
 /**
  * §4.8 window eviction: delete rows matching a departing unit's effective

package/dist/apply.js

@@ -1,3 +1,4 @@
+import { RETAINED_ROWS } from './failed-overlay.js';
 import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
 /**
  * Local application of server data: `COMMIT` frames (§4.5), rows segments
@@ -6,7 +7,7 @@ import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
  */
 import { decodeRow, } from '@syncular/core';
 import { ClientSyncError, invalidRequest } from './errors.js';
-import { quoteIdent, SYNC_VERSION_COLUMN, toSqlValue, rowValueToJson, } from './schema.js';
+import { quoteIdent, matchesLocalScopes, SYNC_VERSION_COLUMN, toSqlValue, rowValueToJson, } from './schema.js';
 function upsertSql(table) {
     const names = [
         ...table.columns.map((column) => quoteIdent(column.name)),
@@ -75,8 +76,14 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
         });
     }
     transaction(() => {
-        restoreFailedBases(db, schema);
-        for (const change of resolved) {
+        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);
+        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(`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);
             }
@@ -84,6 +91,7 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
                 upsertLocalRow(db, change.table, change.values, change.rowVersion);
             }
         }
+        return rowKeys;
     });
 }
 /**
@@ -123,26 +131,31 @@ export function validateSegmentColumns(schema, table, segment) {
  * (`sync.scope_revoked`) when the table has no local mapping for a key:
  * precision or nothing, never clear-the-table.
  */
-export function deleteScopedRows(db, table, effective) {
+export function localScopePredicate(table, effective) {
     const entries = Object.entries(effective);
-    if (entries.length === 0)
+    if (!entries.length || entries.some(([, values]) => !values.length))
         return;
-    const clauses = [];
     const params = [];
-    for (const [variable, values] of entries) {
+    const sql = entries
+        .map(([variable, values]) => {
         const column = table.scopeColumnByVariable.get(variable);
-        if (column === undefined) {
-            throw new ClientSyncError('sync.scope_revoked', `table ${JSON.stringify(table.name)} has no local scope-column mapping for ${JSON.stringify(variable)} (§3.3 fail-closed)`);
-        }
-        if (values.length === 0)
-            return;
-        clauses.push(`${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`);
+        if (column === undefined)
+            throw new ClientSyncError('sync.scope_revoked', 'table has no local scope-column mapping');
         params.push(...values);
-    }
-    for (const row of db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`, params)) {
+        return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
+    })
+        .join(' AND ');
+    return { sql, params };
+}
+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)) {
         retainedBaseWrite(db, table, String(row.id));
     }
-    db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`, params);
+    db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${sql}`, params);
 }
 /**
  * §4.8 window eviction: delete rows matching a departing unit's effective
@@ -155,21 +168,10 @@ export function deleteScopedRows(db, table, effective) {
  * cache), which is automatic since the version column is per-row.
  */
 export function evictScopedRows(db, table, effective, pinnedRowIds) {
-    const entries = Object.entries(effective);
-    if (entries.length === 0)
+    const scope = localScopePredicate(table, effective);
+    if (!scope)
         return { remaining: false, deferred: false };
-    const clauses = [];
-    const params = [];
-    for (const [variable, values] of entries) {
-        const column = table.scopeColumnByVariable.get(variable);
-        if (column === undefined) {
-            throw new ClientSyncError('sync.scope_revoked', `table ${JSON.stringify(table.name)} has no local scope-column mapping for ${JSON.stringify(variable)} (§4.8/§3.3 fail-closed)`);
-        }
-        if (values.length === 0)
-            return { remaining: false, deferred: false };
-        clauses.push(`${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`);
-        params.push(...values);
-    }
+    const { sql, params } = scope;
     const pk = quoteIdent(table.primaryKey);
     let pinnedClause = '';
     if (pinnedRowIds.size > 0) {
@@ -178,10 +180,16 @@ export function evictScopedRows(db, table, effective, pinnedRowIds) {
         params.push(...ids);
     }
     const target = quoteIdent(table.name);
-    db.exec(`DELETE FROM ${target} WHERE ${pk} IN(SELECT ${pk} FROM ${target} WHERE ${clauses.join(' AND ')}${pinnedClause} LIMIT 1024)`, params);
-    const remaining = db.query(`SELECT 1 FROM ${target} WHERE ${clauses.join(' AND ')}${pinnedClause} LIMIT 1`, params).length > 0;
+    for (const row of db.query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl=?`, [table.name])) {
+        if (!pinnedRowIds.has(row.id) &&
+            [row.intent, row.base].some((json) => json !== null &&
+                matchesLocalScopes(table, effective, JSON.parse(json))))
+            db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq IS NOT NULL`, [table.name, row.id]);
+    }
+    db.exec(`DELETE FROM ${target} WHERE ${pk} IN(SELECT ${pk} FROM ${target} WHERE ${sql}${pinnedClause} LIMIT 1024)`, params);
+    const remaining = db.query(`SELECT 1 FROM ${target} WHERE ${sql}${pinnedClause} LIMIT 1`, params).length > 0;
     const deferred = remaining ||
-        db.query(`SELECT 1 FROM ${target} WHERE ${clauses.join(' AND ')} LIMIT 1`, params.slice(0, params.length - pinnedRowIds.size)).length > 0;
+        db.query(`SELECT 1 FROM ${target} WHERE ${sql} LIMIT 1`, params.slice(0, params.length - pinnedRowIds.size)).length > 0;
     return { remaining, deferred };
 }
 const IMAGE_ALIAS = 'syncular_image';
@@ -199,7 +207,7 @@ function imageInvalid(detail) {
 export async function applySqliteSegment(db, schema, table, bytes, descriptor, options) {
     const withImage = db.withSqliteImage?.bind(db);
     if (withImage === undefined) {
-        throw invalidRequest('received a sqlite segment but the database backend cannot import images (§4.2: do not advertise accept bit 2)');
+        throw invalidRequest('database cannot import images; disable accept bit 2 (§4.2)');
     }
     if (descriptor.table !== table.name) {
         imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
@@ -339,12 +347,12 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
         if (!clearThisBlock && rows.length === 0)
             continue;
         (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
-            restoreFailedBases(db, schema);
+            const protectedRows = restoreFailedBases(db, schema);
             if (clearThisBlock) {
                 deleteScopedRows(db, table, options.effective);
             }
             for (const row of rows) {
-                upsertLocalRow(db, table, row.values, row.serverVersion);
+                upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
                 applied += 1;
                 if (applied % 1024 === 0)
                     options.onProgress?.(applied);

package/dist/client.js

@@ -1,3 +1,4 @@
+import { RETAINED_ROWS } from './failed-overlay.js';
 import { dropFailedRows, failedOverlayCommits, retainFailedRows, restoreFailedBases, uniqueConflicts, } from './failed-overlay.js';
 import { ProgressEmitter, } from './progress.js';
 /**
@@ -11,7 +12,7 @@ import { ProgressEmitter, } from './progress.js';
  */
 import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encodeMessage, encodePresencePublish, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
 import { EncryptError } from '@syncular/core';
-import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
+import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
 import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
 import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
@@ -25,7 +26,7 @@ import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encod
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
 import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
-import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
+import { compileClientSchema, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
 import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, saveSubscriptionScopeSchema, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
 /** Stable client-local error while protected operations are preflight-gated. */
@@ -221,7 +222,7 @@ export class SyncClient {
     #preflightBarrier;
     constructor(config) {
         if (config.securityPreflight === true && config.encryption !== undefined) {
-            throw invalidRequest('securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight');
+            throw invalidRequest('securityPreflight and encryption are mutually exclusive; activateSecurity installs keys');
         }
         this.#retainFailedCommits = config.retainFailedCommits === true;
         this.#db = config.database;
@@ -287,7 +288,7 @@ export class SyncClient {
             persisted !== this.#config.clientId) {
             await this.#lease.release();
             this.#lease = undefined;
-            throw new ClientSyncError('client.identity_mismatch', `this client database belongs to ${JSON.stringify(persisted)}; refusing to rebind it to ${JSON.stringify(this.#config.clientId)}`);
+            throw new ClientSyncError('client.identity_mismatch', `database clientId ${JSON.stringify(persisted)} differs from ${JSON.stringify(this.#config.clientId)}`);
         }
         this.#clientId = persisted ?? this.#config.clientId ?? crypto.randomUUID();
         if (persisted === undefined) {
@@ -319,6 +320,7 @@ export class SyncClient {
         // an application-issued sync() call.
         const startupWork = this.#schemaFloor === undefined &&
             (countOutbox(this.#db) > 0 ||
+                this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
                 loadPendingEvictions(this.#db).length > 0 ||
                 subscriptions.some((sub) => sub.status === 'active'));
         if (startupWork && this.#securityLifecycle === 'active') {
@@ -396,6 +398,7 @@ export class SyncClient {
                     writePreviousVersionAudit(this.#db, buildPreviousVersionAudit(this.#schema, listOutbox(this.#db), previousVersion, this.#schema.version, this.#now()));
                 }
                 pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), this.#schema, true);
+                this.#discardAcknowledgedRows();
                 dropAndRecreateSyncedTables(this.#db, this.#schema);
                 resetSubscriptionsForBump(this.#db);
                 setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
@@ -477,6 +480,7 @@ export class SyncClient {
         this.#sweepPreviousVersionContainer();
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
+                this.#discardAcknowledgedRows();
                 dropAndRecreateSyncedTables(this.#db, this.#schema);
                 resetSubscriptionsForBump(this.#db);
                 setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
@@ -1179,7 +1183,7 @@ export class SyncClient {
                 try {
                     result = fn(batch);
                     if (this.#db
-                        .query('SELECT DISTINCT tbl FROM _syncular_failed_rows')
+                        .query(`SELECT DISTINCT tbl FROM ${RETAINED_ROWS} WHERE commit_seq IS NULL`)
                         .some((row) => batch.hasTable(String(row.tbl))))
                         batch.outcomes();
                     if (batch.touched) {
@@ -1454,7 +1458,7 @@ export class SyncClient {
         const priorRejections = this.#rejections;
         return this.#applyBatch((batch) => {
             restoreFailedBases(this.#db, this.#schema);
-            this.#db.exec('DELETE FROM _syncular_failed_rows WHERE commit_id=?', [
+            this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [
                 input.clientCommitId,
             ]);
             const resolved = persistCommitOutcomeResolution(this.#db, input, this.#now());
@@ -1569,7 +1573,7 @@ export class SyncClient {
                     canonicalScopeJson(input.scopes) &&
                 existing.params === input.params;
             if (!sameIntent) {
-                throw new ClientSyncError('client.subscription_intent_mismatch', 'subscribe: the subscription id is already registered for a different table, scopes, or params');
+                throw new ClientSyncError('client.subscription_intent_mismatch', 'subscription id already names different table, scopes, or params');
             }
             return;
         }
@@ -1616,7 +1620,7 @@ export class SyncClient {
         this.#requireActive();
         const table = this.#table(base.table);
         if (!table.scopeColumnByVariable.has(base.variable)) {
-            throw invalidRequest(`setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`);
+            throw invalidRequest(`${base.table}: unknown scope variable ${base.variable} (§4.8)`);
         }
         // Serialize the whole window edit: it spans an `await deriveSubId` between
         // db transactions, so without the chain a delta apply (or a concurrent
@@ -1983,16 +1987,7 @@ export class SyncClient {
             return this.#applyBatch((batch) => {
                 const targetsByTable = this.#localPurgeTargetsByTable(purge);
                 restoreFailedBases(this.#db, this.#schema);
-                const droppedRetained = dropFailedRows(this.#db, (table, values) => (targetsByTable.get(table) ?? []).some((target) => target.selectors.every((selector) => selector.values.includes(String(values[selector.column])))));
-                for (const commit of droppedRetained) {
-                    batch.conflicts();
-                    batch.rejections();
-                    this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== commit.clientCommitId);
-                    this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== commit.clientCommitId);
-                    for (const operation of commit.operations)
-                        batch.table(operation.table);
-                    batch.outcomes();
-                }
+                this.#dropRetainedRows(batch, (table, values) => (targetsByTable.get(table) ?? []).some((target) => target.selectors.every((selector) => selector.values.includes(String(values[selector.column])))));
                 // Doomed detection runs to fixpoint, matching the Rust core's rule:
                 // a commit is doomed when any of its ops touches a base-matching
                 // row. Base values only become visible here as rollbacks restore
@@ -2128,6 +2123,7 @@ export class SyncClient {
                 this.#upgrading = true;
                 this.#needsPull = true;
                 batch.status();
+                this.#discardAcknowledgedRows();
                 dropAndRecreateSyncedTables(this.#db, this.#schema);
                 resetSubscriptionsForBump(this.#db);
                 for (const table of this.#schema.tables.values()) {
@@ -2972,6 +2968,7 @@ export class SyncClient {
                                 index += 1;
                             }
                         }
+                        const previousNeedsPull = this.#needsPull;
                         const conflictCount = this.#conflicts.length;
                         const rejectionCount = this.#rejections.length;
                         let outboxCount = countOutbox(this.#db);
@@ -2988,9 +2985,10 @@ export class SyncClient {
                                 pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
                             }
                         }, () => this.#statusSnapshot(outboxCount), (cause) => {
+                            this.#needsPull = previousNeedsPull;
                             this.#conflicts.length = conflictCount;
                             this.#rejections.length = rejectionCount;
-                            const error = new ClientSyncError('client.outcome_persistence_failed', 'local commit outcome could not be persisted');
+                            const error = new ClientSyncError('client.outcome_persistence_failed', 'outcome persistence failed');
                             error.cause = cause;
                             throw error;
                         });
@@ -3201,6 +3199,10 @@ export class SyncClient {
         if (frame.status === 'applied' || frame.status === 'cached') {
             // §6.3: applied and cached both drain the outbox — cached means
             // "already applied, you may have missed the ack".
+            if (frame.commitSeq === undefined)
+                throw new ClientSyncError('client.invalid_host_response', 'ACK lacks a commit sequence');
+            retainFailedRows(this.#db, commit, listOutboxBeforeImages(this.#db, commit.clientCommitId), frame.commitSeq);
+            this.#setSyncNeeded(true);
             recordCommitOutcome(this.#db, {
                 clientCommitId: frame.clientCommitId,
                 status: frame.status,
@@ -3327,10 +3329,7 @@ export class SyncClient {
         await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
             this.#recordCommitChanges(batch, frame);
             const result = fn();
-            if (this.#retainFailedCommits &&
-                this.#db.query('SELECT 1 FROM _syncular_failed_rows LIMIT 1')
-                    .length > 0)
-                this.#replayOutbox();
+            this.#replayOutbox(result);
             return result;
         }));
         summary.commitsApplied += 1;
@@ -3375,19 +3374,9 @@ export class SyncClient {
     }
     /** Whether a fresh-bootstrap clear would remove at least one local row. */
     #scopedRowsExist(table, effective) {
-        const entries = Object.entries(effective);
-        if (entries.length === 0)
-            return false;
-        const clauses = [];
-        const params = [];
-        for (const [variable, values] of entries) {
-            const column = table.scopeColumnByVariable.get(variable);
-            if (column === undefined || values.length === 0)
-                return false;
-            clauses.push(`${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`);
-            params.push(...values);
-        }
-        return (this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')} LIMIT 1`, params).length > 0);
+        const scope = localScopePredicate(table, effective);
+        return (scope !== undefined &&
+            this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${scope.sql} LIMIT 1`, scope.params).length > 0);
     }
     /**
      * Apply a segment (rows or sqlite image); a §5.6/§3.3 fail-closed error
@@ -3461,7 +3450,7 @@ export class SyncClient {
             if (frame.urlExpiresAtMs !== undefined &&
                 frame.urlExpiresAtMs <= this.#now()) {
                 // §5.4: MUST NOT start a fetch at/past expiry.
-                throw new ClientSyncError('sync.segment_expired', `signed URL for segment ${frame.segmentId} expired before fetch — re-pull mints fresh descriptors (§5.4)`, true);
+                throw new ClientSyncError('sync.segment_expired', `segment download grant expired; pull again (§5.4)`, true);
             }
             bytes = await fetchUrl(frame.url, onProgress);
         }
@@ -3504,6 +3493,25 @@ export class SyncClient {
                     effectiveScopes: start.effectiveScopes,
                     status: 'active',
                 }));
+                if (completed) {
+                    const table = this.#table(sub.table);
+                    const effective = start.effectiveScopes;
+                    const covered = this.#db
+                        .query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`, [sub.table, nextCursor])
+                        .filter((row) => [row.intent, row.base].some((json) => {
+                        if (json === null)
+                            return false;
+                        const values = JSON.parse(String(json));
+                        return matchesLocalScopes(table, effective, values);
+                    }));
+                    if (covered.length) {
+                        restoreFailedBases(this.#db, this.#schema);
+                        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();
+                    }
+                }
                 if (completed && registered !== undefined) {
                     // A zero-row bootstrap is a window-domain transition, not a fake
                     // row/table change (SPEC §4.8 / §7.5).
@@ -3545,17 +3553,8 @@ export class SyncClient {
                 Object.keys(lastEffective).length > 0) {
                 try {
                     restoreFailedBases(this.#db, this.#schema);
-                    const droppedRetained = dropFailedRows(this.#db, (name, values) => name === table.name &&
-                        Object.entries(lastEffective).every(([variable, allowed]) => allowed.includes(String(values[table.scopeColumnByVariable.get(variable)]))));
-                    for (const commit of droppedRetained) {
-                        batch.conflicts();
-                        batch.rejections();
-                        this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== commit.clientCommitId);
-                        this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== commit.clientCommitId);
-                        for (const operation of commit.operations)
-                            batch.table(operation.table);
-                        batch.outcomes();
-                    }
+                    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) => [
@@ -3775,19 +3774,36 @@ export class SyncClient {
         }
     }
     /** Re-apply every pending outbox commit on top of server state (§7.1). */
-    #replayOutbox() {
+    #discardAcknowledgedRows() {
+        this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
+    }
+    #dropRetainedRows(batch, matches) {
+        for (const commit of dropFailedRows(this.#db, 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)
+                batch.table(op.table);
+        }
+    }
+    #replayOutbox(rowKeys) {
+        const acknowledged = failedOverlayCommits(this.#db, true, rowKeys);
         const pending = [
-            ...failedOverlayCommits(this.#db),
-            ...listOutbox(this.#db),
+            ...failedOverlayCommits(this.#db, false, rowKeys),
+            ...listOutbox(this.#db, rowKeys),
         ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
-        if (pending.length === 0)
+        if (pending.length === 0 && acknowledged.length === 0)
             return;
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
-                restoreFailedBases(this.#db, this.#schema);
-                restoreFailedBases(this.#db, this.#schema, true);
-                for (const commit of pending)
-                    this.#applyOperationsLocally(commit.operations, batch, true);
+                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);
             });
         });
     }
@@ -3800,19 +3816,19 @@ export class SyncClient {
     #table(name) {
         const table = this.#schema.tables.get(name);
         if (table === undefined) {
-            throw new ClientSyncError('sync.unknown_table', `unknown local table ${JSON.stringify(name)}`);
+            throw new ClientSyncError('sync.unknown_table', `unknown table ${name}`);
         }
         return table;
     }
     #requireStarted() {
         if (!this.#started) {
-            throw invalidRequest('SyncClient.start() has not completed');
+            throw invalidRequest('call SyncClient.start() first');
         }
     }
     #requireActive() {
         this.#requireStarted();
         if (this.#securityLifecycle === 'preflight') {
-            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data');
+            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'security preflight must complete before accessing protected data; call activateSecurity');
         }
     }
 }

package/dist/failed-overlay.d.ts

@@ -1,3 +1,4 @@
+export declare const RETAINED_ROWS = "_syncular_failed_rows";
 import type { ClientDatabase } from './database.js';
 import type { CompiledClientSchema, CompiledClientTable, JsonRowValue } from './schema.js';
 import type { RowValue } from '@syncular/core';
@@ -6,9 +7,9 @@ import type { OutboxCommit, OutboxBeforeImage } from './outbox.js';
 /** Protected failure state. The server base advances independently of intent. */
 export declare function ensureFailedOverlaySchema(db: ClientDatabase): void;
 export declare function retainedBaseWrite(db: ClientDatabase, table: CompiledClientTable, rowId: string, values?: Readonly<Record<string, JsonRowValue>>, version?: number): void;
-export declare function retainFailedRows(db: ClientDatabase, commit: OutboxCommit, images: readonly OutboxBeforeImage[]): void;
+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): void;
-export declare function failedOverlayCommits(db: ClientDatabase): OutboxCommit[];
+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[];