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

package/dist/inspect.d.ts

@@ -0,0 +1,96 @@
+import type { LockEntries, Locks } from './locks';
+import type { SQLiteVFS } from './types';
+export declare const resolveRealmId: (locks: Locks, snapshot: LockEntries, ownMarkerName?: string) => Promise<string>;
+/** One live client on a database. */
+export type DatabaseClient = {
+    readonly id: string;
+    readonly name: string;
+    /** The realm holding it. Every client in one tab reports the same value. */
+    readonly tab: string;
+    /** That realm is the caller's. A same-origin iframe is another tab here. */
+    readonly sameTab: boolean;
+    /** Four VFS share the `opfs` namespace, and therefore the file. */
+    readonly vfs: SQLiteVFS;
+};
+export type InspectionBase = {
+    readonly file: string;
+    readonly vfs: SQLiteVFS;
+    /** Distinct realms among the clients. */
+    readonly tabs: number;
+    readonly write: {
+        /** The realm writing now, never the client. `null` when nobody writes. */
+        readonly tab: string | null;
+        /** Always false when `tab` is null. */
+        readonly sameTab: boolean;
+        /** Writers queued behind it, across the whole origin. */
+        readonly waiting: number;
+    };
+};
+export type DatabaseInspection = InspectionBase & {
+    readonly clients: readonly DatabaseClient[];
+};
+export type ClientInspection = InspectionBase & {
+    /**
+     * This client, or `null` when this client's own marker is not in the
+     * snapshot — the brief window before its Web Locks grant has landed, or when
+     * the grant could not be taken at all.
+     */
+    readonly self: DatabaseClient | null;
+    readonly siblings: readonly DatabaseClient[];
+};
+/**
+ * The census, given locks that are already known to work.
+ *
+ * One `entries()` call supplies the roster, the writer and the queue together,
+ * so those three always describe the same instant and cannot compose a state
+ * that never existed. The one exception: a realm whose id has never been
+ * resolved and that was given no marker pays one extra query to read its own
+ * `clientId` back — once, and never again for that realm's lifetime.
+ */
+export declare const inspectWith: (locks: Locks, file: string, vfs: SQLiteVFS, ownMarkerName?: string) => Promise<DatabaseInspection>;
+/**
+ * Whether any OTHER client of this library holds `file` on `vfs`.
+ *
+ * The discriminator behind the `openTimeout` message: a slot that never became
+ * ready is usually blamed on another tab, and that is often false — a page
+ * reloaded without `close()` leaves a dead context holding the database, and
+ * no live client to find. One `entries()` call tells the two apart.
+ *
+ * Deliberately NOT `inspectWith`: this runs while the pool is half-open, so it
+ * resolves no realm id (which would take a lock), touches nothing the client
+ * owns, and never throws. `undefined` is "could not be answered" — Web Locks
+ * missing, a VFS whose pages never leave their worker, a registry that rejects,
+ * or one that does not answer within `deadlineMs`. A caller that reads
+ * `undefined` as `false` would state the opposite of what was observed.
+ *
+ * `false` means no client of THIS library holds it — never that nobody does.
+ * Another library, another origin's tooling and native code are all invisible
+ * to the Web Locks registry.
+ */
+export declare const libraryClientsHold: (locks: Locks, file: string, vfs: SQLiteVFS, ownId: string, deadlineMs?: number) => Promise<boolean | undefined>;
+export type InspectDatabaseOptions = {
+    /**
+     * The VFS the database was created with. Required, and not defaulted: four
+     * VFS share one underlying file, and the others are separate stores
+     * entirely, so guessing would report on a different database.
+     */
+    vfs: SQLiteVFS;
+};
+/**
+ * Who is live on a database, without opening it.
+ *
+ * This is a snapshot, stale the instant it resolves. It informs a UI; it never
+ * authorizes an action — `deleteDatabase` raising `DATABASE_IN_USE` is the only
+ * authority on whether a database can be removed.
+ *
+ * Takes `file` positionally like `createSQLiteClient` and `deleteDatabase`:
+ * every root export of this library names the database the same way.
+ *
+ * @throws {SQLiteError} `INVALID_OPTION` when `vfs` is missing, unknown, or a
+ *   memory VFS, where two clients are two databases and the question has no
+ *   meaning.
+ * @throws {SQLiteError} `UNSUPPORTED` where the Web Locks API is unavailable.
+ *   Reporting zero there would be indistinguishable from a database nobody
+ *   holds.
+ */
+export declare const inspectDatabase: (file: string, options: InspectDatabaseOptions) => Promise<DatabaseInspection>;

