@evolu/sqlite-wasm 2.2.4 → 3.53.4-build1

package/dist/src/Database.js

@@ -0,0 +1,1177 @@
+/**
+ * Evolu's SQLite API: databases and statements over the CApi functions, with
+ * typed errors and explicit resource management.
+ *
+ * Status: {@link createSqliteDatabase} opens Memory databases, and File and
+ * EncryptedFile databases on a {@link SqliteVfs} or {@link SqliteEncryptingVfs},
+ * which a {@link SahPool} is, and {@link createEncryptedSqliteDatabase} also
+ * opens the encrypted databases `@evolu/web` 3 created with
+ * `@evolu/sqlite-wasm` 2.2.4 in a pool. The pool's own encryption is tested in
+ * Node.js over a fake OPFS against 2.2.4, which creates databases as
+ * `@evolu/web` does and leaves a hot journal the pool rolls back, and in
+ * Chromium, Firefox and WebKit on real OPFS against 2.2.4.
+ *
+ * ## Calls
+ *
+ * - Synchronous. Every call returns when SQLite returns. The only asynchronous
+ *   step, deriving a legacy key with WebCrypto, runs between the two opens of
+ *   {@link createEncryptedSqliteDatabase}.
+ * - Bound once per database. {@link createSqliteDatabase} binds the C functions
+ *   and memory helpers it needs and allocates one {@link SqliteScratch}; running
+ *   a statement then calls wasm exports directly.
+ * - Every fallible call returns a Result. {@link SqliteError} copies
+ *   `sqlite3_errmsg` and `sqlite3_extended_errcode` right after the failing
+ *   call, before any other call on the connection replaces them. It copies
+ *   `sqlite3_error_offset` only for SQLITE_ERROR from prepare, exec or step,
+ *   the code of the parser errors that set it, because SQLite keeps an offset
+ *   until a later prepare succeeds or a statement resets.
+ * - The VFS records the first failure since the last top-level call (open,
+ *   prepare, run, exec, export), and {@link SqliteError.cause} carries it. The
+ *   database clears the record before each such call. A call that runs inside
+ *   another call of a database on the same VFS, as a query a callback runs
+ *   does, is not top-level, so it leaves the record to the outer call.
+ * - Every call, disposal included, enters wasm through {@link SqliteWasm.call}. An
+ *   exception or trap that escapes wasm, such as from a call through a disposed
+ *   function pointer, is a defect: it is rethrown, and every later call on any
+ *   database of the instance throws without entering wasm, because the C stack
+ *   and SQLite's state are left inconsistent. A trap after a File or
+ *   EncryptedFile connection opened reaches the caller of the open as a
+ *   `SuppressedError` whose `suppressed` is the trap, because the open's
+ *   deferred close and the free of its scratch memory are refused as it
+ *   unwinds.
+ *
+ * ## Opening
+ *
+ * - A Memory database opens `:memory:` on the default VFS.
+ * - A File or EncryptedFile database's path is a {@link SqliteVfsPath}, a
+ *   canonical path, which SQLite passes to the VFS as it is, never as a URI or
+ *   an in-memory database, followed by the name of the VFS.
+ * - A File or EncryptedFile database opens its path on its VFS, an EncryptedFile
+ *   database keyed as the next section describes. Either then prepares a query
+ *   of `sqlite_schema`, because SQLite reads a file only when a statement needs
+ *   it. So the open rolls back a hot journal, and fails for a file that is not
+ *   a database, with SQLITE_NOTADB, or for a hot journal that cannot be rolled
+ *   back.
+ * - The database uses its VFS only through {@link SqliteVfs} or
+ *   {@link SqliteEncryptingVfs}, so any VFS that implements them can hold it,
+ *   and a driver can open each database on the VFS that has it, as
+ *   {@link SqliteVfs.getPaths} tells.
+ * - Flags are READWRITE, CREATE and EXRESCODE, so failures during the open
+ *   already carry extended codes.
+ * - When the open fails, the message is read first and then the handle SQLite
+ *   returned anyway is closed with `sqlite3_close_v2`. Without a handle, as
+ *   when memory runs out, the error is the open's result code.
+ *
+ * ## Encryption
+ *
+ * - The VFS encrypts an EncryptedFile database itself, and a {@link SahPool} does
+ *   it as SQLite3 Multiple Ciphers' `sqlcipher` scheme did with its default
+ *   parameters, those of SQLCipher 4, which `PRAGMA cipher = 'sqlcipher'`
+ *   selected in `@evolu/web` 3 with 2.2.4. The open registers the key for the
+ *   path with {@link SqliteEncryptingVfs.registerKey} before it enters wasm and
+ *   disposes the registration when it returns, by when the VFS has taken the
+ *   key for the database file; the module documentation of `SahPool.ts`
+ *   describes the pool's format. The key never appears in SQL, a URI, an error
+ *   or SQLite's memory, and the caller's key is never modified.
+ * - Then `sqlite3_file_control` with SQLITE_FCNTL_RESERVE_BYTES asks for 80 bytes
+ *   at the end of each page, where the pool keeps the page's IV and HMAC, which
+ *   takes effect for a new database, and `PRAGMA secure_delete = ON` makes
+ *   deletes overwrite freed content, as SQLite3 Multiple Ciphers did for every
+ *   encrypted connection. A {@link SahPool} refuses to turn it off for an
+ *   encrypted database, because a freed page SQLite does not write would fail
+ *   to authenticate, as `SahPool.ts` describes.
+ * - Registering validates nothing, so the read of `sqlite_schema` checks the key.
+ *   A wrong key fails there with SQLITE_NOTADB, from page 1, or with
+ *   SQLITE_CORRUPT when the first page of a hot journal is another page, and
+ *   {@link SqliteError.cause} is the VFS's {@link SqlitePageAuthenticationError}.
+ *   The rollback stops at that first page, which fails to authenticate, so it
+ *   writes no page of the journal and keeps the journal for the right key.
+ *   Before that page, SQLite truncates the database to the size the journal
+ *   records, as the right key's rollback does too. It would extend a shorter
+ *   database by one zeroed page, encrypted with the wrong key, but a commit
+ *   shrinks the file only after it deletes the journal, and a pool refuses a
+ *   VACUUM that would change an encrypted database's page size, so no database
+ *   is shorter than its hot journal records.
+ * - `@evolu/web` with 2.2.4 ran `PRAGMA key = "x'<hex>'"`, SQLCipher's notation
+ *   for a raw key, which SQLite3 Multiple Ciphers 2.2.4 took as a passphrase
+ *   because of a bug
+ *   (https://github.com/utelle/SQLite3MultipleCiphers/issues/218, fixed in
+ *   2.2.5), deriving the key with the `sqlcipher` scheme, so those databases
+ *   fail as with a wrong key. {@link createEncryptedSqliteDatabase} then opens
+ *   them with the key {@link deriveLegacySqliteKey} derives through
+ *   {@link SubtleCryptoDep}, and {@link SqliteEncryptedDatabase.keyDerivation}
+ *   says which key opened the database. Nothing rekeys a database.
+ * - `@evolu/web` 1.0.1-preview.6 to 2.4.0 also ran `PRAGMA legacy = 4`, so the
+ *   databases it encrypted fail with SQLITE_NOTADB, as with a wrong key, since
+ *   page 1 is encrypted from byte 16; they have not opened since `@evolu/web`
+ *   3.0.0 (see `SahPool.ts`).
+ * - Only page 1 of the database or a record of its journal that failed to
+ *   authenticate counts as a wrong key. Another page of the database that fails
+ *   means that page 1 proved the key and the page is damaged, so it fails with
+ *   SQLITE_CORRUPT and that page as the cause, also with the key 2.2.4 derived.
+ *   An I/O error fails with its own code, and the VFS's record as its cause,
+ *   and a database whose pages authenticate but whose content is malformed
+ *   fails with SQLite's code and no cause.
+ *
+ * ## Statements
+ *
+ * - SQL is copied into its own memory, which is freed when the call returns,
+ *   because SQLite parses it in place and copies a statement's SQL, which a
+ *   schema change prepares again, only after the parse. Meanwhile a callback,
+ *   such as a collation-needed callback during the parse or a function during a
+ *   step of {@link SqliteDatabase.exec}, can run a query on the same database,
+ *   and that query reuses the scratch memory.
+ * - `sqlite3_prepare_v3` gets the SQL's byte length, counting a NUL terminator,
+ *   which spares SQLite a copy, and, for statements
+ *   {@link SqliteDatabase.prepare} returns, SQLITE_PREPARE_PERSISTENT. Empty SQL
+ *   and SQL with more than one statement are errors, so nothing after the first
+ *   statement is silently ignored. SQLite reads SQL only up to a NUL character,
+ *   and UTF-8 cannot encode a lone surrogate, which encoding would replace with
+ *   U+FFFD, so SQL that contains either fails with
+ *   {@link SqliteInvalidSqlTextError} before SQLite sees it, in
+ *   {@link SqliteDatabase.exec} too.
+ * - A second statement is found by scanning the rest of the SQL as SQLite
+ *   3.53.4's tokenizer reads it, not by preparing it, because SQLite applies
+ *   many pragmas, such as `foreign_keys`, when it prepares them, so SQL that
+ *   fails with {@link SqliteMultipleStatementsError} would still change the
+ *   connection. Only semicolons, whitespace, UTF-8 byte order marks and
+ *   comments may follow the first statement. A pragma in the first statement
+ *   still takes effect when the SQL then fails, as SQLite documents for prepare
+ *   (https://sqlite.org/pragma.html).
+ * - {@link SqliteDatabase.exec} prepares each statement where the previous one
+ *   ended and steps it to completion, so {@link SqliteError.sqlOffset} counts
+ *   from the start of the whole SQL.
+ * - Parameters are positional. Their number is read once at prepare and a run
+ *   with a different number fails, so no binding leaks from a previous run.
+ *   {@link SqliteDatabase.exec} binds none, so a statement with a parameter
+ *   fails there without running, rather than run with NULL.
+ * - Binding: null binds NULL; a 32-bit integer binds with `sqlite3_bind_int`;
+ *   another safe integer with `sqlite3_bind_int64`, so it stays INTEGER; any
+ *   other number with `sqlite3_bind_double`. Text is encoded with `encodeInto`
+ *   and bytes are copied into the scratch memory, both bound with
+ *   SQLITE_TRANSIENT and an explicit byte length, so embedded NUL characters
+ *   survive and an empty value stays non-NULL. A value that can take more than
+ *   64 KiB, counting 3 bytes per UTF-16 code unit of text, is allocated exactly
+ *   and handed over with SQLITE_WASM_DEALLOC instead, so the scratch memory
+ *   does not keep the size of the largest value, and SQLite does not copy it
+ *   twice. Such text is encoded into a new array first, and when JavaScript
+ *   cannot allocate it, the run fails with SQLITE_NOMEM and the operation
+ *   `bind`, while the instance keeps working, because the encoding runs no
+ *   wasm. {@link SqliteDatabase.exec} copies its SQL the same way and fails with
+ *   the operation `exec`. SQLite keeps a bound value until its parameter is
+ *   bound again, so a run that handed a value over clears the bindings before
+ *   it returns, also when it fails, and a prepared statement keeps no large
+ *   value between runs, while smaller ones keep the buffers SQLite reuses for
+ *   them. A {@link SqliteValue} string may contain a lone surrogate, which UTF-8
+ *   cannot encode, so text binds it as U+FFFD, as better-sqlite3 does.
+ * - Reading: `sqlite3_column_type` first. INTEGER and FLOAT read with
+ *   `sqlite3_column_double`, so no BigInt is created; integers beyond 2^53 lose
+ *   precision, as in better-sqlite3. TEXT reads the pointer, then the byte
+ *   length, and decodes keeping a leading byte order mark. A BLOB is one copy
+ *   into its own `ArrayBuffer`, so it can be transferred. With the type read
+ *   first, a NULL pointer is never SQL NULL: for TEXT it is SQLITE_NOMEM, and
+ *   for a BLOB it is an empty value unless `sqlite3_errcode`, read right after,
+ *   returns SQLITE_NOMEM. A NULL column name is SQLITE_NOMEM too, and so is a
+ *   TEXT or BLOB that JavaScript cannot allocate a copy of, whatever error the
+ *   engine throws then, because the copy runs no wasm, so the instance keeps
+ *   working. Each fails the run with the operation `step`. Rows are
+ *   null-prototype objects, so a column named `__proto__` is an ordinary
+ *   property, and of columns with the same name, the last one wins.
+ * - Column names are read after the first row and cached with the statement's
+ *   SQLITE_STMTSTATUS_REPREPARE counter. A schema change re-prepares the
+ *   statement, and `SELECT *` then returns other columns, so the names are read
+ *   again when the counter changed.
+ * - {@link SqliteStatement.run} always resets the statement, so it is reusable
+ *   after an error, and ignores the result: SQLITE_OK after SQLITE_DONE, and a
+ *   failed step's error again after it. A deferred constraint or commit failure
+ *   comes from the last step, so it is not lost. A run whose read fails is cut
+ *   short, and its reset completes the statement, so a write with RETURNING is
+ *   committed although the run fails.
+ * - `changes` compares `sqlite3_total_changes64` before and after the run: 0 when
+ *   it did not move, `sqlite3_changes64` otherwise, as in better-sqlite3, and
+ *   unlike it also 0 when `sqlite3_stmt_readonly` is true, as for a SELECT
+ *   whose function writes. SQLite keeps one count per connection, of the last
+ *   INSERT, UPDATE or DELETE that finished, so reading it alone would report a
+ *   stale count after a SELECT or DDL. {@link SqliteRunResult.changes} says
+ *   which writes the count can come from.
+ * - A callback may run queries on the database, but SQLite forbids resetting or
+ *   finalizing a statement that is stepping and closing a connection while it
+ *   runs. So running or disposing a statement during its own run, and disposing
+ *   the database while one of its operations runs, throw before wasm is
+ *   entered, and the instance keeps working. A callback installed with
+ *   `installWasmFunctions` then fails as a defect.
+ *
+ * ## Exporting and closing
+ *
+ * - {@link SqliteDatabase.export} calls `sqlite3_serialize(db, NULL, &size, 0)`
+ *   for the main schema, copies the pages into their own `ArrayBuffer` and
+ *   frees SQLite's copy. The size has its own memory, because SQLite writes it
+ *   before it finalizes its query, whose trace callback can run a query on the
+ *   same database. `sqlite3_serialize` does not report a failed allocation to
+ *   the connection, so the connection's error is cleared with
+ *   `sqlite3_set_errmsg` first, and NULL then fails with the error the
+ *   connection reports, or else SQLITE_NOMEM, as when JavaScript cannot
+ *   allocate the copy of the pages, which still frees SQLite's copy. SQLite
+ *   gives an empty database its first page before copying, so NULL with a size
+ *   of 0 and no error is only a database that has no pages and cannot get one,
+ *   such as a read-only empty one, which exports as zero bytes. Pages come
+ *   through the pager, so an encrypted database exports as plaintext. SQLite
+ *   zero-fills a page that fails to read and reports success, so the export of
+ *   a File or EncryptedFile database fails when its VFS recorded a failure
+ *   during it, caused by the VFS's record: with SQLITE_CORRUPT for a page that
+ *   failed to authenticate, a {@link SqlitePageAuthenticationError}, and with
+ *   SQLITE_IOERR otherwise.
+ * - Disposing a database finalizes its statements that are still open and then
+ *   calls `sqlite3_close_v2`, so no deferred close keeps the VFS's files open.
+ *
+ * @module
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { assert, brand, disposable, err, exhaustiveCheck, ok, safelyStringifyUnknownValue, String, trySync, } from "@evolu/common";
+import { sqlite3_bind_blob, sqlite3_bind_double, sqlite3_bind_int, sqlite3_bind_int64, sqlite3_bind_null, sqlite3_bind_parameter_count, sqlite3_bind_text, sqlite3_changes64, sqlite3_clear_bindings, sqlite3_close_v2, sqlite3_column_blob, sqlite3_column_bytes, sqlite3_column_count, sqlite3_column_double, sqlite3_column_name, sqlite3_column_text, sqlite3_column_type, sqlite3_errcode, sqlite3_errmsg, sqlite3_error_offset, sqlite3_errstr, sqlite3_extended_errcode, sqlite3_file_control, sqlite3_finalize, sqlite3_free, sqlite3_get_autocommit, sqlite3_open_v2, sqlite3_prepare_v3, sqlite3_reset, sqlite3_serialize, sqlite3_set_errmsg, sqlite3_step, sqlite3_stmt_readonly, sqlite3_stmt_status, sqlite3_total_changes64, } from "./CApi.js";
+import { SQLITE_BLOB, SQLITE_CORRUPT, SQLITE_DONE, SQLITE_ERROR, SQLITE_FCNTL_RESERVE_BYTES, SQLITE_FLOAT, SQLITE_INTEGER, SQLITE_IOERR, SQLITE_NOMEM, SQLITE_NULL, SQLITE_OK, SQLITE_OPEN_CREATE, SQLITE_OPEN_EXRESCODE, SQLITE_OPEN_READWRITE, SQLITE_PREPARE_PERSISTENT, SQLITE_ROW, SQLITE_STMTSTATUS_REPREPARE, SQLITE_TEXT, SQLITE_TRANSIENT, SQLITE_WASM_DEALLOC, } from "./Constants.js";
+import { allocCString, allocWasm, copyWasmBytes, createSqliteScratch, isInt32, readCString, readUtf8, writeUtf8, writeWasmBytes, } from "./Memory.js";
+import { sahPoolMaxDatabasePathSize, } from "./SahPool.js";
+/**
+ * Returns the primary result code of a result code, its low 8 bits, such as
+ * SQLITE_CONSTRAINT for SQLITE_CONSTRAINT_NOTNULL. A primary result code
+ * returns itself.
+ */
+export const sqliteResultCodeToPrimary = (code) => (code & 0xff);
+/**
+ * The canonical path of a database file on a {@link SqliteVfs}, such as
+ * `/evolu1.db`, one spelling per file, as {@link SqliteVfs.getPaths} lists it.
+ *
+ * A path is canonical when it is its own `new URL(path,
+ * "file://localhost/").pathname`, the path a {@link SahPool} maps a name to, so
+ * the VFS opens, lists and deletes the file by the path the database opened it
+ * with, and an EncryptedFile database registers its key for that file. A
+ * canonical path starts with `/` and is printable ASCII without `?` or `#`, so
+ * SQLite passes it to the VFS as it is, and the paths SQLite derives from it by
+ * appending a suffix, as for the journal, are canonical too. It rejects:
+ *
+ * - Another spelling of a path, such as `evolu1.db`, `/x/../evolu1.db`,
+ *   `FILE:evolu1.db` or `/a b.db` for `/a%20b.db`, and a name with a scheme,
+ *   such as `db:evolu1.db`, which a pool would map to the relative path
+ *   `evolu1.db`.
+ * - A path SQLite reads itself: an empty path and `:memory:`, which open an
+ *   in-memory database, `:localStorage:` and `:sessionStorage:`, which SQLite
+ *   opens on its kvvfs, and a `file:` URI, whose query and fragment SQLite
+ *   strips and whose escapes it decodes, so the VFS would get another name, and
+ *   an EncryptedFile database would be written without its key.
+ * - A path longer than {@link sahPoolMaxDatabasePathSize}, 498 bytes, because a
+ *   pool slot's header holds a path of up to 510 bytes, and SQLite names a
+ *   super-journal by appending 12 bytes to the database's path.
+ */
+export const SqliteVfsPath = /*#__PURE__*/ brand("SqliteVfsPath", String, (value) => {
+    const canonical = trySync(() => new URL(value, "file://localhost/").pathname, () => null);
+    // A canonical path is ASCII, because a URL path percent-encodes every other
+    // character, so its length is its length in UTF-8.
+    return canonical.ok &&
+        canonical.value === value &&
+        value.length <= sahPoolMaxDatabasePathSize
+        ? ok()
+        : err({ type: "SqliteVfsPath", value });
+}, (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a valid SqliteVfsPath.`);
+/**
+ * Opens a database.
+ *
+ * With a wrong key or a file that is not a database, it fails with
+ * SQLITE_NOTADB, or with SQLITE_CORRUPT for a wrong key and a hot journal whose
+ * first record is not page 1. On a {@link SahPool}, an encrypted database opened
+ * without its key while it has a hot journal that records pages fails with
+ * SQLITE_CANTOPEN, and the journal stays for the key. A leftover journal that
+ * is not hot, such as one `journal_mode = PERSIST` or TRUNCATE keeps, gives
+ * SQLITE_NOTADB, as no journal does. For encrypted databases that 2.2.4 may
+ * have keyed, use {@link createEncryptedSqliteDatabase}.
+ */
+export const createSqliteDatabase = (deps) => (options) => {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const { call } = deps.sqliteWasm;
+        const vfs = options.type === "Memory" ? null : options.vfs;
+        // The operations of this database that are running, as one that a
+        // callback of another runs, so the database is not disposed under them.
+        let runningOperations = 0;
+        // The VFS takes the key when SQLite opens the file. Registered before wasm
+        // is entered, so a VFS that refuses it, as a pool with a key already
+        // registered for the path does, throws without breaking the instance.
+        const _registration = __addDisposableResource(env_1, options.type === "EncryptedFile"
+            ? options.vfs.registerKey(options.path, options.key)
+            : null, false);
+        // Clears the VFS's failure record and then calls an operation through
+        // call, so the cause of a SqliteError is a failure of this operation. A
+        // VFS that throws, as a disposed pool does, then throws before wasm is
+        // entered, without breaking the instance. An operation inside another on
+        // the same VFS, as a query a callback runs, keeps the record, which the
+        // outer operation still reads.
+        const callOperation = (fn) => {
+            runningOperations++;
+            try {
+                if (vfs == null)
+                    return call(fn);
+                const running = runningOperationsByVfs.get(vfs) ?? 0;
+                if (running === 0)
+                    vfs.clearFailure();
+                runningOperationsByVfs.set(vfs, running + 1);
+                try {
+                    return call(fn);
+                }
+                finally {
+                    runningOperationsByVfs.set(vfs, running);
+                }
+            }
+            finally {
+                runningOperations--;
+            }
+        };
+        return callOperation(() => {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const bindBlob = sqlite3_bind_blob(deps);
+                const bindDouble = sqlite3_bind_double(deps);
+                const bindInt = sqlite3_bind_int(deps);
+                const bindInt64 = sqlite3_bind_int64(deps);
+                const bindNull = sqlite3_bind_null(deps);
+                const bindParameterCount = sqlite3_bind_parameter_count(deps);
+                const bindText = sqlite3_bind_text(deps);
+                const changes64 = sqlite3_changes64(deps);
+                const clearBindings = sqlite3_clear_bindings(deps);
+                const closeV2 = sqlite3_close_v2(deps);
+                const columnBlob = sqlite3_column_blob(deps);
+                const columnBytes = sqlite3_column_bytes(deps);
+                const columnCount = sqlite3_column_count(deps);
+                const columnDouble = sqlite3_column_double(deps);
+                const columnName = sqlite3_column_name(deps);
+                const columnText = sqlite3_column_text(deps);
+                const columnType = sqlite3_column_type(deps);
+                const errcode = sqlite3_errcode(deps);
+                const errmsg = sqlite3_errmsg(deps);
+                const errorOffset = sqlite3_error_offset(deps);
+                const errstr = sqlite3_errstr(deps);
+                const extendedErrcode = sqlite3_extended_errcode(deps);
+                const finalize = sqlite3_finalize(deps);
+                const free = sqlite3_free(deps);
+                const getAutocommit = sqlite3_get_autocommit(deps);
+                const prepareV3 = sqlite3_prepare_v3(deps);
+                const reset = sqlite3_reset(deps);
+                const serialize = sqlite3_serialize(deps);
+                const setErrmsg = sqlite3_set_errmsg(deps);
+                const step = sqlite3_step(deps);
+                const stmtReadonly = sqlite3_stmt_readonly(deps);
+                const stmtStatus = sqlite3_stmt_status(deps);
+                const totalChanges64 = sqlite3_total_changes64(deps);
+                const alloc = allocWasm(deps);
+                const allocString = allocCString(deps);
+                const copyBytes = copyWasmBytes(deps);
+                const readString = readCString(deps);
+                const readText = readUtf8(deps);
+                const writeBytes = writeWasmBytes(deps);
+                const writeText = writeUtf8(deps);
+                const statements = new Set();
+                // Reads the connection's error right after the failing call, before any
+                // other call replaces it.
+                const toSqliteError = (db, operation) => {
+                    const extendedCode = extendedErrcode(db);
+                    // SQLite sets the offset only for parser errors and keeps it until a
+                    // prepare succeeds or a statement resets or finalizes, so any other code
+                    // or operation would read the offset of an earlier failed prepare.
+                    const offset = sqliteResultCodeToPrimary(extendedCode) === SQLITE_ERROR &&
+                        (operation === "prepare" ||
+                            operation === "exec" ||
+                            operation === "step")
+                        ? errorOffset(db)
+                        : -1;
+                    return {
+                        type: "SqliteError",
+                        operation,
+                        extendedCode,
+                        // SQLite falls back to sqlite3_errstr, so it is never NULL.
+                        message: readString(errmsg(db)),
+                        sqlOffset: offset < 0 ? null : offset,
+                        cause: vfs?.getFailure() ?? null,
+                    };
+                };
+                // For a failure without a connection that could report it.
+                const toCodeError = (operation, extendedCode) => ({
+                    type: "SqliteError",
+                    operation,
+                    extendedCode,
+                    // SQLite describes an unknown code as "unknown error", never NULL.
+                    message: readString(errstr(extendedCode)),
+                    sqlOffset: null,
+                    cause: null,
+                });
+                const readPtr = (ptr) => deps.sqliteWasm.getHeapDataView().getUint32(ptr, true);
+                const disposer = __addDisposableResource(env_2, new DisposableStack(), false);
+                const createdScratch = createSqliteScratch(deps);
+                if (!createdScratch.ok)
+                    return err(toCodeError("open", SQLITE_NOMEM));
+                const scratch = createdScratch.value;
+                disposer.defer(() => {
+                    call(() => {
+                        scratch[Symbol.dispose]();
+                    });
+                });
+                const pzTail = (scratch.out + 4);
+                // A File or EncryptedFile database's path is followed by the name of its
+                // VFS.
+                const filename = allocString(options.type === "Memory"
+                    ? ":memory:"
+                    : `${options.path}\0${options.vfs.vfsName}`);
+                if (!filename.ok)
+                    return err(toCodeError("open", SQLITE_NOMEM));
+                const zFilename = filename.value;
+                const pathEnd = deps.sqliteWasm.getHeapU8().indexOf(0, zFilename);
+                const rc = (() => {
+                    const env_3 = { stack: [], error: void 0, hasError: false };
+                    try {
+                        const filenameDisposer = __addDisposableResource(env_3, new DisposableStack(), false);
+                        filenameDisposer.defer(() => {
+                            free(zFilename);
+                        });
+                        return sqlite3_open_v2(deps)(zFilename, scratch.out, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_EXRESCODE, options.type === "Memory" ? 0 : (pathEnd + 1));
+                    }
+                    catch (e_3) {
+                        env_3.error = e_3;
+                        env_3.hasError = true;
+                    }
+                    finally {
+                        __disposeResources(env_3);
+                    }
+                })();
+                const db = readPtr(scratch.out);
+                if (rc !== SQLITE_OK) {
+                    const error = db === 0 ? toCodeError("open", rc) : toSqliteError(db, "open");
+                    closeV2(db);
+                    return err(error);
+                }
+                disposer.defer(() => {
+                    call(() => closeV2(db));
+                });
+                // Finalized before the close, so no deferred close keeps files open.
+                disposer.defer(() => {
+                    for (const statement of statements)
+                        statement[Symbol.dispose]();
+                });
+                const prepareStatement = (sql, prepFlags, operation = "prepare") => {
+                    if (!isValidSqlText(sql))
+                        return err({ type: "SqliteInvalidSqlText" });
+                    // SQLite parses the SQL in place, while a callback can run a query on
+                    // this database, which reuses the scratch memory. Three bytes per
+                    // UTF-16 code unit hold any UTF-8, and encoding into them is faster
+                    // than allocCString's exact copy, which encodes into a temporary array
+                    // first. A run prepares SQL every time, so it is a hot path.
+                    const capacity = sql.length * 3;
+                    const allocated = alloc(capacity + 1);
+                    if (!allocated.ok)
+                        return err(toCodeError(operation, SQLITE_NOMEM));
+                    const zSql = allocated.value;
+                    try {
+                        const written = writeText(sql, zSql, capacity);
+                        deps.sqliteWasm.getHeapU8()[zSql + written] = 0;
+                        const rc = prepareV3(db, zSql, written + 1, prepFlags, scratch.out, pzTail);
+                        if (rc !== SQLITE_OK)
+                            return err(toSqliteError(db, operation));
+                        const stmt = readPtr(scratch.out);
+                        if (stmt === 0)
+                            return err({ type: "SqliteEmptySqlError" });
+                        // The rest is scanned, not prepared, because SQLite applies some
+                        // pragmas, such as foreign_keys, when it prepares them.
+                        if (!isEmptySql(deps.sqliteWasm.getHeapU8(), readPtr(pzTail), zSql + written)) {
+                            finalize(stmt);
+                            return err({ type: "SqliteMultipleStatementsError" });
+                        }
+                        return ok(stmt);
+                    }
+                    finally {
+                        free(zSql);
+                    }
+                };
+                // The steps after the connection opened run in a call of their own, so
+                // a trap in them breaks the instance before it unwinds to the deferred
+                // close, which then refuses to close the connection on the state the
+                // trap left.
+                const prepared = call(() => {
+                    if (options.type === "EncryptedFile") {
+                        // The IV and the HMAC at the end of each page, for a new database. It
+                        // returns SQLITE_OK for main, a NULL schema name, and an existing
+                        // database keeps what its header says.
+                        deps.sqliteWasm
+                            .getHeapDataView()
+                            .setInt32(scratch.out, encryptedReservedBytes, true);
+                        sqlite3_file_control(deps)(db, 0, SQLITE_FCNTL_RESERVE_BYTES, scratch.out);
+                        // As SQLite3 Multiple Ciphers did for every encrypted connection.
+                        const secureDelete = prepareStatement("PRAGMA secure_delete = ON", 0, "open");
+                        if (!secureDelete.ok) {
+                            assert(secureDelete.error.type === "SqliteError", "The pragma is one statement.");
+                            return err(secureDelete.error);
+                        }
+                        const stepped = step(secureDelete.value);
+                        const error = stepped === SQLITE_ROW ? null : toSqliteError(db, "open");
+                        finalize(secureDelete.value);
+                        if (error)
+                            return err(error);
+                    }
+                    // SQLite reads a file only when a statement needs it, so a File or
+                    // EncryptedFile database reads its schema now: a hot journal is rolled
+                    // back, and a file that is not a database fails the open rather than the
+                    // first statement.
+                    if (options.type !== "Memory") {
+                        const schema = prepareStatement("SELECT 1 FROM sqlite_schema", 0, "open");
+                        if (!schema.ok) {
+                            assert(schema.error.type === "SqliteError", "The schema query is one statement.");
+                            return err(schema.error);
+                        }
+                        finalize(schema.value);
+                    }
+                    return ok();
+                });
+                if (!prepared.ok)
+                    return err(prepared.error);
+                const createRunner = (stmt) => {
+                    const parameterCount = bindParameterCount(stmt);
+                    let names = null;
+                    let namesReprepares = 0;
+                    const run = (parameters) => {
+                        if (parameters.length !== parameterCount)
+                            return err({
+                                type: "SqliteParameterCountError",
+                                expected: parameterCount,
+                                actual: parameters.length,
+                            });
+                        // SQLite keeps a bound value until its parameter is bound again, so
+                        // a run that handed SQLite a value above 64 KiB clears the bindings
+                        // before it returns, also when it fails.
+                        let clearsBindings = false;
+                        let bindError = null;
+                        for (const [index, value] of parameters.entries()) {
+                            const position = index + 1;
+                            let bindRc;
+                            if (value === null)
+                                bindRc = bindNull(stmt, position);
+                            else if (typeof value === "number")
+                                bindRc = isInt32(value)
+                                    ? bindInt(stmt, position, value)
+                                    : Number.isSafeInteger(value)
+                                        ? bindInt64(stmt, position, BigInt(value))
+                                        : bindDouble(stmt, position, value);
+                            else if (typeof value === "string" &&
+                                value.length * 3 <= maxScratchValue) {
+                                const reserved = scratch.reserve(value.length * 3);
+                                if (!reserved.ok) {
+                                    bindError = toCodeError("bind", SQLITE_NOMEM);
+                                    break;
+                                }
+                                const length = writeText(value, reserved.value, value.length * 3);
+                                bindRc = bindText(stmt, position, reserved.value, length, SQLITE_TRANSIENT);
+                            }
+                            else if (typeof value === "string") {
+                                // JavaScript can fail to allocate the UTF-8, which runs no wasm,
+                                // so the instance keeps working.
+                                const bytes = trySync(() => utf8Encoder.encode(value));
+                                if (!bytes.ok) {
+                                    bindError = toCodeError("bind", SQLITE_NOMEM);
+                                    break;
+                                }
+                                const allocated = alloc(bytes.value.length);
+                                if (!allocated.ok) {
+                                    bindError = toCodeError("bind", SQLITE_NOMEM);
+                                    break;
+                                }
+                                writeBytes(allocated.value, bytes.value);
+                                clearsBindings = true;
+                                bindRc = bindText(stmt, position, allocated.value, bytes.value.length, SQLITE_WASM_DEALLOC);
+                            }
+                            else if (value.length <= maxScratchValue) {
+                                const reserved = scratch.reserve(value.length);
+                                if (!reserved.ok) {
+                                    bindError = toCodeError("bind", SQLITE_NOMEM);
+                                    break;
+                                }
+                                writeBytes(reserved.value, value);
+                                bindRc = bindBlob(stmt, position, reserved.value, value.length, SQLITE_TRANSIENT);
+                            }
+                            else {
+                                const allocated = alloc(value.length);
+                                if (!allocated.ok) {
+                                    bindError = toCodeError("bind", SQLITE_NOMEM);
+                                    break;
+                                }
+                                writeBytes(allocated.value, value);
+                                clearsBindings = true;
+                                bindRc = bindBlob(stmt, position, allocated.value, value.length, SQLITE_WASM_DEALLOC);
+                            }
+                            if (bindRc !== SQLITE_OK) {
+                                bindError = toSqliteError(db, "bind");
+                                break;
+                            }
+                        }
+                        if (bindError) {
+                            if (clearsBindings)
+                                clearBindings(stmt);
+                            return err(bindError);
+                        }
+                        const totalChanges = totalChanges64(db);
+                        const rows = [];
+                        let rc;
+                        // A read that fails because SQLite is out of memory leaves the loop
+                        // with SQLITE_ROW.
+                        steps: while ((rc = step(stmt)) === SQLITE_ROW) {
+                            // A schema change re-prepares the statement, and SELECT * can then
+                            // return other columns, so the first row checks the counter.
+                            const reprepares = rows.length === 0
+                                ? stmtStatus(stmt, SQLITE_STMTSTATUS_REPREPARE, 0)
+                                : namesReprepares;
+                            if (names == null || reprepares !== namesReprepares) {
+                                const columnNames = [];
+                                for (let index = 0; index < columnCount(stmt); index++) {
+                                    const name = columnName(stmt, index);
+                                    if (name === 0)
+                                        break steps;
+                                    columnNames.push(readString(name));
+                                }
+                                names = columnNames;
+                                namesReprepares = reprepares;
+                            }
+                            const row = Object.create(null);
+                            for (const [index, name] of names.entries()) {
+                                // With the type read first, a NULL pointer is never SQL NULL.
+                                const type = columnType(stmt, index);
+                                switch (type) {
+                                    case SQLITE_INTEGER:
+                                    case SQLITE_FLOAT:
+                                        row[name] = columnDouble(stmt, index);
+                                        break;
+                                    case SQLITE_TEXT: {
+                                        const ptr = columnText(stmt, index);
+                                        if (ptr === 0)
+                                            break steps;
+                                        const text = tryCopy(readText, ptr, columnBytes(stmt, index));
+                                        if (text == null)
+                                            break steps;
+                                        row[name] = text;
+                                        break;
+                                    }
+                                    case SQLITE_BLOB: {
+                                        const ptr = columnBlob(stmt, index);
+                                        // NULL for an empty BLOB too.
+                                        if (ptr !== 0) {
+                                            const bytes = tryCopy(copyBytes, ptr, columnBytes(stmt, index));
+                                            if (bytes == null)
+                                                break steps;
+                                            row[name] = bytes;
+                                        }
+                                        else if (errcode(db) === SQLITE_NOMEM)
+                                            break steps;
+                                        else
+                                            row[name] = new Uint8Array();
+                                        break;
+                                    }
+                                    case SQLITE_NULL:
+                                        row[name] = null;
+                                        break;
+                                    default:
+                                        exhaustiveCheck(type);
+                                }
+                            }
+                            rows.push(row);
+                        }
+                        const error = rc === SQLITE_DONE
+                            ? null
+                            : rc === SQLITE_ROW
+                                ? toCodeError("step", SQLITE_NOMEM)
+                                : toSqliteError(db, "step");
+                        // After SQLITE_DONE it returns SQLITE_OK, and after a failure it
+                        // repeats it, so its result is ignored.
+                        reset(stmt);
+                        if (clearsBindings)
+                            clearBindings(stmt);
+                        if (error)
+                            return err(error);
+                        // SQLite keeps the count of the last INSERT, UPDATE or DELETE across
+                        // other statements, also one that a function of this statement ran,
+                        // and a statement that cannot write changes no rows itself.
+                        const changes = totalChanges64(db) === totalChanges || stmtReadonly(stmt) !== 0
+                            ? 0
+                            : Number(changes64(db));
+                        return ok({ rows, changes });
+                    };
+                    return { parameterCount, run };
+                };
+                const database = disposable({
+                    prepare: (sql) => callOperation(() => {
+                        const env_4 = { stack: [], error: void 0, hasError: false };
+                        try {
+                            const prepared = prepareStatement(sql, SQLITE_PREPARE_PERSISTENT);
+                            if (!prepared.ok)
+                                return prepared;
+                            const stmt = prepared.value;
+                            const runner = createRunner(stmt);
+                            // SQLite forbids resetting or finalizing a statement that is
+                            // stepping, which running or disposing it from a callback of its
+                            // run would do. Both throw before wasm is entered, so the
+                            // instance keeps working.
+                            let running = false;
+                            const statementDisposer = __addDisposableResource(env_4, new DisposableStack(), false);
+                            statementDisposer.defer(() => {
+                                statements.delete(statement);
+                                call(() => finalize(stmt));
+                            });
+                            const statement = disposable({
+                                parameterCount: runner.parameterCount,
+                                run: (parameters) => {
+                                    if (running)
+                                        throw new Error(runningStatementMessage);
+                                    running = true;
+                                    try {
+                                        return callOperation(() => runner.run(parameters));
+                                    }
+                                    finally {
+                                        running = false;
+                                    }
+                                },
+                            }, statementDisposer);
+                            const disposeStatement = statement[Symbol.dispose];
+                            statement[Symbol.dispose] = () => {
+                                if (running)
+                                    throw new Error(runningStatementMessage);
+                                disposeStatement();
+                            };
+                            statements.add(statement);
+                            return ok(statement);
+                        }
+                        catch (e_4) {
+                            env_4.error = e_4;
+                            env_4.hasError = true;
+                        }
+                        finally {
+                            __disposeResources(env_4);
+                        }
+                    }),
+                    run: (sql, parameters) => callOperation(() => {
+                        const prepared = prepareStatement(sql, 0);
+                        if (!prepared.ok)
+                            return prepared;
+                        const result = createRunner(prepared.value).run(parameters);
+                        finalize(prepared.value);
+                        return result;
+                    }),
+                    exec: (sql) => callOperation(() => {
+                        const env_5 = { stack: [], error: void 0, hasError: false };
+                        try {
+                            if (!isValidSqlText(sql))
+                                return err({ type: "SqliteInvalidSqlText" });
+                            // A step can call back into this connection, as a function that runs
+                            // a query does, and that call reuses the scratch memory, so the
+                            // statements not yet prepared need their own copy. JavaScript can
+                            // fail to allocate the UTF-8, which runs no wasm, so the instance
+                            // keeps working.
+                            const bytes = trySync(() => utf8Encoder.encode(sql));
+                            if (!bytes.ok)
+                                return err(toCodeError("exec", SQLITE_NOMEM));
+                            const copied = alloc(bytes.value.length + 1);
+                            if (!copied.ok)
+                                return err(toCodeError("exec", SQLITE_NOMEM));
+                            const zSql = copied.value;
+                            const execDisposer = __addDisposableResource(env_5, new DisposableStack(), false);
+                            execDisposer.defer(() => {
+                                free(zSql);
+                            });
+                            writeBytes(zSql, bytes.value);
+                            // The lengths SQLite gets count the NUL terminator, as in
+                            // prepare.
+                            const end = zSql + bytes.value.length + 1;
+                            deps.sqliteWasm.getHeapU8()[end - 1] = 0;
+                            // Each statement is prepared from where the previous one ended, so
+                            // an error offset is relative to it, also when a step re-prepares
+                            // the statement after a schema change and fails.
+                            const toExecError = (statementStart) => {
+                                const error = toSqliteError(db, "exec");
+                                return error.sqlOffset == null
+                                    ? error
+                                    : {
+                                        ...error,
+                                        sqlOffset: statementStart - zSql + error.sqlOffset,
+                                    };
+                            };
+                            for (let start = zSql; start < end - 1;) {
+                                const rc = prepareV3(db, start, end - start, 0, scratch.out, pzTail);
+                                if (rc !== SQLITE_OK)
+                                    return err(toExecError(start));
+                                const stmt = readPtr(scratch.out);
+                                const statementStart = start;
+                                start = readPtr(pzTail);
+                                // NULL for whitespace and comments.
+                                if (stmt === 0)
+                                    continue;
+                                // A parameter exec cannot bind would run as NULL.
+                                const parameterCount = bindParameterCount(stmt);
+                                if (parameterCount !== 0) {
+                                    finalize(stmt);
+                                    return err({
+                                        type: "SqliteParameterCountError",
+                                        expected: parameterCount,
+                                        actual: 0,
+                                    });
+                                }
+                                let stepRc;
+                                while ((stepRc = step(stmt)) === SQLITE_ROW)
+                                    ;
+                                const error = stepRc === SQLITE_DONE ? null : toExecError(statementStart);
+                                finalize(stmt);
+                                if (error)
+                                    return err(error);
+                            }
+                            return ok();
+                        }
+                        catch (e_5) {
+                            env_5.error = e_5;
+                            env_5.hasError = true;
+                        }
+                        finally {
+                            __disposeResources(env_5);
+                        }
+                    }),
+                    export: () => callOperation(() => {
+                        const env_6 = { stack: [], error: void 0, hasError: false };
+                        try {
+                            // SQLite writes the size before it finalizes its query, which
+                            // can call a trace callback that runs a query on this
+                            // database, which reuses the scratch memory.
+                            const allocatedSize = alloc(8);
+                            if (!allocatedSize.ok)
+                                return err(toCodeError("export", SQLITE_NOMEM));
+                            const pSize = allocatedSize.value;
+                            const sizeDisposer = __addDisposableResource(env_6, new DisposableStack(), false);
+                            sizeDisposer.defer(() => {
+                                free(pSize);
+                            });
+                            // An error the connection reports after a NULL then comes from this
+                            // call, which does not report its own failed allocations.
+                            setErrmsg(db, SQLITE_OK, 0);
+                            // NULL is the main schema.
+                            const pages = serialize(db, 0, pSize, 0);
+                            const size = deps.sqliteWasm
+                                .getHeapDataView()
+                                .getBigInt64(pSize, true);
+                            if (pages === 0) {
+                                if (errcode(db) !== SQLITE_OK)
+                                    return err(toSqliteError(db, "export"));
+                                // NULL with a size of 0 is a database without pages that cannot
+                                // get one.
+                                return size === 0n
+                                    ? ok(new Uint8Array())
+                                    : err(toCodeError("export", SQLITE_NOMEM));
+                            }
+                            const bytes = tryCopy(copyBytes, pages, Number(size));
+                            free(pages);
+                            // SQLite zero-fills a page it cannot read and reports success.
+                            const failure = vfs?.getFailure() ?? null;
+                            if (failure != null)
+                                return err({
+                                    ...toCodeError("export", isPageAuthenticationError(failure.error)
+                                        ? SQLITE_CORRUPT
+                                        : SQLITE_IOERR),
+                                    cause: failure,
+                                });
+                            if (bytes == null)
+                                return err(toCodeError("export", SQLITE_NOMEM));
+                            return ok(bytes);
+                        }
+                        catch (e_6) {
+                            env_6.error = e_6;
+                            env_6.hasError = true;
+                        }
+                        finally {
+                            __disposeResources(env_6);
+                        }
+                    }),
+                    isAutocommit: () => call(() => getAutocommit(db) !== 0),
+                }, disposer);
+                // SQLite forbids closing a connection while it runs, which disposing the
+                // database from a callback of one of its operations would do.
+                const disposeDatabase = database[Symbol.dispose];
+                database[Symbol.dispose] = () => {
+                    if (runningOperations > 0)
+                        throw new Error("A SqliteDatabase cannot be disposed while one of its operations runs.");
+                    disposeDatabase();
+                };
+                return ok(database);
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                __disposeResources(env_2);
+            }
+        });
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+};
+/**
+ * Opens an EncryptedFile database on a pool, falling back to the key
+ * `@evolu/sqlite-wasm` 2.2.4 derived.
+ *
+ * `@evolu/web` passed 2.2.4 the key as the SQL text `x'<hex>'`, SQLCipher's
+ * notation for a raw key, which SQLite3 Multiple Ciphers 2.2.4 treated as a
+ * passphrase because of a bug
+ * (https://github.com/utelle/SQLite3MultipleCiphers/issues/218, fixed in
+ * 2.2.5). So every database it encrypted is keyed with PBKDF2-HMAC-SHA512 of
+ * that text, not with the key itself. This Task:
+ *
+ * 1. Opens with the raw key. A new or empty file always accepts it.
+ * 2. Only when a wrong key failed it, so page 1 of the database or a record of its
+ *    hot journal failed to authenticate, which the pool records as a
+ *    {@link SqlitePageAuthenticationError}, reads the first 16 bytes of the file
+ *    through {@link SahPool.read}: the unencrypted cipher salt. Another page of
+ *    the database that fails to authenticate is damaged, because page 1 proved
+ *    the key, so the open fails with SQLITE_CORRUPT.
+ * 3. Derives the legacy key with {@link deriveLegacySqliteKey}, opens again with it
+ *    as the raw key, and zeroes it.
+ *
+ * The result says which key opened the database. When neither key opens it, the
+ * error is the raw key's, unless the second open failed otherwise. Rekeying a
+ * legacy database to the raw key is a separate decision: it rewrites every
+ * page, needs space, and makes the database unreadable to 2.2.4 tabs that share
+ * the pool.
+ */
+export const createEncryptedSqliteDatabase = (options) => async (run) => {
+    const open = createSqliteDatabase(run.deps);
+    const raw = open(options);
+    if (raw.ok)
+        return ok({ database: raw.value, keyDerivation: "Raw" });
+    if (!isWrongKey(raw.error, options.path))
+        return err(raw.error);
+    const salt = options.vfs.read(options.path, 0, 16);
+    if (!salt.ok) {
+        assert(salt.error.type === "SqliteVfsIoError", "The pool has the file the raw key failed to open.");
+        return err(salt.error);
+    }
+    const legacyKey = await run.ok(deriveLegacySqliteKey(options.key, salt.value));
+    let legacy;
+    try {
+        legacy = open({ ...options, key: legacyKey });
+    }
+    finally {
+        legacyKey.fill(0);
+    }
+    if (legacy.ok)
+        return ok({ database: legacy.value, keyDerivation: "Legacy224" });
+    return err(isWrongKey(legacy.error, options.path) ? raw.error : legacy.error);
+};
+/**
+ * Derives the key `@evolu/sqlite-wasm` 2.2.4 used: PBKDF2-HMAC-SHA512 with
+ * 256000 iterations and a 32-byte output, over the UTF-8 text `x'` followed by
+ * the key in lowercase hex and `'`, salted with the database's first 16 bytes.
+ *
+ * It exists because of a bug in SQLite3 Multiple Ciphers 2.2.4, which 2.2.4
+ * packaged. `x'<hex>'` is SQLCipher's notation for a raw key, which
+ * `@evolu/web` used, but that version took it as a passphrase and derived the
+ * key from the text
+ * (https://github.com/utelle/SQLite3MultipleCiphers/issues/218, fixed in
+ * 2.2.5). So the databases it encrypted are keyed with this derivation, and
+ * opening them needs it for as long as they exist, because nothing rekeys
+ * them.
+ *
+ * The text is built byte by byte, so no string holds the key, and zeroed once
+ * WebCrypto has imported it.
+ */
+export const deriveLegacySqliteKey = (key, salt) => async (run) => {
+    const { subtleCrypto } = run.deps;
+    // x' followed by the key in lowercase hex and ', where 0x78 is x and 0x27
+    // is '.
+    const passphrase = new Uint8Array(2 * key.length + 3).fill(0x27);
+    passphrase[0] = 0x78;
+    for (const [index, byte] of key.entries()) {
+        passphrase[2 + 2 * index] = lowercaseHexDigit(byte >> 4);
+        passphrase[3 + 2 * index] = lowercaseHexDigit(byte & 0xf);
+    }
+    let passphraseKey;
+    try {
+        passphraseKey = await subtleCrypto.importKey("raw", passphrase, "PBKDF2", false, ["deriveBits"]);
+    }
+    finally {
+        passphrase.fill(0);
+    }
+    const bits = await subtleCrypto.deriveBits({
+        name: "PBKDF2",
+        hash: "SHA-512",
+        salt: new Uint8Array(salt),
+        iterations: 256_000,
+    }, passphraseKey, 256);
+    return ok(new Uint8Array(bits));
+};
+// A wrong key fails to authenticate page 1 of the database, which is
+// SQLITE_NOTADB, or first a hot journal's first record, which is SQLITE_CORRUPT
+// for any other page. Without a hot journal, SQLite reads page 1 before any
+// other page, and a pool records a record of a journal that fails only until a
+// page 1 proved the key, so another page of the database that fails means that
+// the key fit and the page is damaged.
+const isWrongKey = (error, path) => error.cause != null &&
+    isPageAuthenticationError(error.cause.error) &&
+    (error.cause.path !== path || error.cause.error.pageNumber === 1);
+const isPageAuthenticationError = (error) => typeof error === "object" &&
+    error !== null &&
+    "type" in error &&
+    error.type === "SqlitePageAuthenticationError";
+// The character code of a hex digit in lowercase, as 2.2.4's hex had it.
+const lowercaseHexDigit = (nibble) => nibble < 10 ? 0x30 + nibble : 0x61 - 10 + nibble;
+const runningStatementMessage = "A SqliteStatement cannot run or be disposed while it runs.";
+// Copies a value out of wasm memory, or returns null when JavaScript cannot
+// allocate the copy, as SQLite returns NULL when it cannot allocate. Engines
+// throw different errors then, such as V8's RangeError for an ArrayBuffer and
+// Node.js's Error for a string longer than V8's limit. The copy runs no wasm,
+// so whatever it throws leaves SQLite as it was, unlike an exception that
+// escapes wasm, which breaks the instance.
+const tryCopy = (copy, ptr, byteLength) => {
+    try {
+        return copy(ptr, byteLength);
+    }
+    catch {
+        return null;
+    }
+};
+// Whether SQLite reads SQL as the string holds it: SQLite reads SQL only up to
+// a NUL character, and UTF-8 cannot encode a lone surrogate, which encoding
+// would replace with U+FFFD.
+const isValidSqlText = (sql) => !sql.includes("\0") && sql.isWellFormed();
+// How many operations of databases on each VFS are running, so only the
+// outermost clears the VFS's failure record. The record is one per VFS, and a
+// query a callback runs during an operation is an operation too, on the same
+// database or another one on the VFS.
+const runningOperationsByVfs = /*#__PURE__*/ new WeakMap();
+// Whether UTF-8 SQL from start to end holds no statement, only the tokens
+// SQLite 3.53.4's tokenizer skips: a semicolon; a space, which starts with a
+// space, \t, \n, \f or \r and continues over sqlite3Isspace, which adds \v,
+// while a \v that starts a token is illegal; a UTF-8 byte order mark, a space
+// of its own; a comment from "--" to a newline or the end; and a comment from
+// "/*" that a byte follows, to the first "*/" after the "/*" or the end, so
+// "/*/" stays open. An auto-extension can turn comments off with
+// SQLITE_DBCONFIG_ENABLE_COMMENTS, which makes SQLite reject them, but a tail
+// of only comments is still accepted here, and it runs nothing.
+const isEmptySql = (bytes, start, end) => {
+    let index = start;
+    while (index < end) {
+        switch (bytes[index]) {
+            case semicolon:
+                index++;
+                break;
+            case space:
+            case tab:
+            case newline:
+            case formFeed:
+            case carriageReturn:
+                index++;
+                while (index < end &&
+                    (bytes[index] === space ||
+                        (bytes[index] >= tab && bytes[index] <= carriageReturn)))
+                    index++;
+                break;
+            // The first byte of a UTF-8 byte order mark.
+            case 0xef:
+                if (index + 2 >= end ||
+                    bytes[index + 1] !== 0xbb ||
+                    bytes[index + 2] !== 0xbf)
+                    return false;
+                index += 3;
+                break;
+            case hyphen:
+                if (index + 1 === end || bytes[index + 1] !== hyphen)
+                    return false;
+                index += 2;
+                while (index < end && bytes[index] !== newline)
+                    index++;
+                break;
+            case slash: {
+                if (index + 2 >= end || bytes[index + 1] !== asterisk)
+                    return false;
+                let close = index + 2;
+                while (close + 1 < end &&
+                    !(bytes[close] === asterisk && bytes[close + 1] === slash))
+                    close++;
+                index = close + 1 < end ? close + 2 : end;
+                break;
+            }
+            default:
+                return false;
+        }
+    }
+    return true;
+};
+// The ASCII codes isEmptySql reads; \v (11) is between \n and \f.
+const tab = 0x09;
+const newline = 0x0a;
+const formFeed = 0x0c;
+const carriageReturn = 0x0d;
+const space = 0x20;
+const asterisk = 0x2a;
+const hyphen = 0x2d;
+const slash = 0x2f;
+const semicolon = 0x3b;
+// The bytes an EncryptedFile database leaves to its VFS at the end of each
+// page, where the pool keeps the IV and the HMAC.
+const encryptedReservedBytes = 80;
+// The largest text or blob bound from the scratch memory, which keeps the
+// memory of the largest value it held. A larger value is allocated exactly and
+// handed over, which also spares SQLite a copy.
+const maxScratchValue = 65_536;
+const utf8Encoder = /*#__PURE__*/ new TextEncoder();