@syncular/client 0.18.0 → 0.20.0

package/dist/client.js

@@ -1,3 +1,4 @@
+import { ProgressEmitter, } from './progress.js';
 /**
  * SyncClient implements the client side of SPEC.md §§3–8.
  *
@@ -9,7 +10,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';
@@ -102,6 +103,8 @@ export class SyncClient {
     #realtimeGeneration = 0;
     #pendingRound;
     #needsPull = false;
+    #progress = new ProgressEmitter();
+    #progressAttempt = 0;
     #syncing = false;
     /**
      * True from the synchronous entry of `sync()` until its serialized round
@@ -191,39 +194,8 @@ 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);
-        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}`);
-            }
-        });
+        if (this.#hasBlobs)
+            ensureBlobSchema(this.#db);
         this.#db.transaction(() => {
             pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
         });
@@ -390,6 +362,7 @@ export class SyncClient {
         await this.#lease?.release();
         this.#lease = undefined;
         this.#started = false;
+        this.#progress.clear();
         this.#syncNeededListeners.clear();
         this.#syncIntentListeners.clear();
     }
@@ -568,6 +541,12 @@ export class SyncClient {
         return this.#invalidation.on(listener);
     }
     /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
+    onProgress(listener) {
+        return this.#progress.on(listener);
+    }
+    progressSnapshot() {
+        return this.#progress.snapshot();
+    }
     onChange(listener) {
         return this.#changes.on(listener);
     }
@@ -893,13 +872,11 @@ export class SyncClient {
             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,
@@ -927,7 +904,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;
@@ -962,9 +939,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, blobId);
+        this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
         this.#enforceBlobCacheCap();
         const stored = getCachedBlob(this.#db, blobId);
         if (stored === undefined) {
@@ -977,7 +952,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() {
@@ -1446,6 +1421,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();
             });
@@ -1604,7 +1604,7 @@ export class SyncClient {
                     batch.rejections();
                     batch.outcomes();
                 }
-                this.#reconcileBlobs(true);
+                this.#deleteUnreferencedBlobs();
                 setMeta(this.#db, metaKey, purge.canonicalPlan);
                 return {
                     alreadyApplied: false,
@@ -1847,6 +1847,12 @@ export class SyncClient {
         }, (error) => {
             const completedAtMs = this.#now();
             const code = error.code;
+            this.#progress.update({
+                state: 'failed',
+                errorCode: typeof code === 'string'
+                    ? this.#diagnosticCode(code)
+                    : 'client.unknown_failure',
+            });
             this.#lastRound = {
                 status: 'failed',
                 startedAtMs,
@@ -1893,7 +1899,15 @@ export class SyncClient {
             : 'client.unknown_failure';
     }
     async #runSync() {
+        this.#progress.emit({
+            attempt: ++this.#progressAttempt,
+            state: 'running',
+            phase: 'request',
+            bytesReceived: 0,
+            rowsProcessed: 0,
+        });
         if (this.#schemaFloor !== undefined) {
+            this.#progress.update({ state: 'complete' });
             return {
                 ...emptySummary(0),
                 bootstrapping: [],
@@ -1968,6 +1982,9 @@ export class SyncClient {
             // §4.8 E1: the push half may have drained commits that pinned rows of
             // a shrunk window unit — retry any deferred evictions now.
             this.#drainPendingEvictions();
+            this.#progress.update(summary.failed.length > 0
+                ? { state: 'failed', errorCode: 'sync.scope_revoked' }
+                : { state: 'complete' });
             this.#retryDelayMs = 250;
             if (deferred > 0) {
                 // §6.1 splitBatch remainder: more queued commits than this request
@@ -2440,8 +2457,19 @@ export class SyncClient {
                             break;
                         }
                         const segment = decodeRowsSegment(frame.payload);
+                        this.#progress.update({
+                            phase: 'import',
+                            subscriptionId: section.sub.id,
+                            table: section.sub.table,
+                            segmentId: undefined,
+                            bytesReceived: frame.payload.byteLength,
+                            bytesTotal: frame.payload.byteLength,
+                            rowsProcessed: 0,
+                            rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
+                        });
                         await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
                             clearFirst,
+                            onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                             effective,
                             transaction: (fn) => this.#applyBatch((batch) => {
                                 if (segment.blocks.some((block) => block.length > 0) ||
@@ -2467,6 +2495,7 @@ export class SyncClient {
                             throw new ClientSyncError('sync.invalid_request', 'SEGMENT_REF mediaType sqlite was not advertised in accept (§4.2)');
                         }
                         const bytes = await this.#downloadSegment(frame, section.sub);
+                        this.#progress.update({ phase: 'import' });
                         if (frame.mediaType === 'sqlite') {
                             // §5.3: images are whole-table — a paged descriptor is
                             // invalid, and the image is always its table's first page.
@@ -2481,6 +2510,7 @@ export class SyncClient {
                                 scopeDigest: frame.scopeDigest,
                             }, {
                                 clearFirst,
+                                onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                                 effective,
                                 transaction: (fn) => this.#applyBatch((batch) => {
                                     if (frame.rowCount > 0 ||
@@ -2496,6 +2526,7 @@ export class SyncClient {
                             const segment = decodeRowsSegment(bytes);
                             await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
                                 clearFirst,
+                                onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                                 effective,
                                 transaction: (fn) => this.#applyBatch((batch) => {
                                     if (segment.blocks.some((block) => block.length > 0) ||
@@ -2546,7 +2577,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();
@@ -2801,6 +2831,19 @@ export class SyncClient {
         if (downloader === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'received SEGMENT_REF but no segment downloader is configured');
         }
+        this.#progress.update({
+            phase: 'download',
+            subscriptionId: sub.id,
+            table: frame.table,
+            segmentId: frame.segmentId,
+            bytesReceived: 0,
+            bytesTotal: frame.byteLength,
+            rowsProcessed: 0,
+            rowsTotal: frame.rowCount,
+        });
+        const onProgress = (bytesReceived) => {
+            this.#progress.update({ bytesReceived });
+        };
         let bytes;
         if (frame.url !== undefined) {
             // §5.4: a url-carrying descriptor MUST be fetched from that URL —
@@ -2817,18 +2860,20 @@ export class SyncClient {
                 // §5.4: MUST NOT start a fetch at/past expiry.
                 throw new ClientSyncError('sync.segment_expired', `signed URL for segment ${frame.segmentId} expired before fetch — re-pull mints fresh descriptors (§5.4)`, true);
             }
-            bytes = await fetchUrl(frame.url);
+            bytes = await fetchUrl(frame.url, onProgress);
         }
         else {
             bytes = await downloader({
                 segmentId: frame.segmentId,
                 table: frame.table,
                 requestedScopesJson: canonicalScopeJson(sub.scopes),
+                onProgress,
             });
         }
         // §5.1: verify the content address before applying; on mismatch the
         // segment is discarded and the cursor/resume token stay unpersisted,
         // so the next pull re-delivers.
+        onProgress(bytes.byteLength);
         const hash = await sha256Hex(bytes);
         if (`sha256:${hash}` !== frame.segmentId) {
             throw new ClientSyncError('sync.invalid_request', `segment ${frame.segmentId} failed content-address verification (§5.1)`, true);
@@ -2935,7 +2980,7 @@ export class SyncClient {
                         batch.rejections();
                         batch.outcomes();
                     }
-                    this.#reconcileBlobs(true);
+                    this.#deleteUnreferencedBlobs();
                 }
                 catch (error) {
                     if (error instanceof ClientSyncError &&
@@ -3107,18 +3152,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, blobId) {
+    #deleteUnreferencedBlobs() {
         if (!this.#hasBlobs)
             return;
-        reconcileBlobRefcounts(this.#db, this.#schema, {
-            deleteOrphans,
-            ...(blobId === undefined ? {} : { blobId }),
-        });
+        deleteUnreferencedCachedBlobs(this.#db, this.#schema);
     }
     // -- helpers -----------------------------------------------------------------
     #table(name) {

package/dist/http.d.ts

@@ -16,14 +16,6 @@ export declare function httpSyncTransport(syncUrl: string, options?: HttpTranspo
 export declare function httpRemoteOperationTransport(operationsUrl: string, options?: HttpTransportOptions): RemoteOperationTransport;
 /** WebSocket connector for registered query snapshots. */
 export declare function webSocketRemoteOperationConnector(realtimeUrl: string): RemoteOperationRealtimeConnector;
