@syncular/client 0.7.0 → 0.9.0

package/src/client.ts

@@ -22,6 +22,7 @@ import {
   parseRealtimeServerEvent,
   REALTIME_TAG_DELTA,
   REALTIME_TAG_ROUND,
+  type RejectionDetails,
   type RequestFrame,
   type ResponseMessage,
   type RowColumn,
@@ -89,6 +90,20 @@ import {
   OutboxEncodeError,
   type OutboxOperation,
 } from './outbox';
+import {
+  activeFailureRecords,
+  type CommitOperationOutcome,
+  type CommitOutcome,
+  type CommitOutcomeQuery,
+  type ConflictRecord,
+  listCommitOutcomes,
+  persistCommitOutcomeResolution,
+  pruneCommitOutcomes,
+  type RejectionRecord,
+  type ResolveCommitOutcomeInput,
+  commitOutcome as readCommitOutcome,
+  recordCommitOutcome,
+} from './outcomes';
 import { assertReadOnlyQuery } from './query-guard';
 import {
   type ClientSchema,
@@ -159,30 +174,14 @@ export type MutationInput =
       readonly baseVersion?: number;
     };
 
-/** A §6.3 conflict result, surfaced to the app — never auto-resolved. */
-export interface ConflictRecord {
-  readonly clientCommitId: string;
-  readonly opIndex: number;
-  readonly table: string;
-  readonly rowId: string;
-  readonly code: string;
-  readonly message: string;
-  readonly serverVersion: number;
-  /** The current server row, decoded — resolve without a round-trip. */
-  readonly serverRow: Readonly<Record<string, RowValue>>;
-  /** The losing local operation (absent only for malformed op indexes). */
-  readonly operation?: OutboxOperation;
-}
-
-/** A non-conflict `error` result from a rejected commit (§6.3). */
-export interface RejectionRecord {
-  readonly clientCommitId: string;
-  readonly opIndex: number;
-  readonly code: string;
-  readonly message: string;
-  readonly retryable: boolean;
-  readonly operation?: OutboxOperation;
-}
+export type {
+  CommitOperationOutcome,
+  CommitOutcome,
+  CommitOutcomeQuery,
+  ConflictRecord,
+  RejectionRecord,
+  ResolveCommitOutcomeInput,
+} from './outcomes';
 
 export interface SchemaFloor {
   readonly requiredSchemaVersion?: number;
@@ -246,6 +245,12 @@ export interface SyncClientLimits {
    * `withSqliteImage` and a segment downloader is configured (§5.3).
    */
   readonly accept?: number;
+  /**
+   * Maximum retained durable commit outcomes. Old applied/cached or resolved
+   * entries are pruned first; unresolved conflicts/rejections are never
+   * deleted to satisfy this cap. Defaults to 1,000.
+   */
+  readonly outcomeRetentionMaxEntries?: number;
 }
 
 export interface SyncClientConfig {
@@ -454,6 +459,7 @@ export class SyncClient {
   /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
   readonly #encryption: EncryptionConfig | undefined;
   readonly #now: () => number;
+  readonly #outcomeRetentionMaxEntries: number;
   #started = false;
   #lease: LeaderLease | undefined;
   #clientId = '';
@@ -511,6 +517,18 @@ export class SyncClient {
     this.#schema = compileClientSchema(config.schema);
     this.#encryption = config.encryption;
     this.#now = config.now ?? Date.now;
+    const outcomeRetentionMaxEntries =
+      config.limits?.outcomeRetentionMaxEntries ?? 1_000;
+    if (
+      !Number.isSafeInteger(outcomeRetentionMaxEntries) ||
+      outcomeRetentionMaxEntries < 1
+    ) {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        'outcomeRetentionMaxEntries must be a positive safe integer',
+      );
+    }
+    this.#outcomeRetentionMaxEntries = outcomeRetentionMaxEntries;
     this.#hasBlobs = schemaHasBlobs(this.#schema);
   }
 
@@ -525,6 +543,14 @@ export class SyncClient {
     );
     ensureLocalSchema(this.#db, this.#schema);
     if (this.#hasBlobs) ensureBlobSchema(this.#db);
+    this.#db.transaction(() => {
+      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+    });
+    const activeFailures = activeFailureRecords(
+      listCommitOutcomes(this.#db, { activeOnly: true }),
+    );
+    this.#conflicts = activeFailures.conflicts;
+    this.#rejections = activeFailures.rejections;
     const persisted = getMeta(this.#db, 'clientId');
     if (
       persisted !== undefined &&
@@ -1037,6 +1063,92 @@ export class SyncClient {
     return this.#rejections;
   }
 
+  /** One durable final outcome by the originating client commit id. */
+  commitOutcome(clientCommitId: string): CommitOutcome | undefined {
+    this.#requireStarted();
+    return readCommitOutcome(this.#db, clientCommitId);
+  }
+
+  /** Newest-first durable outcome journal. */
+  commitOutcomes(query: CommitOutcomeQuery = {}): readonly CommitOutcome[] {
+    this.#requireStarted();
+    return listCommitOutcomes(this.#db, query);
+  }
+
+  /**
+   * 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
+   * dismissed. The transition is one-way and survives restart.
+   */
+  resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome {
+    this.#requireStarted();
+    const current = readCommitOutcome(this.#db, input.clientCommitId);
+    if (current === undefined) {
+      throw new ClientSyncError(
+        'sync.outcome_not_found',
+        `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`,
+      );
+    }
+    if (current.resolution !== 'active') return current;
+    const replacement = input.replacementClientCommitId;
+    if (input.resolution === 'superseded') {
+      if (
+        replacement === undefined ||
+        replacement.length === 0 ||
+        replacement === input.clientCommitId
+      ) {
+        throw new ClientSyncError(
+          'sync.invalid_request',
+          'superseded outcomes require a distinct replacementClientCommitId',
+        );
+      }
+    } else if (replacement !== undefined) {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        'replacementClientCommitId is valid only for superseded outcomes',
+      );
+    }
+    const allowed =
+      (current.status === 'conflict' &&
+        (input.resolution === 'resolved_keep_server' ||
+          input.resolution === 'superseded')) ||
+      (current.status === 'rejected' && input.resolution === 'superseded') ||
+      ((current.status === 'applied' || current.status === 'cached') &&
+        input.resolution === 'dismissed');
+    if (!allowed) {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        `resolution ${input.resolution} is invalid for ${current.status} outcome`,
+      );
+    }
+
+    return this.#applyBatch((batch) => {
+      const resolved = persistCommitOutcomeResolution(
+        this.#db,
+        input,
+        this.#now(),
+      );
+      if (resolved === undefined) {
+        throw new ClientSyncError(
+          'sync.outcome_not_found',
+          `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`,
+        );
+      }
+      this.#conflicts = this.#conflicts.filter(
+        (record) => record.clientCommitId !== input.clientCommitId,
+      );
+      this.#rejections = this.#rejections.filter(
+        (record) => record.clientCommitId !== input.clientCommitId,
+      );
+      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+      batch.outcomes();
+      if (current.status === 'conflict') batch.conflicts();
+      if (current.status === 'rejected') batch.rejections();
+      return resolved;
+    });
+  }
+
   /** Non-undefined once the server declared a schema floor (§1.6). */
   get schemaFloor(): SchemaFloor | undefined {
     return this.#schemaFloor;
@@ -1391,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 {
@@ -1425,6 +1544,9 @@ export class SyncClient {
           ? { baseVersion: mutation.baseVersion }
           : {}),
         values: json,
+        ...(changedFieldsByIndex[index] !== undefined
+          ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
+          : {}),
       };
     });
     this.#applyBatch((batch) => {
@@ -1477,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). */
@@ -1595,7 +1721,7 @@ export class SyncClient {
           deleteLocalRow(this.#db, table, operation.rowId);
         }
       }
-      this.#rejections.push({
+      const rejection: RejectionRecord = {
         clientCommitId: commit.clientCommitId,
         opIndex: 0,
         code: OUTBOX_INCOMPATIBLE_CODE,
@@ -1604,9 +1730,18 @@ export class SyncClient {
         ...(commit.operations[0] !== undefined
           ? { operation: commit.operations[0] }
           : {}),
+      };
+      this.#rejections.push(rejection);
+      recordCommitOutcome(this.#db, {
+        clientCommitId: commit.clientCommitId,
+        status: 'rejected',
+        recordedAtMs: this.#now(),
+        results: [{ status: 'error', rejection }],
       });
+      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
       batch.status();
       batch.rejections();
+      batch.outcomes();
     });
   }
 
