@syncular/client 0.30.6 → 0.30.9

package/README.md

@@ -361,7 +361,7 @@ that rolled back with the terminating operation. It stays in the protected
 client database and is never added to the wire protocol, preferences, or
 telemetry; successful and historical outcomes may omit it.
 
-Rejected optimistic state is removed immediately, even when a validator emits
+By default, rejected optimistic state is removed immediately, even when a validator emits
 no server row in the pull half. The TypeScript client stores protected,
 restart-safe before-images beside each pending outbox commit, restores the last
 confirmed rows (including rejected deletes and atomic siblings), and then
@@ -373,7 +373,17 @@ Use `patch(table, rowId, partial, { baseVersion? })` for editor-style partial
 updates. The wire carries a sparse operation: the primary key plus the supplied
 columns are present, and the durable local operation keeps the same presence
 set so conflict and rejection UI knows which columns the user touched. A
-full-row `mutate` marks every column present.
+full-row `mutate` upsert marks every column present. `mutate` also accepts
+`op: 'patch'` with the primary key and supplied columns. A batch can mix sparse
+patches, upserts and deletes atomically. Omitted encrypted columns require no
+key and retain their ciphertext.
+
+Set `retainFailedCommits: true` to keep the complete failed aggregate visible
+and durable after its outbox drains. Incoming server state advances a separate
+base. `outcome.retainedRows` exposes complete intended rows and the latest
+server rows and versions. Resolve explicitly with `resolved_keep_server`, or
+create a reviewed replacement and link it through `superseded`. Security purge
+and scope revocation remove whole retained aggregates.
 
 ## Application-authorized local security purge
 

package/dist/apply.d.ts

@@ -9,8 +9,8 @@ import type { EncryptionConfig } from './encryption.js';
 import { type CompiledClientSchema, type CompiledClientTable } from './schema.js';
 /** Lets the client wrap the physical write in its revision transaction. */
 export type ApplyTransaction = <T>(fn: () => T) => T;
-export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number): void;
-export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string): void;
+export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, serverWrite?: boolean): void;
+export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string, serverWrite?: boolean): void;
 /**
  * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4).
  * Upserts land with `_sync_version = rowVersion`; deletes remove the row.

package/dist/apply.js

@@ -1,11 +1,12 @@
+import { retainedBaseWrite } from './failed-overlay.js';
 /**
  * Local application of server data: `COMMIT` frames (§4.5), rows segments
  * (§5.2, §5.6), and the scope-matched delete shared by the §3.3 purge
  * contract and the §5.6 first-page rule.
  */
 import { decodeRow, } from '@syncular/core';
