@syncular/client 0.15.48 → 0.17.0

package/README.md

@@ -543,6 +543,14 @@ Node 22.13 or newer. No SQLite package or native addon is required. Both
 adapters support synchronous `exec`, `query`, nested transactions, boolean
 bindings, `null`, `Uint8Array` BLOB values, and §5.3 SQLite-image attachment.
 
+Persistent Bun and Node databases use SQLite WAL journaling with
+`synchronous=FULL`. Each application or sync commit retains its own durable
+transaction. SQLite keeps in-memory databases on its memory journal. Use a
+local filesystem path; WAL uses adjacent `-wal` and `-shm` files. Close every
+connection before copying the database file, or use SQLite's backup facilities
+while it is open. Copying only the main file while writers are active can omit
+committed WAL contents.
+
 Runtime-specific imports remain available:
 
 ```ts
@@ -580,3 +588,45 @@ Tests drive the real worker entry in a bun `Worker` with bun:sqlite
 injected through the bootstrap's database-factory override
 (`test/worker-rpc.test.ts`); the OPFS path itself is browser-only and is
 exercised by `apps/demo`.
+
+## Snapshot API migration
+
+This source-breaking revision uses methods for application reads across the
+direct client, worker leaders and followers, Tauri, and React Native. Replace
+`client.conflicts`, `client.rejections`, and `client.securityLifecycle` on the
+direct client with method calls. Replace `schemaFloor`, `leaseState`,
+`upgrading`, and `syncNeeded` getters or bridge methods with fields from one
+`statusSnapshot()` call:
+
+```ts
+const status = await client.statusSnapshot();
+if (status.schemaFloor) showUpgradeRequired(status.schemaFloor);
+const conflicts = await client.conflicts();
+const outcome = await client.commitOutcome(commitId);
+```
+
+The direct client returns snapshots synchronously. Worker and native bridges
+return promises; `await` works with both. `querySnapshot` returns rows, coverage,
+and revision from one read. `diagnosticsSnapshot`, `commitOutcome`,
+`commitOutcomes`, and `resolveCommitOutcome` retain their existing arguments.
+The shared `ClientSnapshotMethods` and `PromiseMethods` types describe these
+contracts. Key-bearing security activation stays on each concrete host type.
+
+React uses the supplied client directly; `useSyncClient()` preserves its
+identity. Remove imports of `normalizeClient` and the
+`@syncular/client/realtime-supervisor-observation` forwarding utility. Pass the
+client to `SyncProvider` and use `realtimeSupervisorSnapshot(client)` to inspect
+an attached supervisor. Custom React clients must implement the snapshot
+methods and method-form collection reads. See the [React migration](https://syncular.dev/platform-react/)
+for the `onEnqueued` callback rename.
+
+## Outbox read costs
+
+Request encoding pins the pending count and highest local sequence before its
+first asynchronous step. It reads keyset pages of 32 raw records, decodes only
+the consumed prefix, and stops at the first whole commit that exceeds the
+remaining operation budget. Mutations appended during encoding enter the next
+request. Status and diagnostics use `COUNT(*)` without parsing pending bodies.
+Optimistic replay still reads the remaining outbox after each response. The
+100/1,000/10,000-commit workload and measured limits are recorded in
+[the reliability RFC](../../docs/RFC-RELIABILITY-DX.md#9-implementation-evidence-2026-09-05).

package/dist/bun-database.js

@@ -20,6 +20,17 @@ export class BunClientDatabase {
     #tx = { depth: 0 };
     constructor(path = ':memory:') {
         this.db = new Database(path);
+        // Match native Rust persistence: append durable commits to the WAL
+        // instead of creating and syncing a rollback journal per transaction.
+        // SQLite retains its in-memory journal for :memory: databases.
+        try {
+            this.db.run('PRAGMA journal_mode = WAL');
+            this.db.run('PRAGMA synchronous = FULL');
+        }
+        catch (error) {
+            this.db.close();
+            throw error;
+        }
     }
     exec(sql, params = []) {
         this.db.query(sql).run(...coerceParams(params));

package/dist/client.d.ts

@@ -231,6 +231,16 @@ export interface QuerySnapshot<Row = SqlRow> {
  * complete once its bootstrap round finishes — emptiness ≠ pendency.
  */
 export declare function windowComplete(state: WindowState, unit: string): boolean;
+/** Canonical client reads, shared by synchronous cores and promise hosts. */
+export type ClientSnapshotMethods = Pick<SyncClient, 'querySnapshot' | 'statusSnapshot' | 'diagnosticsSnapshot' | 'conflicts' | 'rejections' | 'commitOutcome' | 'commitOutcomes' | 'resolveCommitOutcome'>;
+/** Project a method contract across an asynchronous host boundary. */
+export type PromiseMethods<Methods> = {
+    [Key in keyof Methods]: Methods[Key] extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<Awaited<Result>> : never;
+};
+/** A reader can execute locally or cross a worker/native boundary. */
+export type ClientSnapshotReader = {
+    [Key in keyof ClientSnapshotMethods]: (...args: Parameters<ClientSnapshotMethods[Key]>) => ReturnType<ClientSnapshotMethods[Key]> | Promise<ReturnType<ClientSnapshotMethods[Key]>>;
+};
 export declare class SyncClient {
     #private;
     constructor(config: SyncClientConfig);
@@ -238,7 +248,7 @@ export declare class SyncClient {
     start(): Promise<void>;
     close(): Promise<void>;
     /** Current fail-closed local-replica security state. */
-    get securityLifecycle(): SecurityLifecycle;
+    securityLifecycle(): SecurityLifecycle;
     /**
      * Block new protected operations immediately, then wait for every already
      * serialized database/network operation to settle before releasing key
@@ -320,8 +330,8 @@ export declare class SyncClient {
     fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
     /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
     flushBlobUploads(): Promise<void>;
-    get conflicts(): readonly ConflictRecord[];
-    get rejections(): readonly RejectionRecord[];
+    conflicts(): readonly ConflictRecord[];
+    rejections(): readonly RejectionRecord[];
     /** One durable final outcome by the originating client commit id. */
     commitOutcome(clientCommitId: string): CommitOutcome | undefined;
     /** Newest-first durable outcome journal. */
@@ -333,28 +343,11 @@ export declare class SyncClient {
      * 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;
-    /**
-     * §7.4.5: true while a schema-bump reset + first re-bootstrap is in
-     * flight — the app's "upgrading…" cue. Clears when the first post-reset
-     * bootstrap round reaches idle (every subscription past its fresh
-     * bootstrap).
-     */
-    get upgrading(): boolean;
-    /**
-     * §7.3.5: the current auth-lease state (opaque). Undefined until a
-     * `LEASE` frame arrives. `errorCode` is set when a round was rejected
-     * with a request-level lease code — syncing on the lease has stopped.
-     */
-    get leaseState(): LeaseState | undefined;
     /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
      * `undefined` if no lease is held. Negative once expired. */
     leaseRemainingMs(now?: number): number | undefined;
     /** True when syncing is stopped pending a client upgrade. */
     get stopped(): boolean;
-    /** §8: a hello/wake-up asked for a pull that has not run yet. */
-    get syncNeeded(): boolean;
     /**
      * §8.6 presence on a scope key: the current peers present there (a map
      * of `actorId clientId` → peer). Empty for a key with no present peers.

package/dist/client.js

@@ -18,7 +18,7 @@ import { singleOwnerLock, } from './leader-lock.js';
 import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
 import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
 import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
-import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
+import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
 import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
@@ -232,7 +232,7 @@ export class SyncClient {
         // this as an exact core-owned intent so hosts never need a startup poll or
         // an application-issued sync() call.
         const startupWork = this.#schemaFloor === undefined &&
-            (listOutbox(this.#db).length > 0 ||
+            (countOutbox(this.#db) > 0 ||
                 subscriptions.some((sub) => sub.status === 'active'));
         if (startupWork && this.#securityLifecycle === 'active') {
             this.#needsPull = true;
@@ -247,10 +247,10 @@ export class SyncClient {
             role: () => 'direct',
             outbox: async () => this.pendingCommits().length,
             subscriptions: async () => this.subscriptions(),
-            conflicts: async () => this.conflicts.length,
-            rejections: async () => this.rejections.length,
-            syncNeeded: async () => this.syncNeeded,
-            upgrading: async () => this.upgrading,
+            conflicts: async () => this.conflicts().length,
+            rejections: async () => this.rejections().length,
+            syncNeeded: async () => this.statusSnapshot().syncNeeded,
+            upgrading: async () => this.statusSnapshot().upgrading,
             onInvalidate: (listener) => this.onInvalidate(listener),
         });
         this.#emitDiagnostics();
@@ -395,7 +395,7 @@ export class SyncClient {
         }
     }
     /** Current fail-closed local-replica security state. */
-    get securityLifecycle() {
+    securityLifecycle() {
         return this.#securityLifecycle;
     }
     /**
@@ -439,7 +439,7 @@ export class SyncClient {
         this.#encryption = options.encryption;
         this.#securityLifecycle = 'active';
         const startupWork = this.#schemaFloor === undefined &&
-            (listOutbox(this.#db).length > 0 ||
+            (countOutbox(this.#db) > 0 ||
                 loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
         if (startupWork) {
             this.#setSyncNeeded(true);
@@ -666,7 +666,7 @@ export class SyncClient {
             replica: {
                 localRevision: getLocalRevision(this.#db).toString(),
                 syncNeeded: this.#needsPull,
-                pendingOutbox: listOutbox(this.#db).length,
+                pendingOutbox: countOutbox(this.#db),
             },
             lease: leaseState,
             subscriptions: allSubscriptions.slice(0, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS),
@@ -757,7 +757,7 @@ export class SyncClient {
     #statusSnapshot(outboxCount) {
         return {
             currentSchemaVersion: this.#config.schema.version,
-            outbox: outboxCount ?? listOutbox(this.#db).length,
+            outbox: outboxCount ?? countOutbox(this.#db),
             upgrading: this.#upgrading,
             leaseState: this.#leaseState,
             schemaFloor: this.#schemaFloor,
@@ -770,7 +770,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, statusSnapshotOverride) {
+    #applyBatch(fn, statusSnapshotOverride, onRollback) {
         if (this.#batch !== undefined)
             return fn(this.#batch);
         const batch = new ChangeAccumulator();
@@ -796,6 +796,7 @@ export class SyncClient {
         }
         catch (error) {
             this.#batch = undefined;
+            onRollback?.(error);
             throw error;
         }
         if (revision !== undefined) {
@@ -929,6 +930,9 @@ export class SyncClient {
             throw new ClientSyncError('sync.invalid_request', `blob content address mismatch for ${blobId} (§5.9.5)`);
         }
         putCachedBlob(this.#db, blobId, bytes, this.#now());
+        // The referencing row can arrive before its body. Pin the new cache entry
+        // from current visible references before applying the size cap (§5.9.7 B1).
+        this.#reconcileBlobs(false);
         this.#enforceBlobCacheCap();
         const stored = getCachedBlob(this.#db, blobId);
         if (stored === undefined) {
@@ -994,11 +998,11 @@ export class SyncClient {
         }
         await transport.upload(blobId, bytes, mediaType);
     }
-    get conflicts() {
+    conflicts() {
         this.#requireActive();
         return this.#conflicts;
     }
-    get rejections() {
+    rejections() {
         this.#requireActive();
         return this.#rejections;
     }
@@ -1062,27 +1066,6 @@ export class SyncClient {
             return resolved;
         });
     }
-    /** Non-undefined once the server declared a schema floor (§1.6). */
-    get schemaFloor() {
-        return this.#schemaFloor;
-    }
-    /**
-     * §7.4.5: true while a schema-bump reset + first re-bootstrap is in
-     * flight — the app's "upgrading…" cue. Clears when the first post-reset
-     * bootstrap round reaches idle (every subscription past its fresh
-     * bootstrap).
-     */
-    get upgrading() {
-        return this.#upgrading;
-    }
-    /**
-     * §7.3.5: the current auth-lease state (opaque). Undefined until a
-     * `LEASE` frame arrives. `errorCode` is set when a round was rejected
-     * with a request-level lease code — syncing on the lease has stopped.
-     */
-    get leaseState() {
-        return this.#leaseState;
-    }
     /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
      * `undefined` if no lease is held. Negative once expired. */
     leaseRemainingMs(now = this.#now()) {
@@ -1093,10 +1076,6 @@ export class SyncClient {
     get stopped() {
         return this.#schemaFloor !== undefined;
     }
-    /** §8: a hello/wake-up asked for a pull that has not run yet. */
-    get syncNeeded() {
-        return this.#needsPull;
-    }
     /**
      * §8.6 presence on a scope key: the current peers present there (a map
      * of `actorId clientId` → peer). Empty for a key with no present peers.
@@ -1731,21 +1710,27 @@ export class SyncClient {
      * the encoded push frames index-aligned with the surviving `outbox`.
      */
     async #encodeOutboxForPush() {
-        const pending = listOutbox(this.#db);
+        // Pin before the first encryption await: mutations can append while a
+        // round is encoding, and belong to the next request.
+        const bounds = this.#db.query('SELECT COUNT(*) AS count, MAX(seq) AS last_seq FROM _syncular_outbox')[0];
+        const pendingCount = bounds.count;
+        const throughSeq = bounds.last_seq ?? 0;
         const pushFrames = [];
         const outbox = [];
         let deferred = 0;
         let ops = 0;
-        for (const commit of pending) {
+        let processed = 0;
+        for (const commit of iterateOutbox(this.#db, throughSeq)) {
             // §6.1 splitBatch: whole commits in commit order, stopping before the
             // per-request operation cap. A first commit that alone exceeds the cap
             // is sent alone — the server rejects it loudly rather than the queue
             // wedging silently. Deferred commits stay queued for the next round.
             if (outbox.length > 0 &&
                 ops + commit.operations.length > MAX_OPS_PER_REQUEST) {
-                deferred += 1;
-                continue;
+                deferred = pendingCount - processed;
+                break;
             }
+            processed += 1;
             try {
                 pushFrames.push(
                 // §5.11: encrypted columns are encrypted at this encode-at-send
@@ -2003,7 +1988,8 @@ export class SyncClient {
                 last.segmentRowsApplied === 0 &&
                 last.bootstrapping.length === 0 &&
                 last.resets.length === 0 &&
-                (last.deferredCommits ?? 0) === 0) {
+                (last.deferredCommits ?? 0) === 0 &&
+                !this.#needsPull) {
                 return last;
             }
         }
@@ -2085,8 +2071,16 @@ export class SyncClient {
         }
         let openedSocket;
         const socket = await connector({
-            onText: (text) => this.#handleRealtimeText(text),
-            onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
+            onText: (text) => {
+                if (generation !== this.#realtimeGeneration || !this.#started)
+                    return;
+                this.#handleRealtimeText(text);
+            },
+            onBinary: (bytes) => {
+                if (generation !== this.#realtimeGeneration || !this.#started)
+                    return;
+                this.#routeRealtimeBinary(bytes);
+            },
             onClose: () => {
                 if (openedSocket === undefined || this.#socket !== openedSocket)
                     return;
@@ -2329,12 +2323,14 @@ 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)) {
+            for (let index = 1; index < message.frames.length; index += 1) {
+                const frame = message.frames[index];
+                if (frame === undefined)
+                    break;
                 switch (frame.type) {
                     case 'RESP_HEADER':
                         break;
@@ -2347,13 +2343,41 @@ export class SyncClient {
                         });
                         break;
                     case 'PUSH_RESULT': {
-                        let outboxCount = responseOutboxCount ?? listOutbox(this.#db).length;
+                        const results = [frame];
+                        if (frame.status !== 'rejected') {
+                            while (index + 1 < message.frames.length) {
+                                const next = message.frames[index + 1];
+                                if (next?.type !== 'PUSH_RESULT' || next.status === 'rejected')
+                                    break;
+                                results.push(next);
+                                index += 1;
+                            }
+                        }
+                        const conflictCount = this.#conflicts.length;
+                        const rejectionCount = this.#rejections.length;
+                        let outboxCount = countOutbox(this.#db);
                         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;
+                            let drained = false;
+                            for (const result of results) {
+                                if (this.#handlePushResult(result, commitsById, summary, batch, rejectionDetailsByCommit.get(result.clientCommitId))) {
+                                    outboxCount -= 1;
+                                    drained = true;
+                                }
+                            }
+                            if (drained &&
+                                results.some((result) => result === lastFinalPushResult)) {
+                                pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+                            }
+                        }, () => this.#statusSnapshot(outboxCount), (cause) => {
+                            this.#conflicts.length = conflictCount;
+                            this.#rejections.length = rejectionCount;
+                            const error = new ClientSyncError('client.outcome_persistence_failed', 'local commit outcome could not be persisted');
+                            error.cause = cause;
+                            throw error;
+                        });
+                        for (const conflict of this.#conflicts.slice(conflictCount)) {
+                            this.#config.onConflict?.(conflict);
+                        }
                         break;
                     }
                     case 'PUSH_RESULT_DETAILS':
@@ -2519,7 +2543,7 @@ export class SyncClient {
         }
         return { ...summary, bootstrapping };
     }
-    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails, pruneOutcomes) {
+    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails) {
         const commit = commitsById.get(frame.clientCommitId);
         if (commit === undefined)
             return false;
@@ -2543,9 +2567,6 @@ export class SyncClient {
                 })),
             });
             deleteOutboxCommit(this.#db, frame.clientCommitId);
-            if (pruneOutcomes) {
-                pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
-            }
             batch.status();
             batch.outcomes();
             summary.applied.push(frame.clientCommitId);
@@ -2580,7 +2601,6 @@ export class SyncClient {
                 outcomeResults.push({ status: 'conflict', conflict });
                 batch.conflicts();
                 summary.conflicts.push(conflict);
-                this.#config.onConflict?.(conflict);
             }
             else if (result.status === 'error') {
                 const details = rejectionDetails?.get(result.opIndex);
@@ -2610,9 +2630,6 @@ export class SyncClient {
             results: outcomeResults,
             operations: commit.operations,
         });
-        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;

package/dist/node-database.js

@@ -32,6 +32,14 @@ export class NodeClientDatabase {
     #tx = { depth: 0 };
     constructor(path = ':memory:') {
         this.db = new DatabaseSync(path);
+        try {
+            this.db.exec('PRAGMA journal_mode = WAL');
+            this.db.exec('PRAGMA synchronous = FULL');
+        }
+        catch (error) {
+            this.db.close();
+            throw error;
+        }
     }
     exec(sql, params = []) {
         this.db.prepare(sql).run(...coerceParams(params));

package/dist/outbox.d.ts

@@ -38,8 +38,12 @@ export interface OutboxBeforeImage {
     readonly values?: Readonly<Record<string, JsonRowValue>>;
 }
 export declare function appendOutboxCommit(db: ClientDatabase, clientCommitId: string, operations: readonly OutboxOperation[], nowMs: number, beforeImages?: readonly OutboxBeforeImage[]): void;
-/** Pending commits in FIFO creation order (§7.1). */
+/** Pending commits in FIFO creation order (§7.1). Full reads serve replay and the public listing. */
 export declare function listOutbox(db: ClientDatabase): OutboxCommit[];
+/** Keyset pages bound staging; laziness decodes only commits consumed by the encoder. */
+export declare function iterateOutbox(db: ClientDatabase, throughSeq: number): Generator<OutboxCommit>;
+/** Routine status reads never load operation bodies. */
+export declare function countOutbox(db: ClientDatabase): number;
 export declare function deleteOutboxCommit(db: ClientDatabase, clientCommitId: string): void;
 export declare function listOutboxBeforeImages(db: ClientDatabase, clientCommitId: string): OutboxBeforeImage[];
 export declare function replaceOutboxBeforeImages(db: ClientDatabase, clientCommitId: string, replacements: readonly OutboxBeforeImage[]): void;

package/dist/outbox.js

@@ -26,17 +26,40 @@ export function appendOutboxCommit(db, clientCommitId, operations, nowMs, before
         ]);
     }
 }
-/** Pending commits in FIFO creation order (§7.1). */
+/** Pending commits in FIFO creation order (§7.1). Full reads serve replay and the public listing. */
 export function listOutbox(db) {
     return db
         .query(`SELECT seq, client_commit_id, created_at_ms, operations
        FROM _syncular_outbox ORDER BY seq ASC`)
-        .map((row) => ({
+        .map(decodeOutboxRow);
+}
+function decodeOutboxRow(row) {
+    return {
         seq: row.seq,
         clientCommitId: row.client_commit_id,
         createdAtMs: row.created_at_ms,
         operations: JSON.parse(row.operations),
-    }));
+    };
+}
+/** Keyset pages bound staging; laziness decodes only commits consumed by the encoder. */
+export function* iterateOutbox(db, throughSeq) {
+    let afterSeq = 0;
+    while (afterSeq < throughSeq) {
+        const rows = db.query(`SELECT seq, client_commit_id, created_at_ms, operations FROM _syncular_outbox
+       WHERE seq > ? AND seq <= ? ORDER BY seq ASC LIMIT 32`, [afterSeq, throughSeq]);
+        if (rows.length === 0)
+            return;
+        for (const row of rows) {
+            const commit = decodeOutboxRow(row);
+            afterSeq = commit.seq;
+            yield commit;
+        }
+    }
+}
+/** Routine status reads never load operation bodies. */
+export function countOutbox(db) {
+    return db.query('SELECT COUNT(*) AS count FROM _syncular_outbox')[0]
+        .count;
 }
 export function deleteOutboxCommit(db, clientCommitId) {
     db.exec('DELETE FROM _syncular_outbox_before_images WHERE client_commit_id = ?', [clientCommitId]);

package/dist/reactive-store.d.ts

@@ -1,5 +1,5 @@
 import { type SyncAvailability } from './availability.js';
-import type { CommitOutcome, QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
+import type { CommitOutcome, ClientSnapshotReader, QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
 import type { SqlValue } from './database.js';
 import type { ClientChangeListener, SyncStatusSnapshot } from './invalidation.js';
 import type { LeadershipState } from './multi-tab.js';
@@ -27,16 +27,14 @@ export interface LiveQueryResult<Row> {
     readonly isRefreshing: boolean;
     readonly availability: SyncAvailability;
 }
-export interface ReactiveQueryClient {
+export interface ReactiveQueryClient extends Pick<ClientSnapshotReader, 'statusSnapshot' | 'commitOutcomes'> {
     readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
     querySnapshot<Row = Record<string, SqlValue>>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
-    statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
     leadershipSnapshot?(): LeadershipState | undefined;
     onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
-    readonly conflicts: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
-    readonly rejections: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
-    commitOutcomes(): readonly CommitOutcome[] | Promise<readonly CommitOutcome[]>;
+    conflicts(): readonly unknown[] | Promise<readonly unknown[]>;
+    rejections(): readonly unknown[] | Promise<readonly unknown[]>;
     setWindow(base: WindowBase, units: readonly string[]): void | Promise<void>;
     windowState(base: WindowBase): WindowState | Promise<WindowState>;
 }
@@ -85,6 +83,14 @@ export declare class ReactiveClientStore {
     window(base: WindowBase): ExternalStoreEntry<WindowState>;
     setWindowClaim(owner: symbol, base: WindowBase, units: readonly string[]): Promise<void>;
     releaseWindowClaims(owner: symbol): void;
+    /** Retained observation counts for diagnostics and resource benchmarks. */
+    cacheStats(): {
+        queries: number;
+        activeQueries: number;
+        windows: number;
+        activeWindows: number;
+        windowClaims: number;
+    };
     start(): void;
     dispose(): void;
 }