@syncular/client 0.18.0 → 0.20.0

package/src/client.ts

@@ -1,3 +1,8 @@
+import {
+  ProgressEmitter,
+  type SyncProgress,
+  type SyncProgressListener,
+} from './progress';
 /**
  * SyncClient implements the client side of SPEC.md §§3–8.
  *
@@ -47,13 +52,13 @@ import {
   type CachedBlob,
   clearPendingUpload,
   computeBlobId,
+  deleteUnreferencedCachedBlobs,
   enforceBlobCacheCap,
   ensureBlobSchema,
   getCachedBlob,
   listPendingUploads,
   parseBlobRef,
   putCachedBlob,
-  reconcileBlobRefcounts,
   recordPendingUpload,
   schemaHasBlobs,
   serializeBlobRef,
@@ -302,9 +307,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;
@@ -584,6 +589,8 @@ export class SyncClient {
   #realtimeGeneration = 0;
   #pendingRound: PendingRound | undefined;
   #needsPull = false;
+  readonly #progress = new ProgressEmitter();
+  #progressAttempt = 0;
   #syncing = false;
   /**
    * True from the synchronous entry of `sync()` until its serialized round
@@ -688,47 +695,7 @@ 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);
     });
@@ -913,6 +880,7 @@ export class SyncClient {
     await this.#lease?.release();
     this.#lease = undefined;
     this.#started = false;
+    this.#progress.clear();
     this.#syncNeededListeners.clear();
     this.#syncIntentListeners.clear();
   }
@@ -1113,6 +1081,14 @@ export class SyncClient {
   }
 
   /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
+  onProgress(listener: SyncProgressListener): () => void {
+    return this.#progress.on(listener);
+  }
+
+  progressSnapshot(): SyncProgress | undefined {
+    return this.#progress.snapshot();
+  }
+
   onChange(listener: ClientChangeListener): () => void {
     return this.#changes.on(listener);
   }
@@ -1510,13 +1486,11 @@ export class SyncClient {
       );
     }
     const blobId = await computeBlobId(bytes);
+    const nowMs = this.#now();
     this.#db.transaction(() => {
-      putCachedBlob(this.#db, blobId, bytes, this.#now(), options?.mediaType);
-      recordPendingUpload(this.#db, blobId, this.#now(), options?.mediaType);
+      putCachedBlob(this.#db, blobId, bytes, nowMs, options?.mediaType);
+      recordPendingUpload(this.#db, blobId, nowMs, options?.mediaType);
     });
-    // §5.9.7 B1: a staged upload is pinned (recordPendingUpload), so the cap
-    // trim below will never evict it — but a stage may push other zero-ref
-    // bodies over the cap, so run the trim.
     this.#enforceBlobCacheCap();
     return {
       blobId,
@@ -1547,7 +1521,7 @@ export class SyncClient {
     const blobId = blobIdOrRef.startsWith('sha256:')
       ? blobIdOrRef
       : parseBlobRef(blobIdOrRef).blobId;
-    const cached = getCachedBlob(this.#db, blobId, this.#now());
+    const cached = getCachedBlob(this.#db, blobId);
     if (cached !== undefined) return cached;
     const transport = this.#config.blobs;
     if (transport === undefined) {
@@ -1595,9 +1569,7 @@ export class SyncClient {
       );
     }
     putCachedBlob(this.#db, blobId, bytes, this.#now());
-    // The referencing row can arrive before its body. Pin the new cache entry
-    // from current visible references before applying the size cap (§5.9.7 B1).
-    this.#reconcileBlobs(false, blobId);
+    this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
     this.#enforceBlobCacheCap();
     const stored = getCachedBlob(this.#db, blobId);
     if (stored === undefined) {
@@ -1613,7 +1585,7 @@ export class SyncClient {
   #enforceBlobCacheCap(): void {
     const cap = this.#config.blobCacheMaxBytes;
     if (cap === undefined) return;
-    enforceBlobCacheCap(this.#db, cap);
+    enforceBlobCacheCap(this.#db, this.#schema, cap);
   }
 
   /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
@@ -2188,6 +2160,29 @@ export class SyncClient {
           this.#now(),
           this.#captureBeforeImages(operations),
         );
+        for (const operation of operations) {
+          if (operation.op !== 'upsert') continue;
+          const table = this.#schema.tables.get(operation.table);
+          if (table === undefined) continue;
+          for (const column of table.columns) {
+            if (column.type !== 'blob_ref') continue;
+            const raw = operation.values?.[column.name];
+            if (typeof raw !== 'string') continue;
+            let blobId: string;
+            try {
+              blobId = parseBlobRef(raw).blobId;
+            } catch {
+              continue;
+            }
+            this.#db.exec(
+              `INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
+               SELECT ?, ? WHERE EXISTS (
+                 SELECT 1 FROM _syncular_blobs WHERE blob_id = ?
+               )`,
+              [clientCommitId, blobId, blobId],
+            );
+          }
+        }
         this.#applyOperationsLocally(operations, batch);
         batch.status();
       });
@@ -2386,7 +2381,7 @@ export class SyncClient {
           batch.rejections();
           batch.outcomes();
         }
-        this.#reconcileBlobs(true);
+        this.#deleteUnreferencedBlobs();
         setMeta(this.#db, metaKey, purge.canonicalPlan);
         return {
           alreadyApplied: false,
@@ -2676,6 +2671,13 @@ export class SyncClient {
         (error: unknown) => {
           const completedAtMs = this.#now();
           const code = (error as { code?: unknown }).code;
+          this.#progress.update({
+            state: 'failed',
+            errorCode:
+              typeof code === 'string'
+                ? this.#diagnosticCode(code)
+                : 'client.unknown_failure',
+          });
           this.#lastRound = {
             status: 'failed',
             startedAtMs,
@@ -2730,7 +2732,15 @@ export class SyncClient {
   }
 
   async #runSync(): Promise<SyncSummary> {
+    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: [],
@@ -2821,6 +2831,11 @@ 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
@@ -3389,6 +3404,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,
@@ -3400,6 +3428,8 @@ export class SyncClient {
                   segment,
                   {
                     clearFirst,
+                    onProgress: (rowsProcessed) =>
+                      this.#progress.update({ rowsProcessed }),
                     effective,
                     transaction: (fn) =>
                       this.#applyBatch((batch) => {
@@ -3439,6 +3469,7 @@ export class SyncClient {
               );
             }
             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.
@@ -3468,6 +3499,8 @@ export class SyncClient {
                     },
                     {
                       clearFirst,
+                      onProgress: (rowsProcessed) =>
+                        this.#progress.update({ rowsProcessed }),
                       effective,
                       transaction: (fn) =>
                         this.#applyBatch((batch) => {
@@ -3497,6 +3530,8 @@ export class SyncClient {
                     segment,
                     {
                       clearFirst,
+                      onProgress: (rowsProcessed) =>
+                        this.#progress.update({ rowsProcessed }),
                       effective,
                       transaction: (fn) =>
                         this.#applyBatch((batch) => {
@@ -3564,7 +3599,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();
       }
@@ -3879,6 +3913,19 @@ export class SyncClient {
         '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: number): void => {
+      this.#progress.update({ bytesReceived });
+    };
     let bytes: Uint8Array;
     if (frame.url !== undefined) {
       // §5.4: a url-carrying descriptor MUST be fetched from that URL —
@@ -3906,17 +3953,19 @@ export class SyncClient {
           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(
@@ -4047,7 +4096,7 @@ export class SyncClient {
             batch.rejections();
             batch.outcomes();
           }
-          this.#reconcileBlobs(true);
+          this.#deleteUnreferencedBlobs();
         } catch (error) {
           if (
             error instanceof ClientSyncError &&
@@ -4265,17 +4314,9 @@ export class SyncClient {
     });
   }
 
-  /**
-   * §5.9.7 B1/B2: recompute blob-cache refcounts from live `blob_ref`
-   * columns. No-op unless the schema has blob columns. `deleteOrphans`
-   * triggers the revocation-side body deletion (B2).
-   */
-  #reconcileBlobs(deleteOrphans: boolean, blobId?: string): void {
+  #deleteUnreferencedBlobs(): void {
     if (!this.#hasBlobs) return;
-    reconcileBlobRefcounts(this.#db, this.#schema, {
-      deleteOrphans,
-      ...(blobId === undefined ? {} : { blobId }),
-    });
+    deleteUnreferencedCachedBlobs(this.#db, this.#schema);
   }
 
   // -- helpers -----------------------------------------------------------------

