@syncular/client 0.15.16 → 0.15.18

package/README.md

@@ -179,6 +179,35 @@ The state is a discriminated union covering startup, migration,
 children; a blocked live query has `phase === 'blocked'`, never an indefinite
 loading state.
 
+## Privacy-safe support diagnostics
+
+Every direct and Worker/multi-tab client exposes the same versioned snapshot:
+
+```ts
+const snapshot = await client.diagnosticsSnapshot({
+  expectedSubscriptions: [
+    { id: 'membership-security', table: 'facility_memberships' },
+    { id: 'scheduler-window', table: 'surgeries' },
+  ],
+});
+
+const off = client.onDiagnostics(() => refreshSupportView());
+```
+
+`expectedSubscriptions` contains application intent only—stable PHI-free ids
+and generated table names, never scopes. It lets a support screen distinguish
+an absent registration from a legitimate zero-row completed bootstrap. The
+snapshot also distinguishes reset, revocation, failure, schema floor, lease
+stop, pending outbox, offline transport, and storage pressure/unreadability.
+Worker leaders and followers return identical evidence with their honest role.
+
+The contract intentionally excludes scope values, rows and clinical row
+counts, SQL, paths, client/actor/lease ids, auth, keys, mutation bodies, stack
+traces, and arbitrary prose. It is safe to copy the JSON snapshot into a
+redacted support ticket as long as the application also keeps subscription ids
+free of patient/user data. Do not attach database files, console dumps, query
+results, or app state alongside it. See SPEC §7.6.
+
 ## Durable commit outcomes
 
 `SyncClient` and every host bridge expose `commitOutcome(id)`,

package/dist/client.d.ts

@@ -10,6 +10,7 @@
 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 ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.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';
@@ -283,6 +284,13 @@ export declare class SyncClient {
     onInvalidate(listener: InvalidationListener): () => void;
     /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
     onChange(listener: ClientChangeListener): () => void;
+    /** Subscribe to complete, privacy-safe diagnostic snapshots. */
+    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
+    /**
+     * One atomic support/product-health view. It never returns scope values,
+     * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
+     */
+    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): ClientDiagnosticsSnapshot;
     /** One call for the complete status domain used by reactive hosts. */
     statusSnapshot(): SyncStatusSnapshot;
     /**

package/dist/client.js

@@ -11,6 +11,7 @@ import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encode
 import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, upsertLocalRow, } from './apply.js';
 import { clearPendingUpload, computeBlobId, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, reconcileBlobRefcounts, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
+import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, } from './diagnostics.js';
 import { ClientSyncError } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
@@ -68,6 +69,12 @@ function emptySummary(pushed) {
         failed: [],
     };
 }
+function isFinalPushResult(frame) {
+    return (frame.status !== 'rejected' ||
+        !frame.results.some((result) => result.status === 'error' &&
+            result.code === 'sync.idempotency_cache_miss' &&
+            result.retryable));
+}
 export class SyncClient {
     #config;
     #db;
@@ -110,6 +117,11 @@ export class SyncClient {
     #invalidation = new InvalidationEmitter();
     /** §8.6: subscribable presence-change listeners (twin of onPresence). */
     #presenceListeners = new Set();
