@crvouga/sqlite-mem 1.12.0 → 1.14.0

package/AGENTS.md

@@ -67,6 +67,8 @@ Hot / large files: `parser/parser.ts`, `executor/select.ts`, `executor/dml.ts`.
 - **`Database`** (API) vs **`DatabaseState`** (engine storage).
 - Throw **`SqliteError`** with an `ErrorCategory`. Missing SQL must fail loud via `unsupported()` — the inventory gate fails if the oracle exposes an unimplemented builtin/module.
 - Fast-path helpers (`tryExecuteSimpleSelect`, `tryFastInsert`, `tryIndexedTableRows`, …): return `null` → fall through. Update **both** paths when semantics change.
+- **Dual-path invariant:** residual `WHERE` filtering is skipped on an index/hash access path only when `whereFullyCovered(where, coveredColumns, …)` is true (see [`src/planner/access.ts`](src/planner/access.ts)). Any change to WHERE/join/insert semantics requires updating both fast and full paths **and** the fast≡full property tests under `tests/fuzz/fast-path.test.ts`.
+- Internal invariants use always-on asserts in [`src/runtime/assert.ts`](src/runtime/assert.ts) (`assert`, `assertUnreachable`, `assertRowShape`).
 - TypeScript: `strict` + `noUncheckedIndexedAccess`. Imports use `.ts` extensions. Biome: 2-space, double quotes, 120 columns.
 - IEEE `-0` is canonicalized to `+0` on bind, affinity, and arithmetic. Keep determinism invariants (see README).
 

package/dist/executor/env.d.ts

@@ -49,6 +49,10 @@ export declare class ExecutionEnv {
     triggerScope: ScopeRow | null;
     /** Cap SELECT output rows (used by Statement.get). */
     maxRows: number;
+    /** When true, skip simple-select / simple-join fast paths (tests only). */
+    forceFullSelect: boolean;
+    /** When true, skip tryFastInsert (tests only). */
+    forceFullInsert: boolean;
     includeNamedRows: boolean;
     includeValues: boolean;
     /** Source text of the statement currently executing (for sqlite_master.sql). */

package/dist/index.js

@@ -2765,6 +2765,7 @@ var IndexStore = class _IndexStore {
   entries;
   keyValues;
   sortedKeys;
+  mapsShared = false;
   frozen = false;
   constructor(name = "index", entries, keyValues) {
     this.name = name;
@@ -2818,10 +2819,22 @@ var IndexStore = class _IndexStore {
     if (values.some((value) => value === null)) return [];
     const prefix = serializeIndexEntry(values);
     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);
+    const keys = this.orderedKeys();
+    let start = 0;
+    let end = keys.length;
+    while (start < end) {
+      const mid = start + end >>> 1;
+      const kv = this.keyValues.get(keys[mid]);
+      if (!kv || prefixKeyLess(kv, values)) start = mid + 1;
+      else end = mid;
+    }
+    for (let i = start; i < keys.length; i++) {
+      const kv = this.keyValues.get(keys[i]);
+      if (!kv || !prefixKeyMatches(kv, values)) break;
+      const key = keys[i];
+      if (key === prefix) continue;
+      rowids.push(...this.entries.get(key) ?? []);
     }
     return rowids;
   }
@@ -2830,9 +2843,12 @@ var IndexStore = class _IndexStore {
    * `op` applies to the first key component.
    */
   rangeLookup(op, bound, bound2) {
-    const rowids = [];
     const keys = this.orderedKeys();
-    for (const key of keys) {
+    const rowids = [];
+    const start = lowerBoundKeyValues(keys, this.keyValues, bound, op === ">" ? "gt" : op === ">=" ? "ge" : "any");
+    const end = op === "<" || op === "<=" ? upperBoundKeyValues(keys, this.keyValues, bound, op === "<" ? "lt" : "le") : op === "between" && bound2 !== void 0 ? upperBoundKeyValues(keys, this.keyValues, bound2, "le") : keys.length;
+    for (let i = start; i < end; i++) {
+      const key = keys[i];
       const values = this.keyValues.get(key);
       if (!values || values[0] === void 0 || values[0] === null) continue;
       const cmp = compareSerializedOrder(values[0], bound);
@@ -2889,7 +2905,12 @@ var IndexStore = class _IndexStore {
     this.sortedKeys = null;
   }
   clone() {
-    return new _IndexStore(this.name, this.entries, this.keyValues);
+    const copy = new _IndexStore(this.name);
+    copy.entries = this.entries;
+    copy.keyValues = this.keyValues;
+    copy.sortedKeys = this.sortedKeys;
+    copy.mapsShared = true;
+    return copy;
   }
   freeze() {
     this.frozen = true;
@@ -2945,6 +2966,18 @@ var IndexStore = class _IndexStore {
   }
   assertMutable() {
     if (this.frozen) throw new SqliteError("internal: cannot mutate a frozen index", "other");
+    this.forkMaps();
+  }
+  forkMaps() {
+    if (!this.mapsShared) return;
+    const entries = /* @__PURE__ */ new Map();
+    for (const [key, rowids] of this.entries) entries.set(key, [...rowids]);
+    const keyValues = /* @__PURE__ */ new Map();
+    for (const [key, values] of this.keyValues) keyValues.set(key, [...values]);
+    this.entries = entries;
+    this.keyValues = keyValues;
+    this.mapsShared = false;
+    this.sortedKeys = null;
   }
 };
 function serializeIndexKey(values) {
@@ -2983,6 +3016,53 @@ function serializeValue(value) {
 function compareSerializedOrder(left, right) {
   return compareSql(left, right) ?? 0;
 }
+function prefixKeyLess(keyValues, prefix) {
+  for (let i = 0; i < prefix.length; i++) {
+    const cmp = compareSerializedOrder(keyValues[i] ?? null, prefix[i]);
+    if (cmp !== 0) return cmp < 0;
+  }
+  return false;
+}
+function prefixKeyMatches(keyValues, prefix) {
+  for (let i = 0; i < prefix.length; i++) {
+    if (compareSerializedOrder(keyValues[i] ?? null, prefix[i]) !== 0) return false;
+  }
+  return true;
+}
+function lowerBoundKeyValues(keys, keyValues, bound, mode) {
+  let lo = 0;
+  let hi = keys.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    const value = keyValues.get(keys[mid])?.[0];
+    if (value === void 0 || value === null) {
+      lo = mid + 1;
+      continue;
+    }
+    const cmp = compareSerializedOrder(value, bound);
+    const before = mode === "gt" ? cmp <= 0 : mode === "ge" ? cmp < 0 : false;
+    if (before) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+function upperBoundKeyValues(keys, keyValues, bound, mode) {
+  let lo = 0;
+  let hi = keys.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    const value = keyValues.get(keys[mid])?.[0];
+    if (value === void 0 || value === null) {
+      lo = mid + 1;
+      continue;
+    }
+    const cmp = compareSerializedOrder(value, bound);
+    const after = mode === "lt" ? cmp >= 0 : cmp > 0;
+    if (after) hi = mid;
+    else lo = mid + 1;
+  }
+  return lo;
+}
 function sameRowid(left, right) {
   return typeof left === "bigint" || typeof right === "bigint" ? BigInt(left) === BigInt(right) : left === right;
 }
@@ -3366,6 +3446,9 @@ function parseFts5Query(input) {
     }
     if (p.kind === "TERM") {
       next();
+      if (p.prefix && (p.value === "" || p.value.includes("*"))) {
+        throw new SqliteError(`unknown special query: ${p.value}`, "other");
+      }
       return { type: "term", value: p.value, prefix: p.prefix, column: null, columns: null };
     }
     throw new SqliteError(`fts5: syntax error near "${displayTok(p)}"`, "syntax");
@@ -3532,17 +3615,7 @@ function displayTok(t) {
   }
 }
 function parseFts3Query(input) {
-  try {
-    return parseFts5Query(input);
-  } catch {
-    const terms = input.split(/\s+/).filter(Boolean).filter((t) => !/^(AND|OR|NOT|NEAR)$/i.test(t));
-    if (terms.length === 0) return { type: "true" };
-    const nodes = terms.map((t) => {
-      const prefix = t.endsWith("*");
-      return { type: "term", value: prefix ? t.slice(0, -1) : t, prefix, column: null, columns: null };
-    });
-    return nodes.length === 1 ? nodes[0] : { type: "and", children: nodes };
-  }
+  return parseFts5Query(input);
 }
 
 // src/vtable/fts/porter.ts
@@ -4593,6 +4666,26 @@ var FtsVocabVirtualTable = class _FtsVocabVirtualTable {
   }
 };
 
+// src/runtime/assert.ts
+function assert(condition, message) {
+  if (!condition) {
+    throw new SqliteError(`internal assertion failed: ${message}`, "other");
+  }
+}
+function assertUnreachable(value, message = "unreachable") {
+  throw new SqliteError(`internal assertion failed: ${message} (${String(value)})`, "other");
+}
+function assertRowShape(table, row) {
+  assert(row.values.length === table.columns.length, `row.values.length !== table.columns.length for ${table.name}`);
+}
+var SQLITE_MAX_LENGTH = 2147483647;
+function assertBlobLength(length, _feature) {
+  if (!Number.isFinite(length) || length < 0) return;
+  if (length >= SQLITE_MAX_LENGTH) {
+    throw new SqliteError(`string or blob too big`, "other", "SQLITE_TOOBIG");
+  }
+}
+
 // src/types/collation.ts
 function normalizeForCollation(value, name) {
   const collation = builtinCollation(name);
@@ -4769,6 +4862,7 @@ var Table = class _Table {
     this.scanCache = null;
   }
   commitRow(row) {
+    assertRowShape(this, row);
     this.indexEquality(row);
     this.invalidateScan();
   }
@@ -4991,16 +5085,11 @@ var Table = class _Table {
     copy.nextRowid = this.nextRowid;
     copy.maximumRowid = this.maximumRowid;
     if (this.slab) {
-      let max = null;
-      for (const row of this.slab.scan()) {
-        copy.rows.set(row.rowid, cloneRow(row));
-        if (max === null || compareRowids(row.rowid, max) > 0) max = row.rowid;
-      }
-      copy.maximumRowid = max ?? void 0;
+      for (const row of this.slab.scan()) copy.rows.set(row.rowid, row);
     } else {
-      for (const [rowid, row] of this.rows) copy.rows.set(rowid, cloneRow(row));
+      for (const [rowid, row] of this.rows) copy.rows.set(rowid, row);
     }
-    for (const [clusterKey, row] of this.clusteredRows) copy.clusteredRows.set(clusterKey, cloneRow(row));
+    for (const [clusterKey, row] of this.clusteredRows) copy.clusteredRows.set(clusterKey, row);
     return copy;
   }
   freeze() {
@@ -9297,6 +9386,7 @@ var scalarFunctions = {
     requireArgs3("randomblob", args, 1);
     if (args[0] === null) return null;
     const length = Math.max(0, Math.trunc(numeric(args[0])));
+    assertBlobLength(length, "randomblob");
     const out = new Uint8Array(length);
     let offset = 0;
     while (offset < length) {
@@ -9311,6 +9401,7 @@ var scalarFunctions = {
     requireArgs3("zeroblob", args, 1);
     if (args[0] === null) return null;
     const length = Math.max(0, Math.trunc(numeric(args[0])));
+    assertBlobLength(length, "zeroblob");
     return new Uint8Array(length);
   },
   hex(args) {
@@ -9676,6 +9767,10 @@ var ExecutionEnv = class {
   triggerScope = null;
   /** Cap SELECT output rows (used by Statement.get). */
   maxRows = Number.POSITIVE_INFINITY;
+  /** When true, skip simple-select / simple-join fast paths (tests only). */
+  forceFullSelect = false;
+  /** When true, skip tryFastInsert (tests only). */
+  forceFullInsert = false;
   includeNamedRows = true;
   includeValues = true;
   /** Source text of the statement currently executing (for sqlite_master.sql). */
@@ -9696,6 +9791,8 @@ var ExecutionEnv = class {
     this.triggerDepth = 0;
     this.triggerScope = null;
     this.maxRows = Number.POSITIVE_INFINITY;
+    this.forceFullSelect = false;
+    this.forceFullInsert = false;
     this.includeNamedRows = true;
     this.includeValues = true;
     this.statementSql = null;
@@ -9987,10 +10084,19 @@ function evalBinary(op, leftExpr, rightExpr, ctx) {
   if (left === null || right === null) return null;
   switch (op) {
     case "+":
+      if (storageClassOf(left) === "integer" && storageClassOf(right) === "integer") {
+        return integerArithmetic("+", left, right);
+      }
       return asNumber(numberValue(left) + numberValue(right));
     case "-":
+      if (storageClassOf(left) === "integer" && storageClassOf(right) === "integer") {
+        return integerArithmetic("-", left, right);
+      }
       return asNumber(numberValue(left) - numberValue(right));
     case "*":
+      if (storageClassOf(left) === "integer" && storageClassOf(right) === "integer") {
+        return integerArithmetic("*", left, right);
+      }
       return asNumber(numberValue(left) * numberValue(right));
     case "/": {
       const divisor = numberValue(right);
@@ -10027,6 +10133,17 @@ function evalBinary(op, leftExpr, rightExpr, ctx) {
 function safeIntegerResult(value) {
   return value <= BigInt(Number.MAX_SAFE_INTEGER) && value >= BigInt(Number.MIN_SAFE_INTEGER) ? Number(value) : value;
 }
+var I64_MIN = -(2n ** 63n);
+var I64_MAX = 2n ** 63n - 1n;
+function integerArithmetic(op, left, right) {
+  const a = integerValue(left);
+  const b = integerValue(right);
+  const result = op === "+" ? a + b : op === "-" ? a - b : a * b;
+  if (result < I64_MIN || result > I64_MAX) {
+    return asSqlReal(Number(result));
+  }
+  return safeIntegerResult(result);
+}
 function compareRowValues(op, leftExprs, rightExprs, ctx) {
   if (leftExprs.length !== rightExprs.length) {
     throw new SqliteError("row value misused", "misuse");
@@ -11255,6 +11372,11 @@ function valuesEqual(left, right) {
   return false;
 }
 
+// src/runtime/catch.ts
+function isExpectedFastPathMiss(error, categories = ["no_such_table"]) {
+  return error instanceof SqliteError && categories.includes(error.category);
+}
+
 // src/planner/access.ts
 function conjunctions(expr) {
   if (expr.type === "binary" && expr.op === "AND") {
@@ -11318,7 +11440,8 @@ function lookupTableRows(from, where, env) {
   let table;
   try {
     table = db.getTable(from.name);
-  } catch {
+  } catch (error) {
+    if (!isExpectedFastPathMiss(error)) throw error;
     return null;
   }
   const parts = conjunctions(where);
@@ -11326,8 +11449,9 @@ function lookupTableRows(from, where, env) {
   const evalConst = (expr) => {
     try {
       return evalExpr(expr, env.createEvalContext(null));
-    } catch {
-      return void 0;
+    } catch (error) {
+      if (error instanceof SqliteError) return void 0;
+      throw error;
     }
   };
   const resolved = [];
@@ -11474,7 +11598,8 @@ function tryIndexedOrder(from, order, env, limit) {
   let table;
   try {
     table = db.getTable(from.name);
-  } catch {
+  } catch (error) {
+    if (!isExpectedFastPathMiss(error)) throw error;
     return null;
   }
   const col = order.expr.name.toLowerCase();
@@ -11708,7 +11833,8 @@ function buildSqliteMaster(state) {
 function tryExecuteSimpleSelect(stmt, env) {
   if (stmt.with || stmt.compound || stmt.distinct || stmt.groupBy.length > 0 || stmt.having || stmt.windows.length > 0)
     return null;
-  if (stmt.orderBy.length > 0) return null;
+  if (stmt.orderBy.length > 1) return null;
+  if (stmt.orderBy.length === 1 && stmt.where) return null;
   if (stmt.from?.type !== "table") return null;
   for (const column of stmt.columns) {
     if (column.type === "star") continue;
@@ -11724,7 +11850,8 @@ function tryExecuteSimpleSelect(stmt, env) {
   let table;
   try {
     table = db.getTable(from.name);
-  } catch {
+  } catch (error) {
+    if (!isExpectedFastPathMiss(error)) throw error;
     return null;
   }
   if (table.withoutRowid) return null;
@@ -11749,8 +11876,9 @@ function tryExecuteSimpleSelect(stmt, env) {
       let value;
       try {
         value = evalIndependent(eq.valueExpr, env);
-      } catch {
-        return null;
+      } catch (error) {
+        if (error instanceof SqliteError) return null;
+        throw error;
       }
       const column = eq.column.toLowerCase();
       const affinity = isRowidName2(column) ? "INTEGER" : table.columns.find((item) => (item.nameLower ?? item.name.toLowerCase()) === column)?.affinity;
@@ -11767,19 +11895,26 @@ function tryExecuteSimpleSelect(stmt, env) {
       offset = Math.max(0, Number(offsetValue));
       const n = Number(limitValue);
       if (n >= 0) limit = Math.min(limit, n);
-    } catch {
-      return null;
+    } catch (error) {
+      if (error instanceof SqliteError) return null;
+      throw error;
     }
   }
   const columns = projectNames(stmt.columns, table);
   if (limit <= 0) return pack(env, columns, []);
   let source = table.scan();
   let alreadyFiltered = false;
-  if (stmt.where) {
+  if (stmt.orderBy.length === 1 && stmt.orderBy[0]) {
+    const take = limit < Number.MAX_SAFE_INTEGER ? offset + limit : void 0;
+    const ordered = tryIndexedOrder(from, { expr: stmt.orderBy[0].expr, dir: stmt.orderBy[0].dir ?? "ASC" }, env, take);
+    if (!ordered) return null;
+    source = ordered.rows;
+    alreadyFiltered = true;
+  } else if (stmt.where) {
     const indexed = lookupTableRows(from, stmt.where, env);
     if (indexed) {
       source = indexed.rows;
-      alreadyFiltered = true;
+      alreadyFiltered = whereFullyCovered(stmt.where, indexed.coveredColumns, alias, table.name);
     }
   }
   const projectors = projectionFns(stmt.columns, table);
@@ -11825,7 +11960,8 @@ function tryExecuteSimpleJoin(stmt, env) {
   try {
     leftTable = leftDb.getTable(leftRef.name);
     rightTable = rightDb.getTable(rightRef.name);
-  } catch {
+  } catch (error) {
+    if (!isExpectedFastPathMiss(error)) throw error;
     return null;
   }
   if (leftTable.withoutRowid || rightTable.withoutRowid) return null;
@@ -11910,7 +12046,7 @@ function evalIndependent(expr, env) {
   if (expr.type === "null") return null;
   if (expr.type === "parameter") return env.getBoundParameter(expr.name);
   if (expr.type === "unary" && expr.op === "-" && expr.expr.type === "literal" && typeof expr.expr.value === "number") {
-    return -expr.expr.value;
+    return canonicalizeNumber(-expr.expr.value);
   }
   throw new Error("not independent");
 }
@@ -11930,7 +12066,7 @@ function applyAffinityLocal(value, affinity) {
 }
 function executeSelect2(stmt, env, parent) {
   env.selectRunner = executeSelect2;
-  if (!parent && !stmt.with && !stmt.compound) {
+  if (!parent && !stmt.with && !stmt.compound && !env.forceFullSelect) {
     const simple = tryExecuteSimpleSelect(stmt, env) ?? tryExecuteSimpleJoin(stmt, env);
     if (simple) return simple;
   }
@@ -13524,7 +13660,7 @@ function executeInsertCore(stmt, env) {
   const totalBefore = env.state.totalChanges;
   const view = writableView(stmt.table, "INSERT", env);
   if (view) return executeViewInsert(stmt, view, env, totalBefore);
-  const fast = tryFastInsert(stmt, env);
+  const fast = env.forceFullInsert ? null : tryFastInsert(stmt, env);
   if (fast) return fast;
   let table = env.state.getWritableTable(stmt.table);
   const columnNames = stmt.columns ?? table.columns.map((column) => column.name);
@@ -13727,7 +13863,8 @@ function tryFastInsert(stmt, env) {
   let table;
   try {
     table = env.state.getWritableTable(plan.tableName);
-  } catch {
+  } catch (error) {
+    if (!isExpectedFastPathMiss(error)) throw error;
     return null;
   }
   if (env.state.databaseForTable(table).triggers.size > 0) return null;
@@ -13742,7 +13879,8 @@ function buildFastInsertPlan(stmt, env) {
   let table;
   try {
     table = env.state.getTable(stmt.table);
-  } catch {
+  } catch (error) {
+    if (!isExpectedFastPathMiss(error)) throw error;
     return null;
   }
   if (!table.isUnconstrained()) return null;
@@ -14330,16 +14468,91 @@ function assertForeignKeyValues(values, constraint, env, excludeParent) {
   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) => {
-    if (excludeParent && candidate.rowid === excludeParent.rowid) return false;
-    return values.every((value, index) => {
-      const parentColumn = parentColumns[index];
-      return parentColumn !== void 0 && compareSql(value, parent.cell(candidate, normalizeColumnName(parentColumn))) === 0;
-    });
-  })) {
+  if (findParentRowsForFk(parent, parentColumns, values, env, excludeParent).length === 0) {
     throw new SqliteError("FOREIGN KEY constraint failed", "constraint_foreign", "SQLITE_CONSTRAINT_FOREIGNKEY");
   }
 }
+function parentRowMatchesFk(parent, parentColumns, values, excludeParent, candidate) {
+  if (excludeParent && candidate.rowid === excludeParent.rowid) return false;
+  return values.every((value, index) => {
+    const parentColumn = parentColumns[index];
+    return parentColumn !== void 0 && compareSql(value, parent.cell(candidate, normalizeColumnName(parentColumn))) === 0;
+  });
+}
+function findParentRowsForFk(parent, parentColumns, values, env, excludeParent) {
+  const db = env.state.databaseForTable(parent);
+  const pk = parent.integerPkColumn();
+  if (parentColumns.length === 1) {
+    const col = parentColumns[0].toLowerCase();
+    if (col === "rowid" || col === "_rowid_" || col === "oid" || pk && col === (pk.nameLower ?? pk.name.toLowerCase())) {
+      const row = parent.getByKey(values[0]);
+      if (row && parentRowMatchesFk(parent, parentColumns, values, excludeParent, row)) return [row];
+      return [];
+    }
+  }
+  const normalizedValues = values.map((value, index) => {
+    const colName = parentColumns[index];
+    const column = parent.columns.find((item) => (item.nameLower ?? item.name.toLowerCase()) === colName.toLowerCase());
+    return normalizeForCollation(value, column?.collate ?? "BINARY");
+  });
+  for (const indexName of parent.indexes) {
+    const index = db.indexes.get(indexName.toLowerCase());
+    if (!index?.unique || index.where || index.columns.some((column) => column.expr)) continue;
+    if (index.columns.length !== parentColumns.length) continue;
+    if (!index.columns.every((column, idx) => column.name.toLowerCase() === parentColumns[idx].toLowerCase()))
+      continue;
+    const rows = [];
+    for (const rowid of index.store.lookup(normalizedValues)) {
+      const candidate = parent.get(rowid);
+      if (candidate && parentRowMatchesFk(parent, parentColumns, values, excludeParent, candidate))
+        rows.push(candidate);
+    }
+    return rows;
+  }
+  return [...parent.scan()].filter(
+    (candidate) => parentRowMatchesFk(parent, parentColumns, values, excludeParent, candidate)
+  );
+}
+function findChildRowsForFk(child, childColumns, parentColumns, parent, parentRow, env) {
+  const refValues = parentColumns.map((name) => parent.cell(parentRow, normalizeColumnName(name)));
+  if (refValues.some((value) => value === null)) return [];
+  if (childColumns.length === 1) {
+    const col = childColumns[0].toLowerCase();
+    const matches = child.lookupEquality(col, refValues[0]);
+    if (matches) {
+      return matches.filter(
+        (candidate) => foreignKeyMatches(childColumns, candidate, parentColumns, parentRow, child, parent)
+      );
+    }
+  }
+  const db = env.state.databaseForTable(child);
+  const normalizedValues = refValues.map((value, index) => {
+    const colName = childColumns[index];
+    const column = child.columns.find((item) => (item.nameLower ?? item.name.toLowerCase()) === colName.toLowerCase());
+    return normalizeForCollation(value, column?.collate ?? "BINARY");
+  });
+  for (const indexName of child.indexes) {
+    const index = db.indexes.get(indexName.toLowerCase());
+    if (!index || index.where || index.columns.some((column) => column.expr)) continue;
+    if (index.columns.length < childColumns.length) continue;
+    if (!childColumns.every((name, idx) => index.columns[idx]?.name.toLowerCase() === name.toLowerCase())) {
+      continue;
+    }
+    const lookupValues = normalizedValues.slice(0, index.columns.length);
+    const rowids = lookupValues.length === index.columns.length ? index.store.lookup(lookupValues) : index.store.lookupPrefix(lookupValues);
+    const rows = [];
+    for (const rowid of rowids) {
+      const candidate = child.get(rowid);
+      if (candidate && foreignKeyMatches(childColumns, candidate, parentColumns, parentRow, child, parent)) {
+        rows.push(candidate);
+      }
+    }
+    return rows;
+  }
+  return [...child.scan()].filter(
+    (candidate) => foreignKeyMatches(childColumns, candidate, parentColumns, parentRow, child, parent)
+  );
+}
 function checkDeferredForeignKeys(env) {
   if (!env.state.foreignKeysEnabled) return;
   for (const table of env.state.tables.values()) {
@@ -14362,8 +14575,8 @@ function applyReferentialDelete(parent, row, env) {
       child = env.state.ensureWritableTable(child);
       const target = child;
       const referenced = constraint.refColumns ?? parentPk;
-      const matches = [...target.scan()].filter(
-        (candidate) => !(target === parent && candidate.rowid === row.rowid) && foreignKeyMatches(constraint.columns, candidate, referenced, row, target, parent)
+      const matches = findChildRowsForFk(target, constraint.columns, referenced, parent, row, env).filter(
+        (candidate) => !(target === parent && candidate.rowid === row.rowid)
       );
       for (const candidate of matches) {
         if (constraint.onDelete === "CASCADE") {
@@ -14409,9 +14622,7 @@ function applyReferentialUpdate(parent, before, after, env) {
       const oldValues = referenced.map((name) => parent.cell(before, normalizeColumnName(name)));
       const newValues = referenced.map((name) => parent.cell(after, normalizeColumnName(name)));
       if (oldValues.every((value, index) => compareSql(value, newValues[index] ?? null) === 0)) continue;
-      const matches = [...target.scan()].filter(
-        (candidate) => foreignKeyMatches(constraint.columns, candidate, referenced, before, target, parent)
-      );
+      const matches = findChildRowsForFk(target, constraint.columns, referenced, parent, before, env);
       for (const candidate of matches) {
         if (constraint.onUpdate === "CASCADE") {
           const updated = updateOne(
@@ -14801,6 +15012,8 @@ function executeStatement(stmt, env) {
     case "vacuum":
       env.state.recordChange(0);
       return emptyResult(0, env.state.lastInsertRowid);
+    default:
+      return assertUnreachable(stmt);
   }
 }
 function executeReindex(stmt, env) {