package/dist/locks.d.ts

@@ -8,20 +8,46 @@
  * that is killed has its locks released by the browser, so its orphans become
  * collectable immediately, with no timestamp and no grace period.
  */
+import type { SQLiteVFS } from './types';
+/** One entry in the lock registry as returned by `query()`. */
+type QueriedLock = {
+    name?: string;
+    mode?: string;
+    clientId?: string;
+};
 /** The slice of the Web Locks API this module uses. */
 type LockManager = {
     request: (name: string, optionsOrCallback: any, callback?: (lock: unknown) => Promise<unknown>) => Promise<unknown>;
     query: () => Promise<{
-        held?: {
-            name?: string;
-        }[];
+        held?: QueriedLock[];
+        pending?: QueriedLock[];
     }>;
 };
 export type Locks = {
     /** False when the Web Locks API is missing; every method then no-ops. */
     readonly available: boolean;
-    /** Acquires `name` and resolves with the function that releases it. */
-    hold: (name: string) => Promise<() => void>;
+    /**
+     * Acquires `name` and resolves with the function that releases it.
+     *
+     * `mode: 'shared'` is what the epoch marker uses: many realms may hold the
+     * same name at once, so publishing never waits and two realms can never
+     * collide on one epoch number. `signal` aborts the WAIT — never the hold —
+     * and makes the request reject with `AbortError`.
+     *
+     * `ifAvailable: true` mirrors `tryWithLock`'s semantics: the real API hands
+     * the callback `null` rather than waiting when the lock is held elsewhere.
+     * Resolves with `undefined` in that case instead of waiting. Never waits —
+     * that is the point for the connection guard.
+     */
+    hold(name: string, options?: {
+        mode?: 'exclusive' | 'shared';
+        signal?: AbortSignal;
+    }): Promise<() => void>;
+    hold(name: string, options: {
+        mode?: 'exclusive' | 'shared';
+        signal?: AbortSignal;
+        ifAvailable: true;
+    }): Promise<(() => void) | undefined>;
     /** Runs `fn` while holding `name` exclusively. */
     withLock: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
     /**
@@ -36,13 +62,105 @@ export type Locks = {
     tryWithLock: (name: string, fn: () => Promise<unknown>) => Promise<boolean>;
     /** Names currently held anywhere in this origin — every tab included. */
     heldNames: () => Promise<string[]>;
+    /**
+     * The origin's whole lock registry: held AND pending, each with the realm
+     * holding or awaiting it.
+     *
+     * `heldNames()` answers a different, cheaper question and keeps its own
+     * shape — `epochsFor` only ever needs names.
+     */
+    entries: () => Promise<LockEntries>;
+};
+/** One entry of the origin's lock registry, held or pending. */
+export type LockEntry = {
+    readonly name: string;
+    readonly mode: 'exclusive' | 'shared';
+    readonly clientId: string;
+};
+export type LockEntries = {
+    readonly held: readonly LockEntry[];
+    readonly pending: readonly LockEntry[];
 };
 export declare const stagingTableName: (uuid: string) => string;
 export declare const isStagingTable: (table: string) => boolean;
 export declare const stagingLockName: (file: string, table: string) => string;
 export declare const sweepLockName: (file: string) => string;
