@syncular/client 0.30.6 → 0.30.9

package/dist/database.js

@@ -1,3 +1,4 @@
+import { classifySqliteFailure } from './errors.js';
 /** Attach-schema aliases are code-chosen, never user input — enforce it. */
 export function assertImageAlias(alias) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
@@ -10,6 +11,10 @@ export function assertImageAlias(alias) {
  */
 export function runTransaction(depthHolder, run, fn) {
     const depth = depthHolder.depth;
+    if (depth === 0)
+        delete depthHolder.aborted;
+    else if (depthHolder.aborted)
+        throw depthHolder.aborted.error;
     const savepoint = `syncular_sp_${depth}`;
     if (depth === 0)
         run('BEGIN');
@@ -18,6 +23,9 @@ export function runTransaction(depthHolder, run, fn) {
     depthHolder.depth = depth + 1;
     try {
         const result = fn();
+        const aborted = depthHolder.aborted;
+        if (aborted)
+            throw aborted.error;
         depthHolder.depth = depth;
         if (depth === 0)
             run('COMMIT');
@@ -25,15 +33,26 @@ export function runTransaction(depthHolder, run, fn) {
             run(`RELEASE ${savepoint}`);
         return result;
     }
-    catch (error) {
+    catch (caught) {
+        const aborted = depthHolder.aborted;
+        const error = aborted?.error ?? caught;
         depthHolder.depth = depth;
-        if (depth === 0) {
-            run('ROLLBACK');
+        try {
+            if (depth === 0)
+                run('ROLLBACK');
+            else {
+                run(`ROLLBACK TO ${savepoint}`);
+                run(`RELEASE ${savepoint}`);
+            }
         }
-        else {
-            run(`ROLLBACK TO ${savepoint}`);
-            run(`RELEASE ${savepoint}`);
+        catch (rollbackError) {
+            // SQLite can end the whole transaction after SQLITE_FULL or SQLITE_IOERR.
+            // Poison remaining nested scopes until the outer owner unwinds.
+            depthHolder.aborted = { error };
+            if (error instanceof Error && !('rollbackError' in error)) {
+                Object.defineProperty(error, 'rollbackError', { value: rollbackError });
+            }
         }
-        throw error;
+        throw classifySqliteFailure(error).error;
     }
 }

package/dist/diagnostics.d.ts

@@ -113,7 +113,7 @@ export interface DiagnosticQueryFailure {
     readonly id: string;
     /** Distinct generated table names the query depends on, ascending. */
     readonly tables: readonly string[];
-    readonly code: 'client.storage_corrupt' | 'client.storage_io' | 'client.query_failed';
+    readonly code: 'client.storage_corrupt' | 'client.storage_full' | 'client.storage_io' | 'client.query_failed';
     /** SQLite extended result code, when the driver exposed one. */
     readonly sqliteCode?: number;
     /** First failure since this id's last successful read. */

package/dist/errors.d.ts

@@ -5,6 +5,8 @@ export declare const STORAGE_BUSY_CODE = "client.storage_busy";
 export declare const STORAGE_UNAVAILABLE_CODE = "client.storage_unavailable";
 /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
 export declare const STORAGE_CORRUPT_CODE = "client.storage_corrupt";
+/** Local SQLite storage has no space for the write. */
+export declare const STORAGE_FULL_CODE = "client.storage_full";
 /** A local read hit SQLITE_IOERR (SPEC §7.5). */
 export declare const STORAGE_IO_CODE = "client.storage_io";
 /** SPEC §8.8: a round under `realtimePolicy: 'required'` found no socket. */
@@ -23,6 +25,8 @@ export declare class ClientSyncError extends Error {
     readonly details: Readonly<Record<string, unknown>> | undefined;
     constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>);
 }
+/** Shared invalid-request construction for client validators and transport guards. */
+export declare function invalidRequest(message: string, retryable?: boolean): ClientSyncError;
 /**
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
  * for its required coverage. `code` is the attempt's static progress error
@@ -61,6 +65,6 @@ export declare class RealtimeUnavailableError extends ClientSyncError {
  */
 export declare function classifySqliteFailure(error: unknown): {
     readonly sqliteCode: number | undefined;
-    readonly code: typeof STORAGE_CORRUPT_CODE | typeof STORAGE_IO_CODE | undefined;
+    readonly code: typeof STORAGE_CORRUPT_CODE | typeof STORAGE_FULL_CODE | typeof STORAGE_IO_CODE | undefined;
     readonly error: unknown;
 };

package/dist/errors.js

@@ -4,6 +4,8 @@ export const STORAGE_BUSY_CODE = 'client.storage_busy';
 export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
 /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
 export const STORAGE_CORRUPT_CODE = 'client.storage_corrupt';
+/** Local SQLite storage has no space for the write. */
+export const STORAGE_FULL_CODE = 'client.storage_full';
 /** A local read hit SQLITE_IOERR (SPEC §7.5). */
 export const STORAGE_IO_CODE = 'client.storage_io';
 /** SPEC §8.8: a round under `realtimePolicy: 'required'` found no socket. */
@@ -27,6 +29,10 @@ export class ClientSyncError extends Error {
         this.details = details;
     }
 }
+/** Shared invalid-request construction for client validators and transport guards. */
+export function invalidRequest(message, retryable = false) {
+    return new ClientSyncError('sync.invalid_request', message, retryable);
+}
 /**
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
  * for its required coverage. `code` is the attempt's static progress error
@@ -73,6 +79,31 @@ export class RealtimeUnavailableError extends ClientSyncError {
  * original value.
  */
 export function classifySqliteFailure(error) {
+    if (error instanceof ClientSyncError) {
+        const sqliteCode = error.details?.sqliteCode;
+        let retained = error;
+        if ('rollbackError' in error &&
+            error.details?.rollbackFailure === undefined) {
+            const rollback = error.rollbackError;
+            retained = new ClientSyncError(error.code, error.message, error.retryable, {
+                ...error.details,
+                rollbackFailure: {
+                    message: rollback instanceof Error ? rollback.message : String(rollback),
+                    sqliteCode: classifySqliteFailure(rollback).sqliteCode,
+                },
+            });
+            Object.defineProperty(retained, 'cause', { value: error });
+        }
+        return {
+            sqliteCode: typeof sqliteCode === 'number' ? sqliteCode : undefined,
+            code: error.code === STORAGE_FULL_CODE ||
+                error.code === STORAGE_IO_CODE ||
+                error.code === STORAGE_CORRUPT_CODE
+                ? error.code
+                : undefined,
+            error: retained,
+        };
+    }
     const sqliteCode = error instanceof Error
         ? error.name === 'SQLiteError' &&
             'errno' in error &&
@@ -87,19 +118,34 @@ export function classifySqliteFailure(error) {
                     : undefined
         : undefined;
     const primary = sqliteCode === undefined ? undefined : sqliteCode & 0xff;
-    if (primary === 11 || primary === 26) {
-        return {
-            sqliteCode,
-            code: STORAGE_CORRUPT_CODE,
-            error: new ClientSyncError(STORAGE_CORRUPT_CODE, 'local SQLite storage is corrupt'),
-        };
-    }
-    if (primary === 10) {
-        return {
-            sqliteCode,
-            code: STORAGE_IO_CODE,
-            error: new ClientSyncError(STORAGE_IO_CODE, 'local SQLite storage I/O failed'),
-        };
-    }
-    return { sqliteCode, code: undefined, error };
+    const code = primary === 13
+        ? STORAGE_FULL_CODE
+        : primary === 10
+            ? STORAGE_IO_CODE
+            : primary === 11 || primary === 26
+                ? STORAGE_CORRUPT_CODE
+                : undefined;
+    if (code === undefined)
+        return { sqliteCode, code, error };
+    const rollback = error instanceof Error && 'rollbackError' in error
+        ? error.rollbackError
+        : undefined;
+    const failure = new ClientSyncError(code, primary === 13
+        ? 'local SQLite storage is full'
+        : primary === 10
+            ? 'local SQLite storage I/O failed'
+            : 'local SQLite storage is corrupt', false, {
+        sqliteCode,
+        sqliteMessage: error instanceof Error ? error.message : String(error),
+        ...(rollback !== undefined
+            ? {
+                rollbackFailure: {
+                    message: rollback instanceof Error ? rollback.message : String(rollback),
+                    sqliteCode: classifySqliteFailure(rollback).sqliteCode,
+                },
+            }
+            : {}),
+    });
+    Object.defineProperty(failure, 'cause', { value: error });
+    return { sqliteCode, code, error: failure };
 }

package/dist/failed-overlay.d.ts

@@ -0,0 +1,10 @@
+import type { ClientDatabase } from './database.js';
+import type { CompiledClientSchema, JsonRowValue } from './schema.js';
+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: string, 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 restoreFailedBases(db: ClientDatabase, schema: CompiledClientSchema, absentIntent?: boolean): void;
+export declare function failedOverlayCommits(db: ClientDatabase): OutboxCommit[];
+export declare function dropFailedRows(db: ClientDatabase, matches: (table: string, values: Readonly<Record<string, JsonRowValue>>) => boolean): OutboxCommit[];

package/dist/failed-overlay.js

@@ -0,0 +1,97 @@
+import { ClientSyncError } from './errors.js';
+import { jsonToRowValue, quoteIdent } 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,
+    PRIMARY KEY(commit_id, idx))`);
+}
+export function retainedBaseWrite(db, table, rowId, values, version) {
+    db.exec('UPDATE _syncular_failed_rows SET base = ?, version = ? WHERE tbl = ? AND id = ?', [
+        values === undefined ? null : JSON.stringify(values),
+        version ?? null,
+        table,
+        rowId,
+    ]);
+}
+export function retainFailedRows(db, commit, images) {
+    for (const [index, operation] of commit.operations.entries()) {
+        const image = images.find((image) => image.opIndex === index);
+        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 (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+            commit.clientCommitId,
+            index,
+            operation.table,
+            operation.rowId,
+            commit.createdAtMs,
+            JSON.stringify(operation),
+            initial ? JSON.stringify(initial) : null,
+            image.values ? JSON.stringify(image.values) : null,
+            image.syncVersion ?? null,
+        ]);
+    }
+}
+export function restoreFailedBases(db, schema, absentIntent = false) {
+    const seen = new Set();
+    for (const row of db.query('SELECT * FROM _syncular_failed_rows ORDER BY at, commit_id, idx')) {
+        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));
+        if (!table)
+            throw new ClientSyncError('sync.unknown_table', 'retained intent references an unknown table');
+        const json = absentIntent ? row.intent : row.base;
+        if (absentIntent &&
+            (json === null ||
+                db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [String(row.id)]).length))
+            continue;
+        if (json === null)
+            deleteLocalRow(db, table, String(row.id), false);
+        else {
+            const values = JSON.parse(String(json));
+            upsertLocalRow(db, table, table.columns.map((column) => jsonToRowValue(values[column.name] ?? null)), Number(row.version ?? -1), false);
+        }
+    }
+}
+export function failedOverlayCommits(db) {
+    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));
+        const prior = commits.get(id);
+        if (prior)
+            prior.operations.push(operation);
+        else
+            commits.set(id, {
+                seq: 0,
+                clientCommitId: id,
+                createdAtMs: Number(row.at),
+                operations: [operation],
+            });
+    }
+    return [...commits.values()];
+}
+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));
+    }
+    const dropped = failedOverlayCommits(db).filter((commit) => ids.has(commit.clientCommitId));
+    for (const id of ids)
+        db.exec('DELETE FROM _syncular_failed_rows WHERE commit_id = ?', [id]);
+    return dropped;
+}

package/dist/invalidation.d.ts

@@ -83,6 +83,7 @@ export declare class ChangeAccumulator {
     scopeMap(table: CompiledClientTable, scopes: ScopeMap): void;
     /** Add precise keys for a COMMIT change's stored scope values. */
     changeScopes(table: CompiledClientTable, scopes: Readonly<Record<string, string>>): void;
+    hasTable(name: string): boolean;
     get touched(): boolean;
     get statusChanged(): boolean;
     finish(revision: LocalRevision, status: SyncStatusSnapshot | undefined): ClientChangeBatch;

package/dist/invalidation.js

@@ -73,6 +73,9 @@ export class ChangeAccumulator {
             }
         }
     }
+    hasTable(name) {
+        return this.#tables.has(name);
+    }
     get touched() {
         return (this.#tables.size > 0 ||
             this.#windows.size > 0 ||

package/dist/outcomes.d.ts

@@ -50,6 +50,15 @@ export type CommitOperationOutcome = {
     readonly status: 'error';
     readonly rejection: RejectionRecord;
 };
+export interface RetainedCommitRow {
+    readonly table: string;
+    readonly rowId: string;
+    /** Complete intended row, or null for a local deletion. */
+    readonly localRow: Readonly<Record<string, RowValue>> | null;
+    /** Latest authorized server base, or null for an absent server row. */
+    readonly serverRow: Readonly<Record<string, RowValue>> | null;
+    readonly serverVersion: number | null;
+}
 export interface CommitOutcome {
     /** Monotonic local journal order; not a server sequence. */
     readonly sequence: number;
@@ -63,6 +72,7 @@ export interface CommitOutcome {
      * for successful and historical outcomes. Never sent over the wire.
      */
     readonly operations?: readonly OutboxOperation[];
+    readonly retainedRows?: readonly RetainedCommitRow[];
     readonly resolution: CommitOutcomeResolution;
     readonly resolvedAtMs?: number;
     readonly replacementClientCommitId?: string;

package/dist/outcomes.js

@@ -36,7 +36,21 @@ function decodeResults(raw) {
         };
     });
 }
-function parseOutcome(row) {
+function parseOutcome(db, row) {
+    const retainedRows = db
+        .query('SELECT tbl, id, intent, base, version FROM _syncular_failed_rows WHERE commit_id = ? ORDER BY idx', [String(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),
+            localRow: decode(retained.intent),
+            serverRow: decode(retained.base),
+            serverVersion: retained.version === null ? null : Number(retained.version),
+        };
+    });
     return {
         sequence: row.seq,
         clientCommitId: row.client_commit_id,
@@ -46,6 +60,7 @@ function parseOutcome(row) {
         ...(typeof row.operations === 'string'
             ? { operations: JSON.parse(row.operations) }
             : {}),
+        ...(retainedRows.length > 0 ? { retainedRows } : {}),
         resolution: row.resolution,
         ...(typeof row.resolved_at_ms === 'number'
             ? { resolvedAtMs: row.resolved_at_ms }
@@ -73,7 +88,7 @@ export function commitOutcome(db, clientCommitId) {
     const row = db.query(`SELECT seq, client_commit_id, status, recorded_at_ms, results, operations,
             resolution, resolved_at_ms, replacement_client_commit_id
        FROM _syncular_commit_outcomes WHERE client_commit_id = ?`, [clientCommitId])[0];
-    return row === undefined ? undefined : parseOutcome(row);
+    return row === undefined ? undefined : parseOutcome(db, row);
 }
 export function listCommitOutcomes(db, query = {}) {
     const limit = query.limit;
@@ -87,7 +102,7 @@ export function listCommitOutcomes(db, query = {}) {
             resolution, resolved_at_ms, replacement_client_commit_id
        FROM _syncular_commit_outcomes ${where}
       ORDER BY seq DESC${limit === undefined ? '' : ' LIMIT ?'}`, limit === undefined ? [] : [limit]);
-    return rows.map(parseOutcome);
+    return rows.map((row) => parseOutcome(db, row));
 }
 export function persistCommitOutcomeResolution(db, input, nowMs) {
     db.exec(`UPDATE _syncular_commit_outcomes

package/dist/remote.js

@@ -5,7 +5,7 @@
 import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeSparseRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
 import { encryptRowValues } from './encryption.js';
 import { ClientSyncError } from './errors.js';
-import { compileClientSchema, recordToRowValues, } from './schema.js';
+import { compileClientSchema, recordToRowValues, normalizeRecordKeys, coerceSqlRepresentation, } from './schema.js';
 export function remoteCommand(id) {
     if (id.length === 0)
         throw invalid('remote command id must be non-empty');
@@ -157,7 +157,12 @@ export class SyncRemoteClient {
                 });
                 continue;
             }
-            let values = recordToRowValues(table, mutation.values);
+            const normalized = normalizeRecordKeys(table, mutation.values);
+            let values = mutation.op === 'patch'
+                ? table.columns.map((column) => normalized.has(column.name)
+                    ? coerceSqlRepresentation(column, normalized.get(column.name))
+                    : undefined)
+                : recordToRowValues(table, mutation.values);
             const rowId = values[table.primaryKeyIndex];
             if (typeof rowId !== 'string' || rowId.length === 0) {
                 throw invalid('remote upsert requires a non-empty string primary key');

package/dist/schema.js

@@ -1,4 +1,5 @@
-import { ClientSyncError } from './errors.js';
+import { ensureFailedOverlaySchema } from './failed-overlay.js';
+import { invalidRequest } from './errors.js';
 import { snakeToCamel } from './naming.js';
 const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
 const ALLOWED_FTS_TOKENIZERS = new Set([
@@ -361,6 +362,7 @@ export function ensureLocalSyncedSchema(db, schema) {
  */
 export function ensureLocalBookkeepingSchema(db) {
     db.transaction(() => {
+        ensureFailedOverlaySchema(db);
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
@@ -510,13 +512,13 @@ export function normalizeRecordKeys(table, record) {
         const index = table.columnIndex.get(key) ?? table.columnIndexByCamel.get(key);
         if (index === undefined) {
             if (key.startsWith('_sync_')) {
-                throw new ClientSyncError('sync.invalid_request', `table ${table.name}: ${JSON.stringify(key)} is an internal sync column and cannot appear in mutation values — did you build this record from a raw SELECT * row? (client.query() strips _sync_* columns; rows read via client.database keep them)`);
+                throw invalidRequest(`table ${table.name}: ${JSON.stringify(key)} is an internal sync column and cannot appear in mutation values — did you build this record from a raw SELECT * row? (client.query() strips _sync_* columns; rows read via client.database keep them)`);
             }
-            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: unknown column ${JSON.stringify(key)} in mutation values (snake_case and camelCase keys are accepted)`);
+            throw invalidRequest(`table ${table.name}: unknown column ${JSON.stringify(key)} in mutation values (snake_case and camelCase keys are accepted)`);
         }
         const sqlName = table.columns[index].name;
         if (normalized.has(sqlName)) {
-            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: column ${JSON.stringify(sqlName)} appears twice in mutation values (as both snake_case and camelCase) — pass it once`);
+            throw invalidRequest(`table ${table.name}: column ${JSON.stringify(sqlName)} appears twice in mutation values (as both snake_case and camelCase) — pass it once`);
         }
         normalized.set(sqlName, value);
     }
@@ -551,7 +553,7 @@ export function recordToRowValues(table, record) {
         const value = normalized.get(column.name);
         if (value === undefined || value === null) {
             if (!column.nullable) {
-                throw new ClientSyncError('sync.invalid_request', `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1 full-row payloads)`);
+                throw invalidRequest(`table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1 full-row payloads)`);
             }
             return null;
         }

package/dist/wasm-database.js

@@ -24,7 +24,7 @@
  */
 import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
 import { assertImageAlias, runTransaction, } from './database.js';
-import { ClientSyncError, STORAGE_BUSY_CODE, STORAGE_UNAVAILABLE_CODE, } from './errors.js';
+import { ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, STORAGE_UNAVAILABLE_CODE, } from './errors.js';
 function coerceParams(params) {
     return params.map((value) => {
         if (typeof value === 'boolean')
@@ -108,7 +108,7 @@ class WasmClientDatabase {
         assertImageAlias(alias);
         const pointer = this.#db.pointer;
         if (pointer === undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'sqlite-wasm database exposes no native handle for image import');
+            throw invalidRequest('sqlite-wasm database exposes no native handle for image import');
         }
         const { capi, wasm } = this.#sqlite3;
         this.exec(`ATTACH ':memory:' AS ${alias}`);
@@ -119,7 +119,7 @@ class WasmClientDatabase {
             // immutable inputs (§5.1).
             capi.SQLITE_DESERIALIZE_FREEONCLOSE | capi.SQLITE_DESERIALIZE_READONLY);
             if (rc !== 0) {
-                throw new ClientSyncError('sync.invalid_request', `sqlite3_deserialize failed with code ${rc} (§5.3)`);
+                throw invalidRequest(`sqlite3_deserialize failed with code ${rc} (§5.3)`);
             }
             return await fn();
         }
@@ -235,10 +235,10 @@ function configureSahCrashRecovery(db, sqlite3) {
  */
 export async function openPersistentWasmDatabase(name, options) {
     if (!/^[A-Za-z0-9._-]+$/.test(name)) {
-        throw new ClientSyncError('sync.invalid_request', `invalid persistent database name ${JSON.stringify(name)}`);
+        throw invalidRequest(`invalid persistent database name ${JSON.stringify(name)}`);
     }
     if (!inWorkerContext()) {
-        throw new ClientSyncError('sync.invalid_request', 'openPersistentWasmDatabase() must run inside a Web Worker: the ' +
+        throw invalidRequest('openPersistentWasmDatabase() must run inside a Web Worker: the ' +
             'persistent mode is whole-core-in-a-worker by design (Direction ' +
             'decision 2, 2026-07-03). Use the worker handle from the main ' +
             'thread, or openWasmDatabase() for explicitly ephemeral state.');

package/dist/window.js

@@ -13,7 +13,7 @@
  * transaction and the invalidation choke point.
  */
 import { canonicalScopeJson } from '@syncular/core';
-import { ClientSyncError } from './errors.js';
+import { invalidRequest } from './errors.js';
 const MAX_TIME_BUCKET_MS = 253_402_300_799_999;
 function monthBucket(year, month) {
     return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}`;
@@ -24,7 +24,7 @@ export function creationTimeBucket(createdAtMs, unit) {
         !Number.isSafeInteger(createdAtMs) ||
         createdAtMs < 0 ||
         createdAtMs > MAX_TIME_BUCKET_MS) {
-        throw new ClientSyncError('sync.invalid_request', 'creationTimeBucket requires a supported unit and a UTC timestamp from 1970 through 9999');
+        throw invalidRequest('creationTimeBucket requires a supported unit and a UTC timestamp from 1970 through 9999');
     }
     const date = new Date(createdAtMs);
     return monthBucket(date.getUTCFullYear(), date.getUTCMonth() + 1);
@@ -38,12 +38,12 @@ export function last(count, unit, nowMs = Date.now()) {
         !Number.isSafeInteger(nowMs) ||
         nowMs < 0 ||
         nowMs > MAX_TIME_BUCKET_MS) {
-        throw new ClientSyncError('sync.invalid_request', 'last requires a supported unit, a count from 1 through 1200, and a UTC timestamp from 1970 through 9999');
+        throw invalidRequest('last requires a supported unit, a count from 1 through 1200, and a UTC timestamp from 1970 through 9999');
     }
     const date = new Date(nowMs);
     const current = date.getUTCFullYear() * 12 + date.getUTCMonth();
     if (current - (count - 1) < 1970 * 12) {
-        throw new ClientSyncError('sync.invalid_request', 'last requires every returned UTC month to fall from 1970 through 9999');
+        throw invalidRequest('last requires every returned UTC month to fall from 1970 through 9999');
     }
     const units = [];
     for (let offset = count - 1; offset >= 0; offset -= 1) {

package/dist/worker-entry.js

@@ -16,11 +16,12 @@
 import { SyncClient } from './client.js';
 import { withClientDiagnosticsHost, } from './diagnostics.js';
 import { encryptionConfigFromKeyring } from './encryption.js';
-import { ClientSyncError, STORAGE_BUSY_CODE } from './errors.js';
+import { classifySqliteFailure, ClientSyncError, STORAGE_BUSY_CODE, } from './errors.js';
 import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
 import { openPersistentWasmDatabase } from './wasm-database.js';
 import { WORKER_FAILED_CODE, } from './worker-protocol.js';
-function toErrorShape(error) {
+function toErrorShape(caught) {
+    const error = classifySqliteFailure(caught).error;
     if (error instanceof ClientSyncError) {
         return {
             code: error.code,
@@ -249,6 +250,9 @@ export function startSyncWorker(overrides = {}) {
             },
             ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
             ...(config.limits !== undefined ? { limits: config.limits } : {}),
+            ...(config.retainFailedCommits !== undefined
+                ? { retainFailedCommits: config.retainFailedCommits }
+                : {}),
             ...(config.realtimePolicy !== undefined
                 ? { realtimePolicy: config.realtimePolicy }
                 : {}),

package/dist/worker-host.d.ts

@@ -87,6 +87,7 @@ export interface SyncClientHandleConfig {
     readonly securityPreflight?: boolean;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
+    readonly retainFailedCommits?: boolean;
     /**
      * SPEC §8.8 realtime policy for the worker-owned core, forwarded into
      * `WorkerInitConfig`. Absent ⇒ `optional`.

package/dist/worker-host.js

@@ -545,6 +545,9 @@ function buildInitConfig(config, headers = config.headers) {
             : {}),
         ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
         ...(config.limits !== undefined ? { limits: config.limits } : {}),
+        ...(config.retainFailedCommits !== undefined
+            ? { retainFailedCommits: config.retainFailedCommits }
+            : {}),
         ...(config.realtimePolicy !== undefined
             ? { realtimePolicy: config.realtimePolicy }
             : {}),

package/dist/worker-protocol.d.ts

@@ -80,6 +80,7 @@ export interface WorkerInitConfig {
     readonly securityPreflight?: boolean;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
+    readonly retainFailedCommits?: boolean;
     /**
      * SPEC §8.8 realtime policy for the worker-owned core; forwarded verbatim.
      * Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.30.6",
+  "version": "0.30.9",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.30.6"
+    "@syncular/core": "0.30.9"
   },
   "devDependencies": {
-    "@syncular/server": "0.30.6",
+    "@syncular/server": "0.30.9",
     "playwright": "1.63.0"
   }
 }