@syncular/client 0.30.11 → 0.30.13

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[];

package/dist/failed-overlay.js

@@ -1,16 +1,17 @@
+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';
 import { deleteLocalRow, upsertLocalRow } from './apply.js';
 /** Protected failure state. The server base advances independently of intent. */
 export function ensureFailedOverlaySchema(db) {
-    db.exec('CREATE TABLE IF NOT EXISTS _syncular_failed_rows(commit_id TEXT NOT NULL,idx INTEGER NOT NULL,tbl TEXT NOT NULL,id TEXT NOT NULL,at INTEGER NOT NULL,op TEXT NOT NULL,intent TEXT,base TEXT,version INTEGER,unique_conflicts TEXT,PRIMARY KEY(commit_id,idx))');
-    if (!db
-        .query('PRAGMA table_info(_syncular_failed_rows)')
-        .some((row) => row.name === 'unique_conflicts'))
-        db.exec('ALTER TABLE _syncular_failed_rows ADD COLUMN unique_conflicts TEXT');
+    db.exec(`CREATE TABLE IF NOT EXISTS ${RETAINED_ROWS}(commit_id TEXT NOT NULL,idx INTEGER NOT NULL,tbl TEXT NOT NULL,id TEXT NOT NULL,at INTEGER NOT NULL,op TEXT NOT NULL,intent TEXT,base TEXT,version INTEGER,unique_conflicts TEXT,commit_seq INTEGER,PRIMARY KEY(commit_id,idx))`);
+    const columns = db.query(`PRAGMA table_info(${RETAINED_ROWS})`);
+    for (const column of ['unique_conflicts TEXT', 'commit_seq INTEGER'])
+        if (!columns.some((row) => row.name === column.split(' ')[0]))
+            db.exec(`ALTER TABLE ${RETAINED_ROWS} ADD COLUMN ${column}`);
 }
 export function retainedBaseWrite(db, table, rowId, values, version) {
-    db.exec('UPDATE _syncular_failed_rows SET base=?,version=? WHERE tbl=? AND id=?', [
+    db.exec(`UPDATE ${RETAINED_ROWS} SET base=?,version=? WHERE tbl=? AND id=?`, [
         values === undefined ? null : JSON.stringify(values),
         version ?? null,
         table.name,
@@ -18,13 +19,13 @@ export function retainedBaseWrite(db, table, rowId, values, version) {
     ]);
     if (!table.indexes.some((index) => index.unique))
         return;
-    for (const retained of db.query('SELECT commit_id,idx,intent,unique_conflicts FROM _syncular_failed_rows WHERE tbl=?', [table.name])) {
+    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
             ? []
-            : JSON.parse(String(retained.unique_conflicts));
+            : JSON.parse(retained.unique_conflicts);
         const conflicts = prior.filter((conflict) => conflict.rowId !== rowId);
         if (values !== undefined && retained.intent !== null) {
-            const intent = JSON.parse(String(retained.intent));
+            const intent = JSON.parse(retained.intent);
             conflicts.push(...uniqueConflicts(db, table, mapRowValues(intent, jsonToRowValue))
                 .filter((conflict) => conflict.rowId === rowId)
                 .map((conflict) => ({
@@ -32,25 +33,27 @@ export function retainedBaseWrite(db, table, rowId, values, version) {
                 serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
             })));
         }
-        db.exec('UPDATE _syncular_failed_rows SET unique_conflicts=? WHERE commit_id=? AND idx=?', [
+        db.exec(`UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`, [
             conflicts.length
                 ? JSON.stringify(conflicts.sort((a, b) => table.indexes.findIndex((index) => index.name === a.index) -
                     table.indexes.findIndex((index) => index.name === b.index)))
                 : null,
-            String(retained.commit_id),
+            retained.commit_id,
             Number(retained.idx),
         ]);
     }
 }
-export function retainFailedRows(db, commit, images) {
+export function retainFailedRows(db, commit, images, commitSeq) {
     for (const [index, operation] of commit.operations.entries()) {
         const image = images.find((image) => image.opIndex === index);
+        if (commitSeq !== undefined && (image?.deliverySeq ?? -1) >= commitSeq)
+            continue;
         const initial = operation.op === 'upsert'
             ? { ...image?.values, ...operation.values }
             : undefined;
         if (!image)
-            throw new ClientSyncError('sync.local_corrupt', 'retained intent has no before-image');
-        db.exec('INSERT INTO _syncular_failed_rows(commit_id,idx,tbl,id,at,op,intent,base,version)VALUES(?,?,?,?,?,?,?,?,?)', [
+            throw new ClientSyncError('sync.local_corrupt', 'missing intent before-image');
+        db.exec(`INSERT INTO ${RETAINED_ROWS}(commit_id,idx,tbl,id,at,op,intent,base,version,commit_seq)VALUES(?,?,?,?,?,?,?,?,?,?)`, [
             commit.clientCommitId,
             index,
             operation.table,
@@ -60,6 +63,7 @@ export function retainFailedRows(db, commit, images) {
             initial ? JSON.stringify(initial) : null,
             image.values ? JSON.stringify(image.values) : null,
             image.syncVersion ?? null,
+            commitSeq ?? null,
         ]);
     }
 }
@@ -83,33 +87,36 @@ export function uniqueConflicts(db, table, values) {
         serverVersion: Number(row[SYNC_VERSION_COLUMN]),
     })));
 }
-export function restoreFailedBases(db, schema, absentIntent = false) {
+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 restoreFailedBases(db, schema, absentIntent = false, rowKeys) {
     const seen = new Set();
-    for (const row of db.query('SELECT * FROM _syncular_failed_rows ORDER BY at,commit_id,idx')) {
+    for (const row of retainedRows(db, rowKeys)) {
         const key = JSON.stringify([row.tbl, row.id]);
         if (!absentIntent && seen.has(key))
             continue;
         seen.add(key);
-        const table = schema.tables.get(String(row.tbl));
+        const table = schema.tables.get(row.tbl);
         if (!table)
-            throw new ClientSyncError('sync.unknown_table', 'retained intent references an unknown 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(String(row.intent));
+            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.unique_conflicts === null) {
+            if (row.commit_seq === null && row.unique_conflicts === null) {
                 const authorized = conflicts.filter((conflict) => conflict.serverVersion >= 0 &&
-                    !db.query("SELECT 1 FROM _syncular_failed_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);
+                    !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);
                 if (authorized.length)
-                    db.exec('UPDATE _syncular_failed_rows SET unique_conflicts=? WHERE commit_id=? AND idx=?', [
+                    db.exec(`UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`, [
                         JSON.stringify(authorized.map((conflict) => ({
                             ...conflict,
                             serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
                         }))),
-                        String(row.commit_id),
-                        Number(row.idx),
+                        row.commit_id,
+                        row.idx,
                     ]);
             }
             if (conflicts.length)
@@ -117,26 +124,30 @@ export function restoreFailedBases(db, schema, absentIntent = false) {
         }
         if (absentIntent &&
             (json === null ||
-                db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [String(row.id)]).length))
+                db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [row.id]).length))
             continue;
         if (json === null)
-            deleteLocalRow(db, table, String(row.id), false);
+            deleteLocalRow(db, table, row.id, false);
         else {
             const values = JSON.parse(String(json));
             if (absentIntent) {
-                const operation = JSON.parse(String(row.op));
-                if (!table.columns.every((column) => Object.hasOwn(operation.values ?? {}, column.name)))
+                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)), Number(row.version ?? -1), false);
+            upsertLocalRow(db, table, table.columns.map((column) => jsonToRowValue(values[column.name] ?? null)), (row.version ?? -1), false);
         }
     }
+    return seen.size > 0;
 }
-export function failedOverlayCommits(db) {
+export function failedOverlayCommits(db, acknowledged = false, rowKeys) {
     const commits = new Map();
-    for (const row of db.query('SELECT * FROM _syncular_failed_rows ORDER BY at,commit_id,idx')) {
-        const id = String(row.commit_id);
-        const operation = JSON.parse(String(row.op));
+    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);
@@ -144,7 +155,7 @@ export function failedOverlayCommits(db) {
             commits.set(id, {
                 seq: 0,
                 clientCommitId: id,
-                createdAtMs: Number(row.at),
+                createdAtMs: row.at,
                 operations: [operation],
             });
     }
@@ -152,17 +163,21 @@ export function failedOverlayCommits(db) {
 }
 export function dropFailedRows(db, matches) {
     const ids = new Set();
-    for (const row of db.query('SELECT * FROM _syncular_failed_rows')) {
-        const json = row.intent ?? row.base;
-        if (json === null)
-            continue;
-        const values = JSON.parse(String(json));
-        if (matches(String(row.tbl), values))
-            ids.add(String(row.commit_id));
+    for (const row of retainedRows(db)) {
+        for (const json of [row.intent, row.base]) {
+            if (json === null)
+                continue;
+            const values = JSON.parse(String(json));
+            if (matches(row.tbl, values))
+                ids.add(row.commit_id);
+        }
     }
-    const dropped = failedOverlayCommits(db).filter((commit) => ids.has(commit.clientCommitId));
+    const dropped = [
+        ...failedOverlayCommits(db),
+        ...failedOverlayCommits(db, true),
+    ].filter((commit) => ids.has(commit.clientCommitId));
     for (const id of ids) {
-        db.exec('DELETE FROM _syncular_failed_rows WHERE commit_id=?', [id]);
+        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]);
     }
     return dropped;

package/dist/outbox.d.ts

@@ -34,12 +34,13 @@ export interface OutboxCommit {
 export interface OutboxBeforeImage {
     readonly opIndex: number;
     readonly existed: boolean;
+    readonly deliverySeq?: number;
     readonly syncVersion?: number;
     readonly values?: Readonly<Record<string, JsonRowValue>>;
 }
 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): OutboxCommit[];
+export declare function listOutbox(db: ClientDatabase, rowKeys?: readonly string[]): 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

@@ -7,26 +7,20 @@
  */
 import { encodeSparseRow, } from '@syncular/core';
 import { ClientSyncError } from './errors.js';
-import { jsonToRowValue, } from './schema.js';
+import { jsonToRowValue, matchesLocalScopes, } from './schema.js';
 export function appendOutboxCommit(db, clientCommitId, operations, nowMs, beforeImages = []) {
     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)]);
-    for (const image of beforeImages) {
-        db.exec('INSERT INTO _syncular_outbox_before_images(client_commit_id,op_index,existed,sync_version,values_json)VALUES(?,?,?,?,?)', [
-            clientCommitId,
-            image.opIndex,
-            image.existed ? 1 : 0,
-            image.syncVersion ?? null,
-            image.values === undefined ? null : JSON.stringify(image.values),
-        ]);
-    }
+    replaceOutboxBeforeImages(db, clientCommitId, beforeImages);
 }
 /** Pending commits in FIFO creation order (§7.1). Full reads serve replay and the public listing. */
-export function listOutbox(db) {
+export function listOutbox(db, rowKeys) {
     return db
-        .query('SELECT seq, client_commit_id, created_at_ms, operations FROM _syncular_outbox ORDER BY seq ASC')
+        .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)])
         .map(decodeOutboxRow);
 }
 function decodeOutboxRow(row) {
@@ -67,10 +61,13 @@ export function deleteOutboxCommit(db, clientCommitId) {
 }
 export function listOutboxBeforeImages(db, clientCommitId) {
     return db
-        .query('SELECT op_index,existed,sync_version,values_json 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 _syncular_outbox_before_images WHERE client_commit_id=? ORDER BY op_index', [clientCommitId])
         .map((row) => ({
         opIndex: row.op_index,
         existed: row.existed === 1,
+        ...(typeof row.delivery_seq === 'number'
+            ? { deliverySeq: row.delivery_seq }
+            : {}),
         ...(typeof row.sync_version === 'number'
             ? { syncVersion: row.sync_version }
             : {}),
@@ -83,8 +80,7 @@ export function listOutboxBeforeImages(db, clientCommitId) {
 }
 export function replaceOutboxBeforeImages(db, clientCommitId, replacements) {
     for (const image of replacements) {
-        db.exec('DELETE FROM _syncular_outbox_before_images WHERE client_commit_id=? AND op_index=?', [clientCommitId, image.opIndex]);
-        db.exec('INSERT INTO _syncular_outbox_before_images(client_commit_id,op_index,existed,sync_version,values_json)VALUES(?,?,?,?,?)', [
+        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', [
             clientCommitId,
             image.opIndex,
             image.existed ? 1 : 0,
@@ -109,7 +105,7 @@ function sparseValues(table, values) {
     // bump removed (or renamed) it — the commit cannot be expressed now.
     for (const key of Object.keys(values)) {
         if (!table.columnIndex.has(key)) {
-            throw new OutboxEncodeError(`outbox commit references column ${JSON.stringify(key)} on ${JSON.stringify(table.name)}, which the current schema no longer has (§7.4.4)`);
+            throw new OutboxEncodeError(`outbox column ${JSON.stringify(key)} is absent from table ${JSON.stringify(table.name)} (§7.4.4)`);
         }
     }
     return table.columns.map((column) => {
@@ -142,7 +138,7 @@ export async function encodeOutboxCommit(schema, commit, encryption, storedKeyId
         const table = schema.tables.get(op.table);
         if (table === undefined) {
             // §7.4.4: the bump removed this table — the commit cannot be encoded.
-            throw new OutboxEncodeError(`outbox commit ${commit.clientCommitId} targets table ${JSON.stringify(op.table)}, which the current schema no longer has (§7.4.4)`);
+            throw new OutboxEncodeError(`outbox table ${JSON.stringify(op.table)} is absent from the current schema (§7.4.4)`);
         }
         if (op.values === undefined) {
             throw new ClientSyncError('sync.invalid_request', `outbox upsert on ${op.table}/${op.rowId} has no values`);
@@ -183,13 +179,7 @@ export function dropOutboxCommitsInScope(db, table, effective) {
         const inScope = commit.operations.some((op) => {
             if (op.table !== table.name || op.values === undefined)
                 return false;
-            return entries.every(([variable, values]) => {
-                const column = table.scopeColumnByVariable.get(variable);
-                if (column === undefined)
-                    return false;
-                const value = op.values?.[column];
-                return typeof value === 'string' && values.includes(value);
-            });
+            return matchesLocalScopes(table, effective, op.values);
         });
         if (inScope) {
             deleteOutboxCommit(db, commit.clientCommitId);

package/dist/outcomes.js

@@ -1,3 +1,4 @@
+import { RETAINED_ROWS } from './failed-overlay.js';
 import { ClientSyncError } from './errors.js';
 import { mapRowValues, jsonToRowValue, rowValueToJson, } from './schema.js';
 function encodeResults(results) {
@@ -32,25 +33,25 @@ function decodeResults(raw) {
 }
 function parseOutcome(db, row) {
     const retainedRows = db
-        .query('SELECT tbl,id,intent,base,version,unique_conflicts FROM _syncular_failed_rows WHERE commit_id=? ORDER BY idx', [String(row.client_commit_id)])
+        .query(`SELECT tbl,id,intent,base,version,unique_conflicts FROM ${RETAINED_ROWS} WHERE commit_seq IS NULL AND commit_id=? ORDER BY idx`, [row.client_commit_id])
         .map((retained) => {
         const decode = (value) => value === null
             ? null
             : Object.fromEntries(Object.entries(JSON.parse(String(value))).map(([key, value]) => [key, jsonToRowValue(value)]));
         return {
-            table: String(retained.tbl),
-            rowId: String(retained.id),
+            table: retained.tbl,
+            rowId: retained.id,
             localRow: decode(retained.intent),
             ...(retained.unique_conflicts === null
                 ? {}
                 : {
-                    uniqueConflicts: JSON.parse(String(retained.unique_conflicts)).map((conflict) => ({
+                    uniqueConflicts: JSON.parse(retained.unique_conflicts).map((conflict) => ({
                         ...conflict,
                         serverRow: decode(JSON.stringify(conflict.serverRow)),
                     })),
                 }),
             serverRow: decode(retained.base),
-            serverVersion: retained.version === null ? null : Number(retained.version),
+            serverVersion: retained.version === null ? null : retained.version,
         };
     });
     return {

package/dist/schema.d.ts

@@ -93,6 +93,7 @@ export declare const OPTIMISTIC_VERSION = -1;
  * pass through this filter.
  */
 export declare function stripSyncColumns(rows: SqlRow[]): SqlRow[];
+export declare function matchesLocalScopes(table: CompiledClientTable, scopes: Readonly<Record<string, readonly string[]>>, values: Readonly<Record<string, JsonRowValue>>): boolean;
 export declare function quoteIdent(name: string): string;
 /**
  * §5.11: the app-side type of a column for local (plaintext) storage. For an