+/**
+ * The marker a client holds to publish that it is alive on a database.
+ *
+ * Held in SHARED mode and contended by NOBODY: like `bsq:staging` this is a
+ * liveness marker, not mutual exclusion. `bsq:conn` stays the only occupancy
+ * detector `deleteDatabase` rests on — a second one would diverge from it.
+ *
+ * The label is `encodeURIComponent`d, which escapes `:` as `%3A`. That is what
+ * makes the tail split unambiguously into exactly three segments whatever the
+ * consumer names their client. The FILE may itself contain a colon, which is
+ * why the reader rebuilds the exact prefix instead of scanning for separators —
+ * the same trap `epochsFor` documents.
+ */
+export declare const clientMarkerName: (vfs: SQLiteVFS, file: string, id: string, clientName: string) => string;
+export type ClientMarker = {
+    readonly id: string;
+    readonly vfs: SQLiteVFS;
+    readonly name: string;
+};
+/**
+ * Reads one of our markers, or `undefined` for anything else.
+ *
+ * Every rejection below is deliberate: a marker this version does not
+ * understand — a future one carrying more segments, say — must be SKIPPED, not
+ * guessed at. Guessing is how a reader reports another database's state.
+ */
+export declare const parseClientMarker: (lockName: string, vfs: SQLiteVFS, file: string) => ClientMarker | undefined;
+/**
+ * The storage namespace a VFS writes into — derived from `layout`, NEVER from
+ * the VFS name.
+ *
+ * `OPFSAdaptiveVFS`, `OPFSAnyContextVFS`, `OPFSCoopSyncVFS` and
+ * `OPFSWriteAheadVFS` all walk from `navigator.storage.getDirectory()` and open
+ * `getFileHandle(filename)`, so one database name is ONE file for all four. A
+ * per-VFS key would let two of them write the same bytes without ever
+ * excluding each other: a missed conflict corrupts, an invented one only slows.
+ *
+ * `idb-store` goes finer than its layout on purpose — its two VFS each own an
+ * IndexedDB database named after their class, so grouping them would invent a
+ * conflict for free. `opfs-pool` and `memory` are alone in their layout, so the
+ * VFS name is already the namespace.
+ *
+ * `worker/worker.ts:627` gates on `layout` for the same reason, in those words.
+ */
+export declare const namespaceFor: (vfs: SQLiteVFS) => string;
+/**
+ * Whether two clients on this VFS can reach the same bytes at all.
+ *
+ * False for the memory VFS: its pages live in the worker that opened them and
+ * `maxPoolSize` is 1, so two clients on one name are two independent
+ * databases. Locking them against each other would be wrong as well as slow —
+ * an origin round trip charged to the VFS chosen for speed. `delete.ts:79`
+ * skips the same layout, for the same reason.
+ */
+export declare const sharesStorage: (vfs: SQLiteVFS) => boolean;
 /** Serializes database opening across the pool — replaces the SAB init mutex. */
-export declare const initLockName: (file: string) => string;
+export declare const initLockName: (vfs: SQLiteVFS, file: string) => string;
+/**
+ * Serializes WRITERS across every client and tab in the origin. Exclusive, so
+ * at most one is held per database at any instant however many clients exist.
+ */
+export declare const writeLockName: (vfs: SQLiteVFS, file: string) => string;
+/**
+ * Origin-wide exclusive connection lock for VFS that cannot safely share a
+ * database across clients (`exclusiveConnection: true` in `VFS_CAPABILITIES`).
+ *
+ * Held for the client's lifetime. A second `createSQLiteClient` that tries to
+ * open the same database will fail its first query with `BUSY` instead of
+ * silently reading a broken, frozen view — the failure mode measured as
+ * AHP-2TAB (2026-09-01) where `SELECT 1` passes and `SELECT count(*) FROM
+ * sqlite_master` returns 0 on an unfixable connection.
+ *
+ * The key uses `namespaceFor(vfs)` for the same reason `writeLockName` does:
+ * the gate is by layout declaration, not by VFS name.
+ */
+export declare const connectionLockName: (vfs: SQLiteVFS, file: string) => string;
 /**
  * Which staging tables no live `output()` is using — pure, so it is driven by
  * Node tests rather than by two browser tabs.

package/dist/pool.d.ts

@@ -1,12 +1,16 @@
-import { SQLiteError } from './errors';
+import { SQLiteError, type SQLiteErrorCode } from './errors';
 import type { Logger } from './logger';
-import type { SQLiteBuild, SQLiteVFS, WasmLocation } from './types';
+import type { SQLiteResultCode } from './sqlite-codes';
+import type { PlatformFeature, SavepointOp, SQLiteBuild, SQLiteVFS, WasmLocation } from './types';
 /**
  * Query execution options forwarded to a pool worker.
  */
 export type PoolWorkerQueryOptions = {
     chunkSize?: number | undefined;
     credits?: number | undefined;
+    timeout?: number | undefined;
+    /** Forwarded to the worker so it installs the async progress handler (§4 D2). */
+    abortable?: boolean | undefined;
     /**
      * When true, the query's completion does not call `deps.onServed`. Set for
      * the commit-propagation barrier: it is a synthetic probe, not user work, and
@@ -16,6 +20,13 @@ export type PoolWorkerQueryOptions = {
      * to prove the barrier stays conditional.
      */
     noServed?: boolean;
+    /**
+     * Read exactly once, when the query is POSTED — below the reuse guard,
+     * never when the query is created. A transaction hands its pending savepoint
+     * conclusion over in here, so a query the guard refuses must not consume it
+     * (spec 2026-09-11, §4).
+     */
+    savepoint?: (() => SavepointOp | undefined) | undefined;
 };
 /**
  * A Worker extended with pool-specific properties.
@@ -38,28 +49,103 @@ export type PoolWorker = Worker & {
     seen: number;
     /** The epoch captured when the current lease was granted. */
     epochTarget: number;
