@syncular/client 0.7.0 → 0.8.0

package/README.md

@@ -108,6 +108,20 @@ With `multiTab` off (the default) the single-tab contract is unchanged: a
 losing tab is an `isLeader === false` handle whose calls reject with
 `client.not_leader`.
 
+## Durable commit outcomes
+
+`SyncClient` and every host bridge expose `commitOutcome(id)`,
+`commitOutcomes({ limit?, activeOnly? })`, and `resolveCommitOutcome(input)`.
+Final `applied`, `cached`, `conflict`, and `rejected` results are journaled in
+the same SQLite transaction that drains their outbox commit. Conflict entries
+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).
+
+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.
+
 ## The support floor (no fallback ladder)
 
 - Persistence is **OPFS via `opfs-sahpool`, only**. No COOP/COEP headers

package/dist/client.d.ts

@@ -7,13 +7,14 @@
  * ownership behind `LeaderLock`. One combined push+pull request per
  * `sync()` round (§7.2); local reads go straight to the database.
  */
-import { type RowValue, type ScopeMap, type WakeReason } from '@syncular/core';
+import { type ScopeMap, type WakeReason } from '@syncular/core';
 import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
 import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
 import type { EncryptionConfig } from './encryption.js';
 import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLock } from './leader-lock.js';
-import { type OutboxCommit, type OutboxOperation } from './outbox.js';
+import { type OutboxCommit } from './outbox.js';
+import { type CommitOutcome, type CommitOutcomeQuery, type ConflictRecord, type RejectionRecord, type ResolveCommitOutcomeInput } from './outcomes.js';
 import { type ClientSchema } from './schema.js';
 import { type SubscriptionRecord } from './state.js';
 import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
