@syncular/client 0.16.1 → 0.18.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

package/dist/blob.d.ts

@@ -115,12 +115,14 @@ export declare function schemaHasBlobs(schema: CompiledClientSchema): boolean;
  * to zero refs *and* have no pending upload (a pending upload pins its body,
  * B4). Called after every apply/purge that may add or remove references.
  *
+ * `blobId` narrows a fresh-download refresh to the inserted cache row.
  * `deleteOrphans` distinguishes the two B2 transitions: revocation purge
  * passes `true` (drop the now-unauthorized body); a benign apply passes
  * `false` (retain zero-ref bodies as LRU cache entries — the shipped
  * default). Bodies pinned by a pending upload are always retained.
  */
 export declare function reconcileBlobRefcounts(db: ClientDatabase, schema: CompiledClientSchema, options?: {
+    readonly blobId?: string;
     readonly deleteOrphans?: boolean;
 }): void;
 export type { BlobRef };

package/dist/blob.js

@@ -11,10 +11,14 @@
  * outbox-adjacent uploads table (B4) and flushed before push.
  */
 import { parseBlobRef, serializeBlobRef } from '@syncular/core';
+import { ClientSyncError } from './errors.js';
 import { quoteIdent } from './schema.js';
 /** `"sha256:" + hex` of the bytes — the content address (§5.9.1). */
 export async function computeBlobId(bytes) {
-    const digest = await crypto.subtle.digest('SHA-256', bytes.slice().buffer);
+    const input = bytes.buffer instanceof ArrayBuffer
+        ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+        : bytes.slice();
+    const digest = await crypto.subtle.digest('SHA-256', input);
     const hex = [...new Uint8Array(digest)]
         .map((b) => b.toString(16).padStart(2, '0'))
         .join('');
@@ -42,6 +46,9 @@ export function ensureBlobSchema(db) {
     blob_id TEXT PRIMARY KEY,
     media_type TEXT,
     created_at_ms INTEGER NOT NULL)`);
+    db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
+    commit_id TEXT NOT NULL, blob_id TEXT NOT NULL, PRIMARY KEY(commit_id, blob_id))`);
+    db.exec('CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body ON _syncular_blob_commit_refs(blob_id)');
 }
 /** Put bytes into the content-addressed cache (idempotent); touches LRU. */
 export function putCachedBlob(db, blobId, bytes, nowMs, mediaType) {
@@ -90,6 +97,7 @@ export function enforceBlobCacheCap(db, maxBytes) {
     const candidates = db.query(`SELECT blob_id, byte_length FROM _syncular_blobs
      WHERE refcount = 0
        AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+       AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
      ORDER BY last_used_ms ASC, created_at_ms ASC`);
     const evicted = [];
     db.transaction(() => {
@@ -111,13 +119,23 @@ export function recordPendingUpload(db, blobId, nowMs, mediaType) {
 }
 export function listPendingUploads(db) {
     return db
-        .query('SELECT blob_id, media_type FROM _syncular_blob_uploads ORDER BY created_at_ms')
-        .map((row) => ({
-        blobId: row.blob_id,
-        ...(row.media_type !== null
-            ? { mediaType: row.media_type }
-            : {}),
-    }));
+        .query(`SELECT blob_id, media_type FROM (
+        SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
+        UNION ALL
+        SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
+        FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
+        WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
+      ) ORDER BY created_at_ms, blob_id`)
+        .map((row) => {
+        if (typeof row.blob_id !== 'string' ||
+            (row.media_type !== null && typeof row.media_type !== 'string')) {
+            throw new ClientSyncError('sync.local_corrupt', 'Pending blob upload metadata is invalid');
+        }
+        return {
+            blobId: row.blob_id,
+            ...(row.media_type !== null ? { mediaType: row.media_type } : {}),
+        };
+    });
 }
 export function clearPendingUpload(db, blobId) {
     db.exec('DELETE FROM _syncular_blob_uploads WHERE blob_id = ?', [blobId]);
@@ -150,6 +168,7 @@ export function schemaHasBlobs(schema) {
  * to zero refs *and* have no pending upload (a pending upload pins its body,
  * B4). Called after every apply/purge that may add or remove references.
  *
+ * `blobId` narrows a fresh-download refresh to the inserted cache row.
  * `deleteOrphans` distinguishes the two B2 transitions: revocation purge
  * passes `true` (drop the now-unauthorized body); a benign apply passes
  * `false` (retain zero-ref bodies as LRU cache entries — the shipped
@@ -159,6 +178,25 @@ export function reconcileBlobRefcounts(db, schema, options) {
     const byTable = blobRefColumnsBySchema(schema);
     if (byTable.size === 0)
         return;
+    if (options?.blobId !== undefined) {
+        let count = 0;
+        for (const [tableName, columns] of byTable) {
+            for (const column of columns) {
+                const identifier = quoteIdent(column);
+                const row = db.query(`SELECT count(*) AS n FROM ${quoteIdent(tableName)}
+           WHERE CASE
+             WHEN typeof(${identifier}) = 'text' AND json_valid(${identifier})
+             THEN json_extract(${identifier}, '$.blobId')
+           END = ?`, [options.blobId])[0];
+                count += Number(row?.n ?? 0);
+            }
+        }
+        db.exec('UPDATE _syncular_blobs SET refcount = ? WHERE blob_id = ?', [
+            count,
+            options.blobId,
+        ]);
+        return;
+    }
     // Count references to each blobId across every blob_ref column.
     const counts = new Map();
     for (const [tableName, columns] of byTable) {
@@ -194,7 +232,8 @@ export function reconcileBlobRefcounts(db, schema, options) {
             // pending upload.
             db.exec(`DELETE FROM _syncular_blobs
          WHERE refcount = 0
-           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)`);
+           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)`);
         }
     });
 }

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.js

@@ -191,8 +191,39 @@ export class SyncClient {
         // Do not materialize new app indexes/FTS projections yet: on a version
         // bump they may reference columns that only exist after the reset.
         ensureLocalBookkeepingSchema(this.#db);
-        if (this.#hasBlobs)
-            ensureBlobSchema(this.#db);
+        this.#db.transaction(() => {
+            for (const trigger of ['insert', 'update', 'delete', 'cache'])
+                this.#db.exec(`DROP TRIGGER IF EXISTS _syncular_blob_commit_${trigger}`);
+            if (this.#hasBlobs) {
+                ensureBlobSchema(this.#db);
+                const columns = JSON.stringify([...this.#schema.tables.values()].flatMap((table) => table.columns
+                    .filter((column) => column.type === 'blob_ref')
+                    .map((column) => [table.name, column.name]))).replaceAll("'", "''");
+                const references = `SELECT o.client_commit_id, b.blob_id
+          FROM _syncular_outbox o JOIN json_each(o.operations) op
+          JOIN json_each(op.value, '$.values') v JOIN json_each('${columns}') c
+          JOIN _syncular_blobs b ON b.blob_id = CASE WHEN v.type = 'text' AND json_valid(v.value) THEN json_extract(v.value, '$.blobId') END
+          WHERE json_extract(op.value, '$.op') = 'upsert'
+            AND json_extract(op.value, '$.table') = json_extract(c.value, '$[0]')
+            AND v.key = json_extract(c.value, '$[1]')`;
+                this.#db
+                    .exec(`CREATE TRIGGER _syncular_blob_commit_insert AFTER INSERT ON _syncular_outbox BEGIN
+          INSERT OR IGNORE INTO _syncular_blob_commit_refs ${references} AND o.client_commit_id = NEW.client_commit_id; END`);
+                this.#db
+                    .exec(`CREATE TRIGGER _syncular_blob_commit_update AFTER UPDATE OF operations ON _syncular_outbox BEGIN
+          DELETE FROM _syncular_blob_commit_refs WHERE commit_id = OLD.client_commit_id;
+          INSERT OR IGNORE INTO _syncular_blob_commit_refs ${references} AND o.client_commit_id = NEW.client_commit_id; END`);
+                this.#db
+                    .exec(`CREATE TRIGGER _syncular_blob_commit_delete BEFORE DELETE ON _syncular_outbox BEGIN
+          DELETE FROM _syncular_blob_uploads WHERE blob_id IN (SELECT blob_id FROM _syncular_blob_commit_refs WHERE commit_id = OLD.client_commit_id)
+            AND NOT EXISTS (SELECT 1 FROM _syncular_blob_commit_refs r WHERE r.blob_id = _syncular_blob_uploads.blob_id AND r.commit_id != OLD.client_commit_id);
+          DELETE FROM _syncular_blob_commit_refs WHERE commit_id = OLD.client_commit_id; END`);
+                this.#db
+                    .exec(`CREATE TRIGGER _syncular_blob_commit_cache AFTER INSERT ON _syncular_blobs BEGIN
+          INSERT OR IGNORE INTO _syncular_blob_commit_refs ${references} AND b.blob_id = NEW.blob_id; END`);
+                this.#db.exec(`INSERT OR IGNORE INTO _syncular_blob_commit_refs ${references}`);
+            }
+        });
         this.#db.transaction(() => {
             pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
         });
@@ -770,7 +801,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 +827,7 @@ export class SyncClient {
         }
         catch (error) {
             this.#batch = undefined;
+            onRollback?.(error);
             throw error;
         }
         if (revision !== undefined) {
@@ -853,7 +885,8 @@ export class SyncClient {
      * (via `mutate`) after this call so upload-before-push holds (§5.9.3).
      */
     uploadBlob(bytes, options) {
-        return this.#runProtectedAsync(() => this.#uploadBlob(bytes, options));
+        const owned = bytes.slice();
+        return this.#runProtectedAsync(() => this.#uploadBlob(owned, options));
     }
     async #uploadBlob(bytes, options) {
         if (this.#config.blobs === undefined) {
@@ -929,6 +962,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, blobId);
         this.#enforceBlobCacheCap();
         const stored = getCachedBlob(this.#db, blobId);
         if (stored === undefined) {
@@ -953,11 +989,12 @@ export class SyncClient {
             return;
         for (const pending of listPendingUploads(this.#db)) {
             const cached = getCachedBlob(this.#db, pending.blobId);
-            if (cached === undefined) {
-                // The bytes are gone (never happens for a well-behaved client);
-                // drop the upload so it does not wedge the queue.
-                clearPendingUpload(this.#db, pending.blobId);
-                continue;
+            if (cached === undefined ||
+                !(cached.bytes instanceof Uint8Array) ||
+                !Number.isSafeInteger(cached.byteLength) ||
+                cached.byteLength !== cached.bytes.byteLength ||
+                (await computeBlobId(cached.bytes)) !== pending.blobId) {
+                throw new ClientSyncError('sync.local_corrupt', 'Pending blob upload body is missing or corrupt');
             }
             await this.#uploadOne(transport, pending.blobId, cached.bytes, pending.mediaType);
             clearPendingUpload(this.#db, pending.blobId);
@@ -2067,8 +2104,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;
@@ -2311,12 +2356,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;
@@ -2329,13 +2376,41 @@ export class SyncClient {
                         });
                         break;
                     case 'PUSH_RESULT': {
-                        let outboxCount = responseOutboxCount ?? countOutbox(this.#db);
+                        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':
@@ -2501,7 +2576,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;
@@ -2525,9 +2600,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);
@@ -2562,7 +2634,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);
@@ -2592,9 +2663,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;
@@ -3044,10 +3112,13 @@ export class SyncClient {
      * columns. No-op unless the schema has blob columns. `deleteOrphans`
      * triggers the revocation-side body deletion (B2).
      */
-    #reconcileBlobs(deleteOrphans) {
+    #reconcileBlobs(deleteOrphans, blobId) {
         if (!this.#hasBlobs)
             return;
-        reconcileBlobRefcounts(this.#db, this.#schema, { deleteOrphans });
+        reconcileBlobRefcounts(this.#db, this.#schema, {
+            deleteOrphans,
+            ...(blobId === undefined ? {} : { blobId }),
+        });
     }
     // -- helpers -----------------------------------------------------------------
     #table(name) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,9 +89,9 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.16.1"
+    "@syncular/core": "0.18.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.16.1"
+    "@syncular/server": "0.18.0"
   }
 }

package/src/blob.ts

@@ -12,6 +12,7 @@
  */
 import { type BlobRef, parseBlobRef, serializeBlobRef } from '@syncular/core';
 import type { ClientDatabase } from './database';
+import { ClientSyncError } from './errors';
 import type { CompiledClientSchema } from './schema';
 import { quoteIdent } from './schema';
 
@@ -93,9 +94,13 @@ export interface CachedBlob {
 
 /** `"sha256:" + hex` of the bytes — the content address (§5.9.1). */
 export async function computeBlobId(bytes: Uint8Array): Promise<string> {
+  const input =
+    bytes.buffer instanceof ArrayBuffer
+      ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+      : bytes.slice();
   const digest = await crypto.subtle.digest(
     'SHA-256',
-    bytes.slice().buffer as ArrayBuffer,
+    input as Uint8Array<ArrayBuffer>,
   );
   const hex = [...new Uint8Array(digest)]
     .map((b) => b.toString(16).padStart(2, '0'))
@@ -126,6 +131,11 @@ export function ensureBlobSchema(db: ClientDatabase): void {
     blob_id TEXT PRIMARY KEY,
     media_type TEXT,
     created_at_ms INTEGER NOT NULL)`);
+  db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
+    commit_id TEXT NOT NULL, blob_id TEXT NOT NULL, PRIMARY KEY(commit_id, blob_id))`);
+  db.exec(
+    'CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body ON _syncular_blob_commit_refs(blob_id)',
+  );
 }
 
 /** Put bytes into the content-addressed cache (idempotent); touches LRU. */
@@ -197,6 +207,7 @@ export function enforceBlobCacheCap(
     `SELECT blob_id, byte_length FROM _syncular_blobs
      WHERE refcount = 0
        AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+       AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
      ORDER BY last_used_ms ASC, created_at_ms ASC`,
   );
   const evicted: string[] = [];
@@ -231,14 +242,29 @@ export function listPendingUploads(
 ): { blobId: string; mediaType?: string }[] {
   return db
     .query(
-      'SELECT blob_id, media_type FROM _syncular_blob_uploads ORDER BY created_at_ms',
+      `SELECT blob_id, media_type FROM (
+        SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
+        UNION ALL
+        SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
+        FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
+        WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
+      ) ORDER BY created_at_ms, blob_id`,
     )
-    .map((row) => ({
-      blobId: row.blob_id as string,
-      ...(row.media_type !== null
-        ? { mediaType: row.media_type as string }
-        : {}),
-    }));
+    .map((row) => {
+      if (
+        typeof row.blob_id !== 'string' ||
+        (row.media_type !== null && typeof row.media_type !== 'string')
+      ) {
+        throw new ClientSyncError(
+          'sync.local_corrupt',
+          'Pending blob upload metadata is invalid',
+        );
+      }
+      return {
+        blobId: row.blob_id,
+        ...(row.media_type !== null ? { mediaType: row.media_type } : {}),
+      };
+    });
 }
 
 export function clearPendingUpload(db: ClientDatabase, blobId: string): void {
@@ -275,6 +301,7 @@ export function schemaHasBlobs(schema: CompiledClientSchema): boolean {
  * to zero refs *and* have no pending upload (a pending upload pins its body,
  * B4). Called after every apply/purge that may add or remove references.
  *
+ * `blobId` narrows a fresh-download refresh to the inserted cache row.
  * `deleteOrphans` distinguishes the two B2 transitions: revocation purge
  * passes `true` (drop the now-unauthorized body); a benign apply passes
  * `false` (retain zero-ref bodies as LRU cache entries — the shipped
@@ -283,10 +310,35 @@ export function schemaHasBlobs(schema: CompiledClientSchema): boolean {
 export function reconcileBlobRefcounts(
   db: ClientDatabase,
   schema: CompiledClientSchema,
-  options?: { readonly deleteOrphans?: boolean },
+  options?: {
+    readonly blobId?: string;
+    readonly deleteOrphans?: boolean;
+  },
 ): void {
   const byTable = blobRefColumnsBySchema(schema);
   if (byTable.size === 0) return;
+  if (options?.blobId !== undefined) {
+    let count = 0;
+    for (const [tableName, columns] of byTable) {
+      for (const column of columns) {
+        const identifier = quoteIdent(column);
+        const row = db.query(
+          `SELECT count(*) AS n FROM ${quoteIdent(tableName)}
+           WHERE CASE
+             WHEN typeof(${identifier}) = 'text' AND json_valid(${identifier})
+             THEN json_extract(${identifier}, '$.blobId')
+           END = ?`,
+          [options.blobId],
+        )[0];
+        count += Number(row?.n ?? 0);
+      }
+    }
+    db.exec('UPDATE _syncular_blobs SET refcount = ? WHERE blob_id = ?', [
+      count,
+      options.blobId,
+    ]);
+    return;
+  }
   // Count references to each blobId across every blob_ref column.
   const counts = new Map<string, number>();
   for (const [tableName, columns] of byTable) {
@@ -323,7 +375,8 @@ export function reconcileBlobRefcounts(
       db.exec(
         `DELETE FROM _syncular_blobs
          WHERE refcount = 0
-           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)`,
+           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)`,
       );
     }
   });

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

@@ -688,7 +688,47 @@ export class SyncClient {
     // Do not materialize new app indexes/FTS projections yet: on a version
     // bump they may reference columns that only exist after the reset.
     ensureLocalBookkeepingSchema(this.#db);
-    if (this.#hasBlobs) ensureBlobSchema(this.#db);
+    this.#db.transaction(() => {
+      for (const trigger of ['insert', 'update', 'delete', 'cache'])
+        this.#db.exec(
+          `DROP TRIGGER IF EXISTS _syncular_blob_commit_${trigger}`,
+        );
+      if (this.#hasBlobs) {
+        ensureBlobSchema(this.#db);
+        const columns = JSON.stringify(
+          [...this.#schema.tables.values()].flatMap((table) =>
+            table.columns
+              .filter((column) => column.type === 'blob_ref')
+              .map((column) => [table.name, column.name]),
+          ),
+        ).replaceAll("'", "''");
+        const references = `SELECT o.client_commit_id, b.blob_id
+          FROM _syncular_outbox o JOIN json_each(o.operations) op
+          JOIN json_each(op.value, '$.values') v JOIN json_each('${columns}') c
+          JOIN _syncular_blobs b ON b.blob_id = CASE WHEN v.type = 'text' AND json_valid(v.value) THEN json_extract(v.value, '$.blobId') END
+          WHERE json_extract(op.value, '$.op') = 'upsert'
+            AND json_extract(op.value, '$.table') = json_extract(c.value, '$[0]')
+            AND v.key = json_extract(c.value, '$[1]')`;
+        this.#db
+          .exec(`CREATE TRIGGER _syncular_blob_commit_insert AFTER INSERT ON _syncular_outbox BEGIN
+          INSERT OR IGNORE INTO _syncular_blob_commit_refs ${references} AND o.client_commit_id = NEW.client_commit_id; END`);
+        this.#db
+          .exec(`CREATE TRIGGER _syncular_blob_commit_update AFTER UPDATE OF operations ON _syncular_outbox BEGIN
+          DELETE FROM _syncular_blob_commit_refs WHERE commit_id = OLD.client_commit_id;
+          INSERT OR IGNORE INTO _syncular_blob_commit_refs ${references} AND o.client_commit_id = NEW.client_commit_id; END`);
+        this.#db
+          .exec(`CREATE TRIGGER _syncular_blob_commit_delete BEFORE DELETE ON _syncular_outbox BEGIN
+          DELETE FROM _syncular_blob_uploads WHERE blob_id IN (SELECT blob_id FROM _syncular_blob_commit_refs WHERE commit_id = OLD.client_commit_id)
+            AND NOT EXISTS (SELECT 1 FROM _syncular_blob_commit_refs r WHERE r.blob_id = _syncular_blob_uploads.blob_id AND r.commit_id != OLD.client_commit_id);
+          DELETE FROM _syncular_blob_commit_refs WHERE commit_id = OLD.client_commit_id; END`);
+        this.#db
+          .exec(`CREATE TRIGGER _syncular_blob_commit_cache AFTER INSERT ON _syncular_blobs BEGIN
+          INSERT OR IGNORE INTO _syncular_blob_commit_refs ${references} AND b.blob_id = NEW.blob_id; END`);
+        this.#db.exec(
+          `INSERT OR IGNORE INTO _syncular_blob_commit_refs ${references}`,
+        );
+      }
+    });
     this.#db.transaction(() => {
       pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
     });