+    /**
+     * Whether the connection was inside a transaction when its last query
+     * ended, as the worker read it (`sqlite3_get_autocommit`). `undefined` until
+     * a query has reported it.
+     *
+     * CONNECTION state, not availability: nothing schedules on it and nothing
+     * may. Availability lives in `scheduler.ts` alone — see the `available`
+     * declaration there — and a flag on this object that the pool consulted would
+     * reopen B1. Its one reader is `transaction.ts`, which asks it whether a
+     * ROLLBACK is still owed and whether its transaction is still alive.
+     */
+    inTransaction?: boolean | undefined;
     query: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: PoolWorkerQueryOptions) => AsyncGenerator<T[] | number>;
     /**
      * Ask the worker to stop. Also settles a `next()` already in flight, which
      * is what lets the consumer's queued `return()` reach the generator's
      * finally instead of waiting behind a chunk that may be minutes away.
+     *
+     * `on` is the transport iterator being stopped, and it is REQUIRED: the call
+     * is a no-op unless the worker is still serving that transport, which is what
+     * keeps a late stop off an unrelated query. It was briefly optional, and an
+     * omitted argument meant "stop whatever is running" — the exact semantics that
+     * let an abandoned generator's late cleanup truncate a healthy query. Nothing
+     * needs that form, so nothing may ask for it.
      */
-    interrupt: () => void;
+    interrupt: (on: object) => void;
     /** Resolves when no query is in flight on this worker. */
     quiesce: () => Promise<void>;
+    /**
+     * Resolves when this worker will accept another query — at `done`, which is
+     * earlier than `quiesce()`. Use it to wait for the WORKER; use `quiesce()`
+     * to wait for a statement to have been fully settled and judged.
+     */
+    free: () => Promise<void>;
     /** Posts `close`, awaits the `closed` reply, then the caller must terminate. */
     close: () => Promise<void>;
+    /**
+     * Stops the thread AND the transport — never the browser's `terminate()`
+     * alone.
+     *
+     * `PoolWorker` IS the native `Worker`, so this used to be the engine's own
+     * method: it killed the thread and told the transport nothing. A request
+     * posted afterwards waited for a reply that could never come — a
+     * transaction's next statement, and its fallback `ROLLBACK`, which carries no
+     * signal by design and so could not even be aborted. Overriding the method,
+     * rather than adding one beside it, is deliberate: there are several
+     * terminate sites and one added later must not be able to forget this.
+     *
+     * `reason` is what in-flight and later requests reject with. It reports
+     * nothing to the client: whoever terminates has already decided this worker's
+     * fate, and going through `onDeath` here would re-enter that decision.
+     */
+    terminate: (reason?: SQLiteError) => void;
+};
+/** What `createPoolWorker` settles with when its worker declined to open. */
+export type DeclinedWorker = {
+    declined: PlatformFeature;
 };
 /**
  * Returns a SQLiteError('BUSY', …) when data carries a lock-conflict result
- * code (5 or 6), else undefined. Shared by both the query-error and
- * open-error paths so the BUSY_CODES decision lives in exactly one place.
+ * code (5 or 6), else undefined. Shared by `statementError` and `startupError`
+ * so the BUSY_CODES decision lives in exactly one place. The extended code
+ * travels with it when it is a subtype (`subtypeOf`) — a query sends one, an
+ * open does not.
  */
 export declare const busyFromCode: (data: {
     message: string;
     cause?: unknown;
-    sqliteCode?: number;
+    sqliteCode?: SQLiteResultCode;
+    sqliteExtendedCode?: number;
 }) => SQLiteError | undefined;