@@ -30,29 +31,7 @@ export type MutationInput = {
     readonly rowId: string;
     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.js';
 export interface SchemaFloor {
     readonly requiredSchemaVersion?: number;
     readonly latestSchemaVersion?: number;
@@ -112,6 +91,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 {
     readonly database: ClientDatabase;
@@ -290,6 +275,17 @@ export declare class SyncClient {
     flushBlobUploads(): Promise<void>;
     get conflicts(): readonly ConflictRecord[];
     get rejections(): readonly RejectionRecord[];
+    /** One durable final outcome by the originating client commit id. */
+    commitOutcome(clientCommitId: string): CommitOutcome | undefined;
+    /** Newest-first durable outcome journal. */
+    commitOutcomes(query?: CommitOutcomeQuery): readonly CommitOutcome[];
+    /**
+     * 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;
     /** Non-undefined once the server declared a schema floor (§1.6). */
     get schemaFloor(): SchemaFloor | undefined;
     /**

package/dist/client.js

@@ -15,6 +15,7 @@ import { ClientSyncError } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, OutboxEncodeError, } from './outbox.js';
+import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
 import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
 import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
@@ -71,6 +72,7 @@ export class SyncClient {
     /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
     #encryption;
     #now;
+    #outcomeRetentionMaxEntries;
     #started = false;
     #lease;
     #clientId = '';
@@ -127,6 +129,12 @@ 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);
     }
     // -- lifecycle ------------------------------------------------------------
@@ -139,6 +147,12 @@ 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 &&
             this.#config.clientId !== undefined &&
@@ -577,6 +591,66 @@ export class SyncClient {
     get rejections() {
         return this.#rejections;
     }
+    /** One durable final outcome by the originating client commit id. */
+    commitOutcome(clientCommitId) {
+        this.#requireStarted();
+        return readCommitOutcome(this.#db, clientCommitId);
+    }
+    /** Newest-first durable outcome journal. */
+    commitOutcomes(query = {}) {
+        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) {
+        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() {
         return this.#schemaFloor;
@@ -1057,7 +1131,7 @@ export class SyncClient {
                     deleteLocalRow(this.#db, table, operation.rowId);
                 }
             }
-            this.#rejections.push({
+            const rejection = {
                 clientCommitId: commit.clientCommitId,
                 opIndex: 0,
                 code: OUTBOX_INCOMPATIBLE_CODE,
@@ -1066,9 +1140,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();
         });
     }
     // -- sync -------------------------------------------------------------------
@@ -1634,8 +1717,19 @@ export class SyncClient {
         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',
+                    opIndex: result.opIndex,
+                })),
+            });
             deleteOutboxCommit(this.#db, frame.clientCommitId);
+            pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
             batch.status();
+            batch.outcomes();
             summary.applied.push(frame.clientCommitId);
             return;
         }
@@ -1649,6 +1743,7 @@ export class SyncClient {
             summary.retryable.push(frame.clientCommitId);
             return;
         }
+        const outcomeResults = [];
         for (const result of frame.results) {
             const operation = commit.operations[result.opIndex];
             if (result.status === 'conflict') {
@@ -1664,22 +1759,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 rejection = {
                     clientCommitId: frame.clientCommitId,
                     opIndex: result.opIndex,
                     code: result.code,
                     message: result.message,
                     retryable: result.retryable,
                     ...(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
@@ -1927,8 +2038,39 @@ 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 = commit.operations.map((operation, opIndex) => {
+                                const rejection = {
+                                    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);
                 }

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/invalidation.d.ts

@@ -33,6 +33,7 @@ export interface ClientChangeBatch {
     readonly status?: SyncStatusSnapshot;
     readonly conflictsChanged: boolean;
     readonly rejectionsChanged: boolean;
+    readonly outcomesChanged: boolean;
 }
 export type ClientChangeListener = (batch: ClientChangeBatch) => void;
 /** Network work created by a core command (SPEC §7.5). */
@@ -67,6 +68,7 @@ export declare class ChangeAccumulator {
     status(): void;
     conflicts(): void;
     rejections(): void;
+    outcomes(): void;
     /** Add precise keys for a requested/effective scope map. */
     scopeMap(table: CompiledClientTable, scopes: ScopeMap): void;
     /** Add precise keys for a COMMIT change's stored scope values. */

package/dist/invalidation.js

@@ -11,6 +11,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) {
         this.#tables.set(name, { tableWide: true, scopeKeys: undefined });
@@ -50,6 +51,9 @@ export class ChangeAccumulator {
     rejections() {
         this.#rejections = true;
     }
+    outcomes() {
+        this.#outcomes = true;
+    }
     /** Add precise keys for a requested/effective scope map. */
     scopeMap(table, scopes) {
         for (const [variable, values] of Object.entries(scopes)) {
@@ -74,7 +78,8 @@ export class ChangeAccumulator {
             this.#windows.size > 0 ||
             this.#status ||
             this.#conflicts ||
-            this.#rejections);
+            this.#rejections ||
+            this.#outcomes);
     }
     get statusChanged() {
         return this.#status;
@@ -104,6 +109,7 @@ export class ChangeAccumulator {
             ...(this.#status ? { status: status } : {}),
             conflictsChanged: this.#conflicts,
             rejectionsChanged: this.#rejections,
+            outcomesChanged: this.#outcomes,
         };
     }
 }

package/dist/outcomes.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 { RowValue } from '@syncular/core';
+import type { ClientDatabase } from './database.js';
+import type { OutboxOperation } from './outbox.js';
+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;
+    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;
+}
+export declare function recordCommitOutcome(db: ClientDatabase, outcome: Omit<CommitOutcome, 'sequence' | 'resolution'>): CommitOutcome;
+export declare function commitOutcome(db: ClientDatabase, clientCommitId: string): CommitOutcome | undefined;
+export declare function listCommitOutcomes(db: ClientDatabase, query?: CommitOutcomeQuery): CommitOutcome[];
+export declare function persistCommitOutcomeResolution(db: ClientDatabase, input: ResolveCommitOutcomeInput, nowMs: number): CommitOutcome | undefined;
+/**
+ * Bound journal growth without deleting active failures. If active failures
+ * alone exceed the cap the journal intentionally remains over-capacity.
+ */
+export declare function pruneCommitOutcomes(db: ClientDatabase, maxEntries: number): number;
+export declare function activeFailureRecords(outcomes: readonly CommitOutcome[]): {
+    readonly conflicts: ConflictRecord[];
+    readonly rejections: RejectionRecord[];
+};

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