@syncular/client 0.17.0 → 0.19.0

package/README.md

@@ -375,7 +375,7 @@ lifecycle with an `EncryptionConfig`; Worker handles use the portable keyring.
 Within one local SQLite transaction the engine deletes exactly the matching
 synced rows, lets generated FTS triggers remove their projections, drops every
 whole pending commit with a matching operation, restores/replays unrelated
-optimistic state, reconciles blob references, persists the `purgeId`, and emits
+optimistic state, removes unreferenced cached blob bodies, persists the `purgeId`, and emits
 one revisioned change batch. A retry with the same canonical plan returns
 `alreadyApplied: true`; reusing an id with different selectors fails closed.
 Only bounded, non-empty, code-like values on plaintext string schema columns
@@ -484,9 +484,8 @@ and are cached locally. **Blob bytes live as `BLOB` columns in the client's own
 SQLite database** (a `_syncular_blobs` cache table), not in a separate OPFS
 directory or IndexedDB store. This is the pinned decision (SPEC §5.9.7 B1):
 
-- **One storage system.** The bytes are transactional with the refcount rows
-  that pin them — a refcount adjust and a body insert/delete commit atomically,
-  so a crash never strands a body against a stale count.
+- **One storage system.** The bytes, upload state, and pending-commit references
+  share the client database. SQLite commits each change atomically.
 - **Survives restarts for free.** The client DB already rides OPFS via the
   sahpool VFS in the browser (and a plain file under `rusqlite`, `bun:sqlite`,
   or `node:sqlite` on native runtimes), so there is no second persistence
@@ -495,25 +494,24 @@ directory or IndexedDB store. This is the pinned decision (SPEC §5.9.7 B1):
 - **SQLite handles multi-MB images fine.** A page-cached `BLOB` read is a memory
   copy, well within the image/document envelope this targets.
 
-### Size cap + LRU eviction
+### Size cap
 
 Pass `blobCacheMaxBytes` to cap the on-device cache. When the sum of cached body
-sizes exceeds the cap, the client evicts **zero-ref, non-pinned** bodies in
-least-recently-used order until back under the cap:
+sizes exceeds the cap, the client evicts bodies with no visible row or pending
+commit by creation timestamp, then blob ID, until back under the cap:
 
 ```ts
 new SyncClient({ /* … */, blobCacheMaxBytes: 256 * 1024 * 1024 }); // 256 MiB
 ```
 
-- A body **referenced by a live row** (refcount > 0) is **never** evicted — it
+- A body **referenced by a live row** is **never** evicted. It
   stays resolvable without a re-download.
-- A body **pinned by a pending upload** (not yet pushed) is never evicted — its
+- A body **needed by a pending upload** (not yet pushed) is never evicted. Its
   bytes are the only copy until the commit drains.
-- Evicting a zero-ref body only costs a future re-download, never correctness:
+- Evicting an unreferenced body only costs a future re-download, never correctness:
   any surviving `blob_ref` value re-enables the fetch (§5.9.7 B3). If every
   over-cap body is referenced or pinned, the cache stays over the cap
-  (correctness beats the cap). A cache-hit read touches "recently used", so a
-  hot image survives a trim. Absent `blobCacheMaxBytes` ⇒ retain until storage
+  (correctness beats the cap). Absent `blobCacheMaxBytes` ⇒ retain until storage
   pressure (the default).
 
 ### Very large media — the escape hatch
@@ -522,7 +520,7 @@ SQLite is **not** the store for gigabyte video: a single `BLOB` must fit the
 client's memory and the SQLite row-size envelope. For very large media, run the
 server with presigned downloads (`blobSignedUrls`) and hand the presigned URL
 straight to a media element instead of pulling bytes through the cache — the
