@syncular/client 0.18.0 → 0.20.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
@@ -457,10 +457,17 @@ still happen during rapid hot-module replacement, or in an embedded/test host
 that shares OPFS data without sharing the same Web Locks and BroadcastChannel
 coordination domain.
 
-Pool acquisition failures surface as `ClientSyncError` with code
-`client.storage_busy` and `retryable === true`. Treat that as a startup state:
-close the competing instance or let it finish shutting down, then create the
-handle again. **Do not delete, rename, or silently replace the database with an
+Persistent worker startup retries retryable `client.storage_busy` failures
+while retaining the leader lease. It opens the same directory at most seven
+times, waiting 50, 100, 200, 400, 800, and 1000 ms between attempts. These delays
+total 2550 ms; browser scheduling and storage operations can extend elapsed time.
+Other errors fail immediately. Direct `openPersistentWasmDatabase` calls remain
+single attempts.
+
+If ownership remains unavailable, handle creation rejects with `ClientSyncError`,
+code `client.storage_busy`, and `retryable === true`, then releases the worker
+and leader lease. Close the competing instance or let it finish shutting down,
+then create the handle again. **Do not delete, rename, or silently replace the database with an
 in-memory one**; the local database and pending outbox may be perfectly healthy.
 Missing or obsolete OPFS APIs instead use the non-retryable
 `client.storage_unavailable` code.
@@ -484,9 +491,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 +501,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 +527,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`)
@@ -586,8 +591,96 @@ they own their buffer.
 
 Tests drive the real worker entry in a bun `Worker` with bun:sqlite
 injected through the bootstrap's database-factory override
-(`test/worker-rpc.test.ts`); the OPFS path itself is browser-only and is
-exercised by `apps/demo`.
+(`test/worker-rpc.test.ts`). The separate Chromium gate exercises actual
+sqlite-wasm, OPFS SAH pools and FTS through the production worker and HTTP paths:
+
+```sh
+cd packages/web-client
+bunx --no-install playwright install chromium
+cd ../..
+bun run test:browser
+```
+
+`test/opfs-bootstrap.browser.test.ts` covers five interruption boundaries:
+
+- Partial segment download: hold the asynchronous transfer, then terminate the worker.
+- Before image import: inject an exception before applying the verified image.
+- Mid-import: terminate the worker after an actual OPFS database page write during
+  `INSERT SELECT`. A commit notification must not precede termination.
+- After import: inject an exception after the transaction commits, before `SUB_END`.
+- After checkpoint: complete the round before terminating the worker.
+
+Each case reloads the page using the same replica identity and requires successful
+startup in the same browser session. It checks SQLite and FTS integrity, search
+results, exact rows, persisted client identity, and subscription checkpoints.
+Incomplete sections must download again; completed sections must not. A held
+synchronous test request after a physical page write keeps the mid-import crash
+boundary stable until worker termination. Two additional ownership cases verify
+recovery when a competing owner closes during retry and bounded failure while
+that owner remains live, including pending outbox preservation.
+
+Each case owns a temporary browser profile and a loopback server. A small SQLite
+page cache forces dirty pages to disk before COMMIT. Tests use no timing sleeps,
+COOP/COEP requirement, existing profiles or application replicas. Failed profiles
+and `recovery-test.json` remain at the path printed by the test; CI retains them
+as an artifact. Successful profiles are removed. `bun run check` keeps its
+Bun-only test lane; CI runs the browser gate separately.
+
+`openPersistentWasmDatabase` corrects the SAH-pool VFS's reserved-lock callback
+before the first SQL statement. sqlite-wasm 3.53 reports a reserved lock
+unconditionally, suppressing SQLite's hot-journal recovery after an interrupted
+write. The pool already excludes other owners. Syncular reports no competing
+writer through SQLite's I/O method binding, matching the other OPFS VFS, and
+retains that callback across database closes and pool opens. The correction ships
+in the client package and preserves the existing database format, DELETE journal
+mode and FULL synchronous mode.
+
+On 2026-09-12, Chromium 153 with sqlite-wasm 3.53.0 failed the mid-import case
+without this correction and passed all five cases with it. The fixture serves
+the unmodified dependency. Bounded worker startup retries handle transient
+`client.storage_busy` while the browser releases old handles. This correction enables
+rollback from an intact hot journal; it does not repair existing corruption
+whose recovery journal has already been lost or overwritten.
+
+## Live sync progress
+
+`onProgress` observes work during a sync round. It immediately delivers the latest
+snapshot when one exists and returns an unsubscribe function. `progressSnapshot()`
+reads the cached snapshot synchronously, including on worker handles. Worker
+leaders and followers forward events while download and import are running.
+
+```ts
+const stop = client.onProgress((progress) => {
+  if (progress.phase === 'download') {
+    renderDownload(progress.bytesReceived, progress.bytesTotal);
+  } else if (progress.phase === 'import') {
+    renderImport(progress.rowsProcessed, progress.rowsTotal);
+  }
+  if (progress.state === 'failed') showError(progress.errorCode);
+});
+// Stop listening when the view is disposed. Sync continues.
+stop();
+```
+
+Each snapshot identifies the round with `attempt`, and the current payload with
+`subscriptionId`, `table`, and optional `segmentId`. Counters reset for each
+payload; `syncUntilIdle` starts a new attempt for each round. `phase` is `request`,
+`download`, or `import`; `state` is `running`, `complete`, or `failed`. Unknown
+totals remain absent. A new attempt clears prior errors and counters.
+
+HTTP downloads report decoded body bytes at 64 KiB intervals or larger network
+chunks. Custom segment downloaders receive `request.onProgress`; signed-URL
+implementations receive an optional second callback argument. Call it with the
+cumulative received byte count. Buffered custom transports report a final count
+through the core, without intermediate download updates.
+
+Import reports every 1,024 rows and its final count. `rowsProcessed` includes work
+inside the current transaction; a failed import can roll those rows back. SQLite
+images retain one atomic transaction. `complete` follows checkpoint persistence
+and optimistic-state reconciliation for the round. More bootstrap pages can
+remain; use subscription coverage to determine whether a query is complete.
+Listener exceptions do not fail sync. Listeners should hand UI work off and avoid
+reentering database commands during an import.
 
 ## Snapshot API migration
 

package/dist/apply.d.ts

@@ -68,6 +68,7 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
     readonly clearFirst: boolean;
     readonly effective: ScopeMap;
     readonly transaction?: ApplyTransaction;
+    readonly onProgress?: (rowsProcessed: number) => void;
 }): number;
 /**
  * Apply a decoded rows segment: each block in one local transaction
@@ -81,4 +82,5 @@ export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledCli
     readonly clearFirst: boolean;
     readonly effective: ScopeMap;
     readonly transaction?: ApplyTransaction;
+    readonly onProgress?: (rowsProcessed: number) => void;
 }, encryption?: EncryptionConfig): Promise<number>;

package/dist/apply.js

@@ -255,17 +255,38 @@ export function applySqliteSegment(db, schema, table, bytes, descriptor, options
             if (options.clearFirst) {
                 deleteScopedRows(db, table, options.effective);
             }
-            db.exec(`INSERT INTO ${quoteIdent(table.name)}
-           (${insertNames.join(', ')})
-         SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')}
-         FROM ${IMAGE_ALIAS}.${quoteIdent(table.name)}
-         WHERE true
-         ON CONFLICT (${quoteIdent(table.primaryKey)}) DO UPDATE SET ${updates}`);
-            const counted = db.query(`SELECT count(*) AS n FROM ${IMAGE_ALIAS}.${quoteIdent(table.name)}`)[0];
-            const applied = Number(counted?.n ?? 0);
+            const source = `${IMAGE_ALIAS}.${quoteIdent(table.name)}`;
+            const primaryKey = quoteIdent(table.primaryKey);
+            let after;
+            let applied = 0;
+            for (;;) {
+                const boundary = db.query(`SELECT ${primaryKey} AS boundary FROM ${source}
+           ${after === undefined ? '' : `WHERE ${primaryKey} > ?`}
+           ORDER BY ${primaryKey} LIMIT 1 OFFSET 1023`, after === undefined ? [] : [after])[0]?.boundary;
+                const predicates = [];
+                const params = [];
+                if (after !== undefined) {
+                    predicates.push(`${primaryKey} > ?`);
+                    params.push(after);
+                }
+                if (boundary !== undefined) {
+                    predicates.push(`${primaryKey} <= ?`);
+                    params.push(boundary);
+                }
+                db.exec(`INSERT INTO ${quoteIdent(table.name)} (${insertNames.join(', ')})
+           SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')}
+           FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}
+           ON CONFLICT (${primaryKey}) DO UPDATE SET ${updates}`, params);
+                applied += Number(db.query('SELECT changes() AS n')[0]?.n ?? 0);
+                if (boundary === undefined)
+                    break;
+                options.onProgress?.(applied);
+                after = boundary;
+            }
             if (applied !== descriptor.rowCount) {
                 imageInvalid(`image holds ${applied} rows, descriptor says ${descriptor.rowCount}`);
             }
+            options.onProgress?.(applied);
             return applied;
         });
     });
@@ -308,8 +329,11 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
             for (const row of rows) {
                 upsertLocalRow(db, table, row.values, row.serverVersion);
                 applied += 1;
+                if (applied % 1024 === 0)
+                    options.onProgress?.(applied);
             }
         });
     }
+    options.onProgress?.(applied);
     return applied;
 }

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,48 +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.
- *
- * `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 declare function deleteUnreferencedCachedBlobs(db: ClientDatabase, schema: CompiledClientSchema): void;
 export type { BlobRef };
 export { parseBlobRef, serializeBlobRef };

