@syncular/client 0.30.11 → 0.30.13

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

@@ -104,6 +104,7 @@ export interface SyncClientLimits {
     readonly outcomeRetentionMaxEntries?: number;
 }
 export interface SyncClientConfig {
+    readonly transportEnabled?: boolean;
     /** Keep rejected/conflicting local intent visible until explicit resolution. */
     readonly retainFailedCommits?: boolean;
     readonly database: ClientDatabase;
@@ -295,6 +296,8 @@ export declare class SyncClient {
     /** Acquire leadership, create local tables, resolve the clientId. */
     start(): Promise<void>;
     close(): Promise<void>;
+    /** Host-owned transport policy; the local replica remains available. */
+    setTransportEnabled(enabled: boolean): void;
     /** Current fail-closed local-replica security state. */
     securityLifecycle(): SecurityLifecycle;
     /**