@syncular/client 0.8.0 → 0.9.0

package/README.md

@@ -118,6 +118,17 @@ retain the losing operation plus `serverVersion`/`serverRow`; active failures
 restore after restart and are never removed by retention. Configure the
 history cap with `limits.outcomeRetentionMaxEntries` (default 1,000).
 
+Use `patch(table, rowId, partial, { baseVersion? })` for editor-style partial
+updates. The wire still carries a full row, but the durable local operation
+records a sorted `changedFields` list so conflict and rejection UI knows which
+fields the user intended to touch. That intent is local-only and never enters
+`PUSH_COMMIT`; full-row `mutate` operations omit it.
+
+Validator rejections may include bounded `details` (`fieldPaths`, `reason`,
+`requiredAction`, and explicitly safe `references`). The details persist with
+the rejection. Treat every value as a machine hint: map known values to
+localized app UI and never render the diagnostic `message` directly.
+
 Resolution is explicit and one-way: conflicts can keep the server result or
 link to a replacement commit, rejections can link to a replacement, and
 successful history may be dismissed. See SPEC §7.2.1.

package/dist/client.js

@@ -963,9 +963,12 @@ export class SyncClient {
      * Returns the generated `clientCommitId`.
      */
     mutate(mutations) {
+        return this.#recordMutations(mutations);
+    }
+    #recordMutations(mutations, changedFieldsByIndex = []) {
         this.#requireStarted();
         const clientCommitId = crypto.randomUUID();
-        const operations = mutations.map((mutation) => {
+        const operations = mutations.map((mutation, index) => {
             const table = this.#table(mutation.table);
             if (mutation.op === 'delete') {
                 return {
@@ -994,6 +997,9 @@ export class SyncClient {
                     ? { baseVersion: mutation.baseVersion }
                     : {}),
                 values: json,
+                ...(changedFieldsByIndex[index] !== undefined
+                    ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
+                    : {}),
             };
         });
         this.#applyBatch((batch) => {
@@ -1033,10 +1039,11 @@ export class SyncClient {
         for (const column of compiled.columns) {
             record[column.name] = fromSqlValue(column, row[column.name] ?? null);
         }
-        for (const [name, value] of normalizeRecordKeys(compiled, partial)) {
+        const normalizedPartial = normalizeRecordKeys(compiled, partial);
+        for (const [name, value] of normalizedPartial) {
             record[name] = value;
         }
-        return this.mutate([
+        return this.#recordMutations([
             {
                 table,
                 op: 'upsert',
@@ -1045,7 +1052,7 @@ export class SyncClient {
                     ? { baseVersion: options.baseVersion }
                     : {}),
             },
-        ]);
+        ], [[...normalizedPartial.keys()].sort()]);
     }
     /** Host-facing patch result with explicit network work intent (§7.5). */
     patchCommand(table, rowId, partial, options) {
@@ -1519,6 +1526,12 @@ export class SyncClient {
         const summary = emptySummary(sentCommits.length);
         const commitsById = new Map(sentCommits.map((commit) => [commit.clientCommitId, commit]));
         const subsById = new Map((sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]));
+        const rejectionDetailsByCommit = new Map();
+        for (const frame of message.frames) {
+            if (frame.type !== 'PUSH_RESULT_DETAILS')
+                continue;
+            rejectionDetailsByCommit.set(frame.clientCommitId, new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])));
+        }
         const header = message.frames[0];
         if (header?.type !== 'RESP_HEADER') {
             throw new ClientSyncError('sync.invalid_request', 'missing RESP_HEADER');
@@ -1563,7 +1576,10 @@ export class SyncClient {
                         });
                         break;
                     case 'PUSH_RESULT':
-                        this.#applyBatch((batch) => this.#handlePushResult(frame, commitsById, summary, batch));
+                        this.#applyBatch((batch) => this.#handlePushResult(frame, commitsById, summary, batch, rejectionDetailsByCommit.get(frame.clientCommitId)));
+                        break;
+                    case 'PUSH_RESULT_DETAILS':
+                        // Pre-indexed above so companion ordering remains wire-additive.
                         break;
                     case 'SUB_START': {
                         const sub = subsById.get(frame.id);
@@ -1710,7 +1726,7 @@ export class SyncClient {
         }
         return { ...summary, bootstrapping };
     }
-    #handlePushResult(frame, commitsById, summary, batch) {
+    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails) {
         const commit = commitsById.get(frame.clientCommitId);
         if (commit === undefined)
             return;
@@ -1765,12 +1781,14 @@ export class SyncClient {
                 this.#config.onConflict?.(conflict);
             }
             else if (result.status === 'error') {
+                const details = rejectionDetails?.get(result.opIndex);
                 const rejection = {
                     clientCommitId: frame.clientCommitId,
                     opIndex: result.opIndex,
                     code: result.code,
                     message: result.message,
                     retryable: result.retryable,
+                    ...(details !== undefined ? { details } : {}),
                     ...(operation !== undefined ? { operation } : {}),
                 };
                 this.#rejections.push(rejection);

package/dist/outbox.d.ts

@@ -18,6 +18,11 @@ export interface OutboxOperation {
     readonly baseVersion?: number;
     /** Full-row values keyed by column name; present iff `op` is `upsert`. */
     readonly values?: Readonly<Record<string, JsonRowValue>>;
+    /**
+     * Local-only normalized columns intentionally supplied to `patch()`.
+     * Absent for full-row mutate/upsert because intent is then unknown.
+     */
+    readonly changedFields?: readonly string[];
 }
 export interface OutboxCommit {
     readonly seq: number;

package/dist/outcomes.d.ts

@@ -6,7 +6,7 @@
  * restart can never turn "rejected" into an inferred success. Conflict payloads
  * deliberately stay local; retention never deletes an unresolved failure.
  */
-import type { RowValue } from '@syncular/core';
+import type { RejectionDetails, RowValue } from '@syncular/core';
 import type { ClientDatabase } from './database.js';
 import type { OutboxOperation } from './outbox.js';
 export interface ConflictRecord {
@@ -28,6 +28,8 @@ export interface RejectionRecord {
     readonly code: string;
     readonly message: string;
     readonly retryable: boolean;
+    /** Bounded host-declared metadata safe for authorized recovery UI. */
+    readonly details?: RejectionDetails;
     readonly operation?: OutboxOperation;
 }
 export type CommitOutcomeStatus = 'applied' | 'cached' | 'conflict' | 'rejected';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.8.0"
+    "@syncular/core": "0.9.0"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.8.0",
+    "@syncular/server": "0.9.0",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -22,6 +22,7 @@ import {
   parseRealtimeServerEvent,
   REALTIME_TAG_DELTA,
   REALTIME_TAG_ROUND,
+  type RejectionDetails,
   type RequestFrame,
   type ResponseMessage,
   type RowColumn,
@@ -1502,9 +1503,16 @@ export class SyncClient {
    * Returns the generated `clientCommitId`.
    */
   mutate(mutations: readonly MutationInput[]): string {
+    return this.#recordMutations(mutations);
+  }
+
+  #recordMutations(
+    mutations: readonly MutationInput[],
+    changedFieldsByIndex: readonly (readonly string[] | undefined)[] = [],
+  ): string {
     this.#requireStarted();
     const clientCommitId = crypto.randomUUID();
-    const operations: OutboxOperation[] = mutations.map((mutation) => {
+    const operations: OutboxOperation[] = mutations.map((mutation, index) => {
       const table = this.#table(mutation.table);
       if (mutation.op === 'delete') {
         return {
@@ -1536,6 +1544,9 @@ export class SyncClient {
           ? { baseVersion: mutation.baseVersion }
           : {}),
         values: json,
+        ...(changedFieldsByIndex[index] !== undefined
+          ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
+          : {}),
       };
     });
     this.#applyBatch((batch) => {
@@ -1588,19 +1599,23 @@ export class SyncClient {
     for (const column of compiled.columns as readonly RowColumn[]) {
       record[column.name] = fromSqlValue(column, row[column.name] ?? null);
     }
-    for (const [name, value] of normalizeRecordKeys(compiled, partial)) {
+    const normalizedPartial = normalizeRecordKeys(compiled, partial);
+    for (const [name, value] of normalizedPartial) {
       record[name] = value;
     }
-    return this.mutate([
-      {
-        table,
-        op: 'upsert',
-        values: record,
-        ...(options?.baseVersion !== undefined
-          ? { baseVersion: options.baseVersion }
-          : {}),
-      },
-    ]);
+    return this.#recordMutations(
+      [
+        {
+          table,
+          op: 'upsert',
+          values: record,
+          ...(options?.baseVersion !== undefined
+            ? { baseVersion: options.baseVersion }
+            : {}),
+        },
+      ],
+      [[...normalizedPartial.keys()].sort()],
+    );
   }
 
   /** Host-facing patch result with explicit network work intent (§7.5). */
@@ -2150,6 +2165,17 @@ export class SyncClient {
     const subsById = new Map(
       (sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]),
     );
+    const rejectionDetailsByCommit = new Map<
+      string,
+      ReadonlyMap<number, RejectionDetails>
+    >();
+    for (const frame of message.frames) {
+      if (frame.type !== 'PUSH_RESULT_DETAILS') continue;
+      rejectionDetailsByCommit.set(
+        frame.clientCommitId,
+        new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])),
+      );
+    }
 
     const header = message.frames[0];
     if (header?.type !== 'RESP_HEADER') {
@@ -2198,9 +2224,18 @@ export class SyncClient {
             break;
           case 'PUSH_RESULT':
             this.#applyBatch((batch) =>
-              this.#handlePushResult(frame, commitsById, summary, batch),
+              this.#handlePushResult(
+                frame,
+                commitsById,
+                summary,
+                batch,
+                rejectionDetailsByCommit.get(frame.clientCommitId),
+              ),
             );
             break;
+          case 'PUSH_RESULT_DETAILS':
+            // Pre-indexed above so companion ordering remains wire-additive.
+            break;
           case 'SUB_START': {
             const sub = subsById.get(frame.id);
             const fresh =
@@ -2427,6 +2462,7 @@ export class SyncClient {
     commitsById: ReadonlyMap<string, OutboxCommit>,
     summary: MutableSummary,
     batch: ChangeAccumulator,
+    rejectionDetails: ReadonlyMap<number, RejectionDetails> | undefined,
   ): void {
     const commit = commitsById.get(frame.clientCommitId);
     if (commit === undefined) return;
@@ -2483,12 +2519,14 @@ export class SyncClient {
         summary.conflicts.push(conflict);
         this.#config.onConflict?.(conflict);
       } else if (result.status === 'error') {
+        const details = rejectionDetails?.get(result.opIndex);
         const rejection: RejectionRecord = {
           clientCommitId: frame.clientCommitId,
           opIndex: result.opIndex,
           code: result.code,
           message: result.message,
           retryable: result.retryable,
+          ...(details !== undefined ? { details } : {}),
           ...(operation !== undefined ? { operation } : {}),
         };
         this.#rejections.push(rejection);

package/src/outbox.ts

@@ -29,6 +29,11 @@ export interface OutboxOperation {
   readonly baseVersion?: number;
   /** Full-row values keyed by column name; present iff `op` is `upsert`. */
   readonly values?: Readonly<Record<string, JsonRowValue>>;
+  /**
+   * Local-only normalized columns intentionally supplied to `patch()`.
+   * Absent for full-row mutate/upsert because intent is then unknown.
+   */
+  readonly changedFields?: readonly string[];
 }
 
 export interface OutboxCommit {

package/src/outcomes.ts

@@ -6,7 +6,7 @@
  * restart can never turn "rejected" into an inferred success. Conflict payloads
  * deliberately stay local; retention never deletes an unresolved failure.
  */
-import type { RowValue } from '@syncular/core';
+import type { RejectionDetails, RowValue } from '@syncular/core';
 import type { ClientDatabase } from './database';
 import { ClientSyncError } from './errors';
 import type { OutboxOperation } from './outbox';
@@ -32,6 +32,8 @@ export interface RejectionRecord {
   readonly code: string;
   readonly message: string;
   readonly retryable: boolean;
+  /** Bounded host-declared metadata safe for authorized recovery UI. */
+  readonly details?: RejectionDetails;
   readonly operation?: OutboxOperation;
 }