@syncular/client 0.15.48 → 0.17.0

package/dist/worker-protocol.d.ts

@@ -18,15 +18,14 @@
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
-import type { ClientDiagnosticsRequest, ClientDiagnosticsSnapshot } from './diagnostics.js';
+import type { ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
-import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
+import type { ClientChangeBatch, LocalRevision } from './invalidation.js';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
 import type { LocalDataRebootstrapInput, LocalDataRebootstrapResult } from './local-rebootstrap.js';
 import type { OutboxCommit } from './outbox.js';
-import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
@@ -88,7 +87,7 @@ export interface WorkerInitResult {
 export interface WorkerSecurityActivation {
     readonly encryption?: EncryptionKeyringConfig;
 }
-export interface WorkerApi {
+export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'> {
     securityLifecycle(): SecurityLifecycle;
     beginSecurityPreflight(): Promise<void>;
     activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
@@ -112,19 +111,6 @@ export interface WorkerApi {
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     querySnapshot(spec: QueryReadSpec): QuerySnapshot;
     localRevision(): LocalRevision;
-    statusSnapshot(): SyncStatusSnapshot;
-    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): ClientDiagnosticsSnapshot;
-    conflicts(): readonly ConflictRecord[];
-    rejections(): readonly RejectionRecord[];
-    commitOutcome(clientCommitId: string): CommitOutcome | undefined;
-    commitOutcomes(query?: CommitOutcomeQuery): readonly CommitOutcome[];
-    resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;
-    schemaFloor(): SchemaFloor | undefined;
-    /** §7.3.5: the opaque auth-lease state, or undefined. */
-    leaseState(): LeaseState | undefined;
-    /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
-    upgrading(): boolean;
-    syncNeeded(): boolean;
     pendingCommits(): OutboxCommit[];
     subscriptions(): SubscriptionRecord[];
     subscription(id: string): SubscriptionRecord | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.48",
+  "version": "0.17.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -34,14 +34,6 @@
         "default": "./dist/index.js"
       }
     },
-    "./realtime-supervisor-observation": {
-      "bun": "./src/realtime-supervisor-observation.ts",
-      "browser": "./dist/realtime-supervisor-observation.js",
-      "import": {
-        "types": "./dist/realtime-supervisor-observation.d.ts",
-        "default": "./dist/realtime-supervisor-observation.js"
-      }
-    },
     "./bun": {
       "bun": "./src/bun-database.ts",
       "browser": "./dist/bun-database.js",
@@ -97,9 +89,9 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.48"
+    "@syncular/core": "0.17.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.15.48"
+    "@syncular/server": "0.17.0"
   }
 }

package/src/bun-database.ts