+/**
+ * What a query's `error` message becomes (spec 2026-09-14 §5.3): a code the
+ * worker minted; else `BUSY` for a lock conflict; else `STATEMENT_FAILED` for
+ * any other code SQLite reported; else — a failure SQLite did not report, such
+ * as a JS exception in the worker — a plain Error, as before. `BUSY` and
+ * `STATEMENT_FAILED` carry `sqliteCode`, and `sqliteExtendedCode` when it is a
+ * subtype (`subtypeOf`).
+ */
+export declare const statementError: (data: {
+    message: string;
+    cause?: unknown;
+    sqliteCode?: SQLiteResultCode;
+    sqliteExtendedCode?: number;
+    errorCode?: SQLiteErrorCode;
+}) => Error;
+/**
+ * What a failed open or delete becomes: `BUSY` for a lock conflict, else
+ * `WORKER_CRASHED` — the slot dies either way — carrying SQLite's primary code
+ * when there is one (spec 2026-09-14, D2). No extended code: when
+ * `sqlite3_open_v2` itself fails there is no connection to ask (D7).
+ */
+export declare const startupError: (data: {
+    message: string;
+    cause?: unknown;
+    sqliteCode?: SQLiteResultCode;
+}) => SQLiteError;
 /**
  * The single `new Worker(new URL(…))` expression in this package.
  *
@@ -81,7 +167,7 @@ export declare const spawnWorker: (name: string) => Worker;
 export declare const createPoolWorker: (deps: {
     index: number;
     pool: (PoolWorker | undefined)[];
-    clientPrefix: string;
+    clientName: string;
     file: string;
     vfs: SQLiteVFS;
     build: SQLiteBuild;
@@ -89,10 +175,17 @@ export declare const createPoolWorker: (deps: {
     wasm?: WasmLocation | undefined;
     pragmas?: Record<string, string> | undefined;
     statementCacheSize?: number | undefined;
+    statementCacheBytes?: number | undefined;
     onDeath?: (index: number, error: SQLiteError) => void;
     onServed?: (index: number) => void;
     drainTimeout: number;
     createWorkerDebugState?: ((index: number, name: string) => any) | undefined;
     createQueryDebugState?: ((index: number, sql: string, params?: unknown[]) => any) | undefined;
     logger: Logger;
-}) => Promise<PoolWorker>;
+    abortSlots?: SharedArrayBuffer | undefined;
+    declineWithout?: readonly PlatformFeature[] | undefined;
+    /** Sent to slot 0 where exclusivity depends on a feature (spec 2026-09-15). */
+    probeFirst?: readonly PlatformFeature[] | undefined;
+    /** Worker 0's probe answer, with the function that lets it open. */
+    onProbed?: ((missing: PlatformFeature | null, proceed: () => void) => void) | undefined;
+}) => Promise<PoolWorker | DeclinedWorker>;

package/dist/queries.d.ts