-import { ClientSyncError } from './errors.js';
-import { quoteIdent, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
+import { ClientSyncError, invalidRequest } from './errors.js';
+import { quoteIdent, SYNC_VERSION_COLUMN, toSqlValue, rowValueToJson, } from './schema.js';
 function upsertSql(table) {
     const names = [
         ...table.columns.map((column) => quoteIdent(column.name)),
@@ -19,10 +20,17 @@ function upsertSql(table) {
     return `INSERT INTO ${quoteIdent(table.name)} (${names.join(', ')}) VALUES (${placeholders})
     ON CONFLICT (${quoteIdent(table.primaryKey)}) DO UPDATE SET ${updates}`;
 }
-export function upsertLocalRow(db, table, values, syncVersion) {
+export function upsertLocalRow(db, table, values, syncVersion, serverWrite = true) {
+    if (serverWrite)
+        retainedBaseWrite(db, table.name, String(values[table.primaryKeyIndex]), Object.fromEntries(table.columns.map((column, index) => [
+            column.name,
+            rowValueToJson(values[index] ?? null),
+        ])), syncVersion);
     db.exec(upsertSql(table), [...values.map(toSqlValue), syncVersion]);
 }
-export function deleteLocalRow(db, table, rowId) {
+export function deleteLocalRow(db, table, rowId, serverWrite = true) {
+    if (serverWrite)
+        retainedBaseWrite(db, table.name, rowId);
     db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [rowId]);
 }
 /**
@@ -42,7 +50,7 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
     for (const change of frame.changes) {
         const tableName = frame.tables[change.tableIndex];
         if (tableName === undefined) {
-            throw new ClientSyncError('sync.invalid_request', `COMMIT change tableIndex ${change.tableIndex} out of range`);
+            throw invalidRequest(`COMMIT change tableIndex ${change.tableIndex} out of range`);
         }
         const table = schema.tables.get(tableName);
         if (table === undefined) {
@@ -53,7 +61,7 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
             continue;
         }
         if (change.row === undefined || change.rowVersion === undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'upsert change without row payload');
+            throw invalidRequest('upsert change without row payload');
         }
         let values = decodeRow(table.columns, change.row);
         if (encryption !== undefined && table.hasEncryptedColumns) {
@@ -131,6 +139,9 @@ export function deleteScopedRows(db, table, effective) {
         clauses.push(`${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`);
         params.push(...values);
     }
+    for (const row of db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`, params)) {
+        retainedBaseWrite(db, table.name, String(row.id));
+    }
     db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`, params);
 }
 /**
@@ -177,7 +188,7 @@ export function evictScopedRows(db, table, effective, pinnedRowIds) {
 }
 const IMAGE_ALIAS = 'syncular_image';
 function imageInvalid(detail) {
-    throw new ClientSyncError('sync.invalid_request', `sqlite segment rejected: ${detail} (§5.3)`);
+    throw invalidRequest(`sqlite segment rejected: ${detail} (§5.3)`);
 }
 /**
  * Apply a §5.3 sqlite image in committed chunks of at most 1,024 rows: validate
@@ -190,7 +201,7 @@ function imageInvalid(detail) {
 export async function applySqliteSegment(db, schema, table, bytes, descriptor, options) {
     const withImage = db.withSqliteImage?.bind(db);
     if (withImage === undefined) {
-        throw new ClientSyncError('sync.invalid_request', 'received a sqlite segment but the database backend cannot import images (§4.2: do not advertise accept bit 2)');
+        throw invalidRequest('received a sqlite segment but the database backend cannot import images (§4.2: do not advertise accept bit 2)');
     }
     if (descriptor.table !== table.name) {
         imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
@@ -283,6 +294,12 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
            FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}
            ON CONFLICT (${primaryKey}) DO UPDATE SET ${updates}`, params);
                 applied += Number(db.query('SELECT changes() AS n')[0]?.n ?? 0);
+                for (const row of db.query(`SELECT * FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}`, params)) {
+                    retainedBaseWrite(db, table.name, String(row[table.primaryKey]), Object.fromEntries(table.columns.map((column) => [
+                        column.name,
+                        rowValueToJson(row[column.name]),
+                    ])), Number(row._syncular_version));
+                }
             });
             options.onProgress?.(applied);
             await yieldToHost();

package/dist/client.d.ts

@@ -26,8 +26,8 @@ import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './tran
 import { type WindowBase } from './window.js';
 export type MutationInput = {
     readonly table: string;
-    readonly op: 'upsert';
-    /** Full-row values keyed by column name (§6.1: full row payloads). */
+    readonly op: 'upsert' | 'patch';
+    /** Column-keyed full row for upsert, or primary key plus present columns for patch. */
     readonly values: Readonly<Record<string, unknown>>;
     readonly baseVersion?: number;
 } | {
@@ -36,7 +36,7 @@ export type MutationInput = {
     readonly rowId: string;
     readonly baseVersion?: number;
 };
-export type { CommitOperationOutcome, CommitOutcome, CommitOutcomeQuery, ConflictRecord, RejectionRecord, ResolveCommitOutcomeInput, } from './outcomes.js';
+export type { CommitOperationOutcome, CommitOutcome, CommitOutcomeQuery, RetainedCommitRow, ConflictRecord, RejectionRecord, ResolveCommitOutcomeInput, } from './outcomes.js';
 export interface SchemaFloor {
     readonly requiredSchemaVersion?: number;
     readonly latestSchemaVersion?: number;
@@ -104,6 +104,8 @@ export interface SyncClientLimits {
     readonly outcomeRetentionMaxEntries?: number;
 }
 export interface SyncClientConfig {
+    /** Keep rejected/conflicting local intent visible until explicit resolution. */
+    readonly retainFailedCommits?: boolean;
     readonly database: ClientDatabase;
     readonly schema: ClientSchema;
     readonly transport: SyncTransport;
@@ -408,7 +410,7 @@ export declare class SyncClient {
     /**
      * Mark a durable failure handled without deleting its evidence. Conflicts
      * may keep the server row or link to a replacement commit; rejections may
-     * only be superseded by a named replacement. Applied/cached history may be
+     * also keep the server row or link to a named replacement. Applied/cached history may be
      * dismissed. The transition is one-way and survives restart.
      */
     resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;