package/src/http.ts

@@ -139,6 +139,40 @@ export function webSocketRemoteOperationConnector(
  * Resolution (which path a descriptor takes, expiry, no fall-through)
  * lives in the client core, not here.
  */
+async function readSegmentBody(
+  response: Response,
+  onProgress?: (bytesReceived: number) => void,
+): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  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: string,
   options?: HttpTransportOptions,
@@ -147,6 +181,7 @@ export function httpSegmentDownloader(
   const direct = async (request: {
     readonly segmentId: string;
     readonly requestedScopesJson: string;
+    readonly onProgress?: (bytesReceived: number) => void;
   }) => {
     const response = await doFetch(
       `${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`,
@@ -158,9 +193,12 @@ export function httpSegmentDownloader(
       },
     );
     if (!response.ok) await throwHttpError(response);
-    return new Uint8Array(await response.arrayBuffer());
+    return readSegmentBody(response, request.onProgress);
   };
-  const fetchUrl = async (url: string) => {
+  const fetchUrl = async (
+    url: string,
+    onProgress?: (bytesReceived: number) => void,
+  ) => {
     // Deliberately headerless: the URL is the bearer grant (§5.4).
     const response = await doFetch(url);
     if (!response.ok) {
@@ -170,7 +208,7 @@ export function httpSegmentDownloader(
         true,
       );
     }
-    return new Uint8Array(await response.arrayBuffer());
+    return readSegmentBody(response, onProgress);
   };
   return Object.assign(direct, { fetchUrl });
 }

package/src/index.ts

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

package/src/outbox.ts

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

package/src/progress.ts

@@ -0,0 +1,62 @@
+/** 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 class ProgressEmitter {
+  #snapshot: SyncProgress | undefined;
+  readonly #listeners = new Set<SyncProgressListener>();
+
+  clear(): void {
+    this.#listeners.clear();
+    this.#snapshot = undefined;
+  }
+
+  snapshot(): SyncProgress | undefined {
+    return this.#snapshot;
+  }
+
+  on(listener: SyncProgressListener): () => void {
+    this.#listeners.add(listener);
+    if (this.#snapshot !== undefined) {
+      try {
+        listener(this.#snapshot);
+      } catch {
+        /* Observers cannot interrupt sync. */
+      }
+    }
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  emit(progress: SyncProgress): void {
+    const snapshot = Object.freeze({ ...progress });
+    this.#snapshot = snapshot;
+    for (const listener of [...this.#listeners]) {
+      try {
+        listener(snapshot);
+      } catch {
+        /* Observers cannot interrupt sync. */
+      }
+    }
+  }
+
+  update(update: Partial<SyncProgress>): void {
+    if (this.#snapshot?.state === 'running')
+      this.emit({ ...this.#snapshot, ...update });
+  }
+}

package/src/schema.ts

@@ -501,6 +501,11 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
   db.transaction(() => {
     db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
+    db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
+      commit_id TEXT NOT NULL, blob_id TEXT NOT NULL, PRIMARY KEY(commit_id, blob_id))`);
+    db.exec(
+      'CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body ON _syncular_blob_commit_refs(blob_id)',
+    );
     db.exec(
       `INSERT OR IGNORE INTO _syncular_meta(key, value) VALUES ('localRevision', '0')`,
     );

package/src/transport.ts

@@ -32,6 +32,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;
 }
 
 /**
@@ -44,7 +45,10 @@ 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 {

package/src/wasm-database.ts

@@ -53,6 +53,13 @@ interface SahPoolUtil {
   OpfsSAHPoolDb: new (filename: string) => Oo1Database;
 }
 
+interface SqliteIoMethods {
+  installMethod(
+    name: 'xCheckReservedLock',
+    callback: (file: number, output: number) => number,
+  ): unknown;
+}
+
 interface Sqlite3Static {
   oo1: {
     DB: new (filename: string, flags?: string) => Oo1Database;
@@ -60,6 +67,18 @@ interface Sqlite3Static {
   capi: {
     SQLITE_DESERIALIZE_FREEONCLOSE: number;
     SQLITE_DESERIALIZE_READONLY: number;
+    SQLITE_FCNTL_FILE_POINTER: number;
+    sqlite3_file_control(
+      db: number,
+      schema: string,
+      operation: number,
+      output: number,
+    ): number;
+    sqlite3_file: new (pointer: number) => {
+      readonly $pMethods: number;
+      dispose(): void;
+    };
+    sqlite3_io_methods: new (pointer: number) => SqliteIoMethods;
     sqlite3_deserialize(
       db: number,
       schema: string,
@@ -71,6 +90,13 @@ interface Sqlite3Static {
   };
   wasm: {
     allocFromTypedArray(bytes: Uint8Array): number;
+    peekPtr(pointer: number): number;
+    poke32(pointer: number, value: number): unknown;
+    pstack: {
+      readonly pointer: number;
+      allocPtr(): number;
+      restore(pointer: number): void;
+    };
   };
   installOpfsSAHPoolVfs(options: {
     name?: string;
@@ -217,6 +243,10 @@ function inWorkerContext(): boolean {
 /** One registered VFS per pool directory, reused across opens. */
 const sahPools = new Map<string, Promise<SahPoolUtil>>();
 
+// 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<number, SqliteIoMethods>();
+
 function opfsSahPoolError(error: unknown, directory: string): ClientSyncError {
   const detail = error instanceof Error ? error.message : String(error);
   const normalized = detail.toLowerCase();
@@ -306,5 +336,53 @@ export async function openPersistentWasmDatabase(
     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);
+  }
 }