@@ -1,4 +1,5 @@
-import type { OptionsWithSignal, SQLiteChunkOptions } from './api';
+import { type AbandonRegistry } from './abandon';
+import type { SQLiteChunkOptions, SQLiteQueryOptions } from './api';
 import type { PoolWorker } from './pool';
 /**
  * Wires an AbortSignal into a promise that rejects the instant the signal
@@ -13,14 +14,42 @@ export declare const makeAbortRace: (signal: AbortSignal | undefined) => {
     aborted: Promise<never> | undefined;
     teardown: () => void;
 };
+/**
+ * `SQLiteChunkOptions` plus what only this library passes. `registry` is
+ * TEST-ONLY and unsupported; it exists so the abandonment path can be driven
+ * without a garbage collection.
+ */
+export type InternalChunkOptions = SQLiteChunkOptions & {
+    credits?: number;
+    /** The owning layer's teardown, run if the generator is abandoned. */
+    onAbandon?: (() => void) | undefined;
+    /**
+     * Handed the transport iterator, synchronously, before the factory returns.
+     *
+     * An owner that must close this generator from the outside needs it: a
+     * method call on an async generator queues behind a `next()` already in
+     * flight, so `return()` alone parks until a chunk arrives — which on an
+     * `ORDER BY` is the whole sort. `worker.interrupt(transport)` is what
+     * settles that `next()`, and it is a no-op unless the worker still serves
+     * that transport, so only its true owner can be handed it. `src/transaction.ts`
+     * is the only caller; the client path drops its generator instead of
+     * closing it and needs nothing here.
+     */
+    onTransport?: ((iterator: AsyncGenerator<unknown>) => void) | undefined;
+    registry?: AbandonRegistry;
+};
 /**
  * The single query primitive. Every other read path is a thin derivation, and
  * abort is implemented here exactly once.
+ *
+ * **A factory, not a generator function**, so that the transport iterator
+ * exists before the generator does and can be handed to the abandonment
+ * registry. Building it early costs nothing: `worker.query()` runs no code
+ * until its first `next()`, so the query message and the reuse guard still
+ * happen when the consumer first pulls.
  */
-export declare const chunk: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: SQLiteChunkOptions & {
-    credits?: number;
-}) => AsyncGenerator<T[]>;
-export declare const streamRows: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: SQLiteChunkOptions) => AsyncGenerator<T>;
+export declare const chunk: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: InternalChunkOptions) => AsyncGenerator<T[]>;
+export declare const streamRows: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: InternalChunkOptions) => AsyncGenerator<T>;
 export declare const readWorker: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: SQLiteChunkOptions) => Promise<T[]>;
 /**
  * First row, then stop. This BREAKS rather than aborting: a break triggers the
@@ -29,8 +58,8 @@ export declare const readWorker: <T extends Record<string, unknown> = Record<str
  * That is why there is no internal AbortController here and no need to tell an
  * internal abort from the caller's.
  */
-export declare const firstWorker: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: OptionsWithSignal) => Promise<T | undefined>;
-export declare const writeWorker: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: OptionsWithSignal) => Promise<{
+export declare const firstWorker: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: SQLiteQueryOptions) => Promise<T | undefined>;
+export declare const writeWorker: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: SQLiteQueryOptions) => Promise<{
     result: T[];
     affected: number;
 }>;

package/dist/scheduler.d.ts