@@ -2030,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') {
@@ -2078,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 =
@@ -2307,14 +2462,26 @@ 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;
     if (frame.status === 'applied' || frame.status === 'cached') {
       // §6.3: applied and cached both drain the outbox — cached means
       // "already applied, you may have missed the ack".
+      recordCommitOutcome(this.#db, {
+        clientCommitId: frame.clientCommitId,
+        status: frame.status,
+        recordedAtMs: this.#now(),
+        results: frame.results.map((result) => ({
+          status: 'applied' as const,
+          opIndex: result.opIndex,
+        })),
+      });
       deleteOutboxCommit(this.#db, frame.clientCommitId);
+      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
       batch.status();
+      batch.outcomes();
       summary.applied.push(frame.clientCommitId);
       return;
     }
@@ -2331,6 +2498,7 @@ export class SyncClient {
       summary.retryable.push(frame.clientCommitId);
       return;
     }
+    const outcomeResults: CommitOperationOutcome[] = [];
     for (const result of frame.results) {
       const operation = commit.operations[result.opIndex];
       if (result.status === 'conflict') {
@@ -2346,21 +2514,38 @@ export class SyncClient {
           ...(operation !== undefined ? { operation } : {}),
         };
         this.#conflicts.push(conflict);
+        outcomeResults.push({ status: 'conflict', conflict });
         batch.conflicts();
         summary.conflicts.push(conflict);
         this.#config.onConflict?.(conflict);
       } else if (result.status === 'error') {
-        this.#rejections.push({
+        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);
+        outcomeResults.push({ status: 'error', rejection });
         batch.rejections();
+      } else {
+        outcomeResults.push({ status: 'applied', opIndex: result.opIndex });
       }
     }