@@ -1360,6 +1400,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();
@@ -1383,6 +1424,7 @@ export class SyncClient {
       });
     } catch (error) {
       this.#batch = undefined;
+      onRollback?.(error);
       throw error;
     }
     if (revision !== undefined) {
@@ -1453,7 +1495,8 @@ export class SyncClient {
     bytes: Uint8Array,
     options?: { readonly mediaType?: string; readonly name?: string },
   ): Promise<BlobRef> {
-    return this.#runProtectedAsync(() => this.#uploadBlob(bytes, options));
+    const owned = bytes.slice();
+    return this.#runProtectedAsync(() => this.#uploadBlob(owned, options));
   }
 
   async #uploadBlob(
@@ -1552,6 +1595,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, blobId);
     this.#enforceBlobCacheCap();
     const stored = getCachedBlob(this.#db, blobId);
     if (stored === undefined) {
@@ -1580,11 +1626,17 @@ export class SyncClient {
     if (transport === undefined || !this.#hasBlobs) return;
     for (const pending of listPendingUploads(this.#db)) {
       const cached = getCachedBlob(this.#db, pending.blobId);
-      if (cached === undefined) {
-        // The bytes are gone (never happens for a well-behaved client);
-        // drop the upload so it does not wedge the queue.
-        clearPendingUpload(this.#db, pending.blobId);
-        continue;
+      if (
+        cached === undefined ||
+        !(cached.bytes instanceof Uint8Array) ||
+        !Number.isSafeInteger(cached.byteLength) ||
+        cached.byteLength !== cached.bytes.byteLength ||
+        (await computeBlobId(cached.bytes)) !== pending.blobId
+      ) {
+        throw new ClientSyncError(
+          'sync.local_corrupt',
+          'Pending blob upload body is missing or corrupt',
+        );
       }
       await this.#uploadOne(
         transport,
@@ -2931,8 +2983,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;
@@ -3223,13 +3281,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;
@@ -3242,22 +3301,61 @@ export class SyncClient {
             });
             break;
           case 'PUSH_RESULT': {
-            let outboxCount = responseOutboxCount ?? countOutbox(this.#db);
+            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':
@@ -3506,7 +3604,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;
@@ -3529,9 +3626,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);
@@ -3569,7 +3663,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 = {
@@ -3597,9 +3690,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;
@@ -4180,9 +4270,12 @@ export class SyncClient {
    * columns. No-op unless the schema has blob columns. `deleteOrphans`
    * triggers the revocation-side body deletion (B2).
    */
-  #reconcileBlobs(deleteOrphans: boolean): void {
+  #reconcileBlobs(deleteOrphans: boolean, blobId?: string): void {
     if (!this.#hasBlobs) return;
-    reconcileBlobRefcounts(this.#db, this.#schema, { deleteOrphans });
+    reconcileBlobRefcounts(this.#db, this.#schema, {
+      deleteOrphans,
+      ...(blobId === undefined ? {} : { blobId }),
+    });
   }
 
   // -- helpers -----------------------------------------------------------------

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 {