@@ -35,6 +35,12 @@ export type WriterPolicy = (index: number) => boolean;
  */
 export type InternalSQLiteClientOptions = CreateSQLiteClientOptions & {
     __unsafeTestWriterPolicy?: WriterPolicy;
+    /**
+     * TEST-ONLY, UNSUPPORTED. The byte bound has no falsifier without it: at a
+     * fixed default nothing in the suite can tell a working bound from one that
+     * never fires. Absent from the public options type on purpose.
+     */
+    __unsafeTestStatementCacheBytes?: number;
 };
 export type Scheduler<W> = {
     add: (worker: W) => void;
@@ -55,6 +61,14 @@ export type Scheduler<W> = {
      * counts towards `shutdown()`'s wait.
      */
     remove: (index: number) => void;
+    /**
+     * Takes a slot out of the pool for good because its worker DECLINED to open:
+     * the environment caps the pool below its requested size (spec 2026-09-13).
+     * Unlike `remove()`, the slot settles the readiness gate as neither opened
+     * nor failed, so it never appears in `onFirstSettle`'s `failedIndices` and
+     * never enters the startup retry round.
+     */
+    retire: (index: number) => void;
     /**
      * Closes the front door. Queued waiters reject with `reason`, later
      * acquisitions reject the same way, and the returned promise settles when the

package/dist/sqlite-codes.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The result codes of SQLite 3.53.0, keyed without the `SQLITE_` prefix, in two
+ * tables that match `SQLiteError`'s two fields: test the family on `sqliteCode`
+ * against `SQLITE_CODES` (`CONSTRAINT`, `FULL`), the subtype on
+ * `sqliteExtendedCode` against `SQLITE_EXTENDED_CODES` (`CONSTRAINT_UNIQUE`).
+ * An extended code's low byte is its family (`(2067 & 0xff) === 19`), and its key
+ * begins with the family's key. What each one means:
+ * https://sqlite.org/rescode.html.
+ *
+ * Transcribed from `src/sqlite.h.in` — the source of `sqlite3.h` — at SQLite's
+ * tag `version-3.53.0`, checked 2026-09-14. That is the SQLite of the vendored
+ * wa-sqlite, v1.1.2 (its `package.json` still reads 1.1.1: upstream did not
+ * bump it): its source-id, read from the wasm, is `2026-04-09 11:41:38
+ * 4525003a53a7fc63ca75`, and the tag's `manifest.uuid` begins with the same
+ * hash. Not read from wa-sqlite's `sqlite-constants.js`, which has no
+ * `BUSY_*`, `LOCKED_*`, `CANTOPEN_*`, `CORRUPT_*` or `READONLY_*` codes;
+ * `tests/unit/sqlite-codes.test.ts` checks every name the two share.
+ * Re-transcribe when wa-sqlite moves to another SQLite.
+ *
+ * `SQLiteError.sqliteCode` is typed `SQLiteResultCode` (strict): since
+ * `sqliteCodeOf`, it is always a primary code of the bundled SQLite (D10).
+ * `sqliteExtendedCode` stays open (`SQLiteExtendedResultCode | (number & {})`):
+ * a wrong read must stay representable (D9).
+ */
+/** The 31 primary result codes — what `SQLiteError.sqliteCode` holds. */
+export declare const SQLITE_CODES: Readonly<{
+    readonly OK: 0;
+    readonly ERROR: 1;
+    readonly INTERNAL: 2;
+    readonly PERM: 3;
+    readonly ABORT: 4;
+    readonly BUSY: 5;
+    readonly LOCKED: 6;
+    readonly NOMEM: 7;
+    readonly READONLY: 8;
+    readonly INTERRUPT: 9;
+    readonly IOERR: 10;
+    readonly CORRUPT: 11;
+    readonly NOTFOUND: 12;
+    readonly FULL: 13;
+    readonly CANTOPEN: 14;
+    readonly PROTOCOL: 15;
+    readonly EMPTY: 16;
+    readonly SCHEMA: 17;
+    readonly TOOBIG: 18;
+    readonly CONSTRAINT: 19;
+    readonly MISMATCH: 20;
+    readonly MISUSE: 21;
+    readonly NOLFS: 22;
+    readonly AUTH: 23;
+    readonly FORMAT: 24;
+    readonly RANGE: 25;
+    readonly NOTADB: 26;
+    readonly NOTICE: 27;
+    readonly WARNING: 28;
+    readonly ROW: 100;
+    readonly DONE: 101;
+}>;
+/**
+ * The 82 extended result codes — what `SQLiteError.sqliteExtendedCode` holds
+ * when SQLite reports a subtype. No primary code is repeated here.
+ */
+export declare const SQLITE_EXTENDED_CODES: Readonly<{
+    readonly ERROR_MISSING_COLLSEQ: 257;
+    readonly ERROR_RETRY: 513;
+    readonly ERROR_SNAPSHOT: 769;
+    readonly ERROR_RESERVESIZE: 1025;
+    readonly ERROR_KEY: 1281;
+    readonly ERROR_UNABLE: 1537;
+    readonly IOERR_READ: 266;
+    readonly IOERR_SHORT_READ: 522;
+    readonly IOERR_WRITE: 778;
+    readonly IOERR_FSYNC: 1034;
+    readonly IOERR_DIR_FSYNC: 1290;
+    readonly IOERR_TRUNCATE: 1546;
+    readonly IOERR_FSTAT: 1802;
+    readonly IOERR_UNLOCK: 2058;
+    readonly IOERR_RDLOCK: 2314;
+    readonly IOERR_DELETE: 2570;
+    readonly IOERR_BLOCKED: 2826;
+    readonly IOERR_NOMEM: 3082;
+    readonly IOERR_ACCESS: 3338;
+    readonly IOERR_CHECKRESERVEDLOCK: 3594;
+    readonly IOERR_LOCK: 3850;
+    readonly IOERR_CLOSE: 4106;
+    readonly IOERR_DIR_CLOSE: 4362;
+    readonly IOERR_SHMOPEN: 4618;
+    readonly IOERR_SHMSIZE: 4874;
+    readonly IOERR_SHMLOCK: 5130;
+    readonly IOERR_SHMMAP: 5386;
+    readonly IOERR_SEEK: 5642;
+    readonly IOERR_DELETE_NOENT: 5898;
+    readonly IOERR_MMAP: 6154;
+    readonly IOERR_GETTEMPPATH: 6410;
+    readonly IOERR_CONVPATH: 6666;
+    readonly IOERR_VNODE: 6922;
+    readonly IOERR_AUTH: 7178;
+    readonly IOERR_BEGIN_ATOMIC: 7434;
+    readonly IOERR_COMMIT_ATOMIC: 7690;
+    readonly IOERR_ROLLBACK_ATOMIC: 7946;
+    readonly IOERR_DATA: 8202;
+    readonly IOERR_CORRUPTFS: 8458;
+    readonly IOERR_IN_PAGE: 8714;
+    readonly IOERR_BADKEY: 8970;
+    readonly IOERR_CODEC: 9226;
+    readonly LOCKED_SHAREDCACHE: 262;
+    readonly LOCKED_VTAB: 518;
+    readonly BUSY_RECOVERY: 261;
+    readonly BUSY_SNAPSHOT: 517;
+    readonly BUSY_TIMEOUT: 773;
+    readonly CANTOPEN_NOTEMPDIR: 270;
+    readonly CANTOPEN_ISDIR: 526;
+    readonly CANTOPEN_FULLPATH: 782;
+    readonly CANTOPEN_CONVPATH: 1038;
+    readonly CANTOPEN_DIRTYWAL: 1294;
+    readonly CANTOPEN_SYMLINK: 1550;
+    readonly CORRUPT_VTAB: 267;
+    readonly CORRUPT_SEQUENCE: 523;
+    readonly CORRUPT_INDEX: 779;
+    readonly READONLY_RECOVERY: 264;
+    readonly READONLY_CANTLOCK: 520;
+    readonly READONLY_ROLLBACK: 776;
+    readonly READONLY_DBMOVED: 1032;
+    readonly READONLY_CANTINIT: 1288;
+    readonly READONLY_DIRECTORY: 1544;
+    readonly ABORT_ROLLBACK: 516;
+    readonly CONSTRAINT_CHECK: 275;
+    readonly CONSTRAINT_COMMITHOOK: 531;
+    readonly CONSTRAINT_FOREIGNKEY: 787;
+    readonly CONSTRAINT_FUNCTION: 1043;
+    readonly CONSTRAINT_NOTNULL: 1299;
+    readonly CONSTRAINT_PRIMARYKEY: 1555;
+    readonly CONSTRAINT_TRIGGER: 1811;
+    readonly CONSTRAINT_UNIQUE: 2067;
+    readonly CONSTRAINT_VTAB: 2323;
+    readonly CONSTRAINT_ROWID: 2579;
+    readonly CONSTRAINT_PINNED: 2835;
+    readonly CONSTRAINT_DATATYPE: 3091;
+    readonly NOTICE_RECOVER_WAL: 283;
+    readonly NOTICE_RECOVER_ROLLBACK: 539;
+    readonly NOTICE_RBU: 795;
+    readonly WARNING_AUTOINDEX: 284;
+    readonly AUTH_USER: 279;
+    readonly OK_LOAD_PERMANENTLY: 256;
+    readonly OK_SYMLINK: 512;
+}>;
+/** A primary result code of SQLite 3.53.0 — the type of `SQLiteError.sqliteCode`. */
+export type SQLiteResultCode = (typeof SQLITE_CODES)[keyof typeof SQLITE_CODES];
+/**
+ * An extended result code of SQLite 3.53.0. `SQLiteError.sqliteExtendedCode`
+ * is typed `SQLiteExtendedResultCode | (number & {})`: open, because a wrong
+ * read must stay representable (spec D9), yet still completing these values.
+ */
+export type SQLiteExtendedResultCode = (typeof SQLITE_EXTENDED_CODES)[keyof typeof SQLITE_EXTENDED_CODES];