@syncular/client 0.7.0 → 0.9.0

package/README.md

@@ -108,6 +108,31 @@ 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).
+
+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.
+
 ## 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;
@@ -889,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 {
@@ -920,6 +997,9 @@ export class SyncClient {
                     ? { baseVersion: mutation.baseVersion }
                     : {}),
                 values: json,
+                ...(changedFieldsByIndex[index] !== undefined
+                    ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
+                    : {}),
             };
         });
         this.#applyBatch((batch) => {
@@ -959,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',
@@ -971,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) {
@@ -1057,7 +1138,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 +1147,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 -------------------------------------------------------------------
@@ -1436,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');
@@ -1480,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);
@@ -1627,15 +1726,26 @@ 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;
         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 +1759,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 +1775,40 @@ 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 = {
                     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
@@ -1927,8 +2056,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/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

@@ -0,0 +1,81 @@
+/**
+ * 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.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;
+    /** 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;
+}
+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[];
+};