package/dist/blob.js

@@ -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 { parseBlobRef, serializeBlobRef } from '@syncular/core';
 import { ClientSyncError } from './errors.js';
@@ -25,51 +20,46 @@ export async function computeBlobId(bytes) {
     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)`);
-    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)');
+    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,
@@ -78,27 +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)
+     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)
-     ORDER BY last_used_ms ASC, created_at_ms ASC`);
+       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) {
@@ -112,11 +96,6 @@ export function enforceBlobCacheCap(db, maxBytes) {
     });
     return evicted;
 }
-/** Record a pending upload (§5.9.7 B4); flushed before the next push. */
-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 (
@@ -137,12 +116,15 @@ export function listPendingUploads(db) {
         };
     });
 }
+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 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();
@@ -162,79 +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.
- *
- * `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 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) {
+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)
-           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)`);
-        }
-    });
+    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

@@ -1,3 +1,4 @@
+import { type SyncProgress, type SyncProgressListener } from './progress.js';
 /**
  * SyncClient implements the client side of SPEC.md §§3–8.
  *
@@ -110,9 +111,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;
@@ -294,6 +295,8 @@ export declare class SyncClient {
      */
     onInvalidate(listener: InvalidationListener): () => void;
     /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
+    onProgress(listener: SyncProgressListener): () => void;
+    progressSnapshot(): SyncProgress | undefined;
     onChange(listener: ClientChangeListener): () => void;
     /** Subscribe to host wake signals raised by startup and realtime. */
     onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;