@syncular/client 0.7.0 → 0.9.0

package/src/outcomes.ts

@@ -0,0 +1,276 @@
+/**
+ * Durable per-client commit outcomes.
+ *
+ * The journal is client-local protected database state. A final push result is
+ * written in the same SQLite transaction that drains its outbox commit, so a
+ * restart can never turn "rejected" into an inferred success. Conflict payloads
+ * deliberately stay local; retention never deletes an unresolved failure.
+ */
+import type { RejectionDetails, RowValue } from '@syncular/core';
+import type { ClientDatabase } from './database';
+import { ClientSyncError } from './errors';
+import type { OutboxOperation } from './outbox';
+import { type JsonRowValue, jsonToRowValue, rowValueToJson } from './schema';
+
+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;
+}
+
+export interface RejectionRecord {
+  readonly clientCommitId: string;
+  readonly opIndex: number;
+  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';
+
+export type CommitOutcomeResolution =
+  | 'active'
+  | 'resolved_keep_server'
+  | 'superseded'
+  | 'dismissed';
+
+export type CommitOperationOutcome =
+  | {
+      readonly status: 'applied';
+      readonly opIndex: number;
+    }
+  | {
+      readonly status: 'conflict';
+      readonly conflict: ConflictRecord;
+    }
+  | {
+      readonly status: 'error';
+      readonly rejection: RejectionRecord;
+    };
+
+export interface CommitOutcome {
+  /** Monotonic local journal order; not a server sequence. */
+  readonly sequence: number;
+  readonly clientCommitId: string;
+  readonly status: CommitOutcomeStatus;
+  readonly recordedAtMs: number;
+  readonly results: readonly CommitOperationOutcome[];
+  readonly resolution: CommitOutcomeResolution;
+  readonly resolvedAtMs?: number;
+  readonly replacementClientCommitId?: string;
+}
+
+export interface CommitOutcomeQuery {
+  /** Newest-first result cap. Defaults to all retained entries. */
+  readonly limit?: number;
+  /** Only unresolved conflict/rejection outcomes. */
+  readonly activeOnly?: boolean;
+}
+
+export interface ResolveCommitOutcomeInput {
+  readonly clientCommitId: string;
+  readonly resolution: Exclude<CommitOutcomeResolution, 'active'>;
+  readonly replacementClientCommitId?: string;
+}
+
+interface StoredConflictRecord extends Omit<ConflictRecord, 'serverRow'> {
+  readonly serverRow: Readonly<Record<string, JsonRowValue>>;
+}
+
+type StoredCommitOperationOutcome =
+  | Extract<CommitOperationOutcome, { status: 'applied' }>
+  | { readonly status: 'conflict'; readonly conflict: StoredConflictRecord }
+  | Extract<CommitOperationOutcome, { status: 'error' }>;
+
+function encodeResults(results: readonly CommitOperationOutcome[]): string {
+  const stored: StoredCommitOperationOutcome[] = results.map((result) => {
+    if (result.status !== 'conflict') return result;
+    return {
+      status: 'conflict',
+      conflict: {
+        ...result.conflict,
+        serverRow: Object.fromEntries(
+          Object.entries(result.conflict.serverRow).map(([key, value]) => [
+            key,
+            rowValueToJson(value),
+          ]),
+        ),
+      },
+    };
+  });
+  return JSON.stringify(stored);
+}
+
+function decodeResults(raw: string): CommitOperationOutcome[] {
+  const stored = JSON.parse(raw) as StoredCommitOperationOutcome[];
+  return stored.map((result) => {
+    if (result.status !== 'conflict') return result;
+    return {
+      status: 'conflict',
+      conflict: {
+        ...result.conflict,
+        serverRow: Object.fromEntries(
+          Object.entries(result.conflict.serverRow).map(([key, value]) => [
+            key,
+            jsonToRowValue(value),
+          ]),
+        ),
+      },
+    };
+  });
+}
+
+function parseOutcome(row: Readonly<Record<string, unknown>>): CommitOutcome {
+  return {
+    sequence: row.seq as number,
+    clientCommitId: row.client_commit_id as string,
+    status: row.status as CommitOutcomeStatus,
+    recordedAtMs: row.recorded_at_ms as number,
+    results: decodeResults(row.results as string),
+    resolution: row.resolution as CommitOutcomeResolution,
+    ...(typeof row.resolved_at_ms === 'number'
+      ? { resolvedAtMs: row.resolved_at_ms }
+      : {}),
+    ...(typeof row.replacement_client_commit_id === 'string'
+      ? { replacementClientCommitId: row.replacement_client_commit_id }
+      : {}),
+  };
+}
+
+export function recordCommitOutcome(
+  db: ClientDatabase,
+  outcome: Omit<CommitOutcome, 'sequence' | 'resolution'>,
+): CommitOutcome {
+  db.exec(
+    `INSERT INTO _syncular_commit_outcomes(
+       client_commit_id, status, recorded_at_ms, results, resolution
+     ) VALUES (?, ?, ?, ?, 'active')`,
+    [
+      outcome.clientCommitId,
+      outcome.status,
+      outcome.recordedAtMs,
+      encodeResults(outcome.results),
+    ],
+  );
+  return commitOutcome(db, outcome.clientCommitId) as CommitOutcome;
+}
+
+export function commitOutcome(
+  db: ClientDatabase,
+  clientCommitId: string,
+): CommitOutcome | undefined {
+  const row = db.query(
+    `SELECT seq, client_commit_id, status, recorded_at_ms, results,
+            resolution, resolved_at_ms, replacement_client_commit_id
+       FROM _syncular_commit_outcomes WHERE client_commit_id = ?`,
+    [clientCommitId],
+  )[0];
+  return row === undefined ? undefined : parseOutcome(row);
+}
+
+export function listCommitOutcomes(
+  db: ClientDatabase,
+  query: CommitOutcomeQuery = {},
+): CommitOutcome[] {
+  const limit = query.limit;
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1)) {
+    throw new ClientSyncError(
+      'sync.invalid_request',
+      'commit outcome limit must be a positive safe integer',
+    );
+  }
+  const where = query.activeOnly
+    ? "WHERE resolution = 'active' AND status IN ('conflict', 'rejected')"
+    : '';
+  const rows = db.query(
+    `SELECT seq, client_commit_id, status, recorded_at_ms, results,
+            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);
+}
+
+export function persistCommitOutcomeResolution(
+  db: ClientDatabase,
+  input: ResolveCommitOutcomeInput,
+  nowMs: number,
+): CommitOutcome | undefined {
+  db.exec(
+    `UPDATE _syncular_commit_outcomes
+        SET resolution = ?, resolved_at_ms = ?, replacement_client_commit_id = ?
+      WHERE client_commit_id = ? AND resolution = 'active'`,
+    [
+      input.resolution,
+      nowMs,
+      input.replacementClientCommitId ?? null,
+      input.clientCommitId,
+    ],
+  );
+  return commitOutcome(db, input.clientCommitId);
+}
+
+/**
+ * Bound journal growth without deleting active failures. If active failures
+ * alone exceed the cap the journal intentionally remains over-capacity.
+ */
+export function pruneCommitOutcomes(
+  db: ClientDatabase,
+  maxEntries: number,
+): number {
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+    throw new ClientSyncError(
+      'sync.invalid_request',
+      'outcome retention maxEntries must be a positive safe integer',
+    );
+  }
+  const count = db.query(
+    'SELECT COUNT(*) AS count FROM _syncular_commit_outcomes',
+  )[0]?.count as number | undefined;
+  const excess = Math.max(0, (count ?? 0) - maxEntries);
+  if (excess === 0) return 0;
+  const candidates = db.query(
+    `SELECT seq FROM _syncular_commit_outcomes
+      WHERE status IN ('applied', 'cached') OR resolution != 'active'
+      ORDER BY seq ASC LIMIT ?`,
+    [excess],
+  );
+  for (const candidate of candidates) {
+    db.exec('DELETE FROM _syncular_commit_outcomes WHERE seq = ?', [
+      candidate.seq as number,
+    ]);
+  }
+  return candidates.length;
+}
+
+export function activeFailureRecords(outcomes: readonly CommitOutcome[]): {
+  readonly conflicts: ConflictRecord[];
+  readonly rejections: RejectionRecord[];
+} {
+  const conflicts: ConflictRecord[] = [];
+  const rejections: RejectionRecord[] = [];
+  for (const outcome of outcomes) {
+    if (outcome.resolution !== 'active') continue;
+    for (const result of outcome.results) {
+      if (result.status === 'conflict') conflicts.push(result.conflict);
+      if (result.status === 'error') rejections.push(result.rejection);
+    }
+  }
+  return { conflicts, rejections };
+}

package/src/reactive-store.ts

@@ -1,4 +1,5 @@
 import type {
+  CommitOutcome,
   QueryReadSpec,
   QuerySnapshot,
   WindowCoverage,
@@ -49,6 +50,9 @@ export interface ReactiveQueryClient {
   readonly rejections:
     | readonly unknown[]
     | (() => readonly unknown[] | Promise<readonly unknown[]>);
+  commitOutcomes():
+    | readonly CommitOutcome[]
+    | Promise<readonly CommitOutcome[]>;
   setWindow(base: WindowBase, units: readonly string[]): void | Promise<void>;
   windowState(base: WindowBase): WindowState | Promise<WindowState>;
 }
@@ -82,6 +86,12 @@ export interface ConflictStoreSnapshot<
   readonly isLoading: boolean;
 }
 
+export interface OutcomeStoreSnapshot {
+  readonly outcomes: readonly CommitOutcome[];
+  readonly error: Error | undefined;
+  readonly isLoading: boolean;
+}
+
 function errorOf(value: unknown): Error {
   return value instanceof Error ? value : new Error(String(value));
 }
@@ -497,6 +507,7 @@ export class ReactiveClientStore {
   #offChange: (() => void) | undefined;
   readonly status: ExternalStoreEntry<StatusStoreSnapshot>;
   readonly conflicts: ExternalStoreEntry<ConflictStoreSnapshot>;
+  readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
 
   constructor(readonly client: ReactiveQueryClient) {
     const status = new ValueEntry<StatusStoreSnapshot>(
@@ -537,10 +548,26 @@ export class ReactiveClientStore {
         }
       },
     );
+    const outcomes = new ValueEntry<OutcomeStoreSnapshot>(
+      { outcomes: [], error: undefined, isLoading: true },
+      async () => {
+        try {
+          return {
+            outcomes: await client.commitOutcomes(),
+            error: undefined,
+            isLoading: false,
+          };
+        } catch (error) {
+          return { outcomes: [], error: errorOf(error), isLoading: false };
+        }
+      },
+    );
     this.status = status;
     this.conflicts = conflicts;
+    this.outcomes = outcomes;
     status.refresh();
     conflicts.refresh();
+    outcomes.refresh();
     this.start();
   }
 
@@ -681,6 +708,7 @@ export class ReactiveClientStore {
       if (batch.conflictsChanged || batch.rejectionsChanged) {
         this.conflicts.refresh();
       }
+      if (batch.outcomesChanged) this.outcomes.refresh();
     });
   }
 

package/src/schema.ts

@@ -288,6 +288,18 @@ export function ensureLocalSchema(
       client_commit_id TEXT NOT NULL UNIQUE,
       created_at_ms INTEGER NOT NULL,
       operations TEXT NOT NULL)`);
