@korajs/store 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/adapters/sqlite-wasm-worker.cjs

@@ -22,9 +22,374 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// src/adapters/sqlite-wasm-worker-core.ts
-var OPFS_POOL_NAME = "kora-opfs";
+// src/adapters/opfs-names.ts
+var LEGACY_OPFS_POOL_NAME = "kora-opfs";
+var OPFS_POOL_PREFIX = "kora-opfs-";
+var MAX_POOL_SLUG_LENGTH = 48;
+function fnv1a32Hex(value) {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function opfsPoolNameFor(dbName) {
+  const sanitized = dbName.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const slug = sanitized.slice(0, MAX_POOL_SLUG_LENGTH);
+  if (slug === dbName) {
+    return `${OPFS_POOL_PREFIX}${slug}`;
+  }
+  return `${OPFS_POOL_PREFIX}${slug}-${fnv1a32Hex(dbName)}`;
+}
+function opfsPoolDirectory(poolName) {
+  return `.${poolName}`;
+}
+function opfsPoolLockName(poolName) {
+  return `kora-opfs-pool:${poolName}`;
+}
+function opfsDatabaseFilename(dbName) {
+  const base = dbName.replace(/[^a-zA-Z0-9._-]/g, "_");
+  return base.endsWith(".db") ? base : `${base}.db`;
+}
+function opfsPoolPath(dbName) {
+  return `/${opfsDatabaseFilename(dbName)}`;
+}
+
+// src/errors.ts
+var import_core = require("@korajs/core");
+var WorkerInitError = class extends import_core.KoraError {
+  constructor(message, context) {
+    super(`Worker initialization failed: ${message}`, "WORKER_INIT_ERROR", context);
+    this.name = "WorkerInitError";
+  }
+};
+var BridgeTerminatedError = class extends import_core.KoraError {
+  constructor(operation, reason) {
+    super(
+      `Storage request "${operation}" was interrupted (${reason}); retry it against the new storage leader.`,
+      "BRIDGE_TERMINATED",
+      { operation, reason, retriable: true }
+    );
+    this.name = "BridgeTerminatedError";
+  }
+};
+
+// src/multi-tab/tab-storage.ts
+var RPC_REQUEST = "kora-worker-request";
+var RPC_RESPONSE = "kora-worker-response";
+var CLIENT_LEAVE = "kora-client-leave";
+var LEADER_PING = "kora-leader-ping";
+var LEADER_PONG = "kora-leader-pong";
+var LEADER_HEARTBEAT = "kora-leader-heartbeat";
+var DEFAULT_HEARTBEAT_MS = 1e3;
+var DEFAULT_TRANSACTION_IDLE_TIMEOUT_MS = 1e4;
+var DEDUP_CAPACITY = 512;
+function createRequestDeduper() {
+  const inflight = /* @__PURE__ */ new Map();
+  const completed = /* @__PURE__ */ new Map();
+  return {
+    run(requestId, start) {
+      const done = completed.get(requestId);
+      if (done) return Promise.resolve(done);
+      if (inflight.has(requestId)) return null;
+      const promise = start().then((response) => {
+        inflight.delete(requestId);
+        completed.set(requestId, response);
+        if (completed.size > DEDUP_CAPACITY) {
+          const oldest = completed.keys().next().value;
+          if (oldest !== void 0) completed.delete(oldest);
+        }
+        return response;
+      });
+      inflight.set(requestId, promise);
+      return promise;
+    }
+  };
+}
+function serveChannel(channel, bridge, source, heartbeatMs) {
+  const epoch = createClientId();
+  const dedup = createRequestDeduper();
+  const beat = () => {
+    const message = { type: LEADER_HEARTBEAT, epoch, source };
+    channel.postMessage(message);
+  };
+  const respond = (requestId, response) => {
+    const msg = { type: RPC_RESPONSE, requestId, response };
+    channel.postMessage(msg);
+  };
+  const onMessage = (event) => {
+    const data = event.data;
+    if (data?.type === LEADER_PING) {
+      channel.postMessage({ type: LEADER_PONG });
+      return;
+    }
+    if (data?.type === CLIENT_LEAVE) {
+      if (hasReclaimClient(bridge)) {
+        bridge.reclaimClient(data.clientId, "client-left");
+      }
+      return;
+    }
+    if (data?.type !== RPC_REQUEST) {
+      return;
+    }
+    if (data.request.type === "close" || data.request.type === "destroy" || data.request.type === "serve") {
+      respond(data.requestId, { id: data.request.id, type: "success" });
+      return;
+    }
+    const pending = dedup.run(
+      data.requestId,
+      () => bridge.send(data.request, data.clientId).catch(
+        (error) => ({
+          id: data.request.id,
+          type: "error",
+          message: error instanceof Error ? error.message : "Worker RPC failed",
+          code: "LEADER_RPC_ERROR"
+        })
+      )
+    );
+    void pending?.then((response) => respond(data.requestId, response));
+  };
+  channel.addEventListener("message", onMessage);
+  const interval = heartbeatMs > 0 ? setInterval(beat, heartbeatMs) : void 0;
+  if (heartbeatMs > 0) beat();
+  return {
+    beat,
+    stop: () => {
+      if (interval !== void 0) clearInterval(interval);
+      channel.removeEventListener("message", onMessage);
+      channel.close();
+    }
+  };
+}
+function startWorkerRpcRelay(channelName, bridge, options = {}) {
+  return serveChannel(
+    new BroadcastChannel(channelName),
+    bridge,
+    "worker",
+    options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS
+  );
+}
+var TransactionSerializingWorkerBridge = class {
+  inner;
+  leaderClientId = createClientId();
+  transactionIdleTimeoutMs;
+  queue = [];
+  activeTransactionClient = null;
+  abortedClients = /* @__PURE__ */ new Set();
+  transactionIdleTimer = null;
+  reclaiming = false;
+  processing = false;
+  terminated = false;
+  constructor(inner, transactionIdleTimeoutMs = DEFAULT_TRANSACTION_IDLE_TIMEOUT_MS) {
+    this.inner = inner;
+    this.transactionIdleTimeoutMs = transactionIdleTimeoutMs;
+  }
+  send(request, clientId = this.leaderClientId) {
+    if (this.terminated) {
+      return Promise.resolve({
+        id: request.id,
+        type: "error",
+        message: "Worker has been terminated",
+        code: "WORKER_TERMINATED"
+      });
+    }
+    if (this.abortedClients.has(clientId)) {
+      if (request.type === "begin") {
+        this.abortedClients.delete(clientId);
+      } else {
+        return Promise.resolve({
+          id: request.id,
+          type: "error",
+          message: "Previous transaction was aborted because the client stopped sending requests.",
+          code: "TRANSACTION_ABORTED"
+        });
+      }
+    }
+    return new Promise((resolve, reject) => {
+      this.queue.push({ clientId, request, resolve, reject });
+      void this.processQueue();
+    });
+  }
+  terminate() {
+    if (this.terminated) {
+      return;
+    }
+    this.terminated = true;
+    this.clearTransactionIdleTimer();
+    this.inner.terminate();
+    const pending = this.queue.splice(0);
+    for (const entry of pending) {
+      entry.reject(new BridgeTerminatedError(entry.request.type, "worker terminated"));
+    }
+  }
+  reclaimClient(clientId, reason) {
+    if (this.terminated) {
+      return;
+    }
+    void this.reclaimClientNow(clientId, reason);
+  }
+  async processQueue() {
+    if (this.processing || this.reclaiming) {
+      return;
+    }
+    this.processing = true;
+    try {
+      while (!this.terminated) {
+        const index = this.nextRunnableIndex();
+        if (index === -1) {
+          return;
+        }
+        const [entry] = this.queue.splice(index, 1);
+        if (!entry) {
+          return;
+        }
+        try {
+          const response = await this.inner.send(entry.request);
+          this.recordTransactionState(entry, response);
+          entry.resolve(response);
+        } catch (error) {
+          this.resetFailedTransaction(entry);
+          entry.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+      }
+    } finally {
+      this.processing = false;
+      if (!this.terminated && !this.reclaiming && this.nextRunnableIndex() !== -1) {
+        void this.processQueue();
+      }
+    }
+  }
+  nextRunnableIndex() {
+    if (this.queue.length === 0) {
+      return -1;
+    }
+    if (this.activeTransactionClient === null) {
+      return 0;
+    }
+    return this.queue.findIndex((entry) => entry.clientId === this.activeTransactionClient);
+  }
+  recordTransactionState(entry, response) {
+    if (response.type === "error") {
+      this.resetFailedTransaction(entry);
+      return;
+    }
+    if (entry.request.type === "begin") {
+      this.activeTransactionClient = entry.clientId;
+      this.armTransactionIdleTimer(entry.clientId);
+      return;
+    }
+    if (this.activeTransactionClient === entry.clientId) {
+      this.armTransactionIdleTimer(entry.clientId);
+    }
+    if (this.activeTransactionClient === entry.clientId && (entry.request.type === "commit" || entry.request.type === "rollback")) {
+      this.activeTransactionClient = null;
+      this.clearTransactionIdleTimer();
+    }
+  }
+  resetFailedTransaction(entry) {
+    if (this.activeTransactionClient === entry.clientId) {
+      this.activeTransactionClient = null;
+      this.clearTransactionIdleTimer();
+    }
+  }
+  armTransactionIdleTimer(clientId) {
+    this.clearTransactionIdleTimer();
+    this.transactionIdleTimer = setTimeout(() => {
+      void this.reclaimClientNow(clientId, "transaction-idle-timeout");
+    }, this.transactionIdleTimeoutMs);
+  }
+  clearTransactionIdleTimer() {
+    if (this.transactionIdleTimer) {
+      clearTimeout(this.transactionIdleTimer);
+      this.transactionIdleTimer = null;
+    }
+  }
+  async reclaimClientNow(clientId, reason) {
+    if (this.reclaiming || this.activeTransactionClient !== clientId) {
+      return;
+    }
+    this.reclaiming = true;
+    this.clearTransactionIdleTimer();
+    this.activeTransactionClient = null;
+    this.abortedClients.add(clientId);
+    this.rejectQueuedClientRequests(clientId, reason);
+    try {
+      const response = await this.inner.send({ id: 0, type: "rollback" });
+      if (response.type === "error") {
+      }
+    } catch {
+    } finally {
+      this.reclaiming = false;
+      if (!this.terminated && this.nextRunnableIndex() !== -1) {
+        void this.processQueue();
+      }
+    }
+  }
+  rejectQueuedClientRequests(clientId, reason) {
+    const keep = [];
+    for (const entry of this.queue) {
+      if (entry.clientId === clientId) {
+        entry.resolve({
+          id: entry.request.id,
+          type: "error",
+          message: `Transaction client was reclaimed: ${reason}`,
+          code: "TRANSACTION_ABORTED"
+        });
+      } else {
+        keep.push(entry);
+      }
+    }
+    this.queue = keep;
+  }
+};
+function hasReclaimClient(bridge) {
+  return typeof bridge.reclaimClient === "function";
+}
+function createClientId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+// src/migrations/schema-ceiling.ts
+var DIRECTIVE = /^--kora:schema-ceiling (\d+)$/;
+function parseSchemaCeiling(sql) {
+  const match = DIRECTIVE.exec(sql.trim());
+  return match ? Number(match[1]) : null;
+}
+function storedSchemaVersion(rows) {
+  const value = Number(rows[0]?.value ?? 0);
+  return Number.isFinite(value) ? value : 0;
+}
+function schemaAheadMessage(stored, code) {
+  return `KORA_SCHEMA_VERSION_AHEAD stored=${stored} code=${code}: the database was migrated by a newer build (schema version ${stored}); this build's schema version is ${code}.`;
+}
+var STORED_SCHEMA_VERSION_SQL = "SELECT value FROM _kora_meta WHERE key = 'schema_version'";
+
+// src/adapters/opfs-pool-ownership.ts
+var OPFS_POOL_HEADROOM = 2;
+var BLOCKED_REPORT_AFTER_MS = 750;
+var INSTALL_RACE_ATTEMPTS = 20;
 var OPFS_INIT_TIMEOUT_MS = 1e4;
+var OPAQUE_DIR_NAME = ".opaque";
+var PoolUnavailableError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "PoolUnavailableError";
+  }
+  reason;
+};
+function opfsSahSupported(sqlite3) {
+  const g = globalThis;
+  const fileHandle = g.FileSystemFileHandle;
+  return typeof sqlite3.installOpfsSAHPoolVfs === "function" && typeof g.FileSystemDirectoryHandle !== "undefined" && typeof fileHandle?.prototype?.createSyncAccessHandle === "function" && typeof navigator !== "undefined" && typeof navigator.storage?.getDirectory === "function";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function withTimeout(promise, timeoutMs, label) {
   let timer;
   try {
@@ -32,7 +397,7 @@ async function withTimeout(promise, timeoutMs, label) {
       promise,
       new Promise((_, reject) => {
         timer = setTimeout(
-          () => reject(new Error(`${label} timed out after ${timeoutMs}ms`)),
+          () => reject(new PoolUnavailableError(`${label} timed out after ${timeoutMs}ms`, "timeout")),
           timeoutMs
         );
       })
@@ -41,25 +406,253 @@ async function withTimeout(promise, timeoutMs, label) {
     if (timer !== void 0) clearTimeout(timer);
   }
 }
-function opfsDatabaseFilename(dbName) {
-  const base = dbName.replace(/[^a-zA-Z0-9._-]/g, "_");
-  return base.endsWith(".db") ? base : `${base}.db`;
+async function holdExclusiveLock(name, reporter) {
+  const locks = typeof navigator !== "undefined" ? navigator.locks : void 0;
+  if (!locks || typeof locks.request !== "function") {
+    return () => {
+    };
+  }
+  const grab = (ifAvailable) => new Promise((resolve, reject) => {
+    locks.request(name, { mode: "exclusive", ifAvailable }, (lock) => {
+      if (lock === null) {
+        resolve(null);
+        return void 0;
+      }
+      return new Promise((release2) => {
+        resolve(() => release2());
+      });
+    }).catch(reject);
+  });
+  const immediate = await grab(true);
+  if (immediate) return immediate;
+  const start = Date.now();
+  reporter?.blocked();
+  const release = await grab(false);
+  if (!release) {
+    throw new PoolUnavailableError(`Web Lock "${name}" was not granted`, "lock-conflict");
+  }
+  reporter?.unblocked(Date.now() - start);
+  return release;
+}
+async function opfsRoot() {
+  return await navigator.storage.getDirectory();
 }
-function classifyOpfsFailure(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  if (/timed out|timeout/i.test(message)) {
-    return "timeout";
+async function childDirectory(parent, name) {
+  try {
+    return await parent.getDirectoryHandle(name);
+  } catch {
+    return null;
   }
-  if (/lock|already|in use|in-use|NoModificationAllowed|acquire|SyncAccessHandle|being created/i.test(
-    message
-  )) {
-    return "lock-conflict";
+}
+async function poolDirectoryExists(poolName) {
+  return await childDirectory(await opfsRoot(), opfsPoolDirectory(poolName)) !== null;
+}
+function isHandleBusy(error) {
+  const name = error?.name;
+  return name === "NoModificationAllowedError" || name === "InvalidStateError";
+}
+async function poolHandlesBusy(poolName) {
+  const dir = await childDirectory(await opfsRoot(), opfsPoolDirectory(poolName));
+  if (!dir) return false;
+  const opaque = await childDirectory(dir, OPAQUE_DIR_NAME);
+  if (!opaque) return false;
+  for await (const [, handle] of opaque.entries()) {
+    if (handle.kind !== "file") continue;
+    try {
+      const access = await handle.createSyncAccessHandle();
+      access.close();
+    } catch (error) {
+      if (isHandleBusy(error)) return true;
+      throw error;
+    }
+  }
+  return false;
+}
+async function waitForPoolHandles(poolName, reporter) {
+  const start = Date.now();
+  let reported = false;
+  let delay = 15;
+  while (await poolHandlesBusy(poolName)) {
+    if (!reported && Date.now() - start >= BLOCKED_REPORT_AFTER_MS) {
+      reported = true;
+      reporter?.blocked();
+    }
+    await sleep(delay);
+    delay = Math.min(delay * 2, 500);
+  }
+  if (reported) reporter?.unblocked(Date.now() - start);
+}
+async function installPool(sqlite3, poolName, reporter) {
+  const install = sqlite3.installOpfsSAHPoolVfs;
+  if (!install || !opfsSahSupported(sqlite3)) {
+    throw new PoolUnavailableError("OPFS SyncAccessHandle pool is not supported", "unsupported");
   }
-  return "unsupported";
+  let lastError = null;
+  for (let attempt = 0; attempt < INSTALL_RACE_ATTEMPTS; attempt += 1) {
+    await waitForPoolHandles(poolName, reporter);
+    try {
+      const pool = await withTimeout(
+        install({ name: poolName, forceReinitIfPreviouslyFailed: true }),
+        OPFS_INIT_TIMEOUT_MS,
+        "OPFS VFS install"
+      );
+      if (pool.isPaused()) {
+        await pool.unpauseVfs();
+      }
+      return pool;
+    } catch (error) {
+      if (error instanceof PoolUnavailableError) throw error;
+      lastError = error;
+      if (!isHandleBusy(error)) break;
+      await sleep(Math.min(25 * 2 ** attempt, 250));
+    }
+  }
+  const message = lastError instanceof Error ? lastError.message : String(lastError);
+  if (isHandleBusy(lastError)) {
+    throw new PoolUnavailableError(
+      `OPFS pool "${poolName}" stayed busy: ${message}`,
+      "lock-conflict"
+    );
+  }
+  throw new PoolUnavailableError(
+    `OPFS pool "${poolName}" could not be installed: ${message}`,
+    "unsupported"
+  );
+}
+async function ensurePoolCapacity(pool) {
+  await pool.reserveMinimumCapacity(pool.getFileCount() + 2 + OPFS_POOL_HEADROOM);
 }
+function assertDatabaseHealthy(db, label) {
+  const rows = db.exec({
+    sql: "PRAGMA quick_check",
+    returnValue: "resultRows",
+    rowMode: "array"
+  });
+  const verdict = rows?.[0]?.[0];
+  if (verdict !== "ok") {
+    throw new Error(`${label} failed integrity check: ${String(verdict)}`);
+  }
+}
+function pausePool(pool) {
+  if (!pool.isPaused()) {
+    pool.pauseVfs();
+  }
+}
+async function migrateFromLegacyPool(sqlite3, target, poolPath, reporter) {
+  if (!await poolDirectoryExists(LEGACY_OPFS_POOL_NAME)) {
+    return false;
+  }
+  const releaseLegacyLock = await holdExclusiveLock(
+    opfsPoolLockName(LEGACY_OPFS_POOL_NAME),
+    reporter
+  );
+  try {
+    if (!await poolDirectoryExists(LEGACY_OPFS_POOL_NAME)) {
+      return false;
+    }
+    const legacy = await installPool(sqlite3, LEGACY_OPFS_POOL_NAME, reporter);
+    try {
+      if (!legacy.getFileNames().includes(poolPath)) {
+        return false;
+      }
+      const legacyDb = new legacy.OpfsSAHPoolDb(poolPath);
+      try {
+        assertDatabaseHealthy(legacyDb, `Legacy database ${poolPath}`);
+      } finally {
+        legacyDb.close();
+      }
+      const bytes = legacy.exportFile(poolPath);
+      if (bytes.byteLength === 0) {
+        legacy.unlink(poolPath);
+        return false;
+      }
+      await ensurePoolCapacity(target);
+      await target.importDb(poolPath, bytes);
+      let migratedDb = null;
+      try {
+        migratedDb = new target.OpfsSAHPoolDb(poolPath);
+        assertDatabaseHealthy(migratedDb, `Migrated database ${poolPath}`);
+      } catch (error) {
+        migratedDb?.close();
+        migratedDb = null;
+        target.unlink(poolPath);
+        throw error;
+      }
+      migratedDb.close();
+      legacy.unlink(poolPath);
+      legacy.unlink(`${poolPath}-journal`);
+      return true;
+    } finally {
+      if (legacy.getFileCount() === 0) {
+        await legacy.removeVfs();
+      } else {
+        pausePool(legacy);
+      }
+    }
+  } finally {
+    releaseLegacyLock();
+  }
+}
+
+// src/adapters/sqlite-wasm-loader.ts
+var SQLITE_INIT_TIMEOUT_MS = 6e4;
+async function loadSqliteModule(init, options = {}) {
+  const timeoutMs = options.timeoutMs ?? SQLITE_INIT_TIMEOUT_MS;
+  const source = options.unhandledRejections ?? globalUnhandledRejections;
+  let timer;
+  let unsubscribe;
+  try {
+    return await Promise.race([
+      init(options.initOptions),
+      new Promise((_, reject) => {
+        unsubscribe = source((reason) => {
+          if (!isWasmLoadFailure(reason)) return;
+          reject(
+            new WorkerInitError(
+              `could not load the SQLite WebAssembly binary (sqlite3.wasm): ${describe(reason)}. The device may be offline before the app was cached, or the file is not served (check the URL and the application/wasm MIME type).`,
+              { cause: describe(reason) }
+            )
+          );
+        });
+        timer = setTimeout(
+          () => reject(
+            new WorkerInitError(`SQLite3 module init timed out after ${String(timeoutMs)}ms`)
+          ),
+          timeoutMs
+        );
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+    unsubscribe?.();
+  }
+}
+function isWasmLoadFailure(reason) {
+  if (reason instanceof TypeError) return true;
+  const wasm = globalThis.WebAssembly;
+  if (!wasm) return false;
+  for (const name of ["CompileError", "LinkError", "RuntimeError"]) {
+    const ctor = wasm[name];
+    if (typeof ctor === "function" && reason instanceof ctor) return true;
+  }
+  return false;
+}
+function describe(reason) {
+  return reason instanceof Error ? reason.message : String(reason);
+}
+var globalUnhandledRejections = (listener) => {
+  const scope = globalThis;
+  if (typeof scope.addEventListener !== "function") return () => {
+  };
+  const handler = (event) => listener(event.reason);
+  scope.addEventListener("unhandledrejection", handler);
+  return () => scope.removeEventListener?.("unhandledrejection", handler);
+};
+
+// src/adapters/sqlite-wasm-worker-core.ts
+var PROGRESS_HEARTBEAT_MS = 500;
+var PROGRESS_HANDLER_OPS = 2e4;
 var sqlite3Promise = null;
-var opfsPoolPromise = null;
-var opfsFallbackReason;
 async function loadSqlite3() {
   const sqlite3InitModule = (await import("@sqlite.org/sqlite-wasm")).default;
   const wasmUrl = globalThis.__KORA_SQLITE_WASM_URL;
@@ -67,72 +660,225 @@ async function loadSqlite3() {
     locateFile: (file) => file.endsWith(".wasm") ? wasmUrl : file
   } : void 0;
   const initFn = sqlite3InitModule;
-  return await withTimeout(initFn(initOptions), 6e4, "SQLite3 module init");
+  return loadSqliteModule(initFn, initOptions ? { initOptions } : {});
 }
 function getSqlite3() {
   if (!sqlite3Promise) {
-    sqlite3Promise = loadSqlite3();
+    const loading = loadSqlite3();
+    sqlite3Promise = loading;
+    loading.catch(() => {
+      if (sqlite3Promise === loading) sqlite3Promise = null;
+    });
   }
   return sqlite3Promise;
 }
-async function installOpfsPool(sqlite3) {
-  if (!sqlite3.installOpfsSAHPoolVfs) {
-    opfsFallbackReason = "unsupported";
-    return null;
+function createSqliteWasmCore(options = {}) {
+  let db = null;
+  let sqlite3Api = null;
+  let persistent = false;
+  let fallbackReason;
+  let pool = null;
+  let poolName = null;
+  let releasePoolLock = null;
+  let openInfo = {
+    created: false,
+    migratedFromLegacy: false
+  };
+  let lastProgressBeat = 0;
+  function reporterFor(resource, name) {
+    return {
+      blocked: () => options.postEvent?.({ kind: "storage-blocked", resource, poolName: name }),
+      unblocked: (waitedMs) => options.postEvent?.({ kind: "storage-unblocked", resource, poolName: name, waitedMs })
+    };
   }
-  try {
-    return await withTimeout(
-      sqlite3.installOpfsSAHPoolVfs({ name: OPFS_POOL_NAME }),
-      OPFS_INIT_TIMEOUT_MS,
-      "OPFS VFS install"
+  async function releaseStorage(mode) {
+    if (db) {
+      detachProgressHandler(db);
+      try {
+        db.close();
+      } finally {
+        db = null;
+      }
+    }
+    if (pool) {
+      if (mode === "remove") {
+        await pool.removeVfs();
+      } else {
+        pausePool(pool);
+      }
+      pool = null;
+    }
+    releasePoolLock?.();
+    releasePoolLock = null;
+  }
+  function attachProgressHandler(target) {
+    const register = sqlite3Api?.capi?.sqlite3_progress_handler;
+    if (!options.onProgress || typeof register !== "function" || !target.pointer) return;
+    register(
+      target.pointer,
+      PROGRESS_HANDLER_OPS,
+      () => {
+        const now = Date.now();
+        if (now - lastProgressBeat >= PROGRESS_HEARTBEAT_MS) {
+          lastProgressBeat = now;
+          options.onProgress?.();
+        }
+        return 0;
+      },
+      0
     );
-  } catch (error) {
-    opfsFallbackReason = classifyOpfsFailure(error);
-    return null;
   }
-}
-function getOpfsPool(sqlite3) {
-  if (!opfsPoolPromise) {
-    opfsPoolPromise = installOpfsPool(sqlite3);
+  function detachProgressHandler(target) {
+    const register = sqlite3Api?.capi?.sqlite3_progress_handler;
+    if (typeof register !== "function" || !target.pointer) return;
+    try {
+      register(target.pointer, 0, 0, 0);
+    } catch {
+    }
   }
-  return opfsPoolPromise;
-}
-function createSqliteWasmCore() {
-  let db = null;
-  let sqlite3Api = null;
-  let persistent = false;
-  async function open(id, ddlStatements, dbName) {
+  async function openOpfs(sqlite3, dbName, mustExist) {
+    const name = opfsPoolNameFor(dbName);
+    const path = opfsPoolPath(dbName);
+    poolName = name;
+    releasePoolLock = await holdExclusiveLock(opfsPoolLockName(name), reporterFor("pool", name));
+    pool = await installPool(sqlite3, name, reporterFor("pool", name));
+    let migratedFromLegacy = false;
+    if (!pool.getFileNames().includes(path)) {
+      migratedFromLegacy = await migrateFromLegacyPool(
+        sqlite3,
+        pool,
+        path,
+        reporterFor("legacy-pool", name)
+      );
+    }
+    const existedBefore = pool.getFileNames().includes(path);
+    if (!existedBefore && mustExist) {
+      await releaseStorage(pool.getFileCount() === 0 ? "remove" : "pause");
+      return { id: 0, type: "error", message: `Database file ${path} not found`, code: "NOT_FOUND" };
+    }
+    await ensurePoolCapacity(pool);
     try {
-      if (db) {
+      db = new pool.OpfsSAHPoolDb(path);
+    } catch (error) {
+      if (!existedBefore) pool.unlink(path);
+      throw error;
+    }
+    persistent = true;
+    openInfo = { created: !existedBefore, migratedFromLegacy };
+    return null;
+  }
+  async function open(id, ddlStatements, dbName, storage, mustExist) {
+    if (db) {
+      try {
         applyDdl(db, ddlStatements);
         return { id, type: "success", data: buildOpenData() };
+      } catch (error) {
+        return { id, type: "error", message: error.message, code: "INIT_ERROR" };
       }
+    }
+    let createdPath = null;
+    try {
       const sqlite3 = await getSqlite3();
       sqlite3Api = sqlite3;
-      const pool = await getOpfsPool(sqlite3);
-      if (pool) {
-        db = new pool.OpfsSAHPoolDb(opfsDatabaseFilename(dbName ?? "kora-db"));
-        persistent = true;
+      if (storage === "opfs" && opfsSahSupported(sqlite3)) {
+        try {
+          const early = await openOpfs(sqlite3, dbName, mustExist);
+          if (early) return { ...early, id };
+          if (openInfo.created) createdPath = opfsPoolPath(dbName);
+        } catch (error) {
+          if (!(error instanceof PoolUnavailableError) || error.reason === "lock-conflict") {
+            throw error;
+          }
+          await releaseStorage("pause");
+          fallbackReason = error.reason;
+        }
       } else {
+        fallbackReason = "unsupported";
+      }
+      if (!db) {
         db = new sqlite3.oo1.DB({ filename: ":memory:" });
         persistent = false;
       }
-      db.exec({ sql: "PRAGMA journal_mode = WAL" });
       db.exec({ sql: "PRAGMA foreign_keys = ON" });
       applyDdl(db, ddlStatements);
+      attachProgressHandler(db);
       return { id, type: "success", data: buildOpenData() };
     } catch (error) {
-      return { id, type: "error", message: error.message, code: "INIT_ERROR" };
+      const currentPool = pool;
+      if (db) {
+        try {
+          db.close();
+        } catch {
+        }
+        db = null;
+      }
+      if (createdPath && currentPool) {
+        try {
+          currentPool.unlink(createdPath);
+          currentPool.unlink(`${createdPath}-journal`);
+        } catch {
+        }
+      }
+      try {
+        await releaseStorage("pause");
+      } catch {
+      }
+      const reason = error instanceof PoolUnavailableError ? error.reason : void 0;
+      return {
+        id,
+        type: "error",
+        message: error.message,
+        code: "INIT_ERROR",
+        context: {
+          ...reason ? { reason } : {},
+          ...createdPath ? { removedCreatedFile: createdPath } : {}
+        }
+      };
+    }
+  }
+  function readJournalMode() {
+    if (!db) return void 0;
+    try {
+      let mode;
+      db.exec({
+        sql: "PRAGMA journal_mode",
+        rowMode: "object",
+        callback: (row) => {
+          if (typeof row.journal_mode === "string") mode = row.journal_mode;
+        }
+      });
+      return mode;
+    } catch {
+      return void 0;
     }
   }
   function buildOpenData() {
+    const journalMode = readJournalMode();
     return {
+      ...journalMode ? { journalMode } : {},
       persistent,
-      ...persistent ? {} : { fallbackReason: opfsFallbackReason ?? "unsupported" }
+      ...persistent ? {} : { fallbackReason: fallbackReason ?? "unsupported" },
+      ...poolName && persistent ? { poolName } : {},
+      created: openInfo.created,
+      migratedFromLegacy: openInfo.migratedFromLegacy
     };
   }
   function applyDdl(target, ddlStatements) {
     for (const sql of ddlStatements) {
+      const ceiling = parseSchemaCeiling(sql);
+      if (ceiling !== null) {
+        const rows = [];
+        target.exec({
+          sql: STORED_SCHEMA_VERSION_SQL,
+          rowMode: "object",
+          callback: (row) => {
+            rows.push({ value: row.value });
+          }
+        });
+        const stored = storedSchemaVersion(rows);
+        if (stored > ceiling) throw new Error(schemaAheadMessage(stored, ceiling));
+        continue;
+      }
       if (sql.startsWith("--kora:safe-alter")) {
         try {
           target.exec({ sql: sql.replace("--kora:safe-alter\n", "") });
@@ -177,12 +923,13 @@ function createSqliteWasmCore() {
       return { id, type: "error", message: error.message, code: "QUERY_ERROR" };
     }
   }
-  function close(id) {
-    if (db) {
-      db.close();
-      db = null;
+  async function close(id, mode) {
+    try {
+      await releaseStorage(mode);
+      return { id, type: "success" };
+    } catch (error) {
+      return { id, type: "error", message: error.message, code: "CLOSE_ERROR" };
     }
-    return { id, type: "success" };
   }
   function migrate(id, statements) {
     if (!db) {
@@ -201,10 +948,9 @@ function createSqliteWasmCore() {
     if (!db) {
       return { id, type: "error", message: "Database is not open", code: "DB_NOT_OPEN" };
     }
-    const dbWithDeserialize = db;
-    if (typeof dbWithDeserialize.deserialize === "function") {
+    if (typeof db.deserialize === "function") {
       try {
-        dbWithDeserialize.deserialize(data);
+        db.deserialize(data);
         return { id, type: "success" };
       } catch (error) {
         return { id, type: "error", message: error.message, code: "IMPORT_ERROR" };
@@ -229,9 +975,17 @@ function createSqliteWasmCore() {
     try {
       switch (request.type) {
         case "open":
-          return await open(request.id, request.ddlStatements, request.dbName);
+          return await open(
+            request.id,
+            request.ddlStatements,
+            request.dbName ?? "kora-db",
+            request.storage ?? "opfs",
+            request.mustExist === true
+          );
         case "close":
-          return close(request.id);
+          return await close(request.id, "pause");
+        case "destroy":
+          return await close(request.id, "remove");
         case "execute":
           return execute(request.id, request.sql, request.params);
         case "query":
@@ -253,6 +1007,8 @@ function createSqliteWasmCore() {
             message: "Export not yet supported in browser worker",
             code: "EXPORT_NOT_SUPPORTED"
           };
+        case "serve":
+          return { id: request.id, type: "success" };
         default:
           return {
             id: request.id,
@@ -274,10 +1030,47 @@ function createSqliteWasmCore() {
 }
 
 // src/adapters/sqlite-wasm-worker.ts
-var core = createSqliteWasmCore();
+var relay = null;
+var core = createSqliteWasmCore({
+  postEvent: (event) => {
+    const message = { id: -1, type: "event", event };
+    self.postMessage(message);
+  },
+  // Keep followers' watchdogs fed while a long statement blocks this worker.
+  onProgress: () => relay?.beat()
+});
+var serializer = new TransactionSerializingWorkerBridge({
+  send: (request) => core.handle(request),
+  terminate: () => {
+  }
+});
 self.onmessage = (event) => {
-  void core.handle(event.data).then((response) => {
+  const { clientId, ...request } = event.data;
+  if (request.type === "serve") {
+    if (!relay) {
+      relay = startWorkerRpcRelay(request.channelName, serializer);
+    }
+    const response = { id: request.id, type: "success" };
     self.postMessage(response);
-  });
+    return;
+  }
+  void serializer.send(request, clientId).then(
+    (response) => {
+      if (request.type === "close" || request.type === "destroy") {
+        relay?.stop();
+        relay = null;
+      }
+      self.postMessage(response);
+    },
+    (error) => {
+      const response = {
+        id: request.id,
+        type: "error",
+        message: error instanceof Error ? error.message : String(error),
+        code: "WORKER_ERROR"
+      };
+      self.postMessage(response);
+    }
+  );
 };
 //# sourceMappingURL=sqlite-wasm-worker.cjs.map