+    #diagnostics = new ClientDiagnosticsEmitter();
+    #diagnosticsDeferralDepth = 0;
+    #diagnosticsPending = false;
+    #lastRound;
+    #lastChange;
     /** The batch accumulator; non-undefined only inside `#applyBatch`. */
     #batch;
     /**
@@ -224,6 +236,7 @@ export class SyncClient {
             upgrading: async () => this.upgrading,
             onInvalidate: (listener) => this.onInvalidate(listener),
         });
+        this.#emitDiagnostics();
     }
     /**
      * §7.4.1/§7.4.2: compare the generated schema version to the persisted
@@ -359,6 +372,7 @@ export class SyncClient {
             this.#config.onSyncNeeded?.('startup');
             this.#config.onSyncIntent?.({ kind: 'interactive' });
         }
+        this.#emitDiagnostics();
     }
     // -- accessors ------------------------------------------------------------
     get clientId() {
@@ -452,15 +466,210 @@ export class SyncClient {
     onChange(listener) {
         return this.#changes.on(listener);
     }
+    /** Subscribe to complete, privacy-safe diagnostic snapshots. */
+    onDiagnostics(listener) {
+        return this.#diagnostics.on(listener);
+    }
+    /**
+     * One atomic support/product-health view. It never returns scope values,
+     * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
+     */
+    diagnosticsSnapshot(request = {}) {
+        this.#requireActive();
+        const expected = request.expectedSubscriptions ?? [];
+        if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
+            throw new ClientSyncError('sync.invalid_request', `diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`);
+        }
+        const registered = loadSubscriptions(this.#db);
+        const subscriptions = new Map();
+        for (const sub of registered) {
+            const reset = sub.cursor < 0 && sub.reasonCode === 'sync.cursor_expired';
+            const complete = sub.status === 'active' &&
+                sub.cursor >= 0 &&
+                sub.bootstrapState === undefined;
+            subscriptions.set(sub.id, {
+                id: sub.id,
+                table: sub.table,
+                state: sub.status === 'revoked'
+                    ? 'revoked'
+                    : sub.status === 'failed'
+                        ? 'failed'
+                        : reset
+                            ? 'reset'
+                            : complete
+                                ? 'complete'
+                                : 'bootstrapping',
+                complete,
+                cursor: sub.cursor,
+                ...(sub.reasonCode !== undefined
+                    ? { reasonCode: this.#diagnosticCode(sub.reasonCode) }
+                    : {}),
+            });
+        }
+        for (const item of expected) {
+            if (typeof item.id !== 'string' ||
+                item.id.length === 0 ||
+                typeof item.table !== 'string' ||
+                item.table.length === 0) {
+                throw new ClientSyncError('sync.invalid_request', 'diagnosticsSnapshot expected subscriptions require non-empty id and table strings');
+            }
+            const registeredSubscription = subscriptions.get(item.id);
+            if (registeredSubscription !== undefined &&
+                registeredSubscription.table !== item.table) {
+                subscriptions.set(item.id, {
+                    id: item.id,
+                    table: item.table,
+                    state: 'failed',
+                    complete: false,
+                    reasonCode: 'client.subscription_intent_mismatch',
+                });
+            }
+            else if (registeredSubscription === undefined) {
+                subscriptions.set(item.id, {
+                    id: item.id,
+                    table: item.table,
+                    state: 'unregistered',
+                    complete: false,
+                });
+            }
+        }
+        const capturedAtMs = this.#now();
+        const leaseState = this.#diagnosticLease(capturedAtMs);
+        const connectivity = this.#lastRound?.status === 'succeeded'
+            ? 'online'
+            : this.#lastRound?.status === 'failed' &&
+                this.#transportFailureCode(this.#lastRound.errorCode)
+                ? 'offline'
+                : 'unknown';
+        const expectedOrder = new Map(expected.map((item, index) => [item.id, index]));
+        const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
+            const aExpected = expectedOrder.get(a.id);
+            const bExpected = expectedOrder.get(b.id);
+            if (aExpected !== undefined || bExpected !== undefined) {
+                return ((aExpected ?? Number.MAX_SAFE_INTEGER) -
+                    (bExpected ?? Number.MAX_SAFE_INTEGER));
+            }
+            return a.id.localeCompare(b.id);
+        });
+        return {
+            version: CLIENT_DIAGNOSTICS_VERSION,
+            capturedAtMs,
+            host: {
+                kind: 'direct',
+                role: 'single',
+                connectivity,
+                realtime: this.#config.realtime === undefined
+                    ? 'unsupported'
+                    : this.#socket === undefined
+                        ? 'disconnected'
+                        : 'connected',
+            },
+            securityLifecycle: this.#securityLifecycle,
+            schema: {
+                currentVersion: this.#config.schema.version,
+                upgrading: this.#upgrading,
+                ...(this.#schemaFloor?.requiredSchemaVersion !== undefined
+                    ? { requiredVersion: this.#schemaFloor.requiredSchemaVersion }
+                    : {}),
+                ...(this.#schemaFloor?.latestSchemaVersion !== undefined
+                    ? { latestVersion: this.#schemaFloor.latestSchemaVersion }
+                    : {}),
+            },
+            replica: {
+                localRevision: getLocalRevision(this.#db).toString(),
+                syncNeeded: this.#needsPull,
+                pendingOutbox: listOutbox(this.#db).length,
+            },
+            lease: leaseState,
+            subscriptions: allSubscriptions.slice(0, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS),
+            subscriptionsTruncated: allSubscriptions.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
+            ...(this.#lastRound !== undefined ? { lastRound: this.#lastRound } : {}),
+            ...(this.#lastChange !== undefined
+                ? { lastChange: this.#lastChange }
+                : {}),
+            storage: this.#diagnosticStorage(),
+        };
+    }
+    #diagnosticLease(nowMs) {
+        const lease = this.#leaseState;
+        if (lease?.errorCode !== undefined) {
+            return {
+                state: 'stopped',
+                errorCode: this.#diagnosticCode(lease.errorCode),
+                ...(lease.expiresAtMs !== undefined
+                    ? { expiresAtMs: lease.expiresAtMs }
+                    : {}),
+            };
+        }
+        if (lease?.expiresAtMs === undefined)
+            return { state: 'none' };
+        return {
+            state: lease.expiresAtMs <= nowMs ? 'expired' : 'active',
+            expiresAtMs: lease.expiresAtMs,
+        };
+    }
+    #diagnosticStorage() {
+        try {
+            const pageCount = Number(this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0);
+            const pageSize = Number(this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0);
+            const outboxBytes = Number(this.#db.query('SELECT COALESCE(SUM(LENGTH(operations)), 0) AS bytes FROM _syncular_outbox')[0]?.bytes ?? 0);
+            const outcome = this.#db.query(`SELECT COUNT(*) AS entries,
+                COALESCE(SUM(LENGTH(results) + COALESCE(LENGTH(operations), 0)), 0) AS bytes
+           FROM _syncular_commit_outcomes`)[0];
+            const blobBytes = this.#hasBlobs
+                ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length), 0) AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
+                : 0;
+            const pressure = this.#config.blobCacheMaxBytes !== undefined &&
+                blobBytes > this.#config.blobCacheMaxBytes;
+            return {
+                status: pressure ? 'pressure' : 'healthy',
+                databaseBytesApprox: Math.max(0, pageCount * pageSize),
+                pendingOutboxBytesApprox: Math.max(0, outboxBytes),
+                retainedOutcomeBytesApprox: Math.max(0, Number(outcome?.bytes ?? 0)),
+                retainedOutcomeEntries: Math.max(0, Number(outcome?.entries ?? 0)),
+                blobCacheBytesApprox: Math.max(0, blobBytes),
+                ...(pressure
+                    ? { pressureReasonCode: 'client.blob_cache_over_limit' }
+                    : {}),
+            };
+        }
+        catch {
+            return { status: 'unreadable' };
+        }
+    }
+    #emitDiagnostics() {
+        if (!this.#started ||
+            this.#securityLifecycle !== 'active' ||
+            !this.#diagnostics.observed) {
+            return;
+        }
+        if (this.#diagnosticsDeferralDepth > 0) {
+            this.#diagnosticsPending = true;
+            return;
+        }
+        this.#diagnostics.emit(this.diagnosticsSnapshot());
+    }
+    #beginDiagnosticsDeferral() {
+        this.#diagnosticsDeferralDepth += 1;
+    }
+    #endDiagnosticsDeferral() {
+        if (this.#diagnosticsDeferralDepth === 0)
+            return;
+        this.#diagnosticsDeferralDepth -= 1;
+        if (this.#diagnosticsDeferralDepth === 0 && this.#diagnosticsPending) {
+            this.#diagnosticsPending = false;
+            this.#emitDiagnostics();
+        }
+    }
     /** One call for the complete status domain used by reactive hosts. */
     statusSnapshot() {
         this.#requireStarted();
         return this.#statusSnapshot();
     }
-    #statusSnapshot() {
+    #statusSnapshot(outboxCount) {
         return {
             currentSchemaVersion: this.#config.schema.version,
-            outbox: listOutbox(this.#db).length,
+            outbox: outboxCount ?? listOutbox(this.#db).length,
             upgrading: this.#upgrading,
             leaseState: this.#leaseState,
             schemaFloor: this.#schemaFloor,
@@ -473,7 +682,7 @@ export class SyncClient {
      * Re-entrant calls share the outer batch so a nested apply never
      * double-emits (e.g. purge → blob reconcile → replay inside one round).
      */
-    #applyBatch(fn) {
+    #applyBatch(fn, statusSnapshotOverride) {
         if (this.#batch !== undefined)
             return fn(this.#batch);
         const batch = new ChangeAccumulator();
@@ -487,8 +696,9 @@ export class SyncClient {
                     result = fn(batch);
                     if (batch.touched) {
                         revision = bumpLocalRevision(this.#db);
-                        if (batch.statusChanged)
-                            status = this.#statusSnapshot();
+                        if (batch.statusChanged) {
+                            status = statusSnapshotOverride?.() ?? this.#statusSnapshot();
+                        }
                     }
                 }
                 finally {
@@ -502,10 +712,25 @@ export class SyncClient {
         }
         if (revision !== undefined) {
             const event = batch.finish(revision, status);
+            const tables = [...new Set(event.tables.map((entry) => entry.table))];
+            const windows = [...new Set(event.windows.map((entry) => entry.table))];
+            this.#lastChange = {
+                revision: revision.toString(),
+                recordedAtMs: this.#now(),
+                tables: tables.slice(0, MAX_DIAGNOSTIC_DOMAINS),
+                windows: windows.slice(0, MAX_DIAGNOSTIC_DOMAINS),
+                domainsTruncated: tables.length > MAX_DIAGNOSTIC_DOMAINS ||
+                    windows.length > MAX_DIAGNOSTIC_DOMAINS,
+                statusChanged: event.status !== undefined,
+                conflictsChanged: event.conflictsChanged,
+                rejectionsChanged: event.rejectionsChanged,
+                outcomesChanged: event.outcomesChanged,
+            };
             this.#changes.emit(event);
             const legacy = invalidationFromChange(event);
             if (legacy !== undefined)
                 this.#invalidation.emit(legacy);
+            this.#emitDiagnostics();
         }
         return result;
     }
@@ -870,6 +1095,7 @@ export class SyncClient {
                 scopes: input.scopes,
                 ...(input.params !== undefined ? { params: input.params } : {}),
             });
+            this.#emitDiagnostics();
             return;
         }
         saveSubscription(this.#db, {
@@ -880,10 +1106,12 @@ export class SyncClient {
             cursor: -1,
             status: 'active',
         });
+        this.#emitDiagnostics();
     }
     unsubscribe(id) {
         this.#requireActive();
         deleteSubscription(this.#db, id);
+        this.#emitDiagnostics();
     }
     // -- windowed subscriptions (§4.8) ------------------------------------------
     /**
@@ -1403,10 +1631,67 @@ export class SyncClient {
             return Promise.reject(new ClientSyncError('sync.invalid_request', 'sync() is already running — the core owns one loop (coalesce wake-ups)'));
         }
         this.#syncOutstanding = true;
-        return this.#serialize(() => this.#runSync()).finally(() => {
+        this.#beginDiagnosticsDeferral();
+        const startedAtMs = this.#now();
+        return this.#serialize(() => this.#runSync())
+            .then((summary) => {
+            const completedAtMs = this.#now();
+            this.#lastRound = {
+                status: 'succeeded',
+                startedAtMs,
+                completedAtMs,
+                durationMs: Math.max(0, completedAtMs - startedAtMs),
+                counters: this.#diagnosticRoundCounters(summary),
+            };
+            this.#emitDiagnostics();
+            return summary;
+        }, (error) => {
+            const completedAtMs = this.#now();
+            const code = error.code;
+            this.#lastRound = {
+                status: 'failed',
+                startedAtMs,
+                completedAtMs,
+                durationMs: Math.max(0, completedAtMs - startedAtMs),
+                errorCode: typeof code === 'string'
+                    ? this.#diagnosticCode(code)
+                    : 'client.unknown_failure',
+            };
+            this.#emitDiagnostics();
+            throw error;
+        })
+            .finally(() => {
             this.#syncOutstanding = false;
+            this.#endDiagnosticsDeferral();
         });
     }
+    #diagnosticRoundCounters(summary) {
+        return {
+            pushed: summary.pushed,
+            applied: summary.applied.length,
+            rejected: summary.rejected.length,
+            retryable: summary.retryable.length,
+            conflicts: summary.conflicts.length,
+            commitsApplied: summary.commitsApplied,
+            segmentRowsApplied: summary.segmentRowsApplied,
+            bootstrapping: summary.bootstrapping.length,
+            resets: summary.resets.length,
+            revoked: summary.revoked.length,
+            failed: summary.failed.length,
+            deferredCommits: summary.deferredCommits ?? 0,
+        };
+    }
+    #transportFailureCode(code) {
+        return (code === 'transport.failed' ||
+            code === 'transport.unavailable' ||
+            code === 'sync.transport_failed' ||
+            code === 'client.worker_failed');
+    }
+    #diagnosticCode(code) {
+        return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
+            ? code
+            : 'client.unknown_failure';
+    }
     async #runSync() {
         if (this.#schemaFloor !== undefined) {
             return {
@@ -1547,8 +1832,17 @@ export class SyncClient {
      */
     #roundTrip(request) {
         const socket = this.#socket;
-        if (socket === undefined)
-            return this.#config.transport(request);
+        if (socket === undefined) {
+            return Promise.resolve()
+                .then(() => this.#config.transport(request))
+                .catch((error) => {
+                if (error instanceof ClientSyncError ||
+                    typeof error?.code === 'string') {
+                    throw error;
+                }
+                throw new ClientSyncError('sync.transport_failed', `transport round failed: ${error instanceof Error ? error.message : String(error)}`, true);
+            });
+        }
         return new Promise((resolve, reject) => {
             // sync() already enforces one round in flight (§8.7).
             this.#pendingRound = {
@@ -1592,6 +1886,7 @@ export class SyncClient {
                 this.#socket = undefined;
                 this.#presence.clear(); // §8.6.1: presence is per-connection
                 this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
+                this.#emitDiagnostics();
             },
         });
         if (this.#securityLifecycle === 'preflight') {
@@ -1599,12 +1894,14 @@ export class SyncClient {
             throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
         }
         this.#socket = socket;
+        this.#emitDiagnostics();
     }
     disconnectRealtime() {
         this.#socket?.close();
         this.#socket = undefined;
         this.#presence.clear(); // §8.6.1: presence is per-connection
         this.#abortPendingRound('realtime socket disconnected mid-round (§8.7)');
+        this.#emitDiagnostics();
     }
     /**
      * §8.7 channel-tag routing (synchronous, so chunk order is preserved):
@@ -1760,10 +2057,16 @@ export class SyncClient {
         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();
+        let lastFinalPushResult;
         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])));
+            if (frame.type === 'PUSH_RESULT_DETAILS') {
+                rejectionDetailsByCommit.set(frame.clientCommitId, new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])));
+            }
+            else if (frame.type === 'PUSH_RESULT' &&
+                commitsById.has(frame.clientCommitId) &&
+                isFinalPushResult(frame)) {
+                lastFinalPushResult = frame;
+            }
         }
         const header = message.frames[0];
         if (header?.type !== 'RESP_HEADER') {
@@ -1793,8 +2096,10 @@ export class SyncClient {
         let section;
         let errorFrame;
         let deltaCursor = -1;
+        let responseOutboxCount;
         // Each durable observer transaction emits its own revisioned batch.
         // Async decrypt/download work happens outside SQLite transactions.
+        this.#beginDiagnosticsDeferral();
         try {
             for (const frame of message.frames.slice(1)) {
                 switch (frame.type) {
@@ -1808,9 +2113,16 @@ export class SyncClient {
                             expiresAtMs: frame.expiresAtMs,
                         });
                         break;
-                    case 'PUSH_RESULT':
-                        this.#applyBatch((batch) => this.#handlePushResult(frame, commitsById, summary, batch, rejectionDetailsByCommit.get(frame.clientCommitId)));
+                    case 'PUSH_RESULT': {
+                        let outboxCount = responseOutboxCount ?? listOutbox(this.#db).length;
+                        this.#applyBatch((batch) => {
+                            const drained = this.#handlePushResult(frame, commitsById, summary, batch, rejectionDetailsByCommit.get(frame.clientCommitId), frame === lastFinalPushResult);
+                            if (drained)
+                                outboxCount -= 1;
+                        }, () => this.#statusSnapshot(outboxCount));
+                        responseOutboxCount = outboxCount;
                         break;
+                    }
                     case 'PUSH_RESULT_DETAILS':
                         // Pre-indexed above so companion ordering remains wire-additive.
                         break;
@@ -1935,10 +2247,15 @@ export class SyncClient {
             }
         }
         finally {
-            // §7.1: local reads see outbox state applied optimistically — replay
-            // the still-pending commits on top of the freshly applied server state.
-            this.#replayOutbox();
-            this.#reconcileBlobs(false);
+            try {
+                // §7.1: local reads see outbox state applied optimistically — replay
+                // the still-pending commits on top of the freshly applied server state.
+                this.#replayOutbox();
+                this.#reconcileBlobs(false);
+            }
+            finally {
+                this.#endDiagnosticsDeferral();
+            }
         }
         if (errorFrame !== undefined)
             throw errorFrame;
@@ -1959,10 +2276,10 @@ export class SyncClient {
         }
         return { ...summary, bootstrapping };
     }
-    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails) {
+    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails, pruneOutcomes) {
         const commit = commitsById.get(frame.clientCommitId);
         if (commit === undefined)
-            return;
+            return false;
         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".
@@ -1976,11 +2293,13 @@ export class SyncClient {
                 })),
             });
             deleteOutboxCommit(this.#db, frame.clientCommitId);
-            pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+            if (pruneOutcomes) {
+                pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+            }
             batch.status();
             batch.outcomes();
             summary.applied.push(frame.clientCommitId);
-            return;
+            return true;
         }
         // rejected
         const cacheMiss = frame.results.some((result) => result.status === 'error' &&
@@ -1990,7 +2309,7 @@ export class SyncClient {
             // §6.3: a serving failure, not the commit's outcome — keep the
             // commit queued and retry the identical push later.
             summary.retryable.push(frame.clientCommitId);
-            return;
+            return false;
         }
         const outcomeResults = [];
         for (const result of frame.results) {
@@ -2041,7 +2360,9 @@ export class SyncClient {
             results: outcomeResults,
             operations: commit.operations,
         });
-        pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+        if (pruneOutcomes) {
+            pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+        }
         batch.outcomes();
         // §7.2: remove the rejected optimistic layer. Before-images restore
         // validator-rejected updates even when the server emitted no new COMMIT;
@@ -2051,6 +2372,7 @@ export class SyncClient {
         });
         batch.status();
         summary.rejected.push(frame.clientCommitId);
+        return true;
     }
     #decodeServerRow(tableName, payload) {
         if (tableName === undefined)