browser-sqlite 1.0.0-rc.4 → 1.0.0-rc.5

package/dist/supervisor.d.ts

@@ -9,7 +9,7 @@
  */
 export type SupervisorDecision = 'restart' | 'lost' | 'fail-client';
 export type Supervisor = {
-    report: (index: number, event: 'spawned' | 'ready' | 'served' | 'died' | 'lost') => SupervisorDecision | undefined;
+    report: (index: number, event: 'spawned' | 'ready' | 'served' | 'died' | 'lost' | 'retired') => SupervisorDecision | undefined;
 };
 export declare const createSupervisor: (options: {
     size: number;

package/dist/transaction.d.ts

@@ -1,6 +1,7 @@
 import type { SQLiteQueryAPI, SQLiteTransactionDB, SQLiteTransactionOptions } from './api';
 import type { ReadFn, TransactionFn, WriteFn } from './bulk';
 import { SQLiteError } from './errors';
+import type { Logger } from './logger';
 import type { PoolWorker } from './pool';
 import type { Scheduler } from './scheduler';
 /**
@@ -13,7 +14,7 @@ import type { Scheduler } from './scheduler';
  */
 export declare const createTransaction: (deps: {
     scheduler: Scheduler<PoolWorker>;
-    afterWrite: (worker: PoolWorker) => void;
+    afterWrite: (worker: PoolWorker) => Promise<unknown>;
     /**
      * Called when a connection may still hold an open transaction. The worker
      * is lost rather than repaired: a "dirty worker" state is one more
@@ -21,6 +22,17 @@ export declare const createTransaction: (deps: {
      * connection is transaction-free by construction.
      */
     onPoisoned: (index: number, error: SQLiteError) => void;
+    /**
+     * Aborted when the client closes, with `CLIENT_CLOSED`.
+     *
+     * Merged into the transaction's own signal so that closing ABANDONS a
+     * running transaction the way a caller's `signal` does — the callback is
+     * not interrupted, it simply can no longer reach the database. Without it
+     * the caller of a transaction whose callback sits on an `await` that is not
+     * a statement waited for ever: nothing else in the transaction observes the
+     * client going away.
+     */
+    closeSignal: AbortSignal;
     /**
      * The client's bulk factory. Called per transaction with the transaction's
      * own read/write and a pass-through `transaction`, so output()'s swap runs
@@ -31,8 +43,19 @@ export declare const createTransaction: (deps: {
         read: ReadFn;
         write: WriteFn;
         transaction: TransactionFn;
+        /** See `src/bulk.ts`: the batch's place in this transaction's queue. */
+        reserve?: () => {
+            started: Promise<void>;
+            done: () => void;
+        };
     }) => {
         bulkWrite: SQLiteQueryAPI['bulkWrite'];
         output: SQLiteQueryAPI['output'];
     };
+    /**
+     * Reached only through `always`: `rollback()` on a transaction that has
+     * already committed warns whatever the `debug` option says (spec R4) — a
+     * warning visible only under debug would be the same as silence.
+     */
+    logger: Pick<Logger, 'always'>;
 }) => <T = void>(callback: (db: SQLiteTransactionDB) => Promise<T>, options?: SQLiteTransactionOptions) => Promise<T>;

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import type { SQLiteErrorCode } from './errors';
+import type { SQLiteResultCode } from './sqlite-codes';
 export type SQLiteWorkerMessageData<_T = unknown> = {
     callId: number;
     terminate?: boolean;
@@ -25,10 +27,25 @@ export declare const SharedArrayTypes: {
     STRING: number;
     OBJECT: number;
 };
+/**
+ * The savepoint a transaction asks the worker to handle around one query
+ * (spec 2026-09-11, D4/D5). `conclude` settles the savepoint the previous
+ * savepointed write left open — `release` keeps that write, `undo` rolls it
+ * back first — and `open` starts one for this query's own statement. Both run
+ * before the statement, conclusion first. Internal: no consumer sets it.
+ */
+export type SavepointOp = {
+    conclude?: 'release' | 'undo';
+    open?: true;
+};
 type SQLOptions = {
     chunkSize?: number;
     /** Chunks the worker may send before waiting for a credit. Spec §3.2. */
     credits?: number;
+    /** When true, the worker installs an async progress handler so an AbortSignal can stop a running step(). */
+    abortable?: boolean;
+    /** See `SavepointOp`. */
+    savepoint?: SavepointOp;
 };
 /**
  * Where a worker fetches its `.wasm` from, when the consumer overrode it.
@@ -57,7 +74,26 @@ export type ClientMessageData = {
     pragmas?: Record<string, string>;
     /** Statements retained per worker; see `src/client.ts`. Internal. */
     statementCacheSize?: number;
+    /** Bytes retained per worker; see `src/client.ts`. Internal. */
+    statementCacheBytes?: number;
     wasm?: WasmLocation;
+    /** Shared abort slots, one Int32 per worker. Isolated contexts only. */
+    abortSlots?: SharedArrayBuffer;
+    /** This worker's index into `abortSlots`. */
+    abortIndex?: number;
+    /**
+     * Features this worker must find before opening; it declines instead of
+     * opening when one is missing (spec 2026-09-13). Sent to slots of index
+     * ≥ 1 only, and only by a VFS that declares `singleConnectionWithout`.
+     */
+    declineWithout?: readonly PlatformFeature[];
+    /**
+     * Features worker 0 probes before opening, where the VFS is exclusive
+     * without one (spec 2026-09-15, §3.2): it reports them with `probed`,
+     * then loads nothing until `proceed`. Sent to slot 0 only, and only by a
+     * VFS that declares `exclusiveConnectionWithout`.
+     */
+    probeFirst?: readonly PlatformFeature[];
 } | {
     type: 'query';
     callId: number;
@@ -74,6 +110,11 @@ export type ClientMessageData = {
 } | {
     type: 'stop';
     callId: number;
+}
+/** The client decided the connection lock; worker 0 may open (spec 2026-09-15). */
+ | {
+    type: 'proceed';
+    callId: number;
 } | {
     type: 'delete';
     callId: number;
@@ -85,6 +126,24 @@ export type ClientMessageData = {
 export type WorkerMessageData = {
     type: 'ready';
     callId: number;
+}
+/**
+ * The worker found a feature of `declineWithout` missing and opened nothing:
+ * the environment caps the pool (spec 2026-09-13).
+ */
+ | {
+    type: 'declined';
+    callId: number;
+    missing: PlatformFeature;
+}
+/**
+ * Worker 0's answer to `probeFirst`: the first feature missing, or null. It
+ * opens nothing until the client sends `proceed` (spec 2026-09-15, §3.2).
+ */
+ | {
+    type: 'probed';
+    callId: number;
+    missing: PlatformFeature | null;
 } | {
     type: 'chunk';
     callId: number;
@@ -100,26 +159,66 @@ export type WorkerMessageData = {
      * "for a sub-millisecond effect, count the round trips").
      */
     prepared: number;
+    /**
+     * Whether the connection is inside a transaction once this query has
+     * ended — `sqlite3_get_autocommit() === 0`. SQLite can leave a
+     * transaction by itself: an interrupted INSERT/UPDATE/DELETE rolls the
+     * whole transaction back. Absent when the worker could not read it.
+     */
+    inTransaction?: boolean | undefined;
 } | {
     type: 'error';
     callId: number;
     message: string;
     cause?: unknown;
     /** SQLite's numeric result code, when the failure came from SQLite. */
-    sqliteCode?: number;
+    sqliteCode?: SQLiteResultCode;
+    /**
+     * SQLite's extended result code, read in the worker where the statement
+     * failed (spec 2026-09-14, §5.1). Sent by the query path only, and
+     * unfiltered: this is exactly what SQLite reported, including a value
+     * equal to `sqliteCode` (no subtype). The client is what drops it in
+     * that case (D9); when SQLite does report a subtype,
+     * `(sqliteExtendedCode & 0xff) === sqliteCode`.
+     */
+    sqliteExtendedCode?: number;
+    /**
+     * A code this library minted, when the worker knows the cause. The
+     * generic path by which a worker-side error keeps its code across the
+     * boundary — `worker.ts` copies it off any thrown error carrying one, so
+     * this is a structural contract and not a hook for one class.
+     *
+     * **Nothing sets it today.** `WorkerQueryTimeout` was its only producer
+     * and it went with the execution budget when `timeout` became a
+     * client-side wall-clock deadline. Kept rather than deleted: it is the
+     * twin of `sqliteCode` above, which is load-bearing, and rebuilding it
+     * would cost the same three sites it occupies.
+     */
+    errorCode?: SQLiteErrorCode;
+    /**
+     * Whether the connection is inside a transaction once this query has
+     * ended — `sqlite3_get_autocommit() === 0`. SQLite can leave a
+     * transaction by itself: an interrupted INSERT/UPDATE/DELETE rolls the
+     * whole transaction back. Absent when the worker could not read it.
+     */
+    inTransaction?: boolean | undefined;
 } | {
     type: 'closed';
     callId: number;
 } | {
     type: 'deleted';
     callId: number;
+}
+/** The delete worker found nothing at that name; deleteDatabase turns it into DATABASE_NOT_FOUND. */
+ | {
+    type: 'not-found';
 } | {
     type: 'open-error';
     callId: number;
     message: string;
     cause?: unknown;
     /** SQLite's numeric result code, when the failure came from SQLite. */
-    sqliteCode?: number;
+    sqliteCode?: SQLiteResultCode;
 };
 /** Which wa-sqlite WebAssembly build a worker loads. */
 export type SQLiteBuild = 'sync' | 'async' | 'jspi';
@@ -139,13 +238,28 @@ export declare const BUILD_REQUIREMENTS: {
     readonly async: readonly [];
     readonly jspi: readonly ["jspi"];
 };
+/**
+ * Platform features a build USES when present and works without, at a cost —
+ * the symmetric of `degradesWithout` on a VFS, at the level where this one
+ * actually lives. The `sync` build cannot carry an abort into a running
+ * `step()` without a `SharedArrayBuffer`, and there is no SharedArrayBuffer
+ * outside a cross-origin isolated context: measured 2026-09-04, it is not
+ * restricted there, it is absent. Nothing here names COOP/COEP or
+ * Document-Isolation-Policy: any of them satisfies the probe, and one of them
+ * is Chrome-only.
+ */
+export declare const BUILD_DEGRADES_WITHOUT: {
+    readonly sync: readonly ["cross-origin-isolated"];
+    readonly async: readonly [];
+    readonly jspi: readonly [];
+};
 /**
  * A platform feature a VFS may need. Which browser versions ship each one is
- * documentation data, not runtime data, so it lives in the README generator
+ * documentation data, not runtime data, so it lives in the VFS.md generator
  * (`scripts/render-vfs-matrix.ts`) with its sources — not here, where it would
  * ship to every consumer for nothing.
  */
-export type PlatformFeature = 'opfs' | 'readwrite-unsafe' | 'jspi' | 'writable-stream';
+export type PlatformFeature = 'opfs' | 'readwrite-unsafe' | 'jspi' | 'writable-stream' | 'cross-origin-isolated';
 /** Where a VFS keeps the database. */
 export type VFSStorage = 'opfs' | 'indexeddb' | 'memory';
 /**
@@ -184,14 +298,40 @@ export type VFSCapability = {
     readonly storage: VFSStorage;
     /** How the database is arranged within that storage. */
     readonly layout: VFSLayout;
+    /**
+     * Whether this VFS takes its OPFS access handle in the EXCLUSIVE mode —
+     * `createSyncAccessHandle()` with no `mode`, rather than
+     * `mode: 'readwrite-unsafe'`.
+     *
+     * It decides whether an acquisition has to be retried. A terminated context
+     * releases its Web Locks at once but keeps its OPFS access handles for up to
+     * ~2 s on Chromium (HANDLE-CORPSE, `mem:measurements`), so a VFS taking an
+     * exclusive handle can meet a file held by something that answers nothing:
+     * no lock to wait on, no owner to ask, only time to wait out. Where
+     * `readwrite-unsafe` is used a second handle is granted regardless, and a
+     * dead holder blocks nobody.
+     *
+     * Declared rather than detected, because the error is not available where the
+     * decision has to be made: wa-sqlite's `jOpen` swallows it (measured
+     * 2026-09-18) and SQLite reports a bare `SQLITE_CANTOPEN`. Where the error IS
+     * available — VFS instantiation — `createVfsInstance` tests it directly and
+     * needs no declaration.
+     *
+     * NOT declared for `OPFSAdaptiveVFS` and `OPFSWriteAheadVFS`, which ask for
+     * `readwrite-unsafe` and fall back to an exclusive handle only on an engine
+     * that lacks it. That combination is real but out of reach: Firefox releases
+     * a dead worker's handle in 1-6 ms (HANDLE-ORPHAN), a window nothing loses.
+     */
+    readonly exclusiveFileHandle: boolean;
     /**
      * Platform features without which this VFS cannot work at all.
      *
      * `readwrite-unsafe` is the one that bites: WebIDL ignores the unknown
      * dictionary member on engines that do not implement it, so the handle
-     * silently opens exclusive and the second connection hangs rather than
-     * failing. Declaring it is what lets the conformance suite probe for it and
-     * skip, instead of leaving it to surface as a 60-second timeout.
+     * silently opens exclusive, and a second connection then waits or fails
+     * depending on the VFS — see `degradesWithout` and `singleConnectionWithout`.
+     * Declaring it is what lets the conformance suite probe for it and skip,
+     * instead of leaving it to surface as a 60-second timeout.
      */
     readonly requires: readonly PlatformFeature[];
     /**
@@ -199,20 +339,119 @@ export type VFSCapability = {
      *
      * `OPFSAdaptiveVFS` is the case this field exists for. Without
      * `readwrite-unsafe` it rotates a single exclusive access handle between
-     * connections instead of holding one each. That works — 102 of 104 browser
-     * tests pass on Firefox — but it serializes the whole pool for the duration
-     * of a long uninterruptible statement.
+     * connections instead of holding one each. That works — Firefox is the engine
+     * the browser suite exercises it on — but a connection in a long
+     * uninterruptible statement holds the handle, and every other connection to
+     * the database, in another client or tab, waits for it. Within one client it
+     * runs a single worker there: see `singleConnectionWithout`.
      *
      * Without this distinction, a support table derived from browser specs would
      * mark that VFS broken everywhere outside Chromium, when it merely degrades.
      */
     readonly degradesWithout: readonly PlatformFeature[];
+    /**
+     * Platform features without which a pool of more than one worker buys this
+     * VFS nothing, so it runs on one (spec 2026-09-13, §3 and §10). Either the
+     * VFS holds its database file exclusively for a connection's whole life and
+     * a second worker cannot open at all (`OPFSWriteAheadVFS`), or it rotates one
+     * exclusive access handle between connections and a second worker only waits
+     * its turn (`OPFSAdaptiveVFS` — measured 2026-09-14 on Firefox: a pool of one
+     * was faster at startup and on bursts of reads, and equal everywhere else).
+     * The pool's surplus workers probe the feature before loading anything and
+     * decline (`src/worker/probes.ts`); every feature listed needs a probe there.
+     */
+    readonly singleConnectionWithout: readonly PlatformFeature[];
+    /**
+     * Files this VFS keeps beside the database, by suffix, beyond the three every
+     * layout may have (`''`, `-journal`, `-wal`). `deleteDatabase` removes them
+     * with the rest; a file missing from this list outlives its database.
+     *
+     * `OPFSWriteAheadVFS` keeps its write-ahead log in two files of its own,
+     * `-wa0` and `-wa1` (wa-sqlite's `#getWriteAheadNameFromDbName`) — measured
+     * left behind by every deletion until 2026-09-14.
+     */
+    readonly extraFileSuffixes: readonly string[];
+    /**
+     * Whether every statement on this VFS must hand its worker back to the event
+     * loop while it runs, abortable or not.
+     *
+     * `IDBBatchAtomicVFS` is why it exists. Its `jLock` opens a readwrite
+     * IndexedDB transaction on reaching SHARED, and IndexedDB commits a
+     * transaction only once its thread returns to the event loop. A worker inside
+     * one long statement never did, so every other connection's read queued
+     * behind it until the statement ended — measured 2026-09-14 on both engines
+     * (`mem:measurements`, IDB-SIGNAL). The worker then runs its progress handler
+     * on every statement, a task turn every `PROGRESS_OPS` VM ops, which measured
+     * no cost. The `sync` build cannot yield and ignores it.
+     */
+    readonly yieldsDuringStatements: boolean;
+    /**
+     * PRAGMAs this library applies on open for this VFS.
+     *
+     * Merged UNDER the consumer's `pragmas`, so any key they set wins and they
+     * never lose a default by setting an unrelated one — `foreign_keys` is the
+     * common case, and replacing rather than merging would silently disable
+     * everything below it.
+     *
+     * The bar is deliberately high, and almost nothing clears it: **more
+     * performance without less reliability, sourced rather than guessed.** Three
+     * things were weighed and rejected. `journal_mode=wal` universally, because
+     * no VFS here implements `xShmMap` and upstream gives write-ahead logging to
+     * `OPFSWriteAheadVFS` alone, inside the VFS and unreachable by pragma.
+     * `synchronous=normal`, because relaxing durability spends the consumer's
+     * data, not their milliseconds. And `cache_size`, because raising it changes
+     * a mode without a measurable gain — Firefox showed none at all, and the
+     * heap it can then reach is never given back (measured 2026-09-02).
+     */
+    readonly defaultPragmas: Readonly<Record<string, string>>;
+    /**
+     * Whether this VFS enforces an origin-wide exclusive connection lock for the
+     * client's lifetime.
+     *
+     * When `true`, `createSQLiteClient` acquires a `bsq:conn:…` Web Lock on first
+     * use. A second client that attempts to open the same database receives `DATABASE_IN_USE`
+     * immediately on its first query instead of silently reading a frozen, broken
+     * view. This field is the only thing standing between a consumer and an
+     * unfalsifiable silent failure — `SELECT 1` and even
+     * `SELECT count(*) FROM sqlite_master` pass on a broken second client.
+     *
+     * `true` only for `AccessHandlePoolVFS`, whose OPFS access-handle pool is not
+     * sharable across connections (measured AHP-2TAB, 2026-09-01).
+     * `false` for `IDBMirrorVFS` — despite `multiConnection: false` — because two
+     * clients on that VFS DO share data over its origin-wide `BroadcastChannel`
+     * (measured 2026-09-01, 3/3 both engines). `multiConnection: false` there marks
+     * concurrent-writer unsafety, not isolation.
+     * `false` for the memory VFS, which are isolated by construction and have
+     * nothing to exclude.
+     *
+     * `VFS_CAPABILITIES` is the single source of truth the client guard, the
+     * conformance suite, the VFS.md generator and the benchmark page all read.
+     * The gate is by this declaration, not by VFS name.
+     */
+    readonly exclusiveConnection: boolean;
+    /**
+     * Platform features without which this VFS holds its database file
+     * exclusively for a connection's whole life, across the origin — so the
+     * client takes `bsq:conn` exclusively, as for `exclusiveConnection`, and a
+     * second client gets `DATABASE_IN_USE` (spec 2026-09-15).
+     *
+     * `OPFSWriteAheadVFS` without `readwrite-unsafe`: upstream's VFS requires the
+     * mode and keeps its three access handles for the connection's life, so
+     * nothing else can open the file — every query of a second client failed
+     * with WORKER_CRASHED on Firefox, 20/20 per shape (2026-09-15).
+     *
+     * The page cannot probe these features, so worker 0 probes them before
+     * opening (`src/worker/probes.ts`): every feature listed needs a probe there,
+     * and must also be in `singleConnectionWithout`, whose surplus workers
+     * decline before they touch the file.
+     */
+    readonly exclusiveConnectionWithout: readonly PlatformFeature[];
 };
 /**
  * The single source of truth for VFS selection. `SQLiteVFS` is derived from its
  * keys, `worker/worker.ts` must supply a loader for every key, the guards in
  * `client.ts` read it, the conformance suite gates its scenarios on it, and the
- * README table is generated from it. Nothing may hold a second copy.
+ * VFS.md table is generated from it. Nothing may hold a second copy.
  *
  * Build order is a decision per VFS, not a rule: `sync` is both the fastest and
  * the most portable build, so it leads wherever supported; `OPFSAdaptiveVFS`
@@ -222,8 +461,8 @@ export type VFSCapability = {
  * wa-sqlite v1.1.2, never copied from upstream's table.
  */
 export declare const VFS_CAPABILITIES: {
-    readonly OPFSAdaptiveVFS: {
-        readonly builds: readonly ["async", "jspi"];
+    readonly OPFSWriteAheadVFS: {
+        readonly builds: readonly ["sync", "async", "jspi"];
         readonly maxPoolSize: null;
         readonly poolLimitReason: null;
         readonly multiConnection: true;
@@ -231,11 +470,18 @@ export declare const VFS_CAPABILITIES: {
         readonly memoryModel: 'page-cache';
         readonly storage: 'opfs';
         readonly layout: 'opfs-path';
+        readonly exclusiveFileHandle: false;
         readonly requires: readonly ["opfs"];
         readonly degradesWithout: readonly ["readwrite-unsafe"];
+        readonly singleConnectionWithout: readonly ["readwrite-unsafe"];
+        readonly extraFileSuffixes: readonly ["-wa0", "-wa1"];
+        readonly yieldsDuringStatements: false;
+        readonly exclusiveConnection: false;
+        readonly exclusiveConnectionWithout: readonly ["readwrite-unsafe"];
+        readonly defaultPragmas: {};
     };
-    readonly OPFSWriteAheadVFS: {
-        readonly builds: readonly ["sync", "async", "jspi"];
+    readonly OPFSAdaptiveVFS: {
+        readonly builds: readonly ["async", "jspi"];
         readonly maxPoolSize: null;
         readonly poolLimitReason: null;
         readonly multiConnection: true;
@@ -243,20 +489,34 @@ export declare const VFS_CAPABILITIES: {
         readonly memoryModel: 'page-cache';
         readonly storage: 'opfs';
         readonly layout: 'opfs-path';
+        readonly exclusiveFileHandle: false;
         readonly requires: readonly ["opfs"];
         readonly degradesWithout: readonly ["readwrite-unsafe"];
+        readonly singleConnectionWithout: readonly ["readwrite-unsafe"];
+        readonly extraFileSuffixes: readonly [];
+        readonly yieldsDuringStatements: false;
+        readonly exclusiveConnection: false;
+        readonly exclusiveConnectionWithout: readonly [];
+        readonly defaultPragmas: {};
     };
     readonly OPFSCoopSyncVFS: {
         readonly builds: readonly ["sync", "async", "jspi"];
-        readonly maxPoolSize: null;
-        readonly poolLimitReason: null;
+        readonly maxPoolSize: 1;
+        readonly poolLimitReason: 'it rotates one exclusive access handle between connections, so another worker only waits its turn';
         readonly multiConnection: true;
         readonly persistent: true;
         readonly memoryModel: 'page-cache';
         readonly storage: 'opfs';
         readonly layout: 'opfs-path';
+        readonly exclusiveFileHandle: true;
         readonly requires: readonly ["opfs"];
         readonly degradesWithout: readonly [];
+        readonly singleConnectionWithout: readonly [];
+        readonly extraFileSuffixes: readonly [];
+        readonly yieldsDuringStatements: false;
+        readonly exclusiveConnection: false;
+        readonly exclusiveConnectionWithout: readonly [];
+        readonly defaultPragmas: {};
     };
     readonly AccessHandlePoolVFS: {
         readonly builds: readonly ["sync", "async", "jspi"];
@@ -267,8 +527,18 @@ export declare const VFS_CAPABILITIES: {
         readonly memoryModel: 'page-cache';
         readonly storage: 'opfs';
         readonly layout: 'opfs-pool';
+        readonly exclusiveFileHandle: true;
         readonly requires: readonly ["opfs"];
         readonly degradesWithout: readonly [];
+        readonly singleConnectionWithout: readonly [];
+        readonly extraFileSuffixes: readonly [];
+        readonly yieldsDuringStatements: false;
+        readonly exclusiveConnection: true;
+        readonly exclusiveConnectionWithout: readonly [];
+        readonly defaultPragmas: {
+            readonly locking_mode: 'exclusive';
+            readonly journal_mode: 'wal';
+        };
     };
     readonly IDBBatchAtomicVFS: {
         readonly builds: readonly ["async", "jspi"];
@@ -279,8 +549,15 @@ export declare const VFS_CAPABILITIES: {
         readonly memoryModel: 'page-cache';
         readonly storage: 'indexeddb';
         readonly layout: 'idb-store';
+        readonly exclusiveFileHandle: false;
         readonly requires: readonly [];
         readonly degradesWithout: readonly [];
+        readonly singleConnectionWithout: readonly [];
+        readonly extraFileSuffixes: readonly [];
+        readonly yieldsDuringStatements: true;
+        readonly exclusiveConnection: false;
+        readonly exclusiveConnectionWithout: readonly [];
+        readonly defaultPragmas: {};
     };
     readonly IDBMirrorVFS: {
         readonly builds: readonly ["async", "jspi"];
@@ -291,8 +568,15 @@ export declare const VFS_CAPABILITIES: {
         readonly memoryModel: 'whole-database';
         readonly storage: 'indexeddb';
         readonly layout: 'idb-store';
+        readonly exclusiveFileHandle: false;
         readonly requires: readonly [];
         readonly degradesWithout: readonly [];
+        readonly singleConnectionWithout: readonly [];
+        readonly extraFileSuffixes: readonly [];
+        readonly yieldsDuringStatements: false;
+        readonly exclusiveConnection: false;
+        readonly exclusiveConnectionWithout: readonly [];
+        readonly defaultPragmas: {};
     };
     readonly OPFSAnyContextVFS: {
         readonly builds: readonly ["async", "jspi"];
@@ -303,8 +587,15 @@ export declare const VFS_CAPABILITIES: {
         readonly memoryModel: 'page-cache';
         readonly storage: 'opfs';
         readonly layout: 'opfs-path';
+        readonly exclusiveFileHandle: false;
         readonly requires: readonly ["opfs", "writable-stream"];
         readonly degradesWithout: readonly [];
+        readonly singleConnectionWithout: readonly [];
+        readonly extraFileSuffixes: readonly [];
+        readonly yieldsDuringStatements: false;
+        readonly exclusiveConnection: false;
+        readonly exclusiveConnectionWithout: readonly [];
+        readonly defaultPragmas: {};
     };
     readonly MemoryVFS: {
         readonly builds: readonly ["sync", "async", "jspi"];
@@ -315,8 +606,15 @@ export declare const VFS_CAPABILITIES: {
         readonly memoryModel: 'whole-database';
         readonly storage: 'memory';
         readonly layout: 'memory';
+        readonly exclusiveFileHandle: false;
         readonly requires: readonly [];
         readonly degradesWithout: readonly [];
+        readonly singleConnectionWithout: readonly [];
+        readonly extraFileSuffixes: readonly [];
+        readonly yieldsDuringStatements: false;
+        readonly exclusiveConnection: false;
+        readonly exclusiveConnectionWithout: readonly [];
+        readonly defaultPragmas: {};
     };
     readonly MemoryAsyncVFS: {
         readonly builds: readonly ["async", "jspi"];
@@ -327,22 +625,18 @@ export declare const VFS_CAPABILITIES: {
         readonly memoryModel: 'whole-database';
         readonly storage: 'memory';
         readonly layout: 'memory';
+        readonly exclusiveFileHandle: false;
         readonly requires: readonly [];
         readonly degradesWithout: readonly [];
+        readonly singleConnectionWithout: readonly [];
+        readonly extraFileSuffixes: readonly [];
+        readonly yieldsDuringStatements: false;
+        readonly exclusiveConnection: false;
+        readonly exclusiveConnectionWithout: readonly [];
+        readonly defaultPragmas: {};
     };
 };
 export type SQLiteVFS = keyof typeof VFS_CAPABILITIES;
 /** The build used when the caller does not name one. */
 export declare const defaultBuildFor: (vfs: SQLiteVFS) => SQLiteBuild;
-/**
- * The VFS this project recommends when a caller has no reason to choose
- * another. It is NOT a default — `vfs` is required, precisely so that the name
- * lives in the consumer's own source and cannot move underneath their data.
- *
- * It lives here, beside the table, because the README generator marks this row
- * `(recommended)` and would otherwise hold a second copy. It is deliberately
- * not exported: a consumer writing `vfs: RECOMMENDED_VFS` would be exposed to
- * the same displacement the day the recommendation changes.
- */
-export declare const RECOMMENDED_VFS: SQLiteVFS;
 export {};

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { SQLiteBuild, WasmLocation } from './types';
+import { type SQLiteBuild, type SQLiteVFS, type WasmLocation } from './types';
 export declare const sqlParams: () => {
     addParam: (v: unknown) => string;
     addParamArray: (values: unknown[]) => string;
@@ -6,13 +6,20 @@ export declare const sqlParams: () => {
 };
 export declare const isReadQuery: (sql: string) => boolean;
 export declare const isWriteQuery: (sql: string) => boolean;
+/**
+ * Whether `sql` manages the transaction or its savepoints rather than data
+ * (spec 2026-09-11, D8). Never wrapped in the library's savepoint: there is
+ * nothing to undo, and a `RELEASE u` run inside it would pop it along with
+ * `u`. The leading keyword decides: these statements are never compound.
+ */
+export declare const isTransactionControl: (sql: string) => boolean;
 /**
  * Combines two abort signals into one that fires with the reason of whichever
  * source aborted first, plus the `release()` that unsubscribes it.
  *
  * NOT `AbortSignal.any()`. That is Chrome 116 / Firefox 124 / Safari 17.4, far
  * above this library's floor (Chrome 92 / Firefox 95 / Safari 15.4), and
- * adopting it would raise every row of the generated README matrix for every
+ * adopting it would raise every row of the generated VFS.md matrix for every
  * consumer.
  *
  * The common case allocates nothing: with one side absent, or one side already
@@ -23,6 +30,26 @@ export declare const mergeSignals: (a: AbortSignal | undefined, b: AbortSignal |
     signal: AbortSignal | undefined;
     release: () => void;
 };
+/**
+ * The `timeout` option: a wall-clock budget in milliseconds, counted from the
+ * call. Returns the signal the call should actually use — the caller's own,
+ * merged with one this library owns and aborts when the budget is spent.
+ *
+ * The abort reason IS the error the caller receives. Every abort path in this
+ * library rejects with `signal.reason`, and `mergeSignals` relays a reason
+ * verbatim, so nothing downstream has to ask which signal fired. That is why
+ * this is an AbortController and a setTimeout rather than
+ * `AbortSignal.timeout()`, which offers no way to set the reason.
+ *
+ * `release()` is owed exactly once, however the call ends.
+ */
+export declare const withDeadline: (options: {
+    signal?: AbortSignal | undefined;
+    timeout?: number | undefined;
+} | undefined, method: string) => {
+    signal: AbortSignal | undefined;
+    release: () => void;
+};
 /**
  * Routing guard for the read-shaped methods (`read`, `chunk`, `stream`, `first`).
  * Throws before a lease is taken, so a rejected statement costs no pool capacity.
@@ -68,6 +95,19 @@ export declare const assertGeneratedExpression: (expr: string, column: string) =
  * `createSQLiteClient()` rather than inside an unrelated query, and by the
  * worker at open, which is the only place the statements actually run.
  */
+/**
+ * The PRAGMAs a client actually applies: the VFS's declared defaults with the
+ * consumer's own layered over them.
+ *
+ * **Merged, never replaced.** A consumer who passes one pragma is answering a
+ * question of their own — `foreign_keys` is the usual one — not declining the
+ * VFS's defaults, and replacing would silently drop every default the moment
+ * they set anything at all. A key they DO set always wins, which is how a
+ * default is refused: pass `journal_mode` yourself and yours is what runs.
+ *
+ * Order matters and is the whole function: spread the defaults first.
+ */
+export declare const resolvePragmas: (vfs: SQLiteVFS, pragmas: Record<string, string> | undefined) => Record<string, string>;
 export declare const renderPragmas: (pragmas: Record<string, string>) => string[];
 /**
  * The single definition of database identity — one string used everywhere: