@crvouga/sqlite-mem 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,7 +1,14 @@
 // src/errors/index.ts
 var SqliteError = class extends Error {
+  /** Coarse error class (constraint vs syntax vs missing object, …). */
   category;
+  /** Optional SQLite result-code name such as `SQLITE_CONSTRAINT`. */
   sqliteCode;
+  /**
+   * @param message - Human-readable error text.
+   * @param category - Coarse class; defaults to `"other"`.
+   * @param sqliteCode - Optional SQLite result-code name.
+   */
   constructor(message, category = "other", sqliteCode) {
     super(message);
     this.name = "SqliteError";
@@ -1176,10 +1183,14 @@ var Parser = class {
     if (!this.match("ON")) return null;
     this.expect("CONFLICT");
     let targetColumns = null;
+    let targetExprs = null;
     if (this.match("LPAREN")) {
       targetColumns = [];
+      targetExprs = [];
       do {
-        targetColumns.push(this.parseIdent());
+        const expr = this.parseExprPrec(PREC.ADD);
+        targetExprs.push(expr);
+        targetColumns.push(expr.type === "column" ? expr.name : "");
       } while (this.match("COMMA"));
       this.expect("RPAREN");
     }
@@ -1187,14 +1198,14 @@ var Parser = class {
     if (this.match("WHERE")) targetWhere = this.parseExpr();
     this.expect("DO");
     if (this.match("NOTHING")) {
-      return { targetColumns, targetWhere, action: "nothing" };
+      return { targetColumns, targetExprs, targetWhere, action: "nothing" };
     }
     this.expect("UPDATE");
     this.expect("SET");
     const set = this.parseSetItems();
     let where = null;
     if (this.match("WHERE")) where = this.parseExpr();
-    return { targetColumns, targetWhere, action: { set, where } };
+    return { targetColumns, targetExprs, targetWhere, action: { set, where } };
   }
   parseSetItems() {
     const items = [];
@@ -1361,7 +1372,8 @@ var Parser = class {
         columns: [],
         constraints: [],
         asSelect,
-        withoutRowid: false
+        withoutRowid: false,
+        strict: false
       };
     }
     this.expect("LPAREN");
@@ -1376,12 +1388,30 @@ var Parser = class {
     } while (this.match("COMMA"));
     this.expect("RPAREN");
     let withoutRowid = false;
-    if (this.match("WITHOUT")) {
-      const word = this.parseIdent();
-      if (word.toUpperCase() !== "ROWID") this.syntaxError("expected ROWID after WITHOUT");
-      withoutRowid = true;
+    let strict = false;
+    while (!this.at("SEMI") && !this.at("EOF")) {
+      if (this.match("WITHOUT")) {
+        const word = this.parseIdent();
+        if (word.toUpperCase() !== "ROWID") this.syntaxError("expected ROWID after WITHOUT");
+        withoutRowid = true;
+      } else {
+        const word = this.parseIdent();
+        if (word.toUpperCase() !== "STRICT") this.syntaxError(`unexpected table option ${word}`);
+        strict = true;
+      }
+      this.match("COMMA");
     }
-    return { type: "create_table", ifNotExists, temp, name, columns, constraints, asSelect: null, withoutRowid };
+    return {
+      type: "create_table",
+      ifNotExists,
+      temp,
+      name,
+      columns,
+      constraints,
+      asSelect: null,
+      withoutRowid,
+      strict
+    };
   }
   parseColumnDef() {
     const name = this.parseIdent();
@@ -1507,7 +1537,8 @@ var Parser = class {
       this.expect("RPAREN");
     }
     const { onDelete, onUpdate } = this.parseFkActions();
-    return { type: "references", table, columns, onDelete, onUpdate };
+    const { deferrable, initiallyDeferred } = this.parseDeferrable();
+    return { type: "references", table, columns, onDelete, onUpdate, deferrable, initiallyDeferred };
   }
   parseTableConstraint() {
     let name = null;
@@ -1554,20 +1585,40 @@ var Parser = class {
         this.expect("RPAREN");
       }
       const { onDelete, onUpdate } = this.parseFkActions();
-      return { type: "foreign_key", columns, refTable, refColumns, onDelete, onUpdate, name };
+      const { deferrable, initiallyDeferred } = this.parseDeferrable();
+      return {
+        type: "foreign_key",
+        columns,
+        refTable,
+        refColumns,
+        onDelete,
+        onUpdate,
+        name,
+        deferrable,
+        initiallyDeferred
+      };
     }
     this.syntaxError("expected table constraint");
   }
   parseIndexedColumns() {
     const cols = [];
     do {
-      const name = this.parseIdent();
+      const expr = this.parseExprPrec(PREC.ADD);
       let collate = null;
+      let inner = expr;
+      if (inner.type === "collate") {
+        collate = inner.collation;
+        inner = inner.expr;
+      }
       if (this.match("COLLATE")) collate = this.parseIdent();
       let order = null;
       if (this.match("ASC")) order = "ASC";
       else if (this.match("DESC")) order = "DESC";
-      cols.push({ name, collate, order });
+      if (inner.type === "column" && inner.table === null) {
+        cols.push({ name: inner.name, collate, order });
+      } else {
+        cols.push({ name: "", collate, order, expr: inner });
+      }
     } while (this.match("COMMA"));
     return cols;
   }
@@ -1610,6 +1661,23 @@ var Parser = class {
     }
     return { onDelete, onUpdate };
   }
+  parseDeferrable() {
+    let deferrable = false;
+    let initiallyDeferred = false;
+    if (this.match("NOT")) {
+      this.expect("DEFERRABLE");
+    } else if (this.match("DEFERRABLE")) {
+      deferrable = true;
+    }
+    if (this.match("INITIALLY")) {
+      if (this.match("DEFERRED")) initiallyDeferred = true;
+      else {
+        this.expect("IMMEDIATE");
+        initiallyDeferred = false;
+      }
+    }
+    return { deferrable, initiallyDeferred: deferrable && initiallyDeferred };
+  }
   parseOrConflict() {
     if (!this.match("OR")) return null;
     return this.parseConflictAction();
@@ -2214,13 +2282,19 @@ var Parser = class {
       start = this.parseFrameBound(true);
       end = { kind: "current_row" };
     }
-    this.match("EXCLUDE");
-    if (this.at("CURRENT")) this.match("CURRENT");
-    if (this.at("ROW")) this.match("ROW");
-    if (this.at("TIES")) this.match("TIES");
-    if (this.at("OTHERS")) this.match("OTHERS");
-    if (this.at("GROUP")) this.match("GROUP");
-    return { type, start, end };
+    let exclude = null;
+    if (this.match("EXCLUDE")) {
+      if (this.match("NO")) {
+        this.expect("OTHERS");
+        exclude = "no_others";
+      } else if (this.match("CURRENT")) {
+        this.expect("ROW");
+        exclude = "current_row";
+      } else if (this.match("GROUP")) exclude = "group";
+      else if (this.match("TIES")) exclude = "ties";
+      else this.syntaxError("expected EXCLUDE CURRENT ROW, GROUP, TIES, or NO OTHERS");
+    }
+    return { type, start, end, exclude };
   }
   parseFrameBound(precedingSide) {
     if (this.match("UNBOUNDED")) {
@@ -2268,6 +2342,9 @@ var DEFAULT_DATABASE_SEED = 1;
 // src/runtime/prng.ts
 var Prng = class _Prng {
   state;
+  /**
+   * @param seed - Engine seed. `0` is replaced with a non-zero constant.
+   */
   constructor(seed = 1) {
     let s = typeof seed === "bigint" ? seed : BigInt(seed | 0);
     if (s === 0n) s = 0x9e3779b97f4a7c15n;
@@ -2289,10 +2366,16 @@ var Prng = class _Prng {
     if (signed === -(1n << 63n)) signed += 1n;
     return signed;
   }
+  /** Next float in `[0, 1)` from 53 bits of {@link nextU64}. */
   nextFloat() {
     const bits = this.nextU64();
     return Number(bits >> 11n) / Number(1n << 53n);
   }
+  /**
+   * Next integer in `[min, max]` (inclusive).
+   *
+   * @throws {RangeError} If `max < min`.
+   */
   nextInt(min, max) {
     if (max < min) throw new RangeError("max < min");
     const span = max - min + 1;
@@ -2302,9 +2385,11 @@ var Prng = class _Prng {
   getState() {
     return this.state;
   }
+  /** Restore unsigned 64-bit engine state from {@link getState}. */
   setState(state) {
     this.state = BigInt.asUintN(64, state);
   }
+  /** Independent copy with the same engine state. */
   clone() {
     const copy = new _Prng(1);
     copy.state = this.state;
@@ -2325,6 +2410,7 @@ function deriveSeed(...parts) {
 
 // src/types/value.ts
 var SqlReal = class {
+  /** IEEE float payload (`-0` already canonicalized to `+0`). */
   value;
   constructor(value) {
     this.value = canonicalizeNumber(value);
@@ -3458,6 +3544,23 @@ function jsonArrowPath(right) {
 function extractOne(root, path) {
   return pathGet(root, parseJsonPath(path));
 }
+function arrayInsertJson(root, path, value) {
+  const steps = parseJsonPath(path);
+  const last = steps[steps.length - 1];
+  if (!last || last.kind === "root" || last.kind === "key") {
+    throw new SqliteError("JSON path error", "other");
+  }
+  const result = cloneJson(root);
+  const parentInfo = pathParent(result, steps);
+  if (parentInfo?.parent.kind !== "array") return result;
+  const parent = parentInfo.parent;
+  let idx = parentInfo.index;
+  if (last.kind === "fromEnd") idx = parent.elements.length - last.n;
+  if (last.kind === "append") idx = parent.elements.length;
+  if (idx < 0 || idx > parent.elements.length) return result;
+  parent.elements.splice(idx, 0, cloneJson(value));
+  return result;
+}
 function mutateJson(root, path, value, mode) {
   const steps = parseJsonPath(path);
   if (steps.length <= 1) {
@@ -3678,6 +3781,26 @@ function textOf(value) {
   if (isSqlJsonText(value)) return value.value;
   return String(value);
 }
+function arrayInsertArgs(args, asJsonb) {
+  if (args.length === 0) {
+    throw new SqliteError("wrong number of arguments to function json_array_insert()", "misuse");
+  }
+  if (args.length % 2 === 0) {
+    throw new SqliteError("json_array_insert() requires an odd number of arguments", "misuse");
+  }
+  if (args.some((arg) => arg === null)) return null;
+  try {
+    let node = ensureJson(args[0]);
+    for (let i = 1; i < args.length; i += 2) {
+      const path = textOf(args[i]);
+      const value = sqlValueToJsonNode(args[i + 1]);
+      node = arrayInsertJson(node, path, value);
+    }
+    return asJsonb ? jsonNodeToSql(node, "jsonb") : jsonNodeToSql(node, "json");
+  } catch (e) {
+    wrapJsonError(e);
+  }
+}
 function mutateArgs(args, mode, asJsonb) {
   if (args.length === 0) throw new SqliteError(`wrong number of arguments to function json_${mode}()`, "misuse");
   if (args.length % 2 === 0) {
@@ -3816,6 +3939,12 @@ var jsonScalarFunctions = {
   jsonb_insert(args) {
     return mutateArgs(args, "insert", true);
   },
+  json_array_insert(args) {
+    return arrayInsertArgs(args, false);
+  },
+  jsonb_array_insert(args) {
+    return arrayInsertArgs(args, true);
+  },
   json_replace(args) {
     return mutateArgs(args, "replace", false);
   },
@@ -4859,6 +4988,10 @@ var scalarFunctions = {
     requireArgs3("sqlite_log", args, 2);
     return null;
   },
+  load_extension(args) {
+    requireArgs3("load_extension", args, 1, 2);
+    throw new SqliteError("not authorized", "misuse");
+  },
   like(args) {
     requireArgs3("like", args, 2, 3);
     if (args[0] === null || args[1] === null || args[2] === null) return null;
@@ -5599,12 +5732,20 @@ function raiseActionName(expr) {
 var IndexStore = class _IndexStore {
   name;
   entries;
-  constructor(name = "index", entries) {
+  keyValues;
+  sortedKeys;
+  frozen = false;
+  constructor(name = "index", entries, keyValues) {
     this.name = name;
     this.entries = /* @__PURE__ */ new Map();
+    this.keyValues = /* @__PURE__ */ new Map();
+    this.sortedKeys = null;
     if (entries) {
       for (const [key, rowids] of entries) this.entries.set(key, [...rowids]);
     }
+    if (keyValues) {
+      for (const [key, values] of keyValues) this.keyValues.set(key, [...values]);
+    }
   }
   checkUnique(values, rowid) {
     const key = serializeIndexKey(values);
@@ -5622,12 +5763,15 @@ var IndexStore = class _IndexStore {
     }
   }
   insert(values, rowid, unique = true) {
+    this.assertMutable();
     const key = serializeIndexKey(values);
     if (key === null) return;
     if (unique) this.checkUnique(values, rowid);
     const existing = this.entries.get(key);
     if (!existing) {
       this.entries.set(key, [rowid]);
+      this.keyValues.set(key, [...values]);
+      this.sortedKeys = null;
       return;
     }
     for (const id of existing) if (sameRowid(id, rowid)) return;
@@ -5638,30 +5782,112 @@ var IndexStore = class _IndexStore {
     if (key === null) return [];
     return this.entries.get(key) ?? [];
   }
+  /** Leftmost prefix match: INDEX(a,b) used for WHERE a = ?. */
+  lookupPrefix(values) {
+    if (values.length === 0) return [];
+    const prefix = serializeIndexKey(values);
+    if (prefix === null) return [];
+    const exact = this.entries.get(prefix);
+    const needle = `${prefix}|`;
+    const rowids = exact ? [...exact] : [];
+    for (const [key, ids] of this.entries) {
+      if (key.startsWith(needle)) rowids.push(...ids);
+    }
+    return rowids;
+  }
+  /**
+   * Ordered scan of rowids for a single-column comparison.
+   * `op` applies to the first key component.
+   */
+  rangeLookup(op, bound, bound2) {
+    const rowids = [];
+    const keys = this.orderedKeys();
+    for (const key of keys) {
+      const values = this.keyValues.get(key);
+      if (!values || values[0] === void 0) continue;
+      const cmp = compareSerializedOrder(values[0], bound);
+      let ok = false;
+      if (op === ">") ok = cmp > 0;
+      else if (op === ">=") ok = cmp >= 0;
+      else if (op === "<") ok = cmp < 0;
+      else if (op === "<=") ok = cmp <= 0;
+      else if (op === "between" && bound2 !== void 0) {
+        ok = cmp >= 0 && compareSerializedOrder(values[0], bound2) <= 0;
+      }
+      if (ok) {
+        const ids = this.entries.get(key);
+        if (ids) rowids.push(...ids);
+      }
+    }
+    return rowids;
+  }
+  orderedRowids(desc = false) {
+    const keys = this.orderedKeys();
+    const rowids = [];
+    const seq = desc ? [...keys].reverse() : keys;
+    for (const key of seq) {
+      const ids = this.entries.get(key);
+      if (ids) rowids.push(...ids);
+    }
+    return rowids;
+  }
   remove(values, rowid) {
+    this.assertMutable();
     const key = serializeIndexKey(values);
     if (key === null) return false;
     const existing = this.entries.get(key);
     if (!existing) return false;
     if (rowid === void 0) {
       this.entries.delete(key);
+      this.keyValues.delete(key);
+      this.sortedKeys = null;
       return true;
     }
     const index = existing.findIndex((id) => sameRowid(id, rowid));
     if (index < 0) return false;
     existing.splice(index, 1);
-    if (existing.length === 0) this.entries.delete(key);
+    if (existing.length === 0) {
+      this.entries.delete(key);
+      this.keyValues.delete(key);
+      this.sortedKeys = null;
+    }
     return true;
   }
   clear() {
+    this.assertMutable();
     this.entries.clear();
+    this.keyValues.clear();
+    this.sortedKeys = null;
   }
   clone() {
-    return new _IndexStore(this.name, this.entries);
+    return new _IndexStore(this.name, this.entries, this.keyValues);
+  }
+  freeze() {
+    this.frozen = true;
   }
   get size() {
     return this.entries.size;
   }
+  orderedKeys() {
+    if (this.sortedKeys) return this.sortedKeys;
+    const keys = [...this.entries.keys()];
+    keys.sort((a, b) => {
+      const left = this.keyValues.get(a);
+      const right = this.keyValues.get(b);
+      if (!left || !right) return a < b ? -1 : a > b ? 1 : 0;
+      const n = Math.min(left.length, right.length);
+      for (let i = 0; i < n; i++) {
+        const cmp = compareSql(left[i] ?? null, right[i] ?? null);
+        if (cmp !== 0) return cmp ?? 0;
+      }
+      return left.length - right.length;
+    });
+    this.sortedKeys = keys;
+    return keys;
+  }
+  assertMutable() {
+    if (this.frozen) throw new SqliteError("internal: cannot mutate a frozen index", "other");
+  }
 };
 function serializeIndexKey(values) {
   if (values.some((value) => value === null)) return null;
@@ -5689,10 +5915,70 @@ function serializeValue(value) {
   for (const byte of value) hex += byte.toString(16).padStart(2, "0");
   return `b:${hex}`;
 }
+function compareSerializedOrder(left, right) {
+  return compareSql(left, right) ?? 0;
+}
 function sameRowid(left, right) {
   return typeof left === "bigint" || typeof right === "bigint" ? BigInt(left) === BigInt(right) : left === right;
 }
 
+// src/types/strict.ts
+var STRICT_TYPES = /* @__PURE__ */ new Set(["INT", "INTEGER", "REAL", "TEXT", "BLOB", "ANY"]);
+function isStrictTypeName(typeName) {
+  if (!typeName) return false;
+  return STRICT_TYPES.has(typeName.trim().toUpperCase());
+}
+function applyStrictValue(value, typeName, table, column) {
+  if (value === null) return null;
+  const declared = typeName.trim().toUpperCase();
+  const storage = storageClassOf(value);
+  if (declared === "ANY") return value;
+  if (declared === "TEXT") {
+    if (storage === "text") return typeof value === "string" ? value : String(value.value);
+    if (storage === "integer" || storage === "real") return String(isSqlReal(value) ? value.value : value);
+    throw cannotStore(storage, declared, table, column);
+  }
+  if (declared === "INT" || declared === "INTEGER") {
+    if (storage === "integer") return value;
+    if (storage === "real") {
+      const n = isSqlReal(value) ? value.value : Number(value);
+      if (Number.isInteger(n)) return n;
+      throw cannotStore(storage, declared, table, column);
+    }
+    if (storage === "text") {
+      const n = coerceToNumber(value);
+      if (n !== null && Number.isInteger(n) && String(value).trim() === String(n)) return n;
+      throw cannotStore(storage, declared, table, column);
+    }
+    throw cannotStore(storage, declared, table, column);
+  }
+  if (declared === "REAL") {
+    if (storage === "real") return isSqlReal(value) ? value : asSqlReal(Number(value));
+    if (storage === "integer") return asSqlReal(typeof value === "bigint" ? Number(value) : Number(value));
+    if (storage === "text") {
+      const n = coerceToNumber(value);
+      if (n !== null) return asSqlReal(n);
+    }
+    throw cannotStore(storage, declared, table, column);
+  }
+  if (declared === "BLOB") {
+    if (storage === "blob") return value;
+    throw cannotStore(storage, declared, table, column);
+  }
+  throw new SqliteError(`unknown datatype for ${table}.${column}: "${typeName}"`, "other");
+}
+function cannotStore(storage, declared, table, column) {
+  const shown = storage === "integer" ? "INT" : storage.toUpperCase();
+  throw new SqliteError(
+    `cannot store ${shown} value in ${declared} column ${table}.${column}`,
+    "datatype_mismatch",
+    "SQLITE_CONSTRAINT_DATATYPE"
+  );
+}
+function unknownStrictType(table, column, typeName) {
+  throw new SqliteError(`unknown datatype for ${table}.${column}: "${typeName}"`, "other");
+}
+
 // src/vtable/fts/options.ts
 var OPTION_NAMES = /* @__PURE__ */ new Set([
   "tokenize",
@@ -7235,11 +7521,13 @@ var Table = class _Table {
   indexes;
   originalSql;
   withoutRowid;
+  strict;
   /** Clustered PK key string → row for WITHOUT ROWID tables. */
   clusteredRows;
   scanCache = null;
   /** Lazy covering hashes: column nameLower → serializeIndexKey → rowids. */
   equalityHashes = null;
+  frozen = false;
   constructor(name, columns, options = {}) {
     this.name = name;
     this.columns = columns.map(cloneColumn);
@@ -7249,6 +7537,7 @@ var Table = class _Table {
     this.indexes = [...options.indexes ?? []];
     this.originalSql = options.originalSql ?? null;
     this.withoutRowid = options.withoutRowid ?? false;
+    this.strict = options.strict ?? false;
     this.clusteredRows = /* @__PURE__ */ new Map();
     this.scanCache = null;
   }
@@ -7284,7 +7573,7 @@ var Table = class _Table {
   }
   /** True when the table has no user constraints that DML must enforce beyond hidden rowid. */
   isUnconstrained() {
-    if (this.withoutRowid || this.indexes.length > 0 || this.constraints.length > 0) return false;
+    if (this.withoutRowid || this.strict || this.indexes.length > 0 || this.constraints.length > 0) return false;
     for (const column of this.columns) {
       if (column.notNull || column.primaryKey || column.unique || column.generated || column.defaultExpr) return false;
     }
@@ -7311,7 +7600,7 @@ var Table = class _Table {
     return rows;
   }
   ensureEqualityHash(columnLower) {
-    if (this.rows.size < EQUALITY_HASH_MIN_ROWS) return false;
+    if (this.frozen || this.rows.size < EQUALITY_HASH_MIN_ROWS) return false;
     const column = this.columns.find((item) => item.nameLower === columnLower);
     if (!column) return false;
     this.equalityHashes ??= /* @__PURE__ */ new Map();
@@ -7361,6 +7650,7 @@ var Table = class _Table {
     }
   }
   insert(input, options) {
+    this.assertMutable();
     const supplied = isInsertRow(input) ? input : { values: input };
     const values = options?.prepared ? supplied.values instanceof Map ? supplied.values : rowValues(supplied.values) : this.prepareValues(supplied.values);
     if (this.withoutRowid) {
@@ -7403,6 +7693,7 @@ var Table = class _Table {
     return rowid;
   }
   update(rowid, updates) {
+    this.assertMutable();
     const key = canonicalRowid(rowid);
     const existing = this.rows.get(key);
     if (!existing) return void 0;
@@ -7445,6 +7736,7 @@ var Table = class _Table {
     return candidate;
   }
   delete(rowid) {
+    this.assertMutable();
     const key = canonicalRowid(rowid);
     const existing = this.rows.get(key);
     if (!existing) return false;
@@ -7468,13 +7760,20 @@ var Table = class _Table {
       constraints: this.constraints,
       indexes: this.indexes,
       originalSql: this.originalSql,
-      withoutRowid: this.withoutRowid
+      withoutRowid: this.withoutRowid,
+      strict: this.strict
     });
     copy.nextRowid = this.nextRowid;
     for (const [rowid, row] of this.rows) copy.rows.set(rowid, cloneRow(row));
     for (const [clusterKey, row] of this.clusteredRows) copy.clusteredRows.set(clusterKey, cloneRow(row));
     return copy;
   }
+  freeze() {
+    this.frozen = true;
+  }
+  assertMutable() {
+    if (this.frozen) throw new SqliteError("internal: cannot mutate a frozen table", "other");
+  }
   /** Rebuild clustered storage after snapshot decode or bulk load. */
   rebuildClusteredRows() {
     if (!this.withoutRowid) return;
@@ -7491,7 +7790,10 @@ var Table = class _Table {
     const result = /* @__PURE__ */ new Map();
     for (const column of this.columns) {
       const key = normalizeColumnName(column.name);
-      result.set(key, applyAffinity(cloneSqlValue(supplied.get(key) ?? null), column.affinity));
+      result.set(
+        key,
+        this.strict ? applyStrictValue(cloneSqlValue(supplied.get(key) ?? null), column.typeName ?? "", this.name, column.name) : applyAffinity(cloneSqlValue(supplied.get(key) ?? null), column.affinity)
+      );
     }
     return result;
   }
@@ -7833,6 +8135,12 @@ var DatabaseState = class _DatabaseState {
     if (stmt.columns.length === 0) {
       throw new SqliteError("table must have at least one column", "syntax");
     }
+    if (stmt.strict) {
+      for (const definition of stmt.columns) {
+        const typeName = definition.typeName?.trim() ?? "";
+        if (!isStrictTypeName(typeName)) unknownStrictType(bare, definition.name, typeName || "null");
+      }
+    }
     const normalizedConstraints = [...stmt.constraints];
     for (const definition of stmt.columns) {
       for (const constraint of definition.constraints) {
@@ -7846,7 +8154,9 @@ var DatabaseState = class _DatabaseState {
             refColumns: constraint.columns,
             onDelete: constraint.onDelete,
             onUpdate: constraint.onUpdate,
-            name: null
+            name: null,
+            deferrable: constraint.deferrable,
+            initiallyDeferred: constraint.initiallyDeferred
           });
         }
       }
@@ -7854,7 +8164,8 @@ var DatabaseState = class _DatabaseState {
     const table = new Table(bare, columns, {
       constraints: normalizedConstraints,
       originalSql,
-      withoutRowid: stmt.withoutRowid
+      withoutRowid: stmt.withoutRowid,
+      strict: stmt.strict
     });
     if (stmt.withoutRowid) {
       const pk = columns.filter((column) => column.primaryKey);
@@ -7937,7 +8248,7 @@ var DatabaseState = class _DatabaseState {
       return this.databaseForSchema(oldSchema, oldName).renameTable(oldBare, splitQualifiedName(newName).bare);
     }
     const oldKey = keyOf(oldBare);
-    const table = this.getTable(oldName);
+    const table = this.getWritableTable(oldName);
     const { schema: newSchema, bare: newBare } = splitQualifiedName(newName);
     if (newSchema !== null) {
       throw new SqliteError(`no such table: ${newName}`, "no_such_table");
@@ -7946,11 +8257,13 @@ var DatabaseState = class _DatabaseState {
     this.tables.delete(oldKey);
     table.name = newBare;
     this.tables.set(keyOf(newBare), table);
-    for (const index of this.indexes.values()) {
-      if (keyOf(index.tableName) === oldKey) index.tableName = newBare;
+    for (const index of [...this.indexes.values()]) {
+      if (keyOf(index.tableName) !== oldKey) continue;
+      this.ensureWritableIndex(index).tableName = newBare;
     }
-    for (const trigger of this.triggers.values()) {
-      if (keyOf(trigger.tableName) === oldKey) trigger.tableName = newBare;
+    for (const [key, trigger] of this.triggers) {
+      if (keyOf(trigger.tableName) !== oldKey) continue;
+      this.triggers.set(key, { ...trigger, tableName: newBare });
     }
     this.schemaVersion++;
     return table;
@@ -7985,7 +8298,7 @@ var DatabaseState = class _DatabaseState {
     return deleted;
   }
   createIndex(stmt, originalSql = null) {
-    const table = this.getTable(stmt.table);
+    const table = this.getWritableTable(stmt.table);
     const { schema, bare } = splitQualifiedName(stmt.name);
     const target = schema !== null ? this.databaseForSchema(schema, stmt.name) : this.databaseForTable(table);
     const key = keyOf(bare);
@@ -7993,6 +8306,7 @@ var DatabaseState = class _DatabaseState {
     if (existing && stmt.ifNotExists) return existing;
     target.assertSchemaNameAvailable(bare);
     for (const indexed of stmt.columns) {
+      if (indexed.expr) continue;
       if (!table.columns.some((column) => keyOf(column.name) === keyOf(indexed.name))) {
         throw new SqliteError(`no such column: ${indexed.name}`, "no_such_column");
       }
@@ -8022,7 +8336,10 @@ var DatabaseState = class _DatabaseState {
     }
     target.indexes.delete(key);
     const table = target.tables.get(keyOf(index.tableName));
-    if (table) table.indexes = table.indexes.filter((item) => keyOf(item) !== key);
+    if (table) {
+      const writable = target.ensureWritableTable(table);
+      writable.indexes = writable.indexes.filter((item) => keyOf(item) !== key);
+    }
     target.schemaVersion++;
     return true;
   }
@@ -8106,6 +8423,71 @@ var DatabaseState = class _DatabaseState {
     copy.totalChanges = this.totalChanges;
     copy.foreignKeysEnabled = this.foreignKeysEnabled;
     copy.schemaVersion = this.schemaVersion;
+    copy.userVersion = this.userVersion;
+    return copy;
+  }
+  /** Share table/index objects with the live state. Callers must freeze first. */
+  cloneShallow() {
+    const copy = new _DatabaseState();
+    copy.tables = new Map(this.tables);
+    for (const [key, table] of this.virtualTables) copy.virtualTables.set(key, table.clone());
+    copy.views = new Map(this.views);
+    copy.indexes = new Map(this.indexes);
+    copy.triggers = new Map(this.triggers);
+    for (const [name, attached] of this.attached) {
+      copy.attached.set(name, { state: attached.state.cloneShallow(), filename: attached.filename });
+    }
+    copy.lastInsertRowid = this.lastInsertRowid;
+    copy.changes = this.changes;
+    copy.totalChanges = this.totalChanges;
+    copy.foreignKeysEnabled = this.foreignKeysEnabled;
+    copy.schemaVersion = this.schemaVersion;
+    copy.userVersion = this.userVersion;
+    return copy;
+  }
+  freezeShared() {
+    for (const table of this.tables.values()) table.freeze();
+    for (const index of this.indexes.values()) index.store.freeze();
+    for (const attached of this.attached.values()) attached.state.freezeShared();
+  }
+  thawShared() {
+    for (const table of this.tables.values()) table.frozen = false;
+    for (const index of this.indexes.values()) index.store.frozen = false;
+    for (const attached of this.attached.values()) attached.state.thawShared();
+  }
+  getWritableTable(name) {
+    const { schema, bare } = splitQualifiedName(name);
+    if (schema !== null) {
+      return this.databaseForSchema(schema, name).getWritableTable(bare);
+    }
+    const table = this.getTable(bare);
+    return this.ensureWritableTable(table);
+  }
+  ensureWritableTable(table) {
+    if (!table.frozen) return table;
+    const key = keyOf(table.name);
+    const copy = table.clone();
+    this.tables.set(key, copy);
+    return copy;
+  }
+  getWritableIndex(name) {
+    const key = keyOf(name);
+    const index = this.indexes.get(key);
+    if (!index) throw new SqliteError(`no such index: ${name}`, "other");
+    return this.ensureWritableIndex(index);
+  }
+  ensureWritableIndex(index) {
+    if (!index.store.frozen) return index;
+    const copy = {
+      name: index.name,
+      tableName: index.tableName,
+      unique: index.unique,
+      columns: structuredClone(index.columns),
+      where: index.where ? structuredClone(index.where) : null,
+      originalSql: index.originalSql,
+      store: index.store.clone()
+    };
+    this.indexes.set(keyOf(index.name), copy);
     return copy;
   }
   replaceWith(state, options) {
@@ -8121,6 +8503,7 @@ var DatabaseState = class _DatabaseState {
     this.totalChanges = copy.totalChanges;
     this.foreignKeysEnabled = copy.foreignKeysEnabled;
     this.schemaVersion = copy.schemaVersion;
+    this.userVersion = copy.userVersion;
   }
   assertSchemaNameAvailable(name) {
     const key = keyOf(name);
@@ -8312,7 +8695,8 @@ function encodeDatabaseState(state, runtime) {
       constraints: table.constraints,
       indexes: [...table.indexes].sort(compareNames),
       originalSql: table.originalSql,
-      withoutRowid: table.withoutRowid || void 0
+      withoutRowid: table.withoutRowid || void 0,
+      strict: table.strict || void 0
     });
     writer.value(table.nextRowid);
     const rows = [...table.rows.values()].sort((a, b) => compareRowids2(a.rowid, b.rowid));
@@ -8364,7 +8748,8 @@ function decodeDatabaseState(snapshot) {
       constraints: meta.constraints,
       indexes: meta.indexes,
       originalSql: meta.originalSql,
-      withoutRowid: meta.withoutRowid ?? false
+      withoutRowid: meta.withoutRowid ?? false,
+      strict: meta.strict ?? false
     });
     table.nextRowid = asRowid2(reader.value());
     const rowCount = reader.u32();
@@ -8478,7 +8863,8 @@ var TransactionManager = class {
     if (this.inTransaction) {
       throw new SqliteError("cannot start a transaction within a transaction", "transaction", "SQLITE_ERROR");
     }
-    this.transactionSnapshot = this.state.clone();
+    this.state.freezeShared();
+    this.transactionSnapshot = this.state.cloneShallow();
     this.transactionPrngState = this.prng.getState();
     this.savepoints = [];
     this.startedBySavepoint = false;
@@ -8489,6 +8875,7 @@ var TransactionManager = class {
     this.transactionPrngState = null;
     this.savepoints = [];
     this.startedBySavepoint = false;
+    this.state.thawShared();
   }
   rollback(savepoint) {
     this.requireTransaction("cannot rollback - no transaction is active");
@@ -8496,7 +8883,7 @@ var TransactionManager = class {
       const index = this.findSavepoint(savepoint);
       const snapshot2 = this.savepoints[index];
       if (!snapshot2) throw new SqliteError(`no such savepoint: ${savepoint}`, "transaction", "SQLITE_ERROR");
-      this.state.replaceWith(snapshot2.state);
+      this.state.replaceWith(snapshot2.state, { adopt: true });
       this.prng.setState(snapshot2.prngState);
       this.savepoints.splice(index + 1);
       return;
@@ -8506,22 +8893,26 @@ var TransactionManager = class {
     if (!snapshot || prngState === null) {
       throw new SqliteError("cannot rollback - no transaction is active", "transaction", "SQLITE_ERROR");
     }
-    this.state.replaceWith(snapshot);
+    this.state.replaceWith(snapshot, { adopt: true });
     this.prng.setState(prngState);
     this.transactionSnapshot = null;
     this.transactionPrngState = null;
     this.savepoints = [];
     this.startedBySavepoint = false;
+    this.state.thawShared();
   }
   savepoint(name) {
     if (!this.inTransaction) {
-      this.transactionSnapshot = this.state.clone();
+      this.state.freezeShared();
+      this.transactionSnapshot = this.state.cloneShallow();
       this.transactionPrngState = this.prng.getState();
       this.startedBySavepoint = true;
+    } else {
+      this.state.freezeShared();
     }
     this.savepoints.push({
       name,
-      state: this.state.clone(),
+      state: this.state.cloneShallow(),
       prngState: this.prng.getState()
     });
   }
@@ -8533,6 +8924,7 @@ var TransactionManager = class {
       this.transactionSnapshot = null;
       this.transactionPrngState = null;
       this.startedBySavepoint = false;
+      this.state.thawShared();
     }
   }
   findSavepoint(name) {
@@ -8721,6 +9113,7 @@ function toSqlValue(value) {
     return canonicalizeNumber(value);
   }
   if (typeof value === "boolean") return value ? 1 : 0;
+  if (value instanceof SqlReal || value instanceof SqlJsonText) return value;
   if (value instanceof Uint8Array) return new Uint8Array(value);
   if (value instanceof ArrayBuffer) return new Uint8Array(value);
   throw new SqliteError(`unsupported bind value: ${typeof value}`, "datatype_mismatch");
@@ -8935,6 +9328,44 @@ function buildSqliteMaster(state) {
   return buildSchemaCatalog(state, "sqlite_master");
 }
 
+// src/expressions/equals.ts
+function exprEquals(left, right) {
+  if (left.type !== right.type) return false;
+  switch (left.type) {
+    case "null":
+      return true;
+    case "literal":
+      return right.type === "literal" && valuesEqual(left.value, right.value);
+    case "column":
+      return right.type === "column" && (left.table ?? "").toLowerCase() === (right.table ?? "").toLowerCase() && left.name.toLowerCase() === right.name.toLowerCase();
+    case "unary":
+      return right.type === "unary" && left.op === right.op && exprEquals(left.expr, right.expr);
+    case "binary":
+      return right.type === "binary" && left.op === right.op && exprEquals(left.left, right.left) && exprEquals(left.right, right.right);
+    case "function":
+      return right.type === "function" && left.name.toLowerCase() === right.name.toLowerCase() && left.distinct === right.distinct && argsEqual(left.args, right.args);
+    case "collate":
+      return right.type === "collate" && left.collation.toLowerCase() === right.collation.toLowerCase() && exprEquals(left.expr, right.expr);
+    case "cast":
+      return right.type === "cast" && (left.typeName ?? "").toUpperCase() === (right.typeName ?? "").toUpperCase() && exprEquals(left.expr, right.expr);
+    default:
+      return JSON.stringify(left) === JSON.stringify(right);
+  }
+}
+function argsEqual(left, right) {
+  if (left === "*" || right === "*") return left === right;
+  if (left.length !== right.length) return false;
+  return left.every((expr, index) => exprEquals(expr, right[index]));
+}
+function valuesEqual(left, right) {
+  if (left === right) return true;
+  if (left instanceof Uint8Array && right instanceof Uint8Array) {
+    if (left.length !== right.length) return false;
+    return left.every((byte, index) => byte === right[index]);
+  }
+  return false;
+}
+
 // src/planner/access.ts
 function conjunctions(expr) {
   if (expr.type === "binary" && expr.op === "AND") {
@@ -8955,6 +9386,16 @@ function equalityAgainstConst(expr) {
   }
   return null;
 }
+function equalityAgainstExpr(expr) {
+  if (expr.type !== "binary" || expr.op !== "=" && expr.op !== "==") return null;
+  if (expr.left.type !== "column" && isRowIndependentExpr(expr.right)) {
+    return { expr: expr.left, valueExpr: expr.right };
+  }
+  if (expr.right.type !== "column" && isRowIndependentExpr(expr.left)) {
+    return { expr: expr.right, valueExpr: expr.left };
+  }
+  return null;
+}
 function whereFullyCovered(where, coveredColumns, alias, tableName) {
   for (const part of conjunctions(where)) {
     const eq = equalityAgainstConst(part);
@@ -8991,8 +9432,8 @@ function lookupTableRows(from, where, env) {
   } catch {
     return null;
   }
-  const equalities = conjunctions(where).map(equalityAgainstConst).filter((item) => item !== null).filter((item) => matchesTable(item.table, alias, table.name));
-  if (equalities.length === 0) return null;
+  const parts = conjunctions(where);
+  const equalities = parts.map(equalityAgainstConst).filter((item) => item !== null).filter((item) => matchesTable(item.table, alias, table.name));
   const evalConst = (expr) => {
     try {
       return evalExpr(expr, env.createEvalContext(null));
@@ -9006,7 +9447,6 @@ function lookupTableRows(from, where, env) {
     if (value === void 0) continue;
     resolved.push({ table: eq.table, column: eq.column, value });
   }
-  if (resolved.length === 0) return null;
   const pk = table.integerPkColumn();
   for (const eq of resolved) {
     const col = eq.column.toLowerCase();
@@ -9026,17 +9466,40 @@ function lookupTableRows(from, where, env) {
   let best = null;
   for (const indexName of table.indexes) {
     const index = db.indexes.get(indexName.toLowerCase());
-    if (!index || index.where) continue;
+    if (!index) continue;
+    if (index.where && !parts.some((part) => exprEquals(part, index.where))) continue;
+    if (index.columns.some((column) => column.expr)) {
+      const prefix2 = [];
+      for (const column of index.columns) {
+        if (!column.expr) {
+          const value2 = byColumn.get(column.name.toLowerCase());
+          if (value2 === void 0) break;
+          prefix2.push(normalizeForCollation(value2, column.collate ?? "BINARY"));
+          continue;
+        }
+        const match = parts.map(equalityAgainstExpr).find((item) => item && exprEquals(item.expr, column.expr));
+        if (!match) break;
+        const value = evalConst(match.valueExpr);
+        if (value === void 0) break;
+        prefix2.push(normalizeForCollation(value, column.collate ?? "BINARY"));
+      }
+      if (prefix2.length === 0) continue;
+      const rowids2 = prefix2.length === index.columns.length ? index.store.lookup(prefix2) : index.store.lookupPrefix(prefix2);
+      best = { rowids: rowids2, columns: index.columns.map((column) => column.name.toLowerCase()) };
+      if (index.unique || rowids2.length <= 1) break;
+      continue;
+    }
     const prefix = [];
     for (const column of index.columns) {
       const value = byColumn.get(column.name.toLowerCase());
       if (value === void 0) break;
       prefix.push(normalizeForCollation(value, column.collate ?? "BINARY"));
     }
-    if (prefix.length !== index.columns.length) continue;
-    const rowids = index.store.lookup(prefix);
-    best = { rowids, columns: index.columns.map((column) => column.name.toLowerCase()) };
-    if (index.unique || rowids.length <= 1) break;
+    if (prefix.length === 0) continue;
+    const rowids = prefix.length === index.columns.length ? index.store.lookup(prefix) : index.store.lookupPrefix(prefix);
+    best = { rowids, columns: index.columns.slice(0, prefix.length).map((column) => column.name.toLowerCase()) };
+    if (index.unique && prefix.length === index.columns.length) break;
+    if (rowids.length <= 1) break;
   }
   if (best) {
     const rows = [];
@@ -9055,6 +9518,77 @@ function lookupTableRows(from, where, env) {
     hashed.sort((a, b) => compareRowids3(a.rowid, b.rowid));
     return { table, alias, rows: hashed, coveredColumns: /* @__PURE__ */ new Set([col]) };
   }
+  const range = rangeAgainstConst(where) ?? rangeFromBetween(where);
+  if (range && matchesTable(range.table, alias, table.name)) {
+    const value = evalConst(range.valueExpr);
+    const value2 = range.valueExpr2 ? evalConst(range.valueExpr2) : void 0;
+    if (value !== void 0) {
+      for (const indexName of table.indexes) {
+        const index = db.indexes.get(indexName.toLowerCase());
+        if (!index || index.where || index.columns.length !== 1) continue;
+        if (index.columns[0].expr) continue;
+        if (index.columns[0].name.toLowerCase() !== range.column.toLowerCase()) continue;
+        const bound = normalizeForCollation(value, index.columns[0].collate ?? "BINARY");
+        const bound2 = value2 !== void 0 ? normalizeForCollation(value2, index.columns[0].collate ?? "BINARY") : void 0;
+        const rowids = index.store.rangeLookup(range.op, bound, bound2);
+        const rows = [];
+        for (const rowid of rowids) {
+          const row = table.get(rowid);
+          if (row) rows.push(row);
+        }
+        return { table, alias, rows, coveredColumns: /* @__PURE__ */ new Set([range.column.toLowerCase()]) };
+      }
+    }
+  }
+  return null;
+}
+function rangeAgainstConst(expr) {
+  if (expr.type !== "binary") return null;
+  const op = expr.op;
+  if (op !== ">" && op !== ">=" && op !== "<" && op !== "<=") return null;
+  if (expr.left.type === "column" && isRowIndependentExpr(expr.right)) {
+    return { table: expr.left.table, column: expr.left.name, op, valueExpr: expr.right };
+  }
+  if (expr.right.type === "column" && isRowIndependentExpr(expr.left)) {
+    const flipped = op === ">" ? "<" : op === ">=" ? "<=" : op === "<" ? ">" : ">=";
+    return { table: expr.right.table, column: expr.right.name, op: flipped, valueExpr: expr.left };
+  }
+  return null;
+}
+function rangeFromBetween(expr) {
+  if (expr.type !== "between" || expr.not || expr.expr.type !== "column") return null;
+  return {
+    table: expr.expr.table,
+    column: expr.expr.name,
+    op: "between",
+    valueExpr: expr.lower,
+    valueExpr2: expr.upper
+  };
+}
+function tryIndexedOrder(from, order, env, limit) {
+  if (from.type !== "table" || order.expr.type !== "column") return null;
+  const alias = from.alias ?? from.name;
+  const db = env.state.databaseForSchema(from.schema, from.schema ? `${from.schema}.${from.name}` : from.name);
+  let table;
+  try {
+    table = db.getTable(from.name);
+  } catch {
+    return null;
+  }
+  const col = order.expr.name.toLowerCase();
+  for (const indexName of table.indexes) {
+    const index = db.indexes.get(indexName.toLowerCase());
+    if (!index || index.where || index.columns.length !== 1 || index.columns[0].expr) continue;
+    if (index.columns[0].name.toLowerCase() !== col) continue;
+    const desc = order.dir === "DESC";
+    const rows = [];
+    for (const rowid of index.store.orderedRowids(desc)) {
+      const row = table.get(rowid);
+      if (row) rows.push(row);
+      if (limit !== void 0 && rows.length >= limit) break;
+    }
+    return { table, alias, rows, coveredColumns: /* @__PURE__ */ new Set([col]) };
+  }
   return null;
 }
 function compareRowids3(left, right) {
@@ -9499,6 +10033,7 @@ function executeWith(stmt, env, parent) {
 function executeSelectCore(stmt, env, parent) {
   let scopes;
   let skipWhere = false;
+  let skipOrder = false;
   if (stmt.from && stmt.where) {
     const indexed = tryIndexedTableRows(stmt.from, stmt.where, env);
     if (indexed) {
@@ -9507,6 +10042,28 @@ function executeSelectCore(stmt, env, parent) {
     } else {
       scopes = scanFrom(stmt.from, env, parent);
     }
+  } else if (stmt.from && stmt.orderBy.length === 1 && stmt.orderBy[0]) {
+    let take;
+    if (stmt.limit) {
+      const ctx = env.createEvalContext(null, parent);
+      const limitValue = toInteger(evalExpr(stmt.limit.limit, ctx));
+      const offsetValue = stmt.limit.offset ? toInteger(evalExpr(stmt.limit.offset, ctx)) : 0;
+      if (limitValue !== null && offsetValue !== null) {
+        const offset = Math.max(0, Number(offsetValue));
+        const limit = Number(limitValue);
+        take = limit < 0 ? void 0 : offset + limit;
+      }
+    }
+    const ordered = tryIndexedOrder(
+      stmt.from,
+      { expr: stmt.orderBy[0].expr, dir: stmt.orderBy[0].dir ?? "ASC" },
+      env,
+      take
+    );
+    if (ordered) {
+      scopes = scopesFromTableRows(ordered.table, ordered.rows, ordered.alias, env, parent);
+      skipOrder = true;
+    } else scopes = scanFrom(stmt.from, env, parent);
   } else {
     scopes = stmt.from ? scanFrom(stmt.from, env, parent) : [{ cells: [] }];
   }
@@ -9580,7 +10137,7 @@ function executeSelectCore(stmt, env, parent) {
       return true;
     });
   }
-  if (stmt.orderBy.length > 0) {
+  if (stmt.orderBy.length > 0 && !skipOrder) {
     output.sort((left, right) => compareOutput(left, right, stmt.orderBy, columns, env, parent));
   }
   if (stmt.limit) {
@@ -10033,8 +10590,9 @@ function windowValue(expr, current, rows, env, parent, namedWindows) {
     }
   }
   if (expr.func.type === "aggregate") {
-    const [start2, end2] = frameBounds(spec, index, partition.length, currentCtx, defaultFrameEnd);
-    return aggregateValue(expr.func, partition.slice(start2, end2 + 1), env, parent);
+    const [start2, end2] = frameBounds(spec, index, partition.length, currentCtx, defaultFrameEnd, orderKeys);
+    const framed2 = frameRows(partition, start2, end2, index, orderKeys, spec.frame?.exclude ?? null);
+    return aggregateValue(expr.func, framed2, env, parent);
   }
   const name = expr.func.name.toLowerCase();
   const args = expr.func.args === "*" ? [] : expr.func.args;
@@ -10056,12 +10614,14 @@ function windowValue(expr, current, rows, env, parent, namedWindows) {
     const target = name === "lag" ? index - offset : index + offset;
     return values[target]?.[0] ?? evaluated[2] ?? null;
   }
-  const [start, end] = frameBounds(spec, index, partition.length, currentCtx, defaultFrameEnd);
-  if (name === "first_value") return values[start]?.[0] ?? null;
-  if (name === "last_value") return values[end]?.[0] ?? null;
+  const [start, end] = frameBounds(spec, index, partition.length, currentCtx, defaultFrameEnd, orderKeys);
+  const framed = frameRows(partition, start, end, index, orderKeys, spec.frame?.exclude ?? null);
+  const framedValues = framed.map((row) => args.map((arg) => evalExpr(arg, env.createEvalContext(row, parent))));
+  if (name === "first_value") return framedValues[0]?.[0] ?? null;
+  if (name === "last_value") return framedValues[framedValues.length - 1]?.[0] ?? null;
   if (name === "nth_value") {
-    const target = start + Number(toInteger(evaluated[1] ?? null) ?? 0) - 1;
-    return target >= start && target <= end ? values[target]?.[0] ?? null : null;
+    const target = Number(toInteger(evaluated[1] ?? null) ?? 0) - 1;
+    return target >= 0 && target < framedValues.length ? framedValues[target]?.[0] ?? null : null;
   }
   if (name === "ntile") {
     const buckets = Math.max(1, Number(toInteger(evaluated[0] ?? 1) ?? 1));
@@ -10108,15 +10668,21 @@ function resolveWindow(spec, namedWindows, seen = /* @__PURE__ */ new Set()) {
     ref: null
   };
 }
-function frameBounds(spec, index, length, ctx, defaultFrameEnd) {
+function frameBounds(spec, index, length, ctx, defaultFrameEnd, orderKeys) {
   if (!spec.frame) return [0, spec.orderBy.length > 0 ? defaultFrameEnd : Math.max(0, length - 1)];
-  const bound = (item, _start) => {
+  const isRangeLike = spec.frame.type === "RANGE" || spec.frame.type === "GROUPS";
+  let peerFirst = index;
+  if (isRangeLike && spec.orderBy.length > 0) {
+    while (peerFirst > 0 && rowsEqual(orderKeys[peerFirst], orderKeys[peerFirst - 1])) peerFirst--;
+  }
+  const bound = (item, isStart) => {
     switch (item.kind) {
       case "unbounded_preceding":
         return 0;
       case "unbounded_following":
         return Math.max(0, length - 1);
       case "current_row":
+        if (isRangeLike) return isStart ? peerFirst : defaultFrameEnd;
         return index;
       case "preceding":
         return Math.max(0, index - Number(toInteger(evalExpr(item.expr, ctx)) ?? 0));
@@ -10126,6 +10692,20 @@ function frameBounds(spec, index, length, ctx, defaultFrameEnd) {
   };
   return [bound(spec.frame.start, true), bound(spec.frame.end, false)];
 }
+function frameRows(partition, start, end, index, orderKeys, exclude) {
+  let peerFirst = index;
+  let peerLast = index;
+  while (peerFirst > 0 && rowsEqual(orderKeys[peerFirst], orderKeys[peerFirst - 1])) peerFirst--;
+  while (peerLast + 1 < partition.length && rowsEqual(orderKeys[peerLast], orderKeys[peerLast + 1])) peerLast++;
+  const rows = [];
+  for (let i = Math.max(0, start); i <= end && i < partition.length; i++) {
+    if (exclude === "current_row" && i === index) continue;
+    if (exclude === "group" && i >= peerFirst && i <= peerLast) continue;
+    if (exclude === "ties" && i >= peerFirst && i <= peerLast && i !== index) continue;
+    rows.push(partition[i]);
+  }
+  return rows;
+}
 function compareScopes(a, b, order, env, parent) {
   for (const item of order) {
     const left = evalExpr(item.expr, env.createEvalContext(a, parent));
@@ -10475,11 +11055,12 @@ function executeCreateIndex(stmt, env) {
           value: row.values.get(normalizeColumnName(column.name)) ?? null
         }))
       });
-      if (stmt.where && !evalExpr(stmt.where, ctx)) continue;
+      if (stmt.where && isTruthySql(evalExpr(stmt.where, ctx)) !== true) continue;
       index.store.insert(
-        stmt.columns.map(
-          (column) => normalizeForCollation(row.values.get(normalizeColumnName(column.name)) ?? null, column.collate ?? "BINARY")
-        ),
+        stmt.columns.map((column) => {
+          const raw = column.expr ? evalExpr(column.expr, ctx) : row.values.get(normalizeColumnName(column.name)) ?? null;
+          return normalizeForCollation(raw, column.collate ?? "BINARY");
+        }),
         row.rowid,
         stmt.unique
       );
@@ -10491,7 +11072,7 @@ function executeCreateIndex(stmt, env) {
   return emptyResult(0, env.state.lastInsertRowid);
 }
 function executeAlterTable(stmt, env) {
-  const table = env.state.getTable(stmt.table);
+  const table = env.state.getWritableTable(stmt.table);
   const action = stmt.action;
   if (action.kind === "rename_table") {
     env.state.renameTable(stmt.table, action.newName);
@@ -10510,7 +11091,7 @@ function executeAlterTable(stmt, env) {
     }
     for (const constraint of table.constraints) renameConstraintColumn(constraint, action.oldName, action.newName);
     for (const name of table.indexes) {
-      const index = env.state.indexes.get(name.toLowerCase());
+      const index = env.state.getWritableIndex(name);
       if (index) {
         for (const indexed of index.columns)
           if (indexed.name.toLowerCase() === action.oldName.toLowerCase()) indexed.name = action.newName;
@@ -10830,13 +11411,17 @@ function executeFtsDelete(table, rowids) {
 }
 
 // src/executor/dml.ts
+function storeColumnValue(table, column, value) {
+  if (table.strict) return applyStrictValue(value, column.typeName ?? "", table.name, column.name);
+  return applyAffinity(value, column.affinity);
+}
 function executeInsert(stmt, env) {
   if (env.state.isVirtualTable(stmt.table)) {
     return executeVirtualInsert(stmt, env);
   }
   const fast = tryFastInsert(stmt, env);
   if (fast) return fast;
-  const table = env.state.getTable(stmt.table);
+  const table = env.state.getWritableTable(stmt.table);
   const columnNames = stmt.columns ?? table.columns.map((column) => column.name);
   const rowidIndexes = columnNames.map((name, index) => isRowidName3(name) ? index : -1).filter((index) => index >= 0);
   if (rowidIndexes.length > 1) throw new SqliteError("duplicate column name: rowid", "other");
@@ -10861,7 +11446,7 @@ function executeInsert(stmt, env) {
         const column = table.columns[index];
         const suppliedIndex = suppliedIndexes[index];
         const value = suppliedIndex >= 0 ? source[suppliedIndex] ?? null : null;
-        values.set(column.nameLower ?? column.name.toLowerCase(), applyAffinity(value, column.affinity));
+        values.set(column.nameLower ?? column.name.toLowerCase(), storeColumnValue(table, column, value));
       }
       last = table.insert({ values }, { prepared: true, skipValidate: true });
       changes++;
@@ -10877,7 +11462,7 @@ function executeInsert(stmt, env) {
       if (column.generated) continue;
       const suppliedIndex = suppliedIndexes[table.columns.indexOf(column)] ?? -1;
       const value = suppliedIndex >= 0 ? source[suppliedIndex] ?? null : column.defaultExpr ? evalExpr(column.defaultExpr, env.createEvalContext()) : null;
-      values.set(column.nameLower ?? column.name.toLowerCase(), applyAffinity(value, column.affinity));
+      values.set(column.nameLower ?? column.name.toLowerCase(), storeColumnValue(table, column, value));
     }
     for (const column of table.columns) {
       if (!column.generated) continue;
@@ -10901,7 +11486,7 @@ function executeInsert(stmt, env) {
           })
         });
         const computed = evalExpr(column.generated.expr, genCtx);
-        values.set(normalizeColumnName(column.name), applyAffinity(computed, column.affinity));
+        values.set(normalizeColumnName(column.name), storeColumnValue(table, column, computed));
       } else {
         values.set(normalizeColumnName(column.name), null);
       }
@@ -10910,7 +11495,7 @@ function executeInsert(stmt, env) {
     const conflicts = conflictingRows(table, values, env);
     if (conflicts.length > 0) {
       if (stmt.upsert) {
-        const targetConflicts = stmt.upsert.targetColumns ? conflictsMatchingTarget(table, values, env, stmt.upsert.targetColumns) : conflicts;
+        const targetConflicts = conflictsForUpsert(table, values, env, stmt.upsert);
         if (targetConflicts.length === 0) {
           throw new SqliteError(
             `UNIQUE constraint failed: ${table.name}`,
@@ -11004,7 +11589,7 @@ function tryFastInsert(stmt, env) {
   }
   let table;
   try {
-    table = env.state.getTable(plan.tableName);
+    table = env.state.getWritableTable(plan.tableName);
   } catch {
     return null;
   }
@@ -11055,7 +11640,7 @@ function executeUpdate(stmt, env) {
   if (env.state.isVirtualTable(stmt.table)) {
     return executeVirtualUpdate(stmt, env);
   }
-  const table = env.state.getTable(stmt.table);
+  const table = env.state.getWritableTable(stmt.table);
   const alias = stmt.alias ?? stmt.table;
   const candidates = [];
   if (stmt.from) {
@@ -11114,7 +11699,7 @@ function executeDelete(stmt, env) {
   if (env.state.isVirtualTable(stmt.table)) {
     return executeVirtualDelete(stmt, env);
   }
-  const table = env.state.getTable(stmt.table);
+  const table = env.state.getWritableTable(stmt.table);
   const selectedSource = stmt.where === null ? null : tryIndexedTableRows({ type: "table", schema: null, name: stmt.table, alias: stmt.alias }, stmt.where, env);
   const selected = [...selectedSource ? selectedSource.rows : table.scan()].filter((row) => {
     if (!stmt.where) return true;
@@ -11148,7 +11733,7 @@ function evaluateSet(items, table, ctx) {
     if (item.columns.length === 1) {
       const column = columnOf(table, item.columns[0]);
       if (column.generated) throw new SqliteError(`cannot UPDATE generated column "${column.name}"`, "misuse");
-      updates.set(normalizeColumnName(column.name), evalExpr(item.expr, ctx));
+      updates.set(normalizeColumnName(column.name), storeColumnValue(table, column, evalExpr(item.expr, ctx)));
       continue;
     }
     if (item.expr.type !== "row" || item.expr.values.length !== item.columns.length) {
@@ -11162,7 +11747,7 @@ function evaluateSet(items, table, ctx) {
       if (column.generated) throw new SqliteError(`cannot UPDATE generated column "${column.name}"`, "misuse");
       updates.set(
         normalizeColumnName(column.name),
-        evalExpr(item.expr.type === "row" ? item.expr.values[index] : item.expr, ctx)
+        storeColumnValue(table, column, evalExpr(item.expr.type === "row" ? item.expr.values[index] : item.expr, ctx))
       );
     });
   }
@@ -11189,7 +11774,7 @@ function updateOne(table, row, updates, env) {
       });
       merged.set(
         normalizeColumnName(column.name),
-        applyAffinity(evalExpr(column.generated.expr, genCtx), column.affinity)
+        storeColumnValue(table, column, evalExpr(column.generated.expr, genCtx))
       );
     }
     after = table.update(row.rowid, merged);
@@ -11220,20 +11805,23 @@ function validateRow(table, row, env) {
   );
 }
 function addIndexes(table, row, env) {
-  const indexes = env.state.databaseForTable(table).indexes;
+  const db = env.state.databaseForTable(table);
   for (const name of table.indexes) {
-    const index = indexes.get(name.toLowerCase());
-    if (!index) continue;
+    const found = db.indexes.get(name.toLowerCase());
+    if (!found) continue;
+    const index = db.ensureWritableIndex(found);
     if (index.where && isTruthySql(evalExpr(index.where, env.createEvalContext(scopeFor(table, row, table.name, env)))) !== true)
       continue;
-    index.store.insert(indexValues(index.columns, row), row.rowid, index.unique);
+    index.store.insert(indexValues(index.columns, row, env, table), row.rowid, index.unique);
   }
 }
 function removeIndexes(table, row, env) {
-  const indexes = env.state.databaseForTable(table).indexes;
+  const db = env.state.databaseForTable(table);
   for (const name of table.indexes) {
-    const index = indexes.get(name.toLowerCase());
-    if (index) index.store.remove(indexValues(index.columns, row), row.rowid);
+    const found = db.indexes.get(name.toLowerCase());
+    if (!found) continue;
+    const index = db.ensureWritableIndex(found);
+    index.store.remove(indexValues(index.columns, row, env, table), row.rowid);
   }
 }
 function removeOne(table, row, env) {
@@ -11266,6 +11854,27 @@ function conflictsMatchingTarget(table, values, env, targetColumns) {
   }
   return conflictsForSets(table, values, matchingSets, env);
 }
+function conflictsForUpsert(table, values, env, upsert) {
+  if (!upsert.targetColumns) return conflictingRows(table, values, env);
+  const exprs = upsert.targetExprs;
+  const hasExpr = exprs?.some((expr) => expr.type !== "column") ?? false;
+  if (hasExpr && exprs) {
+    const db = env.state.databaseForTable(table);
+    for (const indexName of table.indexes) {
+      const index = db.indexes.get(indexName.toLowerCase());
+      if (!index?.unique || index.columns.length !== exprs.length) continue;
+      const matches = index.columns.every((column, i) => {
+        const expr = exprs[i];
+        if (column.expr) return exprEquals(column.expr, expr);
+        return expr.type === "column" && expr.name.toLowerCase() === column.name.toLowerCase();
+      });
+      if (!matches) continue;
+      if (upsert.targetWhere && index.where && !exprEquals(upsert.targetWhere, index.where)) continue;
+      return conflictsForSets(table, values, [index.columns], env);
+    }
+  }
+  return conflictsMatchingTarget(table, values, env, upsert.targetColumns.filter(Boolean));
+}
 function uniqueColumnSets(table, env) {
   const sets = [];
   const seen = /* @__PURE__ */ new Set();
@@ -11277,7 +11886,7 @@ function uniqueColumnSets(table, env) {
   };
   for (const indexName of table.indexes) {
     const index = env.state.databaseForTable(table).indexes.get(indexName.toLowerCase());
-    if (index?.unique && !index.where) remember(index.columns);
+    if (index?.unique) remember(index.columns);
   }
   const pk = table.integerPkColumn();
   if (pk) remember([{ name: pk.name, collate: pk.collate, order: null }]);
@@ -11303,9 +11912,7 @@ function conflictsForSets(table, values, sets, env) {
   };
   const db = env.state.databaseForTable(table);
   for (const columns of sets) {
-    const desired = columns.map(
-      (column) => normalizeForCollation(values.get(normalizeColumnName(column.name)) ?? null, column.collate ?? "BINARY")
-    );
+    const desired = indexValuesFromMap(columns, values, table, env);
     if (desired.some((value) => value === null)) continue;
     if (columns.length === 1) {
       const pk = table.integerPkColumn();
@@ -11318,12 +11925,13 @@ function conflictsForSets(table, values, sets, env) {
     let usedIndex = false;
     for (const indexName of table.indexes) {
       const index = db.indexes.get(indexName.toLowerCase());
-      if (!index?.unique || index.where) continue;
+      if (!index?.unique) continue;
       if (index.columns.length !== columns.length) continue;
       if (!index.columns.every((column, i) => normalizeColumnName(column.name) === normalizeColumnName(columns[i].name))) {
         continue;
       }
       usedIndex = true;
+      if (index.where && !indexWhereMatches(index.where, values, table, env)) continue;
       for (const rowid of index.store.lookup(desired)) {
         const row = table.get(rowid);
         if (row) push(row);
@@ -11332,36 +11940,63 @@ function conflictsForSets(table, values, sets, env) {
     }
     if (usedIndex) continue;
     for (const row of table.scan()) {
-      const existing = indexValues(columns, row);
+      const existing = indexValues(columns, row, env, table);
       if (desired.every((value, index) => compareSql(value, existing[index] ?? null) === 0)) push(row);
     }
   }
   return found;
 }
-function indexValues(columns, row) {
-  return columns.map(
-    (column) => normalizeForCollation(row.values.get(normalizeColumnName(column.name)) ?? null, column.collate ?? "BINARY")
-  );
+function indexValues(columns, row, env, table) {
+  if (!env || !table) {
+    return columns.map(
+      (column) => normalizeForCollation(row.values.get(normalizeColumnName(column.name)) ?? null, column.collate ?? "BINARY")
+    );
+  }
+  const ctx = env.createEvalContext(scopeFor(table, row, table.name, env));
+  return columns.map((column) => {
+    const raw = column.expr ? evalExpr(column.expr, ctx) : row.values.get(normalizeColumnName(column.name)) ?? null;
+    return normalizeForCollation(raw, column.collate ?? "BINARY");
+  });
+}
+function indexValuesFromMap(columns, values, table, env) {
+  const fake = { rowid: 0, values };
+  return indexValues(columns, fake, env, table);
+}
+function indexWhereMatches(where, values, table, env) {
+  const fake = { rowid: 0, values };
+  return isTruthySql(evalExpr(where, env.createEvalContext(scopeFor(table, fake, table.name, env)))) === true;
 }
 function checkForeignKeys(table, row, env) {
   if (!env.state.foreignKeysEnabled) return;
-  const references = [];
   for (const constraint of table.constraints) {
-    if (constraint.type === "foreign_key")
-      references.push({ columns: constraint.columns, table: constraint.refTable, refColumns: constraint.refColumns });
-  }
-  for (const reference of references) {
-    const values = reference.columns.map((name) => row.values.get(normalizeColumnName(name)) ?? null);
-    if (values.some((value) => value === null)) continue;
-    const parent = env.state.getTable(reference.table);
-    const parentColumns = reference.refColumns ?? parent.columns.filter((column) => column.primaryKey).map((column) => column.name);
-    if (![...parent.scan()].some(
-      (candidate) => values.every((value, index) => {
-        const parentColumn = parentColumns[index];
-        return parentColumn !== void 0 && compareSql(value, candidate.values.get(normalizeColumnName(parentColumn)) ?? null) === 0;
-      })
-    )) {
-      throw new SqliteError("FOREIGN KEY constraint failed", "constraint_foreign", "SQLITE_CONSTRAINT_FOREIGNKEY");
+    if (constraint.type !== "foreign_key") continue;
+    if (fkIsDeferred(constraint, env)) continue;
+    assertForeignKeySatisfied(row, constraint, env);
+  }
+}
+function fkIsDeferred(constraint, env) {
+  return env.transactions.inTransaction && constraint.initiallyDeferred;
+}
+function assertForeignKeySatisfied(row, constraint, env) {
+  const values = constraint.columns.map((name) => row.values.get(normalizeColumnName(name)) ?? null);
+  if (values.some((value) => value === null)) return;
+  const parent = env.state.getTable(constraint.refTable);
+  const parentColumns = constraint.refColumns ?? parent.columns.filter((column) => column.primaryKey).map((column) => column.name);
+  if (![...parent.scan()].some(
+    (candidate) => values.every((value, index) => {
+      const parentColumn = parentColumns[index];
+      return parentColumn !== void 0 && compareSql(value, candidate.values.get(normalizeColumnName(parentColumn)) ?? null) === 0;
+    })
+  )) {
+    throw new SqliteError("FOREIGN KEY constraint failed", "constraint_foreign", "SQLITE_CONSTRAINT_FOREIGNKEY");
+  }
+}
+function checkDeferredForeignKeys(env) {
+  if (!env.state.foreignKeysEnabled) return;
+  for (const table of env.state.tables.values()) {
+    for (const constraint of table.constraints) {
+      if (constraint.type !== "foreign_key" || !constraint.initiallyDeferred) continue;
+      for (const row of table.scan()) assertForeignKeySatisfied(row, constraint, env);
     }
   }
 }
@@ -11393,8 +12028,9 @@ function applyReferentialDelete(parent, row, env) {
         } else if (constraint.onDelete === "SET DEFAULT") {
           const updated = updateOne(child, candidate, defaultUpdates(child, constraint.columns, env), env);
           changes += 1 + updated.cascaded;
-        } else
+        } else if (!fkIsDeferred(constraint, env)) {
           throw new SqliteError("FOREIGN KEY constraint failed", "constraint_foreign", "SQLITE_CONSTRAINT_FOREIGNKEY");
+        }
       }
     }
   }
@@ -11435,7 +12071,7 @@ function applyReferentialUpdate(parent, before, after, env) {
         } else if (constraint.onUpdate === "SET DEFAULT") {
           const updated = updateOne(child, candidate, defaultUpdates(child, constraint.columns, env), env);
           changes += 1 + updated.cascaded;
-        } else {
+        } else if (!fkIsDeferred(constraint, env)) {
           throw new SqliteError("FOREIGN KEY constraint failed", "constraint_foreign", "SQLITE_CONSTRAINT_FOREIGNKEY");
         }
       }
@@ -11901,6 +12537,7 @@ function executeStatement(stmt, env) {
       env.transactions.begin();
       return emptyResult(0, env.state.lastInsertRowid);
     case "commit":
+      checkDeferredForeignKeys(env);
       env.transactions.commit();
       return emptyResult(0, env.state.lastInsertRowid);
     case "rollback":
@@ -11947,7 +12584,8 @@ function executeAnalyze(stmt, env) {
         ],
         constraints: [],
         asSelect: null,
-        withoutRowid: false
+        withoutRowid: false,
+        strict: false
       },
       "CREATE TABLE sqlite_stat1(tbl,idx,stat)"
     );
@@ -11990,38 +12628,85 @@ function executeAnalyze(stmt, env) {
 }
 
 // src/api/statement.ts
-var Statement = class {
+var Statement = class _Statement {
   constructor(database, sql, statements) {
     this.database = database;
     this.sql = sql;
     this.statements = statements;
+    this.schemaVersion = database.state.schemaVersion;
   }
   database;
   sql;
-  statements;
   bound = [];
   namedPlan = null;
   env = null;
+  statements;
+  schemaVersion;
+  /**
+   * Construct a {@link Statement} for {@link Database.prepare}.
+   * @internal
+   */
+  static create(database, sql, statements) {
+    return new _Statement(database, sql, statements);
+  }
+  /**
+   * Store parameters for later {@link run} / {@link all} / {@link get} / {@link result}.
+   *
+   * Supports positional `?` / `?NNN` and named `:name` / `@name` / `$name` placeholders.
+   *
+   * @param params - Values to bind, in placeholder order.
+   * @returns `this` for chaining.
+   */
   bind(...params) {
     this.bound = [...params];
     return this;
   }
+  /**
+   * Execute for side effects (INSERT / UPDATE / DELETE / DDL).
+   *
+   * @param params - If provided, override the last {@link bind}; otherwise bound values are used.
+   * @returns Mutation counters for this execution.
+   * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
+   */
   run(...params) {
     const result = this.execute(params.length > 0 ? params : this.bound, { named: false });
     return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
   }
+  /**
+   * Execute and return every result row as an object keyed by column name.
+   *
+   * @typeParam T - Row shape. Defaults to {@link QueryRow}.
+   * @param params - If provided, override the last {@link bind}; otherwise bound values are used.
+   * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
+   */
   all(...params) {
     return this.execute(params.length > 0 ? params : this.bound, { named: true }).rows;
   }
-  /** Full result including column names (needed for empty result-set metadata). */
+  /**
+   * Execute and return the full {@link ResultSet}, including column names.
+   *
+   * Use this when you need metadata for an empty result (column names with zero rows).
+   * {@link all} only returns row objects.
+   *
+   * @param params - If provided, override the last {@link bind}; otherwise bound values are used.
+   * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
+   */
   result(...params) {
     return this.execute(params.length > 0 ? params : this.bound, { named: true });
   }
+  /**
+   * Execute and return the first row, or `undefined` if there are no rows.
+   *
+   * @typeParam T - Row shape. Defaults to {@link QueryRow}.
+   * @param params - If provided, override the last {@link bind}; otherwise bound values are used.
+   * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
+   */
   get(...params) {
     return this.execute(params.length > 0 ? params : this.bound, { named: true, maxRows: 1 }).rows[0];
   }
   execute(params, options) {
     this.database.assertOpen();
+    this.reprepareIfSchemaChanged();
     if (this.statements.length === 0) throw new SqliteError("empty statement", "misuse");
     const env = this.obtainEnv(params);
     env.maxRows = options?.maxRows ?? Number.POSITIVE_INFINITY;
@@ -12051,6 +12736,13 @@ var Statement = class {
     });
     return this.env;
   }
+  reprepareIfSchemaChanged() {
+    if (this.schemaVersion === this.database.state.schemaVersion) return;
+    this.statements = parse(this.sql);
+    this.env = null;
+    this.namedPlan = null;
+    this.schemaVersion = this.database.state.schemaVersion;
+  }
   bindNamed(env, params) {
     this.namedPlan ??= planNamedParameters(this.sql);
     for (const item of this.namedPlan.named) {
@@ -12082,31 +12774,81 @@ function planNamedParameters(sql) {
 
 // src/api/database.ts
 var Database = class {
+  /** @internal Engine catalog, tables, and mutation counters. */
   state = new DatabaseState();
+  /** Seed used to construct the PRNG when `options.prng` is omitted. */
   seed;
+  /**
+   * PRNG backing `random()` / `randomblob()` and related builtins.
+   * Prefer passing `seed` or `prng` to the constructor.
+   * @internal
+   */
   prng;
+  /**
+   * Clock used by `date('now')` / `datetime('now')` / `CURRENT_TIMESTAMP`.
+   * Prefer passing `now` to the constructor.
+   * @internal
+   */
   now;
+  /** @internal Transaction / savepoint manager. */
   transactions;
   closed = false;
   transactionSequence = 0;
+  /**
+   * Create an empty in-memory database.
+   *
+   * @param options - Determinism knobs. See {@link DatabaseOptions}.
+   */
   constructor(options = {}) {
     this.seed = options.seed ?? DEFAULT_DATABASE_SEED;
     this.prng = options.prng ?? new Prng(this.seed);
     this.now = resolveClock(options.now);
     this.transactions = new TransactionManager(this.state, this.prng);
   }
+  /**
+   * Execute SQL for its side effects (DDL/DML). Multiple statements are allowed.
+   *
+   * @param sql - SQL to run (semicolon-separated statements are ok).
+   * @param params - Bound parameters for `?` / `:name` placeholders.
+   * @throws {SqliteError} If the database is closed or the SQL fails.
+   */
   exec(sql, params = []) {
     this.assertOpen();
-    new Statement(this, sql, parse(sql)).run(...params);
+    Statement.create(this, sql, parse(sql)).run(...params);
   }
+  /**
+   * Execute a query and return all rows as objects keyed by column name.
+   *
+   * @typeParam T - Row shape. Defaults to {@link QueryRow}.
+   * @param sql - SQL SELECT (or any statement that produces a result set).
+   * @param params - Bound parameters for `?` / `:name` placeholders.
+   * @returns All result rows.
+   * @throws {SqliteError} If the database is closed or the SQL fails.
+   */
   query(sql, params = []) {
     this.assertOpen();
-    return new Statement(this, sql, parse(sql)).all(...params);
+    return Statement.create(this, sql, parse(sql)).all(...params);
   }
+  /**
+   * Compile `sql` into a reusable {@link Statement}.
+   *
+   * @param sql - SQL to prepare.
+   * @throws {SqliteError} If the database is closed or `sql` cannot be parsed.
+   */
   prepare(sql) {
     this.assertOpen();
-    return new Statement(this, sql, parse(sql));
+    return Statement.create(this, sql, parse(sql));
   }
+  /**
+   * Run `fn` inside a transaction. Commits on success; rolls back if `fn` throws.
+   *
+   * Nested calls use SAVEPOINTs so an inner failure does not abort the outer
+   * transaction.
+   *
+   * @param fn - Work to run while the transaction is open.
+   * @returns The value returned by `fn`.
+   * @throws {SqliteError} If the database is closed. Re-throws whatever `fn` throws after rollback.
+   */
   transaction(fn) {
     this.assertOpen();
     if (!this.transactions.inTransaction) {
@@ -12132,6 +12874,13 @@ var Database = class {
       throw error;
     }
   }
+  /**
+   * Serialize schema, rows, PRNG state, and clock into a custom snapshot blob.
+   *
+   * This is not a `.sqlite` file. Restore it with {@link restore}.
+   *
+   * @throws {SqliteError} If the database is closed.
+   */
   snapshot() {
     this.assertOpen();
     return encodeDatabaseState(this.state, {
@@ -12139,6 +12888,14 @@ var Database = class {
       nowMs: this.now().getTime()
     });
   }
+  /**
+   * Replace this database's contents with a blob from {@link snapshot}.
+   *
+   * Restores PRNG state and the clock when the snapshot includes them (v2).
+   *
+   * @param snapshot - Bytes previously returned by {@link snapshot}.
+   * @throws {SqliteError} If the database is closed, a transaction is open, or the blob is invalid.
+   */
   restore(snapshot) {
     this.assertOpen();
     if (this.transactions.inTransaction) throw new SqliteError("cannot restore during a transaction", "transaction");
@@ -12150,19 +12907,39 @@ var Database = class {
       this.now = fixedClock(new Date(decoded.runtime.nowMs));
     }
   }
+  /**
+   * Close the database. Further SQL throws {@link SqliteError}. Idempotent.
+   *
+   * Rolls back an open transaction, if any.
+   */
   close() {
     if (this.closed) return;
     if (this.transactions.inTransaction) this.transactions.rollback();
     this.closed = true;
   }
+  /**
+   * Rows changed by the most recent INSERT / UPDATE / DELETE (SQLite `changes()`).
+   *
+   * @throws {SqliteError} If the database is closed.
+   */
   get changes() {
     this.assertOpen();
     return this.state.changes;
   }
+  /**
+   * Rowid of the most recent INSERT (SQLite `last_insert_rowid()`).
+   *
+   * @throws {SqliteError} If the database is closed.
+   */
   get lastInsertRowid() {
     this.assertOpen();
     return this.state.lastInsertRowid;
   }
+  /**
+   * Throw if {@link close} has already been called.
+   * @internal
+   * @throws {SqliteError} If the database is closed.
+   */
   assertOpen() {
     if (this.closed) throw new SqliteError("Database is closed", "misuse");
   }
@@ -12172,11 +12949,13 @@ export {
   DEFAULT_NOW,
   Database,
   Prng,
+  SqlJsonText,
   SqlReal,
   SqliteError,
   Statement,
   affinityFromTypeName,
   applyAffinity,
+  asSqlJsonText,
   asSqlReal,
   canonicalizeNumber,
   cloneSqlValue,
@@ -12188,6 +12967,7 @@ export {
   evalExpr,
   fixedClock,
   globMatch,
+  isSqlJsonText,
   isSqlReal,
   isTruthySql,
   likeMatch,