-image-app default (refcounted `BLOB` cache) and the large-media path (presigned
+image-app default (`BLOB` cache) and the large-media path (presigned
 URL, no byte cache) coexist per attachment.
 
 ## Node and Bun SQLite backend (`./sqlite`)

package/dist/blob.d.ts

@@ -1,14 +1,9 @@
 /**
  * Client-side blob cache + transport (SPEC.md §5.9.7).
  *
- * Blob bytes are cached content-addressed by `blobId` and refcounted by the
- * local rows whose `blob_ref` columns reference them (B1). The cache is
- * derived from live-row references: after any apply/purge, refcounts are
- * reconciled from the current `blob_ref` column contents, and a body whose
- * only referencing rows were revocation-purged is deleted (B2, evicted ≠
- * revoked). BlobRefs stay resolvable at any time (B3): the `blobId` in the
- * row value is the whole download key. Pending uploads are tracked in the
- * outbox-adjacent uploads table (B4) and flushed before push.
+ * Blob bytes are cached by `blobId`. Retention reads live references directly
+ * from `blob_ref` columns and keeps explicit pending-commit dependencies.
+ * A small upload row queues each staged body for transfer before push.
  */
 import { type BlobRef, parseBlobRef, serializeBlobRef } from '@syncular/core';
 import type { ClientDatabase } from './database.js';
@@ -82,46 +77,26 @@ export interface CachedBlob {
 /** `"sha256:" + hex` of the bytes — the content address (§5.9.1). */
 export declare function computeBlobId(bytes: Uint8Array): Promise<string>;
 export declare function ensureBlobSchema(db: ClientDatabase): void;
-/** Put bytes into the content-addressed cache (idempotent); touches LRU. */
+/** Put bytes into the content-addressed cache without rewriting an existing body. */
 export declare function putCachedBlob(db: ClientDatabase, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): void;
-export declare function getCachedBlob(db: ClientDatabase, blobId: string, nowMs?: number): CachedBlob | undefined;
+export declare function getCachedBlob(db: ClientDatabase, blobId: string): CachedBlob | undefined;
 /**
- * §5.9.7 B1 size cap + LRU eviction. When the sum of cached body sizes exceeds
- * `maxBytes`, evict **zero-ref, non-pinned** bodies in least-recently-used
- * order until back under the cap. NEVER evicts a referenced body (refcount > 0
- * — it must stay resolvable without a re-download) nor a pending-upload-pinned
- * body (its bytes are the only copy until push, B4). If every over-cap body is
- * referenced or pinned, the cache stays over the cap (correctness beats the
- * cap). Evicting a zero-ref body is always safe: B3 re-enables the fetch from
- * any surviving `blob_ref` value. Returns the evicted blobIds.
+ * §5.9.7 B1 size cap. When the sum of cached body sizes exceeds `maxBytes`,
+ * evict unreferenced, non-pinned bodies by creation timestamp, then blob ID,
+ * until back under the cap. Returns the evicted blobIds.
  */
-export declare function enforceBlobCacheCap(db: ClientDatabase, maxBytes: number): string[];
-/** Record a pending upload (§5.9.7 B4); flushed before the next push. */
-export declare function recordPendingUpload(db: ClientDatabase, blobId: string, nowMs: number, mediaType?: string): void;
+export declare function enforceBlobCacheCap(db: ClientDatabase, schema: CompiledClientSchema, maxBytes: number): string[];
 export declare function listPendingUploads(db: ClientDatabase): {
     blobId: string;
     mediaType?: string;
 }[];
+export declare function recordPendingUpload(db: ClientDatabase, blobId: string, nowMs: number, mediaType?: string): void;
 export declare function clearPendingUpload(db: ClientDatabase, blobId: string): void;
 /**
- * All `blob_ref` column names per table (for refcount reconciliation).
- * Blank result ⇒ the schema has no attachments; callers skip reconciliation.
+ * All `blob_ref` column names per table.
  */
 export declare function blobRefColumnsBySchema(schema: CompiledClientSchema): Map<string, string[]>;
 export declare function schemaHasBlobs(schema: CompiledClientSchema): boolean;
-/**
- * §5.9.7 B1/B2: recompute cache refcounts from the current `blob_ref` column
- * contents across all synced tables, then delete cache bodies that dropped
- * 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.
- *
- * `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 deleteOrphans?: boolean;
-}): void;
+export declare function deleteUnreferencedCachedBlobs(db: ClientDatabase, schema: CompiledClientSchema): void;
 export type { BlobRef };
 export { parseBlobRef, serializeBlobRef };

package/dist/blob.js

@@ -1,68 +1,65 @@
 /**
  * Client-side blob cache + transport (SPEC.md §5.9.7).
  *
- * Blob bytes are cached content-addressed by `blobId` and refcounted by the
- * local rows whose `blob_ref` columns reference them (B1). The cache is
- * derived from live-row references: after any apply/purge, refcounts are
- * reconciled from the current `blob_ref` column contents, and a body whose
- * only referencing rows were revocation-purged is deleted (B2, evicted ≠
- * revoked). BlobRefs stay resolvable at any time (B3): the `blobId` in the
- * row value is the whole download key. Pending uploads are tracked in the
- * outbox-adjacent uploads table (B4) and flushed before push.
+ * Blob bytes are cached by `blobId`. Retention reads live references directly
+ * from `blob_ref` columns and keeps explicit pending-commit dependencies.
+ * A small upload row queues each staged body for transfer 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('');
     return `sha256:${hex}`;
 }
 export function ensureBlobSchema(db) {
-    db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blobs(
-    blob_id TEXT PRIMARY KEY,
-    bytes BLOB NOT NULL,
-    byte_length INTEGER NOT NULL,
-    media_type TEXT,
-    refcount INTEGER NOT NULL DEFAULT 0,
-    created_at_ms INTEGER NOT NULL,
-    last_used_ms INTEGER NOT NULL DEFAULT 0)`);
-    // Migrate a cache created before the §5.9.7 B1 LRU column: additive,
-    // idempotent (a duplicate-column error on an already-migrated DB is
-    // swallowed). last_used_ms drives cap eviction (LRU of zero-ref bodies).
-    try {
-        db.exec('ALTER TABLE _syncular_blobs ADD COLUMN last_used_ms INTEGER NOT NULL DEFAULT 0');
+    const existing = db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_syncular_blobs'");
+    if (existing.length > 0) {
+        const columns = db
+            .query('PRAGMA table_info(_syncular_blobs)')
+            .map((row) => row.name)
+            .sort();
+        const expected = [
+            'blob_id',
+            'byte_length',
+            'bytes',
+            'created_at_ms',
+            'media_type',
+        ].sort();
+        if (columns.length !== expected.length ||
+            columns.some((column, index) => column !== expected[index])) {
+            throw new ClientSyncError('sync.schema_mismatch', 'Local blob schema is incompatible');
+        }
     }
-    catch {
-        // column already exists — the CREATE above included it
+    else {
+        db.exec(`CREATE TABLE _syncular_blobs(
+      blob_id TEXT PRIMARY KEY,
+      bytes BLOB NOT NULL,
+      byte_length INTEGER NOT NULL,
+      media_type TEXT,
+      created_at_ms INTEGER NOT NULL)`);
     }
     db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
-    blob_id TEXT PRIMARY KEY,
-    media_type TEXT,
-    created_at_ms INTEGER NOT NULL)`);
+    blob_id TEXT PRIMARY KEY, media_type TEXT, created_at_ms INTEGER NOT NULL)`);
 }
-/** Put bytes into the content-addressed cache (idempotent); touches LRU. */
+/** Put bytes into the content-addressed cache without rewriting an existing body. */
 export function putCachedBlob(db, blobId, bytes, nowMs, mediaType) {
     db.exec(`INSERT INTO _syncular_blobs(
-       blob_id, bytes, byte_length, media_type, refcount, created_at_ms, last_used_ms)
-     VALUES (?,?,?,?,0,?,?)
-     ON CONFLICT(blob_id) DO UPDATE SET last_used_ms = excluded.last_used_ms`, [blobId, bytes, bytes.length, mediaType ?? null, nowMs, nowMs]);
+       blob_id, bytes, byte_length, media_type, created_at_ms)
+     VALUES (?,?,?,?,?) ON CONFLICT(blob_id) DO NOTHING`, [blobId, bytes, bytes.length, mediaType ?? null, nowMs]);
 }
-export function getCachedBlob(db, blobId, nowMs) {
+export function getCachedBlob(db, blobId) {
     const rows = db.query('SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?', [blobId]);
     const row = rows[0];
     if (row === undefined)
         return undefined;
-    // §5.9.7 B1 LRU: a cache-hit read touches "recently used" so a hot image
-    // survives a cap trim. Skipped when no clock is supplied (pure read).
-    if (nowMs !== undefined) {
-        db.exec('UPDATE _syncular_blobs SET last_used_ms = ? WHERE blob_id = ?', [
-            nowMs,
-            blobId,
-        ]);
-    }
     return {
         blobId,
         bytes: row.bytes,
@@ -71,26 +68,21 @@ export function getCachedBlob(db, blobId, nowMs) {
     };
 }
 /**
- * §5.9.7 B1 size cap + LRU eviction. When the sum of cached body sizes exceeds
- * `maxBytes`, evict **zero-ref, non-pinned** bodies in least-recently-used
- * order until back under the cap. NEVER evicts a referenced body (refcount > 0
- * — it must stay resolvable without a re-download) nor a pending-upload-pinned
- * body (its bytes are the only copy until push, B4). If every over-cap body is
- * referenced or pinned, the cache stays over the cap (correctness beats the
- * cap). Evicting a zero-ref body is always safe: B3 re-enables the fetch from
- * any surviving `blob_ref` value. Returns the evicted blobIds.
+ * §5.9.7 B1 size cap. When the sum of cached body sizes exceeds `maxBytes`,
+ * evict unreferenced, non-pinned bodies by creation timestamp, then blob ID,
+ * until back under the cap. Returns the evicted blobIds.
  */
-export function enforceBlobCacheCap(db, maxBytes) {
+export function enforceBlobCacheCap(db, schema, maxBytes) {
     const totalRow = db.query('SELECT COALESCE(SUM(byte_length), 0) AS total FROM _syncular_blobs')[0];
     let total = Number(totalRow?.total ?? 0);
     if (total <= maxBytes)
         return [];
-    // Eviction candidates: zero-ref AND not pinned by a pending upload, oldest
-    // (LRU) first, then oldest created as a stable tiebreak.
+    // Oldest eligible body first, with blob ID as a stable tie.
     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)
-     ORDER BY last_used_ms ASC, created_at_ms ASC`);
+     WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+       AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
+       AND blob_id NOT IN (${visibleBlobIdsSql(schema)})
+     ORDER BY created_at_ms ASC, blob_id ASC`);
     const evicted = [];
     db.transaction(() => {
         for (const row of candidates) {
@@ -104,27 +96,35 @@ export function enforceBlobCacheCap(db, maxBytes) {
     });
     return evicted;
 }
-/** Record a pending upload (§5.9.7 B4); flushed before the next push. */
+export function listPendingUploads(db) {
+    return db
+        .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 recordPendingUpload(db, blobId, nowMs, mediaType) {
     db.exec(`INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms)
      VALUES (?,?,?)`, [blobId, mediaType ?? null, nowMs]);
 }
-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 }
-            : {}),
-    }));
-}
 export function clearPendingUpload(db, blobId) {
     db.exec('DELETE FROM _syncular_blob_uploads WHERE blob_id = ?', [blobId]);
 }
 /**
- * All `blob_ref` column names per table (for refcount reconciliation).
- * Blank result ⇒ the schema has no attachments; callers skip reconciliation.
+ * All `blob_ref` column names per table.
  */
 export function blobRefColumnsBySchema(schema) {
     const out = new Map();
@@ -144,58 +144,26 @@ export function schemaHasBlobs(schema) {
     }
     return false;
 }
-/**
- * §5.9.7 B1/B2: recompute cache refcounts from the current `blob_ref` column
- * contents across all synced tables, then delete cache bodies that dropped
- * 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.
- *
- * `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 function reconcileBlobRefcounts(db, schema, options) {
-    const byTable = blobRefColumnsBySchema(schema);
-    if (byTable.size === 0)
-        return;
-    // Count references to each blobId across every blob_ref column.
-    const counts = new Map();
-    for (const [tableName, columns] of byTable) {
+function visibleBlobIdsSql(schema) {
+    const selects = [];
+    for (const [tableName, columns] of blobRefColumnsBySchema(schema)) {
         for (const column of columns) {
-            const rows = db.query(`SELECT ${quoteIdent(column)} AS v FROM ${quoteIdent(tableName)}
-         WHERE ${quoteIdent(column)} IS NOT NULL`);
-            for (const row of rows) {
-                const raw = row.v;
-                if (typeof raw !== 'string')
-                    continue;
-                let ref;
-                try {
-                    ref = parseBlobRef(raw);
-                }
-                catch {
-                    continue;
-                }
-                counts.set(ref.blobId, (counts.get(ref.blobId) ?? 0) + 1);
-            }
+            const identifier = quoteIdent(column);
+            selects.push(`SELECT json_extract(${identifier}, '$.blobId') AS blob_id
+         FROM ${quoteIdent(tableName)}
+         WHERE typeof(${identifier}) = 'text'
+           AND json_valid(${identifier})
+           AND json_type(${identifier}, '$.blobId') = 'text'`);
         }
     }
-    db.transaction(() => {
-        // Reset all refcounts, then apply the recomputed counts.
-        db.exec('UPDATE _syncular_blobs SET refcount = 0');
-        for (const [blobId, count] of counts) {
-            db.exec('UPDATE _syncular_blobs SET refcount = ? WHERE blob_id = ?', [
-                count,
-                blobId,
-            ]);
-        }
-        if (options?.deleteOrphans === true) {
-            // §5.9.7 B2 revocation side: delete zero-ref bodies not pinned by a
-            // pending upload.
-            db.exec(`DELETE FROM _syncular_blobs
-         WHERE refcount = 0
-           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)`);
-        }
-    });
+    return selects.length === 0
+        ? 'SELECT NULL AS blob_id WHERE 0'
+        : selects.join(' UNION ');
+}
+export function deleteUnreferencedCachedBlobs(db, schema) {
+    db.exec(`DELETE FROM _syncular_blobs
+     WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+       AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
+       AND blob_id NOT IN (${visibleBlobIdsSql(schema)})`);
 }
 export { parseBlobRef, serializeBlobRef };

package/dist/client.d.ts

@@ -110,9 +110,9 @@ export interface SyncClientConfig {
     readonly blobs?: BlobTransport;
     /**
      * §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
-     * exceeds this, zero-ref, non-pinned bodies are evicted LRU-first after each
-     * cache write (referenced/pinned bodies are never evicted — correctness
-     * beats the cap). Absent ⇒ retain until storage pressure (the shipped
+     * exceeds this, unreferenced bodies without pending work are evicted in
+     * creation timestamp order after each cache write. Referenced bodies remain cached
+     * even when that exceeds the cap. Absent means retain until storage pressure (the shipped
      * default; a referenced body always stays resolvable without a re-download).
      */
     readonly blobCacheMaxBytes?: number;

package/dist/client.js

@@ -9,7 +9,7 @@
  */
 import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encodeMessage, encodePresencePublish, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
 import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, upsertLocalRow, } from './apply.js';
-import { clearPendingUpload, computeBlobId, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, reconcileBlobRefcounts, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
+import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
 import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, } from './diagnostics.js';
 import { ClientSyncError } from './errors.js';
@@ -854,20 +854,19 @@ 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) {
             throw new ClientSyncError('sync.invalid_request', 'uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
         }
         const blobId = await computeBlobId(bytes);
+        const nowMs = this.#now();
         this.#db.transaction(() => {
-            putCachedBlob(this.#db, blobId, bytes, this.#now(), options?.mediaType);
-            recordPendingUpload(this.#db, blobId, this.#now(), options?.mediaType);
+            putCachedBlob(this.#db, blobId, bytes, nowMs, options?.mediaType);
+            recordPendingUpload(this.#db, blobId, nowMs, options?.mediaType);
         });
-        // §5.9.7 B1: a staged upload is pinned (recordPendingUpload), so the cap
-        // trim below will never evict it — but a stage may push other zero-ref
-        // bodies over the cap, so run the trim.
         this.#enforceBlobCacheCap();
         return {
             blobId,
@@ -895,7 +894,7 @@ export class SyncClient {
         const blobId = blobIdOrRef.startsWith('sha256:')
             ? blobIdOrRef
             : parseBlobRef(blobIdOrRef).blobId;
-        const cached = getCachedBlob(this.#db, blobId, this.#now());
+        const cached = getCachedBlob(this.#db, blobId);
         if (cached !== undefined)
             return cached;
         const transport = this.#config.blobs;
@@ -930,9 +929,7 @@ 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.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
         this.#enforceBlobCacheCap();
         const stored = getCachedBlob(this.#db, blobId);
         if (stored === undefined) {
@@ -945,7 +942,7 @@ export class SyncClient {
         const cap = this.#config.blobCacheMaxBytes;
         if (cap === undefined)
             return;
-        enforceBlobCacheCap(this.#db, cap);
+        enforceBlobCacheCap(this.#db, this.#schema, cap);
     }
     /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
     flushBlobUploads() {
@@ -957,11 +954,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);
@@ -1413,6 +1411,31 @@ export class SyncClient {
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
                 appendOutboxCommit(this.#db, clientCommitId, operations, this.#now(), this.#captureBeforeImages(operations));
+                for (const operation of operations) {
+                    if (operation.op !== 'upsert')
+                        continue;
+                    const table = this.#schema.tables.get(operation.table);
+                    if (table === undefined)
+                        continue;
+                    for (const column of table.columns) {
+                        if (column.type !== 'blob_ref')
+                            continue;
+                        const raw = operation.values?.[column.name];
+                        if (typeof raw !== 'string')
+                            continue;
+                        let blobId;
+                        try {
+                            blobId = parseBlobRef(raw).blobId;
+                        }
+                        catch {
+                            continue;
+                        }
+                        this.#db.exec(`INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
+               SELECT ?, ? WHERE EXISTS (
+                 SELECT 1 FROM _syncular_blobs WHERE blob_id = ?
+               )`, [clientCommitId, blobId, blobId]);
+                    }
+                }
                 this.#applyOperationsLocally(operations, batch);
                 batch.status();
             });
@@ -1571,7 +1594,7 @@ export class SyncClient {
                     batch.rejections();
                     batch.outcomes();
                 }
-                this.#reconcileBlobs(true);
+                this.#deleteUnreferencedBlobs();
                 setMeta(this.#db, metaKey, purge.canonicalPlan);
                 return {
                     alreadyApplied: false,
@@ -2513,7 +2536,6 @@ export class SyncClient {
                 // §7.1: local reads see outbox state applied optimistically — replay
                 // the still-pending commits on top of the freshly applied server state.
                 this.#replayOutbox();
-                this.#reconcileBlobs(false);
             }
             finally {
                 this.#endDiagnosticsDeferral();
@@ -2902,7 +2924,7 @@ export class SyncClient {
                         batch.rejections();
                         batch.outcomes();
                     }
-                    this.#reconcileBlobs(true);
+                    this.#deleteUnreferencedBlobs();
                 }
                 catch (error) {
                     if (error instanceof ClientSyncError &&
@@ -3074,15 +3096,10 @@ export class SyncClient {
             });
         });
     }
-    /**
-     * §5.9.7 B1/B2: recompute blob-cache refcounts from live `blob_ref`
-     * columns. No-op unless the schema has blob columns. `deleteOrphans`
-     * triggers the revocation-side body deletion (B2).
-     */
-    #reconcileBlobs(deleteOrphans) {
+    #deleteUnreferencedBlobs() {
         if (!this.#hasBlobs)
             return;
-        reconcileBlobRefcounts(this.#db, this.#schema, { deleteOrphans });
+        deleteUnreferencedCachedBlobs(this.#db, this.#schema);
     }
     // -- helpers -----------------------------------------------------------------
     #table(name) {

package/dist/outbox.js

@@ -62,6 +62,9 @@ export function countOutbox(db) {
         .count;
 }
 export function deleteOutboxCommit(db, clientCommitId) {
+    db.exec('DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?', [
+        clientCommitId,
+    ]);
     db.exec('DELETE FROM _syncular_outbox_before_images WHERE client_commit_id = ?', [clientCommitId]);
     db.exec('DELETE FROM _syncular_outbox WHERE client_commit_id = ?', [
         clientCommitId,

package/dist/schema.js

@@ -339,6 +339,9 @@ export function ensureLocalBookkeepingSchema(db) {
     db.transaction(() => {
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT 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)');
         db.exec(`INSERT OR IGNORE INTO _syncular_meta(key, value) VALUES ('localRevision', '0')`);
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_outbox(
       seq INTEGER PRIMARY KEY AUTOINCREMENT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.17.0",
+  "version": "0.19.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.19.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.17.0"
+    "@syncular/server": "0.19.0"
   }
 }

package/src/blob.ts

@@ -1,17 +1,13 @@
 /**
  * Client-side blob cache + transport (SPEC.md §5.9.7).
  *
- * Blob bytes are cached content-addressed by `blobId` and refcounted by the
- * local rows whose `blob_ref` columns reference them (B1). The cache is
- * derived from live-row references: after any apply/purge, refcounts are
- * reconciled from the current `blob_ref` column contents, and a body whose
- * only referencing rows were revocation-purged is deleted (B2, evicted ≠
- * revoked). BlobRefs stay resolvable at any time (B3): the `blobId` in the
- * row value is the whole download key. Pending uploads are tracked in the
- * outbox-adjacent uploads table (B4) and flushed before push.
+ * Blob bytes are cached by `blobId`. Retention reads live references directly
+ * from `blob_ref` columns and keeps explicit pending-commit dependencies.
+ * A small upload row queues each staged body for transfer before push.
  */
 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 +89,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'))
@@ -104,31 +104,43 @@ export async function computeBlobId(bytes: Uint8Array): Promise<string> {
 }
 
 export function ensureBlobSchema(db: ClientDatabase): void {
-  db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blobs(
-    blob_id TEXT PRIMARY KEY,
-    bytes BLOB NOT NULL,
-    byte_length INTEGER NOT NULL,
-    media_type TEXT,
-    refcount INTEGER NOT NULL DEFAULT 0,
-    created_at_ms INTEGER NOT NULL,
-    last_used_ms INTEGER NOT NULL DEFAULT 0)`);
-  // Migrate a cache created before the §5.9.7 B1 LRU column: additive,
-  // idempotent (a duplicate-column error on an already-migrated DB is
-  // swallowed). last_used_ms drives cap eviction (LRU of zero-ref bodies).
-  try {
-    db.exec(
-      'ALTER TABLE _syncular_blobs ADD COLUMN last_used_ms INTEGER NOT NULL DEFAULT 0',
-    );
-  } catch {
-    // column already exists — the CREATE above included it
+  const existing = db.query(
+    "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_syncular_blobs'",
+  );
+  if (existing.length > 0) {
+    const columns = db
+      .query('PRAGMA table_info(_syncular_blobs)')
+      .map((row) => row.name)
+      .sort();
+    const expected = [
+      'blob_id',
+      'byte_length',
+      'bytes',
+      'created_at_ms',
+      'media_type',
+    ].sort();
+    if (
+      columns.length !== expected.length ||
+      columns.some((column, index) => column !== expected[index])
+    ) {
+      throw new ClientSyncError(
+        'sync.schema_mismatch',
+        'Local blob schema is incompatible',
+      );
+    }
+  } else {
+    db.exec(`CREATE TABLE _syncular_blobs(
+      blob_id TEXT PRIMARY KEY,
+      bytes BLOB NOT NULL,
+      byte_length INTEGER NOT NULL,
+      media_type TEXT,
+      created_at_ms INTEGER NOT NULL)`);
   }
   db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
-    blob_id TEXT PRIMARY KEY,
-    media_type TEXT,
-    created_at_ms INTEGER NOT NULL)`);
+    blob_id TEXT PRIMARY KEY, media_type TEXT, created_at_ms INTEGER NOT NULL)`);
 }
 
-/** Put bytes into the content-addressed cache (idempotent); touches LRU. */
+/** Put bytes into the content-addressed cache without rewriting an existing body. */
 export function putCachedBlob(
   db: ClientDatabase,
   blobId: string,
@@ -138,17 +150,15 @@ export function putCachedBlob(
 ): void {
   db.exec(
     `INSERT INTO _syncular_blobs(
-       blob_id, bytes, byte_length, media_type, refcount, created_at_ms, last_used_ms)
-     VALUES (?,?,?,?,0,?,?)
-     ON CONFLICT(blob_id) DO UPDATE SET last_used_ms = excluded.last_used_ms`,
-    [blobId, bytes, bytes.length, mediaType ?? null, nowMs, nowMs],
+       blob_id, bytes, byte_length, media_type, created_at_ms)
+     VALUES (?,?,?,?,?) ON CONFLICT(blob_id) DO NOTHING`,
+    [blobId, bytes, bytes.length, mediaType ?? null, nowMs],
   );
 }
 
 export function getCachedBlob(
   db: ClientDatabase,
   blobId: string,
-  nowMs?: number,
 ): CachedBlob | undefined {
   const rows = db.query(
     'SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?',
@@ -156,14 +166,6 @@ export function getCachedBlob(
   );
   const row = rows[0];
   if (row === undefined) return undefined;
-  // §5.9.7 B1 LRU: a cache-hit read touches "recently used" so a hot image
-  // survives a cap trim. Skipped when no clock is supplied (pure read).
-  if (nowMs !== undefined) {
-    db.exec('UPDATE _syncular_blobs SET last_used_ms = ? WHERE blob_id = ?', [
-      nowMs,
-      blobId,
-    ]);
-  }
   return {
     blobId,
     bytes: row.bytes as Uint8Array,
@@ -173,17 +175,13 @@ export function getCachedBlob(
 }
 
 /**
- * §5.9.7 B1 size cap + LRU eviction. When the sum of cached body sizes exceeds
- * `maxBytes`, evict **zero-ref, non-pinned** bodies in least-recently-used
- * order until back under the cap. NEVER evicts a referenced body (refcount > 0
- * — it must stay resolvable without a re-download) nor a pending-upload-pinned
- * body (its bytes are the only copy until push, B4). If every over-cap body is
- * referenced or pinned, the cache stays over the cap (correctness beats the
- * cap). Evicting a zero-ref body is always safe: B3 re-enables the fetch from
- * any surviving `blob_ref` value. Returns the evicted blobIds.
+ * §5.9.7 B1 size cap. When the sum of cached body sizes exceeds `maxBytes`,
+ * evict unreferenced, non-pinned bodies by creation timestamp, then blob ID,
+ * until back under the cap. Returns the evicted blobIds.
  */
 export function enforceBlobCacheCap(
   db: ClientDatabase,
+  schema: CompiledClientSchema,
   maxBytes: number,
 ): string[] {
   const totalRow = db.query(
@@ -191,13 +189,13 @@ export function enforceBlobCacheCap(
   )[0];
   let total = Number(totalRow?.total ?? 0);
   if (total <= maxBytes) return [];
-  // Eviction candidates: zero-ref AND not pinned by a pending upload, oldest
-  // (LRU) first, then oldest created as a stable tiebreak.
+  // Oldest eligible body first, with blob ID as a stable tie.
   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)
-     ORDER BY last_used_ms ASC, created_at_ms ASC`,
+     WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+       AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
+       AND blob_id NOT IN (${visibleBlobIdsSql(schema)})
+     ORDER BY created_at_ms ASC, blob_id ASC`,
   );
   const evicted: string[] = [];
   db.transaction(() => {
@@ -212,7 +210,36 @@ export function enforceBlobCacheCap(
   return evicted;
 }
 
-/** Record a pending upload (§5.9.7 B4); flushed before the next push. */
+export function listPendingUploads(
+  db: ClientDatabase,
+): { blobId: string; mediaType?: string }[] {
+  return db
+    .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 recordPendingUpload(
   db: ClientDatabase,
   blobId: string,
@@ -226,28 +253,12 @@ export function recordPendingUpload(
   );
 }
 
-export function listPendingUploads(
-  db: ClientDatabase,
-): { blobId: string; mediaType?: string }[] {
-  return db
-    .query(
-      'SELECT blob_id, media_type FROM _syncular_blob_uploads ORDER BY created_at_ms',
-    )
-    .map((row) => ({
-      blobId: row.blob_id as string,
-      ...(row.media_type !== null
-        ? { mediaType: row.media_type as string }
-        : {}),
-    }));
-}
-
 export function clearPendingUpload(db: ClientDatabase, blobId: string): void {
   db.exec('DELETE FROM _syncular_blob_uploads WHERE blob_id = ?', [blobId]);
 }
 
 /**
- * All `blob_ref` column names per table (for refcount reconciliation).
- * Blank result ⇒ the schema has no attachments; callers skip reconciliation.
+ * All `blob_ref` column names per table.
  */
 export function blobRefColumnsBySchema(
   schema: CompiledClientSchema,
@@ -269,64 +280,35 @@ export function schemaHasBlobs(schema: CompiledClientSchema): boolean {
   return false;
 }
 
-/**
- * §5.9.7 B1/B2: recompute cache refcounts from the current `blob_ref` column
- * contents across all synced tables, then delete cache bodies that dropped
- * 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.
- *
- * `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 function reconcileBlobRefcounts(
-  db: ClientDatabase,
-  schema: CompiledClientSchema,
-  options?: { readonly deleteOrphans?: boolean },
-): void {
-  const byTable = blobRefColumnsBySchema(schema);
-  if (byTable.size === 0) return;
-  // Count references to each blobId across every blob_ref column.
-  const counts = new Map<string, number>();
-  for (const [tableName, columns] of byTable) {
+function visibleBlobIdsSql(schema: CompiledClientSchema): string {
+  const selects: string[] = [];
+  for (const [tableName, columns] of blobRefColumnsBySchema(schema)) {
     for (const column of columns) {
-      const rows = db.query(
-        `SELECT ${quoteIdent(column)} AS v FROM ${quoteIdent(tableName)}
-         WHERE ${quoteIdent(column)} IS NOT NULL`,
+      const identifier = quoteIdent(column);
+      selects.push(
+        `SELECT json_extract(${identifier}, '$.blobId') AS blob_id
+         FROM ${quoteIdent(tableName)}
+         WHERE typeof(${identifier}) = 'text'
+           AND json_valid(${identifier})
+           AND json_type(${identifier}, '$.blobId') = 'text'`,
       );
-      for (const row of rows) {
-        const raw = row.v;
-        if (typeof raw !== 'string') continue;
-        let ref: BlobRef;
-        try {
-          ref = parseBlobRef(raw);
-        } catch {
-          continue;
-        }
-        counts.set(ref.blobId, (counts.get(ref.blobId) ?? 0) + 1);
-      }
     }
   }
-  db.transaction(() => {
-    // Reset all refcounts, then apply the recomputed counts.
-    db.exec('UPDATE _syncular_blobs SET refcount = 0');
-    for (const [blobId, count] of counts) {
-      db.exec('UPDATE _syncular_blobs SET refcount = ? WHERE blob_id = ?', [
-        count,
-        blobId,
-      ]);
-    }
-    if (options?.deleteOrphans === true) {
-      // §5.9.7 B2 revocation side: delete zero-ref bodies not pinned by a
-      // pending upload.
-      db.exec(
-        `DELETE FROM _syncular_blobs
-         WHERE refcount = 0
-           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)`,
-      );
-    }
-  });
+  return selects.length === 0
+    ? 'SELECT NULL AS blob_id WHERE 0'
+    : selects.join(' UNION ');
+}
+
+export function deleteUnreferencedCachedBlobs(
+  db: ClientDatabase,
+  schema: CompiledClientSchema,
+): void {
+  db.exec(
+    `DELETE FROM _syncular_blobs
+     WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+       AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
+       AND blob_id NOT IN (${visibleBlobIdsSql(schema)})`,
+  );
 }
 
 export type { BlobRef };

package/src/client.ts

@@ -47,13 +47,13 @@ import {
   type CachedBlob,
   clearPendingUpload,
   computeBlobId,
+  deleteUnreferencedCachedBlobs,
   enforceBlobCacheCap,
   ensureBlobSchema,
   getCachedBlob,
   listPendingUploads,
   parseBlobRef,
   putCachedBlob,
-  reconcileBlobRefcounts,
   recordPendingUpload,
   schemaHasBlobs,
   serializeBlobRef,
@@ -302,9 +302,9 @@ export interface SyncClientConfig {
   readonly blobs?: BlobTransport;
   /**
    * §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
-   * exceeds this, zero-ref, non-pinned bodies are evicted LRU-first after each
-   * cache write (referenced/pinned bodies are never evicted — correctness
-   * beats the cap). Absent ⇒ retain until storage pressure (the shipped
+   * exceeds this, unreferenced bodies without pending work are evicted in
+   * creation timestamp order after each cache write. Referenced bodies remain cached
+   * even when that exceeds the cap. Absent means retain until storage pressure (the shipped
    * default; a referenced body always stays resolvable without a re-download).
    */
   readonly blobCacheMaxBytes?: number;
@@ -1455,7 +1455,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(
@@ -1469,13 +1470,11 @@ export class SyncClient {
       );
     }
     const blobId = await computeBlobId(bytes);
+    const nowMs = this.#now();
     this.#db.transaction(() => {
-      putCachedBlob(this.#db, blobId, bytes, this.#now(), options?.mediaType);
-      recordPendingUpload(this.#db, blobId, this.#now(), options?.mediaType);
+      putCachedBlob(this.#db, blobId, bytes, nowMs, options?.mediaType);
+      recordPendingUpload(this.#db, blobId, nowMs, options?.mediaType);
     });
-    // §5.9.7 B1: a staged upload is pinned (recordPendingUpload), so the cap
-    // trim below will never evict it — but a stage may push other zero-ref
-    // bodies over the cap, so run the trim.
     this.#enforceBlobCacheCap();
     return {
       blobId,
@@ -1506,7 +1505,7 @@ export class SyncClient {
     const blobId = blobIdOrRef.startsWith('sha256:')
       ? blobIdOrRef
       : parseBlobRef(blobIdOrRef).blobId;
-    const cached = getCachedBlob(this.#db, blobId, this.#now());
+    const cached = getCachedBlob(this.#db, blobId);
     if (cached !== undefined) return cached;
     const transport = this.#config.blobs;
     if (transport === undefined) {
@@ -1554,9 +1553,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.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
     this.#enforceBlobCacheCap();
     const stored = getCachedBlob(this.#db, blobId);
     if (stored === undefined) {
@@ -1572,7 +1569,7 @@ export class SyncClient {
   #enforceBlobCacheCap(): void {
     const cap = this.#config.blobCacheMaxBytes;
     if (cap === undefined) return;
-    enforceBlobCacheCap(this.#db, cap);
+    enforceBlobCacheCap(this.#db, this.#schema, cap);
   }
 
   /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
@@ -1585,11 +1582,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,
@@ -2141,6 +2144,29 @@ export class SyncClient {
           this.#now(),
           this.#captureBeforeImages(operations),
         );
+        for (const operation of operations) {
+          if (operation.op !== 'upsert') continue;
+          const table = this.#schema.tables.get(operation.table);
+          if (table === undefined) continue;
+          for (const column of table.columns) {
+            if (column.type !== 'blob_ref') continue;
+            const raw = operation.values?.[column.name];
+            if (typeof raw !== 'string') continue;
+            let blobId: string;
+            try {
+              blobId = parseBlobRef(raw).blobId;
+            } catch {
+              continue;
+            }
+            this.#db.exec(
+              `INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
+               SELECT ?, ? WHERE EXISTS (
+                 SELECT 1 FROM _syncular_blobs WHERE blob_id = ?
+               )`,
+              [clientCommitId, blobId, blobId],
+            );
+          }
+        }
         this.#applyOperationsLocally(operations, batch);
         batch.status();
       });
@@ -2339,7 +2365,7 @@ export class SyncClient {
           batch.rejections();
           batch.outcomes();
         }
-        this.#reconcileBlobs(true);
+        this.#deleteUnreferencedBlobs();
         setMeta(this.#db, metaKey, purge.canonicalPlan);
         return {
           alreadyApplied: false,
@@ -3517,7 +3543,6 @@ export class SyncClient {
         // §7.1: local reads see outbox state applied optimistically — replay
         // the still-pending commits on top of the freshly applied server state.
         this.#replayOutbox();
-        this.#reconcileBlobs(false);
       } finally {
         this.#endDiagnosticsDeferral();
       }
@@ -4000,7 +4025,7 @@ export class SyncClient {
             batch.rejections();
             batch.outcomes();
           }
-          this.#reconcileBlobs(true);
+          this.#deleteUnreferencedBlobs();
         } catch (error) {
           if (
             error instanceof ClientSyncError &&
@@ -4218,14 +4243,9 @@ export class SyncClient {
     });
   }
 
-  /**
-   * §5.9.7 B1/B2: recompute blob-cache refcounts from live `blob_ref`
-   * columns. No-op unless the schema has blob columns. `deleteOrphans`
-   * triggers the revocation-side body deletion (B2).
-   */
-  #reconcileBlobs(deleteOrphans: boolean): void {
+  #deleteUnreferencedBlobs(): void {
     if (!this.#hasBlobs) return;
-    reconcileBlobRefcounts(this.#db, this.#schema, { deleteOrphans });
+    deleteUnreferencedCachedBlobs(this.#db, this.#schema);
   }
 
   // -- helpers -----------------------------------------------------------------

package/src/outbox.ts

@@ -135,6 +135,9 @@ export function deleteOutboxCommit(
   db: ClientDatabase,
   clientCommitId: string,
 ): void {
+  db.exec('DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?', [
+    clientCommitId,
+  ]);
   db.exec(
     'DELETE FROM _syncular_outbox_before_images WHERE client_commit_id = ?',
     [clientCommitId],

package/src/schema.ts

@@ -501,6 +501,11 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
   db.transaction(() => {
     db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT 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)',
+    );
     db.exec(
       `INSERT OR IGNORE INTO _syncular_meta(key, value) VALUES ('localRevision', '0')`,
     );