@syncular/client 0.30.7 → 0.30.9

package/src/errors.ts

@@ -45,6 +45,14 @@ export class ClientSyncError extends Error {
   }
 }
 
+/** Shared invalid-request construction for client validators and transport guards. */
+export function invalidRequest(
+  message: string,
+  retryable = false,
+): ClientSyncError {
+  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

package/src/failed-overlay.ts

@@ -0,0 +1,165 @@
+import { ClientSyncError } from './errors';
+import type { ClientDatabase } from './database';
+import type { CompiledClientSchema, JsonRowValue } from './schema';
+import { jsonToRowValue, quoteIdent } from './schema';
+import type {
+  OutboxCommit,
+  OutboxBeforeImage,
+  OutboxOperation,
+} from './outbox';
+import { deleteLocalRow, upsertLocalRow } from './apply';
+
+/** Protected failure state. The server base advances independently of intent. */
+export function ensureFailedOverlaySchema(db: ClientDatabase): void {
+  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: ClientDatabase,
+  table: string,
+  rowId: string,
+  values?: Readonly<Record<string, JsonRowValue>>,
+  version?: number,
+): void {
+  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: ClientDatabase,
+  commit: OutboxCommit,
+  images: readonly OutboxBeforeImage[],
+): void {
+  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: ClientDatabase,
+  schema: CompiledClientSchema,
+  absentIntent = false,
+): void {
+  const seen = new Set<string>();
+  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: Record<string, JsonRowValue> = 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: ClientDatabase): OutboxCommit[] {
+  const commits = new Map<
+    string,
+    {
+      seq: number;
+      clientCommitId: string;
+      createdAtMs: number;
+      operations: OutboxOperation[];
+    }
+  >();
+  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: OutboxOperation = 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: ClientDatabase,
+  matches: (
+    table: string,
+    values: Readonly<Record<string, JsonRowValue>>,
+  ) => boolean,
+): OutboxCommit[] {
+  const ids = new Set<string>();
+  for (const row of db.query('SELECT * FROM _syncular_failed_rows')) {
+    const json = row.intent ?? row.base;
+    if (json === null) continue;
+    const values: Record<string, JsonRowValue> = 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/src/invalidation.ts

@@ -164,6 +164,10 @@ export class ChangeAccumulator {
     }
   }
 
+  hasTable(name: string): boolean {
+    return this.#tables.has(name);
+  }
+
   get touched(): boolean {
     return (
       this.#tables.size > 0 ||

package/src/outcomes.ts

@@ -69,6 +69,16 @@ export type CommitOperationOutcome =
       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;
@@ -82,6 +92,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;
@@ -154,7 +165,33 @@ function decodeResults(raw: string): CommitOperationOutcome[] {
   });
 }
 
-function parseOutcome(row: Readonly<Record<string, unknown>>): CommitOutcome {
+function parseOutcome(
+  db: ClientDatabase,
+  row: Readonly<Record<string, unknown>>,
+): CommitOutcome {
+  const retainedRows: RetainedCommitRow[] = 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: unknown): Record<string, RowValue> | null =>
+        value === null
+          ? null
+          : Object.fromEntries(
+              Object.entries(
+                JSON.parse(String(value)) as Record<string, JsonRowValue>,
+              ).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 as number,
     clientCommitId: row.client_commit_id as string,
@@ -164,6 +201,7 @@ function parseOutcome(row: Readonly<Record<string, unknown>>): CommitOutcome {
     ...(typeof row.operations === 'string'
       ? { operations: JSON.parse(row.operations) as OutboxOperation[] }
       : {}),
+    ...(retainedRows.length > 0 ? { retainedRows } : {}),
     resolution: row.resolution as CommitOutcomeResolution,
     ...(typeof row.resolved_at_ms === 'number'
       ? { resolvedAtMs: row.resolved_at_ms }
@@ -205,7 +243,7 @@ export function commitOutcome(
        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(
@@ -229,7 +267,7 @@ export function listCommitOutcomes(
       ORDER BY seq DESC${limit === undefined ? '' : ' LIMIT ?'}`,
     limit === undefined ? [] : [limit],
   );
-  return rows.map(parseOutcome);
+  return rows.map((row) => parseOutcome(db, row));
 }
 
 export function persistCommitOutcomeResolution(

package/src/remote.ts

@@ -15,6 +15,7 @@ import {
   type PushOperationResult,
   type PushResultDetailsFrame,
   type PushResultFrame,
+  type RowValue,
   type RemoteOperationResponse,
 } from '@syncular/core';
 import type { MutationInput } from './client';
@@ -25,6 +26,8 @@ import {
   compileClientSchema,
   type ClientSchema,
   recordToRowValues,
+  normalizeRecordKeys,
+  coerceSqlRepresentation,
 } from './schema';
 import type { SyncTransport } from './transport';
 import type {
@@ -311,7 +314,18 @@ 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),
+                  ) as RowValue)
+                : 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/src/schema.ts

@@ -1,3 +1,4 @@
+import { ensureFailedOverlaySchema } from './failed-overlay';
 /**
  * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
  * compiles and is emitted by codegen. Drives local table
@@ -6,7 +7,7 @@
  */
 import type { RowColumn, RowValue } from '@syncular/core';
 import type { ClientDatabase, SqlRow, SqlValue } from './database';
-import { ClientSyncError } from './errors';
+import { invalidRequest } from './errors';
 import { snakeToCamel } from './naming';
 
 /** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
@@ -532,6 +533,7 @@ export function ensureLocalSyncedSchema(
  */
 export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
   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(
@@ -707,20 +709,17 @@ export function normalizeRecordKeys(
       table.columnIndex.get(key) ?? table.columnIndexByCamel.get(key);
     if (index === undefined) {
       if (key.startsWith('_sync_')) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
+        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',
+      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] as RowColumn).name;
     if (normalized.has(sqlName)) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         `table ${table.name}: column ${JSON.stringify(sqlName)} appears twice in mutation values (as both snake_case and camelCase) — pass it once`,
       );
     }
@@ -765,8 +764,7 @@ export function recordToRowValues(
     const value = normalized.get(column.name);
     if (value === undefined || value === null) {
       if (!column.nullable) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
+        throw invalidRequest(
           `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1 full-row payloads)`,
         );
       }

package/src/wasm-database.ts

@@ -33,6 +33,7 @@ import {
 } from './database';
 import {
   ClientSyncError,
+  invalidRequest,
   STORAGE_BUSY_CODE,
   STORAGE_UNAVAILABLE_CODE,
 } from './errors';
@@ -205,8 +206,7 @@ class WasmClientDatabase implements ClientDatabase {
     assertImageAlias(alias);
     const pointer = this.#db.pointer;
     if (pointer === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'sqlite-wasm database exposes no native handle for image import',
       );
     }
@@ -225,8 +225,7 @@ class WasmClientDatabase implements ClientDatabase {
         capi.SQLITE_DESERIALIZE_FREEONCLOSE | capi.SQLITE_DESERIALIZE_READONLY,
       );
       if (rc !== 0) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
+        throw invalidRequest(
           `sqlite3_deserialize failed with code ${rc} (§5.3)`,
         );
       }
@@ -398,14 +397,12 @@ export async function openPersistentWasmDatabase(
   options?: PersistentWasmDatabaseOptions,
 ): Promise<ClientDatabase> {
   if (!/^[A-Za-z0-9._-]+$/.test(name)) {
-    throw new ClientSyncError(
-      'sync.invalid_request',
+    throw invalidRequest(
       `invalid persistent database name ${JSON.stringify(name)}`,
     );
   }
   if (!inWorkerContext()) {
-    throw new ClientSyncError(
-      'sync.invalid_request',
+    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 ' +

package/src/window.ts

@@ -14,7 +14,7 @@
  */
 import { canonicalScopeJson, type ScopeMap } from '@syncular/core';
 import type { ClientDatabase } from './database';
-import { ClientSyncError } from './errors';
+import { invalidRequest } from './errors';
 
 export type TimeBucketUnit = 'month';
 
@@ -35,8 +35,7 @@ export function creationTimeBucket(
     createdAtMs < 0 ||
     createdAtMs > MAX_TIME_BUCKET_MS
   ) {
-    throw new ClientSyncError(
-      'sync.invalid_request',
+    throw invalidRequest(
       'creationTimeBucket requires a supported unit and a UTC timestamp from 1970 through 9999',
     );
   }
@@ -59,16 +58,14 @@ export function last(
     nowMs < 0 ||
     nowMs > MAX_TIME_BUCKET_MS
   ) {
-    throw new ClientSyncError(
-      'sync.invalid_request',
+    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',
+    throw invalidRequest(
       'last requires every returned UTC month to fall from 1970 through 9999',
     );
   }

package/src/worker-entry.ts

@@ -355,6 +355,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       },
       ...(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/src/worker-host.ts

@@ -196,6 +196,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`.
@@ -929,6 +930,9 @@ function buildInitConfig(
       : {}),
     ...(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/src/worker-protocol.ts

@@ -114,6 +114,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`).