+    recordCommitOutcome(this.#db, {
+      clientCommitId: frame.clientCommitId,
+      status: outcomeResults.some((result) => result.status === 'conflict')
+        ? 'conflict'
+        : 'rejected',
+      recordedAtMs: this.#now(),
+      results: outcomeResults,
+    });
+    pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+    batch.outcomes();
     // §7.2: stop optimistic display and decide about dependents — the
     // commit leaves the outbox; rows it created that the server never
     // confirmed are undone here, rows it overwrote reconcile via the pull
@@ -2680,10 +2865,47 @@ export class SyncClient {
         try {
           deleteScopedRows(this.#db, table, lastEffective);
           batch.scopeMap(table, lastEffective);
-          if (
-            dropOutboxCommitsInScope(this.#db, table, lastEffective).length > 0
-          ) {
+          const pendingById = new Map(
+            listOutbox(this.#db).map((commit) => [
+              commit.clientCommitId,
+              commit,
+            ]),
+          );
+          const droppedIds = dropOutboxCommitsInScope(
+            this.#db,
+            table,
+            lastEffective,
+          );
+          if (droppedIds.length > 0) {
+            for (const clientCommitId of droppedIds) {
+              const commit = pendingById.get(clientCommitId);
+              if (commit === undefined) continue;
+              const results: CommitOperationOutcome[] = commit.operations.map(
+                (operation, opIndex) => {
+                  const rejection: RejectionRecord = {
+                    clientCommitId,
+                    opIndex,
+                    code: 'sync.scope_revoked',
+                    message:
+                      'the commit was dropped because its effective scope was revoked',
+                    retryable: false,
+                    operation,
+                  };
+                  this.#rejections.push(rejection);
+                  return { status: 'error', rejection };
+                },
+              );
+              recordCommitOutcome(this.#db, {
+                clientCommitId,
+                status: 'rejected',
+                recordedAtMs: this.#now(),
+                results,
+              });
+            }
+            pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
             batch.status();
+            batch.rejections();
+            batch.outcomes();
           }
           this.#reconcileBlobs(true);
         } catch (error) {

package/src/index.ts

@@ -22,6 +22,7 @@ export * from './leader-lock';
 export * from './multi-tab';
 export * from './naming';
 export * from './outbox';
+export * from './outcomes';
 export * from './query-guard';
 export * from './reactive-store';
 export * from './schema';

package/src/invalidation.ts

@@ -38,6 +38,7 @@ export interface ClientChangeBatch {
   readonly status?: SyncStatusSnapshot;
   readonly conflictsChanged: boolean;
   readonly rejectionsChanged: boolean;
+  readonly outcomesChanged: boolean;
 }
 
 export type ClientChangeListener = (batch: ClientChangeBatch) => void;
@@ -81,6 +82,7 @@ export class ChangeAccumulator {
   #status = false;
   #conflicts = false;
   #rejections = false;
+  #outcomes = false;
 
   /** Mark a whole table dirty, discarding any weaker scope-only facts. */
   table(name: string): void {
@@ -126,6 +128,10 @@ export class ChangeAccumulator {
     this.#rejections = true;
   }
 
+  outcomes(): void {
+    this.#outcomes = true;
+  }
+
   /** Add precise keys for a requested/effective scope map. */
   scopeMap(table: CompiledClientTable, scopes: ScopeMap): void {
     for (const [variable, values] of Object.entries(scopes)) {
@@ -154,7 +160,8 @@ export class ChangeAccumulator {
       this.#windows.size > 0 ||
       this.#status ||
       this.#conflicts ||
-      this.#rejections
+      this.#rejections ||
+      this.#outcomes
     );
   }
 
@@ -192,6 +199,7 @@ export class ChangeAccumulator {
       ...(this.#status ? { status: status as SyncStatusSnapshot } : {}),
       conflictsChanged: this.#conflicts,
       rejectionsChanged: this.#rejections,
+      outcomesChanged: this.#outcomes,
     };
   }
 }

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 {