@@ -36,6 +36,16 @@ export class BunClientDatabase implements ClientDatabase {
 
   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: string, params: readonly SqlValue[] = []): void {

package/src/client.ts

@@ -119,6 +119,8 @@ import {
   dropOutboxCommitsInScope,
   encodeOutboxCommit,
   listOutbox,
+  iterateOutbox,
+  countOutbox,
   listOutboxBeforeImages,
   type OutboxBeforeImage,
   type OutboxCommit,
@@ -527,6 +529,37 @@ function isFinalPushResult(frame: PushResultFrame): 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 class SyncClient {
   readonly #config: SyncClientConfig;
   readonly #db: ClientDatabase;
@@ -707,7 +740,7 @@ export class SyncClient {
     // 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;
@@ -722,10 +755,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();
@@ -875,7 +908,7 @@ export class SyncClient {
   }
 
   /** Current fail-closed local-replica security state. */
-  get securityLifecycle(): SecurityLifecycle {
+  securityLifecycle(): SecurityLifecycle {
     return this.#securityLifecycle;
   }
 
@@ -927,7 +960,7 @@ export class SyncClient {
     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);
@@ -1194,7 +1227,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(
@@ -1310,7 +1343,7 @@ export class SyncClient {
   #statusSnapshot(outboxCount?: number): SyncStatusSnapshot {
     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,
@@ -1327,6 +1360,7 @@ export class SyncClient {
   #applyBatch<T>(
     fn: (batch: ChangeAccumulator) => T,
     statusSnapshotOverride?: () => SyncStatusSnapshot,
+    onRollback?: (error: unknown) => never,
   ): T {
     if (this.#batch !== undefined) return fn(this.#batch);
     const batch = new ChangeAccumulator();
@@ -1350,6 +1384,7 @@ export class SyncClient {
       });
     } catch (error) {
       this.#batch = undefined;
+      onRollback?.(error);
       throw error;
     }
     if (revision !== undefined) {
@@ -1519,6 +1554,9 @@ export class SyncClient {
       );
     }
     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) {
@@ -1606,12 +1644,12 @@ export class SyncClient {
     await transport.upload(blobId, bytes, mediaType);
   }
 
-  get conflicts(): readonly ConflictRecord[] {
+  conflicts(): readonly ConflictRecord[] {
     this.#requireActive();
     return this.#conflicts;
   }
 
-  get rejections(): readonly RejectionRecord[] {
+  rejections(): readonly RejectionRecord[] {
     this.#requireActive();
     return this.#rejections;
   }
@@ -1702,30 +1740,6 @@ export class SyncClient {
     });
   }
 
-  /** Non-undefined once the server declared a schema floor (§1.6). */
-  get schemaFloor(): SchemaFloor | undefined {
-    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(): boolean {
-    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(): LeaseState | undefined {
-    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: number = this.#now()): number | undefined {
@@ -1738,11 +1752,6 @@ export class SyncClient {
     return this.#schemaFloor !== undefined;
   }
 
-  /** §8: a hello/wake-up asked for a pull that has not run yet. */
-  get syncNeeded(): boolean {
-    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.
@@ -2502,12 +2511,19 @@ export class SyncClient {
     outbox: OutboxCommit[];
     deferred: number;
   }> {
-    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 as number;
+    const throughSeq = (bounds.last_seq as number | null) ?? 0;
     const pushFrames: RequestFrame[] = [];
     const outbox: OutboxCommit[] = [];
     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
@@ -2516,9 +2532,10 @@ export class SyncClient {
         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
@@ -2810,7 +2827,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;
       }
@@ -2918,8 +2936,14 @@ export class SyncClient {
     }
     let openedSocket: RealtimeSocket | undefined;
     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;
         this.#socket = undefined;
@@ -3210,13 +3234,14 @@ export class SyncClient {
     let section: OpenSection | undefined;
     let errorFrame: ClientSyncError | undefined;
     let deltaCursor = -1;
-    let responseOutboxCount: number | undefined;
 
     // 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;
@@ -3229,23 +3254,61 @@ export class SyncClient {
             });
             break;
           case 'PUSH_RESULT': {
-            let outboxCount =
-              responseOutboxCount ?? listOutbox(this.#db).length;
+            const results: PushResultFrame[] = [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;
+                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;
+              },
             );
-            responseOutboxCount = outboxCount;
+            for (const conflict of this.#conflicts.slice(conflictCount)) {
+              this.#config.onConflict?.(conflict);
+            }
             break;
           }
           case 'PUSH_RESULT_DETAILS':
@@ -3494,7 +3557,6 @@ export class SyncClient {
     summary: MutableSummary,
     batch: ChangeAccumulator,
     rejectionDetails: ReadonlyMap<number, RejectionDetails> | undefined,
-    pruneOutcomes: boolean,
   ): boolean {
     const commit = commitsById.get(frame.clientCommitId);
     if (commit === undefined) return false;
@@ -3517,9 +3579,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);
@@ -3557,7 +3616,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);
         const rejection: RejectionRecord = {
@@ -3585,9 +3643,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/src/node-database.ts

@@ -40,6 +40,13 @@ export class NodeClientDatabase implements ClientDatabase {
 
   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: string, params: readonly SqlValue[] = []): void {

package/src/outbox.ts

@@ -11,7 +11,7 @@ import {
   type PushOperation,
   type ScopeMap,
 } from '@syncular/core';
-import type { ClientDatabase } from './database';
+import type { ClientDatabase, SqlRow } from './database';
 import type { EncryptionConfig } from './encryption';
 import { ClientSyncError } from './errors';
 import {
@@ -85,19 +85,50 @@ export function appendOutboxCommit(
   }
 }
 
-/** 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: ClientDatabase): OutboxCommit[] {
   return db
     .query(
       `SELECT seq, client_commit_id, created_at_ms, operations
        FROM _syncular_outbox ORDER BY seq ASC`,
     )
-    .map((row) => ({
-      seq: row.seq as number,
-      clientCommitId: row.client_commit_id as string,
-      createdAtMs: row.created_at_ms as number,
-      operations: JSON.parse(row.operations as string) as OutboxOperation[],
-    }));
+    .map(decodeOutboxRow);
+}
+
+function decodeOutboxRow(row: SqlRow): OutboxCommit {
+  return {
+    seq: row.seq as number,
+    clientCommitId: row.client_commit_id as string,
+    createdAtMs: row.created_at_ms as number,
+    operations: JSON.parse(row.operations as string) as OutboxOperation[],
+  };
+}
+
+/** Keyset pages bound staging; laziness decodes only commits consumed by the encoder. */
+export function* iterateOutbox(
+  db: ClientDatabase,
+  throughSeq: number,
+): Generator<OutboxCommit> {
+  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: ClientDatabase): number {
+  return db.query('SELECT COUNT(*) AS count FROM _syncular_outbox')[0]!
+    .count as number;
 }
 
 export function deleteOutboxCommit(