@syncular/client 0.19.0 → 0.20.0

package/README.md

@@ -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.
@@ -584,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/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.
  *
@@ -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;

package/dist/client.js

@@ -1,3 +1,4 @@
+import { ProgressEmitter, } from './progress.js';
 /**
  * SyncClient implements the client side of SPEC.md §§3–8.
  *
@@ -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
@@ -359,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();
     }
@@ -537,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);
     }
@@ -1837,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,
@@ -1883,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: [],
@@ -1958,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
@@ -2430,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) ||
@@ -2457,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.
@@ -2471,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 ||
@@ -2486,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) ||
@@ -2790,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 —
@@ -2806,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);

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/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/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;