@syncular/client 0.17.0 → 0.18.0

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/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);
         });
@@ -854,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) {
@@ -932,7 +964,7 @@ 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.#reconcileBlobs(false, blobId);
         this.#enforceBlobCacheCap();
         const stored = getCachedBlob(this.#db, blobId);
         if (stored === undefined) {
@@ -957,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);
@@ -3079,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.17.0",
+  "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.17.0"
+    "@syncular/core": "0.18.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.17.0"
+    "@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/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);
     });
@@ -1455,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(
@@ -1556,7 +1597,7 @@ 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.#reconcileBlobs(false, blobId);
     this.#enforceBlobCacheCap();
     const stored = getCachedBlob(this.#db, blobId);
     if (stored === undefined) {
@@ -1585,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,
@@ -4223,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 -----------------------------------------------------------------