@syncular/client 0.7.0 → 0.9.0

package/dist/outcomes.js

@@ -0,0 +1,131 @@
+import { ClientSyncError } from './errors.js';
+import { jsonToRowValue, rowValueToJson } from './schema.js';
+function encodeResults(results) {
+    const stored = 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) {
+    const stored = JSON.parse(raw);
+    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) {
+    return {
+        sequence: row.seq,
+        clientCommitId: row.client_commit_id,
+        status: row.status,
+        recordedAtMs: row.recorded_at_ms,
+        results: decodeResults(row.results),
+        resolution: row.resolution,
+        ...(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, outcome) {
+    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);
+}
+export function commitOutcome(db, clientCommitId) {
+    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, query = {}) {
+    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, input, nowMs) {
+    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, maxEntries) {
+    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;
+    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,
+        ]);
+    }
+    return candidates.length;
+}
+export function activeFailureRecords(outcomes) {
+    const conflicts = [];
+    const rejections = [];
+    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/dist/reactive-store.d.ts

@@ -1,4 +1,4 @@
-import type { QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
+import type { CommitOutcome, QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
 import type { SqlValue } from './database.js';
 import type { ClientChangeListener, SyncStatusSnapshot } from './invalidation.js';
 import { type WindowBase } from './window.js';
@@ -29,6 +29,7 @@ export interface ReactiveQueryClient {
     statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
     readonly conflicts: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
     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>;
 }
@@ -54,6 +55,11 @@ export interface ConflictStoreSnapshot<Conflict = unknown, Rejection = unknown>
     readonly error: Error | undefined;
     readonly isLoading: boolean;
 }
+export interface OutcomeStoreSnapshot {
+    readonly outcomes: readonly CommitOutcome[];
+    readonly error: Error | undefined;
+    readonly isLoading: boolean;
+}
 /** Lossless deterministic identity for query params, bytes, and row keys. */
 export declare function canonicalValue(value: unknown): string;
 export declare class ReactiveClientStore {
@@ -61,6 +67,7 @@ export declare class ReactiveClientStore {
     readonly client: ReactiveQueryClient;
     readonly status: ExternalStoreEntry<StatusStoreSnapshot>;
     readonly conflicts: ExternalStoreEntry<ConflictStoreSnapshot>;
+    readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
     constructor(client: ReactiveQueryClient);
     query<Row>(spec: ReactiveQuerySpec<Row>): ExternalStoreEntry<LiveQueryResult<Row>>;
     /** Retain a composable window working set outside React. The returned

package/dist/reactive-store.js

@@ -385,6 +385,7 @@ export class ReactiveClientStore {
     #offChange;
     status;
     conflicts;
+    outcomes;
     constructor(client) {
         this.client = client;
         const status = new ValueEntry({ status: undefined, error: undefined, isLoading: true }, async () => {
@@ -421,10 +422,24 @@ export class ReactiveClientStore {
                 };
             }
         });
+        const outcomes = new ValueEntry({ 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();
     }
     query(spec) {
@@ -563,6 +578,8 @@ export class ReactiveClientStore {
             if (batch.conflictsChanged || batch.rejectionsChanged) {
                 this.conflicts.refresh();
             }
+            if (batch.outcomesChanged)
+                this.outcomes.refresh();
         });
     }
     dispose() {

package/dist/schema.js

@@ -184,6 +184,18 @@ export function ensureLocalSchema(db, schema) {
       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/dist/worker-entry.js

@@ -286,6 +286,9 @@ export function startSyncWorker(overrides = {}) {
         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/dist/worker-host.d.ts

@@ -29,6 +29,7 @@ import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type Inv
 import { type LeaderLease, type LeaderLock } from './leader-lock.js';
 import { type CrossTabChannel, FollowerLink, LeaderBridge } from './multi-tab.js';
 import type { OutboxCommit } from './outbox.js';
+import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
@@ -149,6 +150,9 @@ export declare class SyncClientHandle {
     statusSnapshot(): Promise<SyncStatusSnapshot>;
     conflicts(): Promise<readonly ConflictRecord[]>;
     rejections(): Promise<readonly RejectionRecord[]>;
+    commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
+    commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
+    resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
     schemaFloor(): Promise<SchemaFloor | undefined>;
     leaseState(): Promise<LeaseState | undefined>;
     /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */

package/dist/worker-host.js

@@ -186,6 +186,15 @@ export class SyncClientHandle {
     rejections() {
         return this.#call('rejections', []);
     }
+    commitOutcome(clientCommitId) {
+        return this.#call('commitOutcome', [clientCommitId]);
+    }
+    commitOutcomes(query = {}) {
+        return this.#call('commitOutcomes', [query]);
+    }
+    resolveCommitOutcome(input) {
+        return this.#call('resolveCommitOutcome', [input]);
+    }
     schemaFloor() {
         return this.#call('schemaFloor', []);
     }

package/dist/worker-protocol.d.ts

@@ -22,6 +22,7 @@ import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryRead
 import type { SqlRow, SqlValue } from './database.js';
 import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
 import type { OutboxCommit } from './outbox.js';
+import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
@@ -93,6 +94,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.7.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.7.0"
+    "@syncular/core": "0.9.0"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.7.0",
+    "@syncular/server": "0.9.0",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }