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

package/dist/adapters/sqlite-wasm.d.cts

@@ -1,7 +1,7 @@
 import { KoraEventEmitter, SchemaDefinition } from '@korajs/core';
-import { S as StorageAdapter, a as StorageOpenState, T as Transaction, M as MigrationPlan } from '../types-BslDOTk0.cjs';
-import { W as WorkerBridge } from '../sqlite-wasm-channel-L6o3bWQK.cjs';
-export { a as WebWorkerBridge, b as WorkerRequest, c as WorkerResponse } from '../sqlite-wasm-channel-L6o3bWQK.cjs';
+import { S as StorageAdapter, T as Transaction, a as StorageOpenState, M as MigrationPlan } from '../types-Dh-xyUjP.cjs';
+import { W as WorkerBridge } from '../sqlite-wasm-channel-DVX93Uiq.cjs';
+export { a as WebWorkerBridge, b as WorkerRequest, c as WorkerResponse, d as WorkerSendOptions, e as WorkerStatusEvent } from '../sqlite-wasm-channel-DVX93Uiq.cjs';
 
 /**
  * Async mutex for serializing access to a resource across `await` boundaries.
@@ -26,6 +26,19 @@ declare class Mutex {
     private createRelease;
 }
 
+/** Per-request options for {@link SqliteWasmAdapter.execute} and `query`. */
+interface StorageRequestOptions {
+    /**
+     * Stop waiting for the response. The leader may still apply a write that
+     * already reached it; retry with the same `requestId` to stay idempotent.
+     */
+    signal?: AbortSignal;
+    /**
+     * Stable id for this request. A follower tab's retry with the same id is
+     * answered from the leader's response cache instead of being applied twice.
+     */
+    requestId?: string;
+}
 /**
  * Options for creating a SqliteWasmAdapter.
  */
@@ -36,7 +49,7 @@ interface SqliteWasmAdapterOptions {
      */
     bridge?: WorkerBridge;
     /**
-     * Database name for persistence. Used as the OPFS file name or IDB key.
+     * Database name for persistence. Each database gets its own OPFS pool.
      */
     dbName?: string;
     /**
@@ -58,18 +71,66 @@ interface SqliteWasmAdapterOptions {
      */
     emitNonPersistentDiagnostic?: boolean;
     /**
-     * When set, storage diagnostics are emitted here: `store:opfs-unavailable` when
-     * persistence silently degraded to a non-persistent in-memory database, and
-     * `store:db-name-collision` when another runtime on this origin was already
-     * using this database name.
+     * Accept writes when durable OPFS storage could not be obtained and the
+     * database runs in memory. Defaults to false: a non-durable open or promotion
+     * emits the blocking `store:durability-lost` event and every write is refused
+     * with {@link StorageDurabilityError}, so data is never accepted and then lost
+     * on reload. Set true only for apps that can tolerate losing local writes.
+     */
+    allowNonDurable?: boolean;
+    /**
+     * For `createApp()`: skip the durability check at open only, because the caller
+     * inspects {@link SqliteWasmAdapter.getStorageOpenState} right after open and
+     * switches to a durable backend itself. A later leader promotion that loses
+     * durable storage is still enforced.
+     */
+    deferOpenDurabilityCheck?: boolean;
+    /**
+     * Release storage ownership when the page is frozen or hidden into the
+     * back/forward cache (`freeze` / `pagehide`), so a visible tab can take over
+     * instead of waiting on a tab that cannot run; ownership is re-acquired on
+     * `resume` / `pageshow`. Defaults to true.
+     */
+    releaseOnFreeze?: boolean;
+    /**
+     * When set, storage diagnostics are emitted here: `store:opfs-unavailable`,
+     * `store:durability-lost`, `store:storage-blocked` (another holder has the
+     * storage; the open waits), `store:storage-migrated` and
+     * `store:db-name-collision`.
      */
     emitter?: KoraEventEmitter;
+    /**
+     * @internal Used by the IndexedDB adapter: open an in-memory database that
+     * never touches OPFS (the IndexedDB adapter persists snapshots itself).
+     */
+    storage?: 'opfs' | 'memory';
+    /**
+     * @internal Do not read or write the storage manifest (the IndexedDB adapter's
+     * inner database and its one-shot OPFS reader manage the manifest themselves).
+     */
+    skipBackendRecord?: boolean;
+    /**
+     * @internal Used by the IndexedDB adapter (STORE-6): runs in one transaction on this
+     * tab's OWN worker right after it opened the database as storage leader (first open
+     * or promotion), before the worker serves any other tab. The IndexedDB adapter
+     * restores its persisted snapshot here, so a snapshot is only ever restored into a
+     * freshly created worker database and never over a leader's live one. Throwing fails
+     * the open (or the promotion, which then refuses writes).
+     */
+    onLeaderWorkerOpened?: (tx: Transaction) => Promise<void>;
 }
 /**
  * SQLite WASM adapter that communicates with a SQLite instance through a WorkerBridge.
  *
- * In browsers, the bridge is backed by a Web Worker running SQLite WASM with OPFS persistence.
- * In Node.js tests, the bridge is backed by MockWorkerBridge wrapping better-sqlite3.
+ * In browsers, one tab per database (the leader) runs a dedicated worker that
+ * owns the database's OPFS pool; other tabs reach that worker over a
+ * BroadcastChannel. In Node.js tests, the bridge is backed by MockWorkerBridge
+ * wrapping better-sqlite3.
+ *
+ * Storage is durable or loud, never silently in memory (W8a): another holder of
+ * the storage makes the open wait (reported with `store:storage-blocked`); only a
+ * runtime without OPFS SAH support gets a non-durable database, which refuses
+ * writes unless the app opted in with `allowNonDurable`.
  *
  * @example
  * ```typescript
@@ -83,6 +144,8 @@ interface SqliteWasmAdapterOptions {
  */
 declare class SqliteWasmAdapter implements StorageAdapter {
     private bridge;
+    /** The dedicated worker this tab runs while it is the database's leader. */
+    private ownWorker;
     private opened;
     private readonly mutex;
     private readonly injectedBridge;
@@ -97,10 +160,45 @@ declare class SqliteWasmAdapter implements StorageAdapter {
     /** Retained so a follower promoted to leader can re-open its own worker. */
     private schema;
     private promoting;
+    private closing;
+    private suspended;
+    /** Requests wait here while leadership changes hands (promotion, resume). */
+    private gate;
+    private removeLifecycleListeners;
+    private readonly allowNonDurable;
+    private readonly deferOpenDurabilityCheck;
+    private readonly releaseOnFreeze;
+    private readonly storage;
+    private readonly skipBackendRecord;
+    /** Set when this adapter lost (or never had) durable storage; writes are refused. */
+    private durabilityLoss;
+    private readonly onLeaderWorkerOpened;
     constructor(options?: SqliteWasmAdapterOptions);
     open(schema: SchemaDefinition): Promise<void>;
-    private openDurableWorkerBridge;
+    /**
+     * Join the database as leader (own worker) or follower (RPC to the leader's
+     * worker), then open it. The open waits, without a timeout, while another
+     * holder still has the storage; the worker reports that as a blocking state.
+     */
+    private attachAndOpen;
+    /** Open the database in this tab's own worker and start serving followers. */
+    private openLeaderWorker;
+    /**
+     * Whether this runtime owns the database's worker: the storage leader in a browser,
+     * or any adapter with an injected bridge (tests, Node). A follower tab relays every
+     * request to the leader's worker (STORE-6).
+     */
+    isLeader(): boolean;
+    private checkedOpen;
     private openCurrentBridge;
+    private onWorkerEvent;
+    /**
+     * Leader-only bookkeeping after a durable open: report a legacy-pool
+     * migration, move an IndexedDB-held copy into OPFS explicitly (never two
+     * disjoint copies), and record OPFS as this database's backend.
+     */
+    private afterLeaderOpen;
+    private applyDumpThroughWorker;
     /**
      * Surface a `store:opfs-unavailable` diagnostic when the worker reported that
      * persistence silently degraded to an in-memory database, so a data-loss
@@ -109,18 +207,58 @@ declare class SqliteWasmAdapter implements StorageAdapter {
      */
     private reportStorageMode;
     getStorageOpenState(): StorageOpenState | null;
+    /**
+     * Durable or loud, never silent (NEW-STORE-6). When the open or a promotion
+     * ended on non-persistent storage and the app did not opt into that, emit the
+     * blocking `store:durability-lost` event and refuse every later write. A
+     * bridge that reports no mode (the Node mock) is not judged.
+     */
+    private enforceDurability;
+    private guardDurableWrite;
     private warnSharedWorkerDeprecated;
+    /**
+     * Close the database. A leader closes the database file and releases the OPFS
+     * pool inside its worker, terminates the worker, and only then releases the
+     * tab leader lock, so the next leader never races a still-running worker for
+     * the file handles (NEW-STORE-10). A follower just leaves.
+     */
     close(): Promise<void>;
+    /**
+     * Release everything this adapter holds, in ownership order: lifecycle
+     * listeners, then the worker (which holds the OPFS pool and its Web Lock),
+     * then the tab leader lock or queued promotion request.
+     */
+    private teardown;
     /**
      * 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.
+     * lock (its tab closed, crashed, or suspended on freeze). The new worker waits
+     * on the pool's Web Lock and handles, so it never races the previous worker.
+     * Requests issued during the hand-off wait for it; requests that were in
+     * flight to the old leader fail with a retriable `BridgeTerminatedError`.
      */
     private promoteToLeader;
-    execute(sql: string, params?: unknown[]): Promise<void>;
-    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Page Lifecycle: a frozen or bfcached page cannot run, so it must not keep
+     * other tabs waiting on its storage. Leaders terminate their worker (freeing
+     * the OPFS pool) and then release the leader lock, so a visible tab is
+     * promoted; followers withdraw their queued lock request so a frozen tab is
+     * never granted leadership it cannot use. Never uses Web Locks `steal`.
+     */
+    private installLifecycleListeners;
+    /** Synchronous by necessity: a `freeze` handler gets no further turns. */
+    private suspend;
+    private resume;
+    /**
+     * Non-transactional write. Takes the same mutex as {@link transaction}, so it
+     * never lands inside this tab's open transaction and is never rolled back
+     * with it (STORE-8). Inside a transaction callback, use the `tx` handle.
+     */
+    execute(sql: string, params?: unknown[], options?: StorageRequestOptions): Promise<void>;
+    /**
+     * Non-transactional read. Waits for this tab's open transaction to finish, so
+     * it never observes uncommitted (possibly rolled-back) rows (STORE-8).
+     */
+    query<T>(sql: string, params?: unknown[], options?: StorageRequestOptions): Promise<T[]>;
     transaction(fn: (tx: Transaction) => Promise<void>): Promise<void>;
     migrate(from: number, to: number, migration: MigrationPlan): Promise<void>;
     /**
@@ -137,4 +275,87 @@ declare class SqliteWasmAdapter implements StorageAdapter {
     private sendChecked;
 }
 
-export { Mutex, SqliteWasmAdapter, type SqliteWasmAdapterOptions, WorkerBridge };
+/**
+ * Kora-owned manifest of the local databases this origin created (W8a).
+ *
+ * One record per database name, kept in its own IndexedDB database so it is
+ * readable from any tab without opening the OPFS pools. It records which backend
+ * holds the database's data, which is how Kora keeps OPFS and IndexedDB from
+ * ever holding two disjoint copies: a backend switch is a recorded, explicit
+ * migration, never a silent fresh start (NEW-STORE-5, LMS-5c).
+ *
+ * The manifest is advisory for listing and authoritative for the backend
+ * choice. Nothing is ever evicted automatically; deletion is the explicit
+ * `deleteDatabase()` API.
+ */
+/** Where a database's data lives. */
+type LocalDatabaseBackend = 'opfs' | 'indexeddb';
+/** One manifest entry, as returned by `listDatabases()`. */
+interface LocalDatabaseRecord {
+    /** The store name (`store.name`, plus the per-user suffix if namespaced). */
+    dbName: string;
+    /** The backend that holds the authoritative copy. */
+    backend: LocalDatabaseBackend;
+    /** OPFS pool holding the file (opfs backend only). */
+    poolName?: string;
+    /** Wall-clock milliseconds; informational only, never used for ordering. */
+    createdAt: number;
+    /** Wall-clock milliseconds of the last durable open; informational only. */
+    lastOpenedAt: number;
+}
+
+/**
+ * Explicit management of the local databases on this origin (W8a, NEW-STORE-7).
+ *
+ * Kora never evicts a database on its own: a full pool is prevented by
+ * per-database pools and capacity reservation, and removing data is always an
+ * explicit call that refuses while the database is open or still holds
+ * operations the server has not acknowledged.
+ */
+
+/** Read-only access to a database handed to the unsynced-data check. */
+interface LocalDatabaseReader {
+    dbName: string;
+    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/** Options for {@link deleteLocalDatabase}. */
+interface DeleteLocalDatabaseOptions {
+    /** URL of the Kora SQLite worker (the same one the app's store uses). */
+    workerUrl: string | URL;
+    /**
+     * Decides whether the database still holds operations the server never
+     * acknowledged. Injected by the app layer, which knows its sync setup.
+     * When it returns true the delete is refused with {@link UnsyncedDataError}.
+     */
+    hasUnsyncedOperations?: (db: LocalDatabaseReader) => Promise<boolean>;
+    /** Delete even when unsynced operations exist (they are lost). */
+    force?: boolean;
+    /** Worker response timeout. Defaults to 30000ms. */
+    workerResponseTimeoutMs?: number;
+}
+/**
+ * Databases Kora has recorded on this origin (created or opened since W8a).
+ * A database still in the pre-W8a shared pool appears after its first open.
+ */
+declare function listLocalDatabases(): Promise<LocalDatabaseRecord[]>;
+/**
+ * Permanently delete a local database and its OPFS pool or IndexedDB copy.
+ *
+ * Refuses with {@link StorageInUseError} while any tab has the database open,
+ * and with {@link UnsyncedDataError} while `hasUnsyncedOperations` reports
+ * unsynced operations (unless `force`). Never touches any other database.
+ *
+ * @returns true when something was deleted, false when the database did not exist
+ */
+declare function deleteLocalDatabase(dbName: string, options: DeleteLocalDatabaseOptions): Promise<boolean>;
+
+/**
+ * The OPFS SAH pool that owns `dbName`. Database names that are already safe
+ * map to `kora-opfs-<dbName>`; anything sanitized or truncated gets a hash suffix
+ * so two distinct names can never share a pool.
+ *
+ * @example opfsPoolNameFor('school__user_alice') === 'kora-opfs-school__user_alice'
+ */
+declare function opfsPoolNameFor(dbName: string): string;
+
+export { type DeleteLocalDatabaseOptions, type LocalDatabaseBackend, type LocalDatabaseReader, type LocalDatabaseRecord, Mutex, SqliteWasmAdapter, type SqliteWasmAdapterOptions, type StorageRequestOptions, WorkerBridge, deleteLocalDatabase, listLocalDatabases, opfsPoolNameFor };

package/dist/adapters/sqlite-wasm.d.ts

@@ -1,7 +1,7 @@
 import { KoraEventEmitter, SchemaDefinition } from '@korajs/core';
-import { S as StorageAdapter, a as StorageOpenState, T as Transaction, M as MigrationPlan } from '../types-BslDOTk0.js';
-import { W as WorkerBridge } from '../sqlite-wasm-channel-L6o3bWQK.js';
-export { a as WebWorkerBridge, b as WorkerRequest, c as WorkerResponse } from '../sqlite-wasm-channel-L6o3bWQK.js';
+import { S as StorageAdapter, T as Transaction, a as StorageOpenState, M as MigrationPlan } from '../types-Dh-xyUjP.js';
+import { W as WorkerBridge } from '../sqlite-wasm-channel-DVX93Uiq.js';
+export { a as WebWorkerBridge, b as WorkerRequest, c as WorkerResponse, d as WorkerSendOptions, e as WorkerStatusEvent } from '../sqlite-wasm-channel-DVX93Uiq.js';
 
 /**
  * Async mutex for serializing access to a resource across `await` boundaries.
@@ -26,6 +26,19 @@ declare class Mutex {
     private createRelease;
 }
 
+/** Per-request options for {@link SqliteWasmAdapter.execute} and `query`. */
+interface StorageRequestOptions {
+    /**
+     * Stop waiting for the response. The leader may still apply a write that
+     * already reached it; retry with the same `requestId` to stay idempotent.
+     */
+    signal?: AbortSignal;
+    /**
+     * Stable id for this request. A follower tab's retry with the same id is
+     * answered from the leader's response cache instead of being applied twice.
+     */
+    requestId?: string;
+}
 /**
  * Options for creating a SqliteWasmAdapter.
  */
@@ -36,7 +49,7 @@ interface SqliteWasmAdapterOptions {
      */
     bridge?: WorkerBridge;
     /**
-     * Database name for persistence. Used as the OPFS file name or IDB key.
+     * Database name for persistence. Each database gets its own OPFS pool.
      */
     dbName?: string;
     /**
@@ -58,18 +71,66 @@ interface SqliteWasmAdapterOptions {
      */
     emitNonPersistentDiagnostic?: boolean;
     /**
-     * When set, storage diagnostics are emitted here: `store:opfs-unavailable` when
-     * persistence silently degraded to a non-persistent in-memory database, and
-     * `store:db-name-collision` when another runtime on this origin was already
-     * using this database name.
+     * Accept writes when durable OPFS storage could not be obtained and the
+     * database runs in memory. Defaults to false: a non-durable open or promotion
+     * emits the blocking `store:durability-lost` event and every write is refused
+     * with {@link StorageDurabilityError}, so data is never accepted and then lost
+     * on reload. Set true only for apps that can tolerate losing local writes.
+     */
+    allowNonDurable?: boolean;
+    /**
+     * For `createApp()`: skip the durability check at open only, because the caller
+     * inspects {@link SqliteWasmAdapter.getStorageOpenState} right after open and
+     * switches to a durable backend itself. A later leader promotion that loses
+     * durable storage is still enforced.
+     */
+    deferOpenDurabilityCheck?: boolean;
+    /**
+     * Release storage ownership when the page is frozen or hidden into the
+     * back/forward cache (`freeze` / `pagehide`), so a visible tab can take over
+     * instead of waiting on a tab that cannot run; ownership is re-acquired on
+     * `resume` / `pageshow`. Defaults to true.
+     */
+    releaseOnFreeze?: boolean;
+    /**
+     * When set, storage diagnostics are emitted here: `store:opfs-unavailable`,
+     * `store:durability-lost`, `store:storage-blocked` (another holder has the
+     * storage; the open waits), `store:storage-migrated` and
+     * `store:db-name-collision`.
      */
     emitter?: KoraEventEmitter;
+    /**
+     * @internal Used by the IndexedDB adapter: open an in-memory database that
+     * never touches OPFS (the IndexedDB adapter persists snapshots itself).
+     */
+    storage?: 'opfs' | 'memory';
+    /**
+     * @internal Do not read or write the storage manifest (the IndexedDB adapter's
+     * inner database and its one-shot OPFS reader manage the manifest themselves).
+     */
+    skipBackendRecord?: boolean;
+    /**
+     * @internal Used by the IndexedDB adapter (STORE-6): runs in one transaction on this
+     * tab's OWN worker right after it opened the database as storage leader (first open
+     * or promotion), before the worker serves any other tab. The IndexedDB adapter
+     * restores its persisted snapshot here, so a snapshot is only ever restored into a
+     * freshly created worker database and never over a leader's live one. Throwing fails
+     * the open (or the promotion, which then refuses writes).
+     */
+    onLeaderWorkerOpened?: (tx: Transaction) => Promise<void>;
 }
 /**
  * SQLite WASM adapter that communicates with a SQLite instance through a WorkerBridge.
  *
- * In browsers, the bridge is backed by a Web Worker running SQLite WASM with OPFS persistence.
- * In Node.js tests, the bridge is backed by MockWorkerBridge wrapping better-sqlite3.
+ * In browsers, one tab per database (the leader) runs a dedicated worker that
+ * owns the database's OPFS pool; other tabs reach that worker over a
+ * BroadcastChannel. In Node.js tests, the bridge is backed by MockWorkerBridge
+ * wrapping better-sqlite3.
+ *
+ * Storage is durable or loud, never silently in memory (W8a): another holder of
+ * the storage makes the open wait (reported with `store:storage-blocked`); only a
+ * runtime without OPFS SAH support gets a non-durable database, which refuses
+ * writes unless the app opted in with `allowNonDurable`.
  *
  * @example
  * ```typescript
@@ -83,6 +144,8 @@ interface SqliteWasmAdapterOptions {
  */
 declare class SqliteWasmAdapter implements StorageAdapter {
     private bridge;
+    /** The dedicated worker this tab runs while it is the database's leader. */
+    private ownWorker;
     private opened;
     private readonly mutex;
     private readonly injectedBridge;
@@ -97,10 +160,45 @@ declare class SqliteWasmAdapter implements StorageAdapter {
     /** Retained so a follower promoted to leader can re-open its own worker. */
     private schema;
     private promoting;
+    private closing;
+    private suspended;
+    /** Requests wait here while leadership changes hands (promotion, resume). */
+    private gate;
+    private removeLifecycleListeners;
+    private readonly allowNonDurable;
+    private readonly deferOpenDurabilityCheck;
+    private readonly releaseOnFreeze;
+    private readonly storage;
+    private readonly skipBackendRecord;
+    /** Set when this adapter lost (or never had) durable storage; writes are refused. */
+    private durabilityLoss;
+    private readonly onLeaderWorkerOpened;
     constructor(options?: SqliteWasmAdapterOptions);
     open(schema: SchemaDefinition): Promise<void>;
-    private openDurableWorkerBridge;
+    /**
+     * Join the database as leader (own worker) or follower (RPC to the leader's
+     * worker), then open it. The open waits, without a timeout, while another
+     * holder still has the storage; the worker reports that as a blocking state.
+     */
+    private attachAndOpen;
+    /** Open the database in this tab's own worker and start serving followers. */
+    private openLeaderWorker;
+    /**
+     * Whether this runtime owns the database's worker: the storage leader in a browser,
+     * or any adapter with an injected bridge (tests, Node). A follower tab relays every
+     * request to the leader's worker (STORE-6).
+     */
+    isLeader(): boolean;
+    private checkedOpen;
     private openCurrentBridge;
+    private onWorkerEvent;
+    /**
+     * Leader-only bookkeeping after a durable open: report a legacy-pool
+     * migration, move an IndexedDB-held copy into OPFS explicitly (never two
+     * disjoint copies), and record OPFS as this database's backend.
+     */
+    private afterLeaderOpen;
+    private applyDumpThroughWorker;
     /**
      * Surface a `store:opfs-unavailable` diagnostic when the worker reported that
      * persistence silently degraded to an in-memory database, so a data-loss
@@ -109,18 +207,58 @@ declare class SqliteWasmAdapter implements StorageAdapter {
      */
     private reportStorageMode;
     getStorageOpenState(): StorageOpenState | null;
+    /**
+     * Durable or loud, never silent (NEW-STORE-6). When the open or a promotion
+     * ended on non-persistent storage and the app did not opt into that, emit the
+     * blocking `store:durability-lost` event and refuse every later write. A
+     * bridge that reports no mode (the Node mock) is not judged.
+     */
+    private enforceDurability;
+    private guardDurableWrite;
     private warnSharedWorkerDeprecated;
+    /**
+     * Close the database. A leader closes the database file and releases the OPFS
+     * pool inside its worker, terminates the worker, and only then releases the
+     * tab leader lock, so the next leader never races a still-running worker for
+     * the file handles (NEW-STORE-10). A follower just leaves.
+     */
     close(): Promise<void>;
+    /**
+     * Release everything this adapter holds, in ownership order: lifecycle
+     * listeners, then the worker (which holds the OPFS pool and its Web Lock),
+     * then the tab leader lock or queued promotion request.
+     */
+    private teardown;
     /**
      * 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.
+     * lock (its tab closed, crashed, or suspended on freeze). The new worker waits
+     * on the pool's Web Lock and handles, so it never races the previous worker.
+     * Requests issued during the hand-off wait for it; requests that were in
+     * flight to the old leader fail with a retriable `BridgeTerminatedError`.
      */
     private promoteToLeader;
-    execute(sql: string, params?: unknown[]): Promise<void>;
-    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Page Lifecycle: a frozen or bfcached page cannot run, so it must not keep
+     * other tabs waiting on its storage. Leaders terminate their worker (freeing
+     * the OPFS pool) and then release the leader lock, so a visible tab is
+     * promoted; followers withdraw their queued lock request so a frozen tab is
+     * never granted leadership it cannot use. Never uses Web Locks `steal`.
+     */
+    private installLifecycleListeners;
+    /** Synchronous by necessity: a `freeze` handler gets no further turns. */
+    private suspend;
+    private resume;
+    /**
+     * Non-transactional write. Takes the same mutex as {@link transaction}, so it
+     * never lands inside this tab's open transaction and is never rolled back
+     * with it (STORE-8). Inside a transaction callback, use the `tx` handle.
+     */
+    execute(sql: string, params?: unknown[], options?: StorageRequestOptions): Promise<void>;
+    /**
+     * Non-transactional read. Waits for this tab's open transaction to finish, so
+     * it never observes uncommitted (possibly rolled-back) rows (STORE-8).
+     */
+    query<T>(sql: string, params?: unknown[], options?: StorageRequestOptions): Promise<T[]>;
     transaction(fn: (tx: Transaction) => Promise<void>): Promise<void>;
     migrate(from: number, to: number, migration: MigrationPlan): Promise<void>;
     /**
@@ -137,4 +275,87 @@ declare class SqliteWasmAdapter implements StorageAdapter {
     private sendChecked;
 }
 
-export { Mutex, SqliteWasmAdapter, type SqliteWasmAdapterOptions, WorkerBridge };
+/**
+ * Kora-owned manifest of the local databases this origin created (W8a).
+ *
+ * One record per database name, kept in its own IndexedDB database so it is
+ * readable from any tab without opening the OPFS pools. It records which backend
+ * holds the database's data, which is how Kora keeps OPFS and IndexedDB from
+ * ever holding two disjoint copies: a backend switch is a recorded, explicit
+ * migration, never a silent fresh start (NEW-STORE-5, LMS-5c).
+ *
+ * The manifest is advisory for listing and authoritative for the backend
+ * choice. Nothing is ever evicted automatically; deletion is the explicit
+ * `deleteDatabase()` API.
+ */
+/** Where a database's data lives. */
+type LocalDatabaseBackend = 'opfs' | 'indexeddb';
+/** One manifest entry, as returned by `listDatabases()`. */
+interface LocalDatabaseRecord {
+    /** The store name (`store.name`, plus the per-user suffix if namespaced). */
+    dbName: string;
+    /** The backend that holds the authoritative copy. */
+    backend: LocalDatabaseBackend;
+    /** OPFS pool holding the file (opfs backend only). */
+    poolName?: string;
+    /** Wall-clock milliseconds; informational only, never used for ordering. */
+    createdAt: number;
+    /** Wall-clock milliseconds of the last durable open; informational only. */
+    lastOpenedAt: number;
+}
+
+/**
+ * Explicit management of the local databases on this origin (W8a, NEW-STORE-7).
+ *
+ * Kora never evicts a database on its own: a full pool is prevented by
+ * per-database pools and capacity reservation, and removing data is always an
+ * explicit call that refuses while the database is open or still holds
+ * operations the server has not acknowledged.
+ */
+
+/** Read-only access to a database handed to the unsynced-data check. */
+interface LocalDatabaseReader {
+    dbName: string;
+    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/** Options for {@link deleteLocalDatabase}. */
+interface DeleteLocalDatabaseOptions {
+    /** URL of the Kora SQLite worker (the same one the app's store uses). */
+    workerUrl: string | URL;
+    /**
+     * Decides whether the database still holds operations the server never
+     * acknowledged. Injected by the app layer, which knows its sync setup.
+     * When it returns true the delete is refused with {@link UnsyncedDataError}.
+     */
+    hasUnsyncedOperations?: (db: LocalDatabaseReader) => Promise<boolean>;
+    /** Delete even when unsynced operations exist (they are lost). */
+    force?: boolean;
+    /** Worker response timeout. Defaults to 30000ms. */
+    workerResponseTimeoutMs?: number;
+}
+/**
+ * Databases Kora has recorded on this origin (created or opened since W8a).
+ * A database still in the pre-W8a shared pool appears after its first open.
+ */
+declare function listLocalDatabases(): Promise<LocalDatabaseRecord[]>;
+/**
+ * Permanently delete a local database and its OPFS pool or IndexedDB copy.
+ *
+ * Refuses with {@link StorageInUseError} while any tab has the database open,
+ * and with {@link UnsyncedDataError} while `hasUnsyncedOperations` reports
+ * unsynced operations (unless `force`). Never touches any other database.
+ *
+ * @returns true when something was deleted, false when the database did not exist
+ */
+declare function deleteLocalDatabase(dbName: string, options: DeleteLocalDatabaseOptions): Promise<boolean>;
+
+/**
+ * The OPFS SAH pool that owns `dbName`. Database names that are already safe
+ * map to `kora-opfs-<dbName>`; anything sanitized or truncated gets a hash suffix
+ * so two distinct names can never share a pool.
+ *
+ * @example opfsPoolNameFor('school__user_alice') === 'kora-opfs-school__user_alice'
+ */
+declare function opfsPoolNameFor(dbName: string): string;
+
+export { type DeleteLocalDatabaseOptions, type LocalDatabaseBackend, type LocalDatabaseReader, type LocalDatabaseRecord, Mutex, SqliteWasmAdapter, type SqliteWasmAdapterOptions, type StorageRequestOptions, WorkerBridge, deleteLocalDatabase, listLocalDatabases, opfsPoolNameFor };