+    db.exec(`CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes(
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      client_commit_id TEXT NOT NULL UNIQUE,
+      status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
+      recorded_at_ms INTEGER NOT NULL,
+      results TEXT NOT NULL,
+      resolution TEXT NOT NULL DEFAULT 'active'
+        CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
+      resolved_at_ms INTEGER,
+      replacement_client_commit_id TEXT)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
+      ON _syncular_commit_outcomes(resolution, seq)`);
     db.exec(`CREATE TABLE IF NOT EXISTS _syncular_subscriptions(
       id TEXT PRIMARY KEY,
       tbl TEXT NOT NULL,

package/src/worker-entry.ts

@@ -378,6 +378,11 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     statusSnapshot: () => requireClient().statusSnapshot(),
     conflicts: () => requireClient().conflicts,
     rejections: () => requireClient().rejections,
+    commitOutcome: (clientCommitId) =>
+      requireClient().commitOutcome(clientCommitId),
+    commitOutcomes: (query) => requireClient().commitOutcomes(query),
+    resolveCommitOutcome: (input) =>
+      requireClient().resolveCommitOutcome(input),
     schemaFloor: () => requireClient().schemaFloor,
     leaseState: () => requireClient().leaseState,
     upgrading: () => requireClient().upgrading,

package/src/worker-host.ts

@@ -64,6 +64,11 @@ import {
   newTabId,
 } from './multi-tab';
 import type { OutboxCommit } from './outbox';
+import type {
+  CommitOutcome,
+  CommitOutcomeQuery,
+  ResolveCommitOutcomeInput,
+} from './outcomes';
 import type { ClientSchema } from './schema';
 import type { SubscriptionRecord } from './state';
 import type { WindowBase } from './window';
@@ -385,6 +390,22 @@ export class SyncClientHandle {
     return this.#call('rejections', []);
   }
 
+  commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined> {
+    return this.#call('commitOutcome', [clientCommitId]);
+  }
+
+  commitOutcomes(
+    query: CommitOutcomeQuery = {},
+  ): Promise<readonly CommitOutcome[]> {
+    return this.#call('commitOutcomes', [query]);
+  }
+
+  resolveCommitOutcome(
+    input: ResolveCommitOutcomeInput,
+  ): Promise<CommitOutcome> {
+    return this.#call('resolveCommitOutcome', [input]);
+  }
+
   schemaFloor(): Promise<SchemaFloor | undefined> {
     return this.#call('schemaFloor', []);
   }

package/src/worker-protocol.ts

@@ -39,6 +39,11 @@ import type {
   SyncStatusSnapshot,
 } from './invalidation';
 import type { OutboxCommit } from './outbox';
+import type {
+  CommitOutcome,
+  CommitOutcomeQuery,
+  ResolveCommitOutcomeInput,
+} from './outcomes';
 import type { ClientSchema } from './schema';
 import type { SubscriptionRecord } from './state';
 import type { WindowBase } from './window';
@@ -133,6 +138,9 @@ export interface WorkerApi {
   statusSnapshot(): SyncStatusSnapshot;
   conflicts(): readonly ConflictRecord[];
   rejections(): readonly RejectionRecord[];
+  commitOutcome(clientCommitId: string): CommitOutcome | undefined;
+  commitOutcomes(query?: CommitOutcomeQuery): readonly CommitOutcome[];
+  resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;
   schemaFloor(): SchemaFloor | undefined;
   /** §7.3.5: the opaque auth-lease state, or undefined. */
   leaseState(): LeaseState | undefined;