-/**
- * §5.5 direct endpoint with the `X-Syncular-Scopes` re-authorization
- * header, plus the §5.4 `fetchUrl` capability (advertises accept bit 3).
- * `fetchUrl` sends NO headers at all — the signed URL is the entire
- * grant, and host auth must never leak to CDN/object hosts (§5.4).
- * Resolution (which path a descriptor takes, expiry, no fall-through)
- * lives in the client core, not here.
- */
 export declare function httpSegmentDownloader(segmentsBaseUrl: string, options?: HttpTransportOptions): SegmentDownloader;
 /**
  * §5.9.3/§5.9.5 blob transport: host-authenticated `PUT`/`GET

package/dist/http.js

@@ -97,6 +97,39 @@ export function webSocketRemoteOperationConnector(realtimeUrl) {
  * Resolution (which path a descriptor takes, expiry, no fall-through)
  * lives in the client core, not here.
  */
+async function readSegmentBody(response, onProgress) {
+    const chunks = [];
+    let received = 0;
+    let reported = 0;
+    const reader = response.body?.getReader();
+    if (reader !== undefined) {
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+                received += value.byteLength;
+                if (received - reported >= 64 * 1024) {
+                    onProgress?.(received);
+                    reported = received;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    if (received !== reported)
+        onProgress?.(received);
+    const bytes = new Uint8Array(received);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
 export function httpSegmentDownloader(segmentsBaseUrl, options) {
     const doFetch = options?.fetch ?? fetch;
     const direct = async (request) => {
@@ -108,15 +141,15 @@ export function httpSegmentDownloader(segmentsBaseUrl, options) {
         });
         if (!response.ok)
             await throwHttpError(response);
-        return new Uint8Array(await response.arrayBuffer());
+        return readSegmentBody(response, request.onProgress);
     };
-    const fetchUrl = async (url) => {
+    const fetchUrl = async (url, onProgress) => {
         // Deliberately headerless: the URL is the bearer grant (§5.4).
         const response = await doFetch(url);
         if (!response.ok) {
             throw new ClientSyncError('sync.transport_failed', `signed-URL fetch failed with HTTP ${response.status} (§5.4: descriptor invalidated, re-pull to recover)`, true);
         }
-        return new Uint8Array(await response.arrayBuffer());
+        return readSegmentBody(response, onProgress);
     };
     return Object.assign(direct, { fetchUrl });
 }

package/dist/index.d.ts

@@ -40,3 +40,4 @@ export * from './transport.js';
 export * from './window.js';
 export * from './worker-host.js';
 export * from './worker-protocol.js';
+export { ProgressEmitter, type SyncProgress, type SyncProgressListener, } from './progress.js';

package/dist/index.js

@@ -40,3 +40,4 @@ export * from './transport.js';
 export * from './window.js';
 export * from './worker-host.js';
 export * from './worker-protocol.js';
+export { ProgressEmitter, } from './progress.js';

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/progress.d.ts

@@ -0,0 +1,24 @@
+/** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
+export interface SyncProgress {
+    readonly attempt: number;
+    readonly state: 'running' | 'complete' | 'failed';
+    readonly phase: 'request' | 'download' | 'import';
+    readonly subscriptionId?: string;
+    readonly table?: string;
+    readonly segmentId?: string | undefined;
+    readonly bytesReceived: number;
+    readonly bytesTotal?: number;
+    readonly rowsProcessed: number;
+    readonly rowsTotal?: number;
+    readonly errorCode?: string;
+}
+export type SyncProgressListener = (progress: SyncProgress) => void;
+/** Shared by the direct client and event-forwarding handles. */
+export declare class ProgressEmitter {
+    #private;
+    clear(): void;
+    snapshot(): SyncProgress | undefined;
+    on(listener: SyncProgressListener): () => void;
+    emit(progress: SyncProgress): void;
+    update(update: Partial<SyncProgress>): void;
+}

package/dist/progress.js

@@ -0,0 +1,42 @@
+/** Shared by the direct client and event-forwarding handles. */
+export class ProgressEmitter {
+    #snapshot;
+    #listeners = new Set();
+    clear() {
+        this.#listeners.clear();
+        this.#snapshot = undefined;
+    }
+    snapshot() {
+        return this.#snapshot;
+    }
+    on(listener) {
+        this.#listeners.add(listener);
+        if (this.#snapshot !== undefined) {
+            try {
+                listener(this.#snapshot);
+            }
+            catch {
+                /* Observers cannot interrupt sync. */
+            }
+        }
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(progress) {
+        const snapshot = Object.freeze({ ...progress });
+        this.#snapshot = snapshot;
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                /* Observers cannot interrupt sync. */
+            }
+        }
+    }
+    update(update) {
+        if (this.#snapshot?.state === 'running')
+            this.emit({ ...this.#snapshot, ...update });
+    }
+}

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/dist/transport.d.ts

@@ -22,6 +22,7 @@ export interface SegmentFetchRequest {
     readonly table: string;
     /** Canonical JSON (§11.2) of the requested scope map (§5.5 header). */
     readonly requestedScopesJson: string;
+    readonly onProgress?: (bytesReceived: number) => void;
 }
 /**
  * Fetch segment bytes from the direct endpoint (§5.5). `fetchUrl`, when
@@ -33,7 +34,7 @@ export interface SegmentFetchRequest {
  */
 export interface SegmentDownloader {
     (request: SegmentFetchRequest): Promise<Uint8Array>;
-    readonly fetchUrl?: (url: string) => Promise<Uint8Array>;
+    readonly fetchUrl?: (url: string, onProgress?: (bytesReceived: number) => void) => Promise<Uint8Array>;
 }
 export interface RealtimeHandlers {
     /** JSON control frame (§8.1): hello / sync / heartbeat / unknown. */

package/dist/wasm-database.js

@@ -122,6 +122,9 @@ function inWorkerContext() {
 }
 /** One registered VFS per pool directory, reused across opens. */
 const sahPools = new Map();
+// SAH pools share an I/O method table within the WASM runtime. Keep the
+// installed callback alive for that runtime, including across database closes.
+const sahIoMethods = new Map();
 function opfsSahPoolError(error, directory) {
     const detail = error instanceof Error ? error.message : String(error);
     const normalized = detail.toLowerCase();
@@ -187,5 +190,42 @@ export async function openPersistentWasmDatabase(name, options) {
         sahPools.set(directory, pool);
     }
     const util = await pool;
-    return new WasmClientDatabase(new util.OpfsSAHPoolDb(`/${name}.db`), sqlite3);
+    const db = new util.OpfsSAHPoolDb(`/${name}.db`);
+    const { capi, wasm } = sqlite3;
+    const stack = wasm.pstack.pointer;
+    try {
+        // Do this before the first SQL statement, when SQLite checks for a hot
+        // journal. The SAH-pool callback in sqlite-wasm 3.53 reports a reserved
+        // lock unconditionally, which suppresses crash rollback. The pool already
+        // excludes other owners; report no competing writer, as the other OPFS
+        // VFS does. Keep DELETE/FULL and the existing database/journal files.
+        const output = wasm.pstack.allocPtr();
+        if (db.pointer === undefined ||
+            capi.sqlite3_file_control(db.pointer, 'main', capi.SQLITE_FCNTL_FILE_POINTER, output) !== 0 ||
+            !wasm.peekPtr(output)) {
+            throw new ClientSyncError(STORAGE_UNAVAILABLE_CODE, 'Could not configure OPFS crash recovery');
+        }
+        const file = new capi.sqlite3_file(wasm.peekPtr(output));
+        const methodsPointer = file.$pMethods;
+        file.dispose(); // Borrowed struct view; SQLite still owns the file.
+        if (!methodsPointer) {
+            throw new ClientSyncError(STORAGE_UNAVAILABLE_CODE, 'Could not configure OPFS crash recovery');
+        }
+        if (!sahIoMethods.has(methodsPointer)) {
+            const methods = new capi.sqlite3_io_methods(methodsPointer);
+            methods.installMethod('xCheckReservedLock', (_file, reserved) => {
+                wasm.poke32(reserved, 0);
+                return 0;
+            });
+            sahIoMethods.set(methodsPointer, methods);
+        }
+        return new WasmClientDatabase(db, sqlite3);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+    finally {
+        wasm.pstack.restore(stack);
+    }
 }

package/dist/worker-entry.d.ts

@@ -4,6 +4,8 @@ import { type WorkerInitConfig } from './worker-protocol.js';
 export interface SyncWorkerOverrides {
     /** Database factory indirection: tests inject bun:sqlite here. */
     readonly openDatabase?: (config: WorkerInitConfig) => Promise<ClientDatabase> | ClientDatabase;
+    /** Retry deadline indirection for deterministic worker-host tests. */
+    readonly waitForStorageRetry?: (delayMs: number) => Promise<void>;
     readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
     readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
     readonly createRealtime?: (config: WorkerInitConfig, clientId: string) => RealtimeConnector | undefined;

package/dist/worker-entry.js

@@ -16,7 +16,7 @@
 import { SyncClient } from './client.js';
 import { withClientDiagnosticsHost, } from './diagnostics.js';
 import { encryptionConfigFromKeyring } from './encryption.js';
-import { ClientSyncError } from './errors.js';
+import { ClientSyncError, STORAGE_BUSY_CODE } from './errors.js';
 import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
 import { openPersistentWasmDatabase } from './wasm-database.js';
 import { WORKER_FAILED_CODE, } from './worker-protocol.js';
@@ -170,9 +170,9 @@ export function startSyncWorker(overrides = {}) {
         return Object.assign(gateOffline(inner), {
             ...(fetchUrl !== undefined
                 ? {
-                    fetchUrl: (url) => {
+                    fetchUrl: (url, onProgress) => {
                         assertOnline();
-                        return fetchUrl(url);
+                        return fetchUrl(url, onProgress);
                     },
                 }
                 : {}),
@@ -183,10 +183,33 @@ export function startSyncWorker(overrides = {}) {
             throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker is already initialized');
         }
         autoSync = config.autoSync ?? true;
-        database =
-            overrides.openDatabase !== undefined
-                ? await overrides.openDatabase(config)
-                : await defaultOpenDatabase(config);
+        for (let attempt = 0;; attempt++) {
+            try {
+                database =
+                    overrides.openDatabase !== undefined
+                        ? await overrides.openDatabase(config)
+                        : await defaultOpenDatabase(config);
+                break;
+            }
+            catch (error) {
+                if (config.database.mode !== 'persistent' ||
+                    !(error instanceof ClientSyncError) ||
+                    error.code !== STORAGE_BUSY_CODE ||
+                    !error.retryable ||
+                    attempt === 6) {
+                    throw error;
+                }
+                // Retain the leader lease while the previous worker's OPFS handles
+                // drain. Only opening is retried; core initialization has not started.
+                const delayMs = Math.min(50 * 2 ** attempt, 1000);
+                if (overrides.waitForStorageRetry !== undefined) {
+                    await overrides.waitForStorageRetry(delayMs);
+                }
+                else {
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+            }
+        }
         const transport = gateOffline(overrides.createTransport !== undefined
             ? overrides.createTransport(config)
             : httpSyncTransport(config.endpoints.syncUrl));
@@ -245,6 +268,10 @@ export function startSyncWorker(overrides = {}) {
                 post({ t: 'event', event: { kind: 'presence', scopeKey } });
             },
         });
+        started.onProgress((progress) => {
+            if (!closed)
+                post({ t: 'event', event: { kind: 'progress', progress } });
+        });
         started.onChange((batch) => {
             if (!closed)
                 post({ t: 'event', event: { kind: 'change', batch } });