@korajs/store 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/adapters/indexeddb.cjs

@@ -21,7 +21,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/errors.ts
-var import_core, AdapterError, StoreNotOpenError, WorkerTimeoutError, PersistenceError;
+var import_core, AdapterError, StoreNotOpenError, WorkerTimeoutError, NoLeaderError, PersistenceError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -48,6 +48,16 @@ var init_errors = __esm({
         this.name = "WorkerTimeoutError";
       }
     };
+    NoLeaderError = class extends import_core.KoraError {
+      constructor(operation) {
+        super(
+          `No live leader tab is answering multi-tab storage RPC for operation "${operation}"`,
+          "NO_LEADER",
+          { operation }
+        );
+        this.name = "NoLeaderError";
+      }
+    };
     PersistenceError = class extends import_core.KoraError {
       constructor(message, context) {
         super(`Persistence error: ${message}`, "PERSISTENCE_ERROR", context);
@@ -190,6 +200,7 @@ __export(indexeddb_exports, {
 module.exports = __toCommonJS(indexeddb_exports);
 
 // src/adapters/indexeddb-adapter.ts
+var import_core3 = require("@korajs/core");
 init_errors();
 
 // src/adapters/indexeddb-persistence-scheduler.ts
@@ -271,130 +282,86 @@ var IndexedDbPersistenceScheduler = class {
 var import_core2 = require("@korajs/core");
 init_errors();
 
-// src/multi-tab/shared-worker-bridge.ts
-init_errors();
-var SW_REQUEST = "kora-sw-request";
-var SW_RESPONSE = "kora-sw-response";
-var SharedWorkerClientBridge = class {
-  constructor(sharedWorker, dbName, workerUrl, timeoutMs = 3e4) {
-    this.dbName = dbName;
-    this.workerUrl = workerUrl;
-    this.timeoutMs = timeoutMs;
-    this.port = sharedWorker.port;
-    this.port.start();
-    this.port.addEventListener("message", (event) => {
-      const data = event.data;
-      if (data?.type !== SW_RESPONSE) {
-        return;
-      }
-      const entry = this.pending.get(data.requestId);
-      if (entry) {
-        this.pending.delete(data.requestId);
-        entry.resolve(data.response);
-      }
-    });
-  }
-  dbName;
-  workerUrl;
-  port;
-  pending = /* @__PURE__ */ new Map();
-  timeoutMs;
-  terminated = false;
-  async send(request) {
-    if (this.terminated) {
-      return {
-        id: request.id,
-        type: "error",
-        message: "SharedWorker bridge terminated",
-        code: "BRIDGE_TERMINATED"
-      };
-    }
-    const requestId = crypto.randomUUID();
-    const msg = {
-      type: SW_REQUEST,
-      requestId,
-      dbName: this.dbName,
-      workerUrl: this.workerUrl,
-      request
-    };
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pending.delete(requestId);
-        reject(new WorkerTimeoutError(`shared-worker:${request.type}`, this.timeoutMs));
-      }, this.timeoutMs);
-      this.pending.set(requestId, {
-        resolve: (response) => {
-          clearTimeout(timer);
-          resolve(response);
-        },
-        reject: (error) => {
-          clearTimeout(timer);
-          reject(error);
-        }
-      });
-      this.port.postMessage(msg);
-    });
-  }
-  terminate() {
-    if (this.terminated) {
-      return;
-    }
-    this.terminated = true;
-    this.port.close();
-    for (const [, entry] of this.pending) {
-      entry.reject(new Error("SharedWorker bridge terminated"));
-    }
-    this.pending.clear();
-  }
-};
-
 // src/multi-tab/tab-storage.ts
 init_errors();
 var RPC_REQUEST = "kora-worker-request";
 var RPC_RESPONSE = "kora-worker-response";
-function isSharedWorkerStorageSupported() {
-  return typeof globalThis !== "undefined" && typeof SharedWorker !== "undefined";
-}
+var CLIENT_LEAVE = "kora-client-leave";
+var LEADER_PING = "kora-leader-ping";
+var LEADER_PONG = "kora-leader-pong";
+var DEFAULT_LIVENESS_PROBE_MS = 2e3;
+var DEFAULT_TRANSACTION_IDLE_TIMEOUT_MS = 1e4;
 function isMultiTabStorageSupported() {
   return typeof globalThis !== "undefined" && typeof BroadcastChannel !== "undefined" && typeof navigator !== "undefined" && typeof navigator.locks?.request === "function";
 }
-async function acquireTabStorageSession(dbName) {
+async function acquireTabStorageSession(dbName, options) {
   const channelName = `kora-storage-${dbName}`;
+  const lockName = `kora-leader-${dbName}`;
   if (!isMultiTabStorageSupported()) {
     return { role: "leader", channelName };
   }
   return new Promise((resolve) => {
     let releaseHeld;
-    void navigator.locks.request(
-      `kora-leader-${dbName}`,
-      { mode: "exclusive", ifAvailable: true },
-      (lock) => {
-        if (lock === null) {
-          resolve({ role: "follower", channelName });
-          return;
-        }
-        resolve({
-          role: "leader",
-          channelName,
-          releaseLock: async () => {
-            releaseHeld?.();
-          }
-        });
-        return new Promise((release) => {
-          releaseHeld = release;
-        });
+    void navigator.locks.request(lockName, { mode: "exclusive", ifAvailable: true }, (lock) => {
+      if (lock === null) {
+        resolve(startFollowerSession(channelName, lockName, options));
+        return;
       }
-    );
+      resolve({
+        role: "leader",
+        channelName,
+        releaseLock: async () => {
+          releaseHeld?.();
+        }
+      });
+      return new Promise((release) => {
+        releaseHeld = release;
+      });
+    });
+  });
+}
+function startFollowerSession(channelName, lockName, options) {
+  let promoted = false;
+  let releasePromotedLock;
+  const abort = new AbortController();
+  void navigator.locks.request(lockName, { mode: "exclusive", signal: abort.signal }, () => {
+    promoted = true;
+    options?.onPromote?.();
+    return new Promise((release) => {
+      releasePromotedLock = release;
+    });
+  }).catch(() => {
   });
+  return {
+    role: "follower",
+    channelName,
+    cancelPromotionWatch: () => {
+      if (promoted) {
+        releasePromotedLock?.();
+      } else {
+        abort.abort();
+      }
+    }
+  };
 }
 function startLeaderRpcRelay(channelName, bridge) {
   const channel = new BroadcastChannel(channelName);
   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;
     }
-    void bridge.send(data.request).then((response) => {
+    void bridge.send(data.request, data.clientId).then((response) => {
       const msg = {
         type: RPC_RESPONSE,
         requestId: data.requestId,
@@ -424,12 +391,21 @@ function startLeaderRpcRelay(channelName, bridge) {
 }
 var FollowerBroadcastBridge = class {
   channel;
+  clientId = createClientId();
+  onPageHide = () => {
+    this.leaveLeader();
+  };
   pending = /* @__PURE__ */ new Map();
   timeoutMs;
+  livenessProbeMs;
   terminated = false;
-  constructor(channelName, timeoutMs = 3e4) {
+  constructor(channelName, timeoutMs = 3e4, livenessProbeMs = DEFAULT_LIVENESS_PROBE_MS) {
     this.timeoutMs = timeoutMs;
+    this.livenessProbeMs = Math.min(livenessProbeMs, timeoutMs);
     this.channel = new BroadcastChannel(channelName);
+    if (typeof addEventListener === "function") {
+      addEventListener("pagehide", this.onPageHide);
+    }
     this.channel.addEventListener("message", (event) => {
       const data = event.data;
       if (data?.type !== RPC_RESPONSE) {
@@ -442,6 +418,48 @@ var FollowerBroadcastBridge = class {
       }
     });
   }
+  /**
+   * Readiness handshake: resolves `true` as soon as a live leader answers a ping,
+   * or `false` if none answers within the budget. The adapter calls this before
+   * its first RPC so a follower created before a leader relay is live retries the
+   * handshake instead of firing into the void and waiting out the full timeout.
+   */
+  async waitForLeader(timeoutMs = 3e3, attempts = 3) {
+    const perAttempt = Math.max(50, Math.floor(timeoutMs / Math.max(1, attempts)));
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      if (this.terminated) {
+        return false;
+      }
+      if (await this.pingLeader(perAttempt)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /** Sends one liveness ping and resolves whether a leader answered in time. */
+  pingLeader(timeoutMs) {
+    if (this.terminated) {
+      return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+      const onPong = (event) => {
+        if (event.data?.type === LEADER_PONG) {
+          cleanup();
+          resolve(true);
+        }
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.channel.removeEventListener("message", onPong);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve(false);
+      }, timeoutMs);
+      this.channel.addEventListener("message", onPong);
+      this.channel.postMessage({ type: LEADER_PING });
+    });
+  }
   async send(request) {
     if (this.terminated) {
       return {
@@ -451,22 +469,33 @@ var FollowerBroadcastBridge = class {
         code: "BRIDGE_TERMINATED"
       };
     }
-    const requestId = crypto.randomUUID();
-    const msg = { type: RPC_REQUEST, requestId, request };
+    const requestId = createClientId();
+    const msg = {
+      type: RPC_REQUEST,
+      requestId,
+      clientId: this.clientId,
+      request
+    };
     return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
+      const settle = (fn) => {
+        clearTimeout(timer);
+        clearTimeout(probe);
         this.pending.delete(requestId);
-        reject(new WorkerTimeoutError(`follower-rpc:${request.type}`, this.timeoutMs));
+        fn();
+      };
+      const timer = setTimeout(() => {
+        settle(() => reject(new WorkerTimeoutError(`follower-rpc:${request.type}`, this.timeoutMs)));
       }, this.timeoutMs);
+      const probe = setTimeout(() => {
+        void this.pingLeader(this.livenessProbeMs).then((alive) => {
+          if (!alive && this.pending.has(requestId)) {
+            settle(() => reject(new NoLeaderError(`follower-rpc:${request.type}`)));
+          }
+        });
+      }, this.livenessProbeMs);
       this.pending.set(requestId, {
-        resolve: (response) => {
-          clearTimeout(timer);
-          resolve(response);
-        },
-        reject: (error) => {
-          clearTimeout(timer);
-          reject(error);
-        }
+        resolve: (response) => settle(() => resolve(response)),
+        reject: (error) => settle(() => reject(error))
       });
       this.channel.postMessage(msg);
     });
@@ -476,16 +505,213 @@ var FollowerBroadcastBridge = class {
       return;
     }
     this.terminated = true;
+    this.leaveLeader();
+    if (typeof removeEventListener === "function") {
+      removeEventListener("pagehide", this.onPageHide);
+    }
     this.channel.close();
     for (const [, entry] of this.pending) {
       entry.reject(new Error("Follower bridge terminated"));
     }
     this.pending.clear();
   }
+  leaveLeader() {
+    try {
+      const message = {
+        type: CLIENT_LEAVE,
+        clientId: this.clientId
+      };
+      this.channel.postMessage(message);
+    } catch {
+    }
+  }
 };
+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 Error("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/adapters/sqlite-wasm-adapter.ts
 init_sqlite_wasm_channel();
+var warnedSharedWorkerDeprecated = false;
 var SqliteWasmAdapter = class {
   bridge = null;
   opened = false;
@@ -495,43 +721,76 @@ var SqliteWasmAdapter = class {
   sharedWorkerUrl;
   workerResponseTimeoutMs;
   dbName;
+  emitter;
   tabSession = null;
-  sharedWorker = null;
+  emitNonPersistentDiagnostic;
+  storageOpenState = null;
+  /** Retained so a follower promoted to leader can re-open its own worker. */
+  schema = null;
+  promoting = false;
   constructor(options = {}) {
     this.injectedBridge = options.bridge;
     this.workerUrl = options.workerUrl;
     this.sharedWorkerUrl = options.sharedWorkerUrl;
     this.workerResponseTimeoutMs = options.workerResponseTimeoutMs ?? 3e4;
     this.dbName = options.dbName ?? "kora-db";
+    this.emitter = options.emitter;
+    this.emitNonPersistentDiagnostic = options.emitNonPersistentDiagnostic ?? true;
   }
   async open(schema) {
     if (this.opened) return;
+    const ddlStatements = (0, import_core2.generateFullDDL)(schema);
     if (this.injectedBridge) {
       this.bridge = this.injectedBridge;
-    } else if (this.sharedWorkerUrl && this.workerUrl && isSharedWorkerStorageSupported()) {
-      const workerUrlString = typeof this.workerUrl === "string" ? this.workerUrl : this.workerUrl.href;
-      const sharedUrl = typeof this.sharedWorkerUrl === "string" ? this.sharedWorkerUrl : this.sharedWorkerUrl.href;
-      this.sharedWorker = new SharedWorker(sharedUrl, { name: `kora-sw-${this.dbName}` });
-      this.bridge = new SharedWorkerClientBridge(this.sharedWorker, this.dbName, workerUrlString);
-    } else if (this.workerUrl) {
-      this.tabSession = await acquireTabStorageSession(this.dbName);
-      const { WebWorkerBridge: WebWorkerBridge2 } = await Promise.resolve().then(() => (init_sqlite_wasm_channel(), sqlite_wasm_channel_exports));
-      if (this.tabSession.role === "leader") {
-        const workerBridge = new WebWorkerBridge2(this.workerUrl, this.workerResponseTimeoutMs);
-        this.tabSession.stopRelay = startLeaderRpcRelay(this.tabSession.channelName, workerBridge);
-        this.bridge = workerBridge;
-      } else {
-        this.bridge = new FollowerBroadcastBridge(
-          this.tabSession.channelName,
-          this.workerResponseTimeoutMs
-        );
+      const response = await this.openCurrentBridge(ddlStatements);
+      this.reportStorageMode(response.data);
+      this.opened = true;
+      return;
+    }
+    if (this.workerUrl) {
+      this.warnSharedWorkerDeprecated();
+      await this.openDurableWorkerBridge(schema);
+      const response = await this.openCurrentBridge(ddlStatements);
+      this.reportStorageMode(response.data);
+      this.opened = true;
+      return;
+    }
+    throw new AdapterError(
+      'SqliteWasmAdapter requires either a bridge (for testing) or a workerUrl (for browsers). Pass { bridge: new MockWorkerBridge() } for tests, or { workerUrl: "/worker.js" } for browsers.'
+    );
+  }
+  async openDurableWorkerBridge(schema) {
+    if (!this.workerUrl) {
+      throw new AdapterError("Durable SQLite WASM storage requires workerUrl.");
+    }
+    this.schema = schema;
+    this.tabSession = await acquireTabStorageSession(this.dbName, {
+      onPromote: () => {
+        void this.promoteToLeader();
       }
-    } else {
-      throw new AdapterError(
-        'SqliteWasmAdapter requires either a bridge (for testing) or a workerUrl (for browsers). Pass { bridge: new MockWorkerBridge() } for tests, or { workerUrl: "/worker.js" } for browsers.'
+    });
+    const { WebWorkerBridge: WebWorkerBridge2 } = await Promise.resolve().then(() => (init_sqlite_wasm_channel(), sqlite_wasm_channel_exports));
+    if (this.tabSession.role === "leader") {
+      const workerBridge = new TransactionSerializingWorkerBridge(
+        new WebWorkerBridge2(this.workerUrl, this.workerResponseTimeoutMs)
       );
+      this.tabSession.stopRelay = startLeaderRpcRelay(this.tabSession.channelName, workerBridge);
+      this.bridge = workerBridge;
+      return;
     }
-    const ddlStatements = (0, import_core2.generateFullDDL)(schema);
+    const followerBridge = new FollowerBroadcastBridge(
+      this.tabSession.channelName,
+      this.workerResponseTimeoutMs
+    );
+    this.bridge = followerBridge;
+    this.emitter?.emit({
+      type: "store:db-name-collision",
+      dbName: this.dbName,
+      message: `Another runtime on this origin is already using database "${this.dbName}"; this runtime is sharing it as a follower. If these are separate apps, give each a distinct store name.`
+    });
+    await followerBridge.waitForLeader();
+  }
+  async openCurrentBridge(ddlStatements) {
     const response = await this.sendRequest({
       id: 0,
       type: "open",
@@ -544,7 +803,40 @@ var SqliteWasmAdapter = class {
         dbName: this.dbName
       });
     }
-    this.opened = true;
+    return response;
+  }
+  /**
+   * Surface a `store:opfs-unavailable` diagnostic when the worker reported that
+   * persistence silently degraded to an in-memory database, so a data-loss
+   * condition is observable instead of failing silently. A persistent open (or a
+   * bridge that does not report a mode, e.g. the Node mock) emits nothing.
+   */
+  reportStorageMode(data) {
+    this.storageOpenState = parseStorageOpenState(data);
+    if (!this.emitNonPersistentDiagnostic || !this.emitter || !this.storageOpenState) {
+      return;
+    }
+    if (this.storageOpenState.persistent === false) {
+      const reason = this.storageOpenState.fallbackReason ?? "unsupported";
+      this.emitter.emit({
+        type: "store:opfs-unavailable",
+        dbName: this.dbName,
+        reason,
+        message: `OPFS persistence is unavailable (${reason}) for database "${this.dbName}"; the store is running in memory and data will not survive a reload.`
+      });
+    }
+  }
+  getStorageOpenState() {
+    return this.storageOpenState;
+  }
+  warnSharedWorkerDeprecated() {
+    if (!this.sharedWorkerUrl || warnedSharedWorkerDeprecated) {
+      return;
+    }
+    warnedSharedWorkerDeprecated = true;
+    console.warn(
+      "[kora] sharedWorkerUrl is deprecated and ignored: SharedWorker-hosted SQLite cannot use OPFS and is never durable. Kora uses the durable dedicated-worker leader/follower path for multi-tab storage."
+    );
   }
   async close() {
     if (!this.bridge) return;
@@ -552,16 +844,42 @@ var SqliteWasmAdapter = class {
       await this.sendRequest({ id: 0, type: "close" });
     } finally {
       this.tabSession?.stopRelay?.();
+      this.tabSession?.cancelPromotionWatch?.();
       if (this.tabSession?.releaseLock) {
         await this.tabSession.releaseLock();
       }
       this.tabSession = null;
-      this.sharedWorker = null;
       this.bridge.terminate();
       this.bridge = null;
       this.opened = false;
     }
   }
+  /**
+   * Promotes a follower to leader after the previous leader released the storage
+   * lock (its tab closed or crashed). The lock is only granted once the old leader
+   * is gone, so opening our own worker here is safe from the OPFS single-writer
+   * rule. In-flight follower RPCs are rejected and left to the caller / reactive
+   * layer to retry against the new leader.
+   */
+  async promoteToLeader() {
+    if (this.promoting || !this.opened || this.workerUrl === void 0 || this.schema === null) {
+      return;
+    }
+    this.promoting = true;
+    const { WebWorkerBridge: WebWorkerBridge2 } = await Promise.resolve().then(() => (init_sqlite_wasm_channel(), sqlite_wasm_channel_exports));
+    const workerBridge = new TransactionSerializingWorkerBridge(
+      new WebWorkerBridge2(this.workerUrl, this.workerResponseTimeoutMs)
+    );
+    const previousBridge = this.bridge;
+    this.bridge = workerBridge;
+    if (this.tabSession) {
+      this.tabSession.role = "leader";
+      this.tabSession.stopRelay = startLeaderRpcRelay(this.tabSession.channelName, workerBridge);
+    }
+    previousBridge?.terminate();
+    const ddlStatements = (0, import_core2.generateFullDDL)(this.schema);
+    await this.sendRequest({ id: 0, type: "open", ddlStatements, dbName: this.dbName });
+  }
   async execute(sql, params) {
     this.guardOpen();
     const response = await this.sendRequest({ id: 0, type: "execute", sql, params });
@@ -649,7 +967,10 @@ var SqliteWasmAdapter = class {
     this.guardOpen();
     const response = await this.sendRequest({ id: 0, type: "export" });
     if (response.type === "error") {
-      throw new AdapterError(`Export failed: ${response.message}`);
+      throw new AdapterError(`Export failed: ${response.message}`, {
+        code: response.code,
+        context: response.context
+      });
     }
     return response.data;
   }
@@ -682,6 +1003,20 @@ var SqliteWasmAdapter = class {
     }
   }
 };
+function parseStorageOpenState(data) {
+  if (typeof data !== "object" || data === null) {
+    return null;
+  }
+  const mode = data;
+  if (typeof mode.persistent !== "boolean") {
+    return null;
+  }
+  return {
+    persistent: mode.persistent,
+    mode: mode.persistent ? "opfs" : "memory",
+    ...mode.fallbackReason ? { fallbackReason: mode.fallbackReason } : {}
+  };
+}
 
 // src/adapters/sqlite-wasm-persistence.ts
 init_errors();
@@ -816,6 +1151,24 @@ async function loadDumpFromIndexedDB(dbName) {
     idb.close();
   }
 }
+async function deleteSnapshotFromIndexedDB(dbName) {
+  const idb = await openIdb();
+  try {
+    await new Promise((resolve, reject) => {
+      const tx = idb.transaction(IDB_STORE_NAME, "readwrite");
+      const store = tx.objectStore(IDB_STORE_NAME);
+      store.delete(dbName);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(
+        new PersistenceError(`Failed to delete database snapshot "${dbName}" from IndexedDB`, {
+          dbName
+        })
+      );
+    });
+  } finally {
+    idb.close();
+  }
+}
 
 // src/adapters/indexeddb-adapter.ts
 var IndexedDbAdapter = class {
@@ -823,6 +1176,7 @@ var IndexedDbAdapter = class {
   dbName;
   emitter;
   scheduler;
+  storageOpenState = null;
   constructor(options = {}) {
     this.dbName = options.dbName ?? "kora-db";
     this.emitter = options.emitter;
@@ -840,8 +1194,12 @@ var IndexedDbAdapter = class {
   }
   async open(schema) {
     await this.inner.open(schema);
+    this.storageOpenState = { persistent: true, mode: "indexeddb" };
     const persisted = await loadFromIndexedDB(this.dbName);
-    if (!persisted) return;
+    if (!persisted) {
+      await this.restoreFromDumpFallback();
+      return;
+    }
     try {
       await this.inner.importDatabase(persisted);
     } catch {
@@ -868,6 +1226,9 @@ var IndexedDbAdapter = class {
     await this.inner.migrate(from, to, migration);
     this.scheduler.schedule();
   }
+  getStorageOpenState() {
+    return this.storageOpenState;
+  }
   /**
    * Force an immediate snapshot write to IndexedDB (skips debounce).
    * Useful before tab unload or in tests.
@@ -876,10 +1237,17 @@ var IndexedDbAdapter = class {
     await this.scheduler.flushNow();
   }
   async writeSnapshot() {
-    const data = await this.inner.exportDatabase();
-    await saveToIndexedDB(this.dbName, data);
     const dump = await this.exportDump();
     await saveDumpToIndexedDB(this.dbName, dump);
+    try {
+      const data = await this.inner.exportDatabase();
+      await saveToIndexedDB(this.dbName, data);
+    } catch (error) {
+      if (!isUnsupportedWorkerExport(error)) {
+        throw error;
+      }
+      await deleteSnapshotFromIndexedDB(this.dbName);
+    }
   }
   handlePersistenceError(error) {
     const message = error instanceof Error ? error.message : "IndexedDB persistence failed";
@@ -904,7 +1272,7 @@ var IndexedDbAdapter = class {
     if (!dump) return;
     for (const table of dump.tables) {
       const name = ensureSafeIdentifier(table.name);
-      await this.inner.execute(`DELETE FROM ${name}`);
+      await this.inner.execute(`DELETE FROM ${(0, import_core3.quoteIdent)(name)}`);
       if (table.rows.length === 0) continue;
       for (const row of table.rows) {
         const columns = table.columns.filter(
@@ -912,10 +1280,10 @@ var IndexedDbAdapter = class {
         );
         if (columns.length === 0) continue;
         const placeholders = columns.map(() => "?").join(", ");
-        const quotedColumns = columns.map((column) => ensureSafeIdentifier(column)).join(", ");
+        const quotedColumns = columns.map((column) => (0, import_core3.quoteIdent)(ensureSafeIdentifier(column))).join(", ");
         const values = columns.map((column) => row[column]);
         await this.inner.execute(
-          `INSERT INTO ${name} (${quotedColumns}) VALUES (${placeholders})`,
+          `INSERT INTO ${(0, import_core3.quoteIdent)(name)} (${quotedColumns}) VALUES (${placeholders})`,
           values
         );
       }
@@ -928,9 +1296,13 @@ var IndexedDbAdapter = class {
     const tables = [];
     for (const tableRow of tableRows) {
       const tableName = ensureSafeIdentifier(tableRow.name);
-      const columns = await this.inner.query(`PRAGMA table_info(${tableName})`);
+      const columns = await this.inner.query(
+        `PRAGMA table_info(${(0, import_core3.quoteIdent)(tableName)})`
+      );
       const columnNames = columns.map((column) => column.name);
-      const rows = await this.inner.query(`SELECT * FROM ${tableName}`);
+      const rows = await this.inner.query(
+        `SELECT * FROM ${(0, import_core3.quoteIdent)(tableName)}`
+      );
       tables.push({
         name: tableName,
         columns: columnNames,
@@ -949,6 +1321,9 @@ function ensureSafeIdentifier(identifier) {
   }
   return identifier;
 }
+function isUnsupportedWorkerExport(error) {
+  return error instanceof AdapterError && error.context?.code === "EXPORT_NOT_SUPPORTED";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   IndexedDbAdapter