@orkestrel/database 0.0.12 → 0.0.14

package/dist/src/server/index.js

@@ -1,26 +1,26 @@
-import { DatabaseError, MemoryDriver, applyQuery, bindRowKey, checkAbort, cloneDriverMetadata, cloneMigrationInput, computeAggregate, equalsValue, extractKey, filterRows, isDatabaseError, isKey, matchesQuery, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, validatePage } from "../core/index.js";
+import { DatabaseError, DriverIterator, MemoryDriver, applyQuery, bindRowKey, checkAbort, cloneDriverMetadata, cloneMigrationInput, computeAggregate, equalsValue, extractKey, filterRows, findColumn, isDatabaseError, isKey, matchesQuery, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, validatePage } from "../core/index.js";
 import { cloneJSONValue, isBoolean, isFiniteNumber, isRecord, isString } from "@orkestrel/contract";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { createSQLiteDatabase, isSQLiteError } from "@orkestrel/sqlite";
 //#region src/server/constants.ts
 /**
-* The declared {@link ColumnStorage}s whose SQL EQUALITY comparisons (`equals` /
+* Lists the declared {@link ColumnStorage}s whose SQL equality comparisons (`equals` /
 * `not` / `any` / `none`) and `starts` / `ends` compiles are provably
 * engine-exact under declared-type trust — `text` / `integer` / `real` /
 * `boolean`; a `json` or `blob` column always refines instead.
 *
 * @remarks
-* This set governs equality and prefix/suffix matching only. RANGE
+* This set governs equality and prefix/suffix matching only. Range
 * comparisons (`above` / `below` / `from` / `to` / `between`) and `ORDER BY`
-* are exact for `integer` / `real` / `boolean` but NOT for `text`: compiled
+* are exact for `integer` / `real` / `boolean` but not for `text`: compiled
 * SQL orders/ranges under SQLite's default BINARY collation, which compares
-* TEXT byte-for-byte as UTF-8 — equivalent to Unicode CODE-POINT order —
+* TEXT byte-for-byte as UTF-8 — equivalent to Unicode code-point order —
 * while the core engine's `compareValues` orders JS strings with `<`, which
-* compares UTF-16 CODE-UNIT order. The two orders diverge for supplementary-
-* plane characters (code points ≥ U+10000, e.g. many emoji): a lead surrogate
-* (`\uD800`–`\uDBFF`) sorts BELOW ``–`￿` in code-unit order, while
-* its code point sorts ABOVE them. So `matchesConditionExactly`'s range family and
+* compares UTF-16 code-unit order. The two orders diverge for supplementary-
+* plane characters (code points ≥ U+10000, for example many emoji): a lead surrogate
+* (`\uD800`–`\uDBFF`) sorts below ``–`￿` in code-unit order, while
+* its code point sorts above them. So `matchesConditionExactly`'s range family and
 * `matchesOrderExactly` exclude `text`, refining through the core engine instead.
 */
 var EXACT_COLUMN_STORAGE = Object.freeze([
@@ -30,7 +30,7 @@ var EXACT_COLUMN_STORAGE = Object.freeze([
 	"boolean"
 ]);
 /**
-* The declared {@link ColumnStorage}s whose SQL RANGE comparisons
+* Lists the declared {@link ColumnStorage}s whose SQL range comparisons
 * (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are
 * provably engine-exact — `integer` / `real` / `boolean` only. `text` is
 * excluded: see {@link EXACT_COLUMN_STORAGE}'s remarks for the BINARY-collation
@@ -43,7 +43,7 @@ var EXACT_RANGE_COLUMN_STORAGE = Object.freeze([
 	"boolean"
 ]);
 /**
-* The reserved metadata table the {@link SQLiteDriver} creates on `open` to
+* Names the reserved metadata table the {@link SQLiteDriver} creates on `open` to
 * persist its stamped `DriverMetadata` (`version` + declared schema JSON) — the
 * SQLite realization of the `metadata` / `stamp` driver hooks.
 *
@@ -55,7 +55,7 @@ var METADATA_TABLE = "_metadata";
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Whether a caught filesystem error reports that nothing is there to read.
+* Reports whether a caught filesystem error says that nothing is there to read.
 *
 * @remarks
 * Two codes carry that meaning: `ENOENT` is a plain absence, and `ENOTDIR` is a
@@ -72,7 +72,7 @@ var METADATA_TABLE = "_metadata";
 * answers `false` rather than being read for a `code` any object could carry.
 *
 * @param error - The caught value to classify; any runtime is accepted
-* @returns `true` when the error reports that the path holds nothing
+* @returns True if the error reports that the path holds nothing; false otherwise
 *
 * @example
 * ```ts
@@ -86,21 +86,21 @@ function matchesAbsentPath(error) {
 	return error.code === "ENOENT" || error.code === "ENOTDIR";
 }
 /**
-* Whether a value's runtime type matches a column's declared exact type —
-* the operand side of the declared-type-trust proof.
+* Reports whether a value's runtime type matches a column's declared exact type
+* — the operand side of the declared-type-trust proof.
 *
 * @remarks
-* `text` ↔ string, `integer` / `real` ↔ FINITE number (`NaN` / `±Infinity`
+* `text` ↔ string, `integer` / `real` ↔ finite number (`NaN` / `±Infinity`
 * fail), `boolean` ↔ boolean. Backs {@link matchesConditionExactly}'s operand checks.
 *
 * @param value - The condition operand to test
-* @param type - The column's declared portable type
-* @returns `true` when the operand's runtime type matches the declared type
+* @param storage - The column's declared portable storage type
+* @returns True if the operand's runtime type matches the declared type; false otherwise
 *
 * @example
 * ```ts
-* matchesDeclaredType('Ada', 'text') // true
-* matchesDeclaredType(Number.NaN, 'integer') // false — only finite numbers
+* matchesDeclaredStorage('Ada', 'text') // true
+* matchesDeclaredStorage(Number.NaN, 'integer') // false — only finite numbers
 * ```
 */
 function matchesDeclaredStorage(value, storage) {
@@ -109,9 +109,9 @@ function matchesDeclaredStorage(value, storage) {
 	return isFiniteNumber(value);
 }
 /**
-* Whether one {@link Condition} compiles to SQL that is PROVABLY identical to
-* the core engine's `matchesCondition` for every value its column's declared
-* type can store.
+* Reports whether one {@link Condition} compiles to SQL that is provably
+* identical to the core engine's `matchesCondition` for every value its
+* column's declared type can store.
 *
 * @remarks
 * `false` for a nested `FieldPath` (an array) or a column absent from `schema`.
@@ -123,32 +123,32 @@ function matchesDeclaredStorage(value, storage) {
 * Required non-null `equals` / `not` require an operand matching the declared
 * storage and exclude `json` / `blob`. `above` / `below` / `from` / `to` /
 * `between` are exact only for {@link EXACT_RANGE_COLUMN_STORAGE} (`integer` /
-* `real` / `boolean`) — a `text` column's range conditions REFINE, because
-* SQLite's default BINARY collation orders TEXT by Unicode CODE POINT while
-* the core engine's `compareValues` orders JS strings by UTF-16 CODE UNIT,
+* `real` / `boolean`) — a `text` column's range conditions refine, because
+* SQLite's default BINARY collation orders TEXT by Unicode code point while
+* the core engine's `compareValues` orders JS strings by UTF-16 code unit,
 * and the two diverge for supplementary-plane characters (see
 * {@link EXACT_COLUMN_STORAGE}'s remarks for the full rationale).
-* `any` / `none` require a NON-EMPTY list where every element matches (an empty
+* `any` / `none` require a non-empty list where every element matches (an empty
 * list is exact under neither: the engine's `any([])` matches nothing while
 * `none([])` matches everything, and SQL `IN ()` is a syntax error) — these
 * stay exact on `text` (byte equality is collation-independent and engine-
 * identical). `starts` / `ends` are exact only on a `text` column with a
 * string operand (case-sensitive `substr` compile, see {@link compileConditionSQL}) —
-* likewise collation-independent. `like` / `glob` are NEVER exact — SQLite
+* likewise collation-independent. `like` / `glob` are never exact — SQLite
 * `LIKE` folds case ASCII-only against the engine's Unicode fold, and `GLOB`
 * has character classes the engine treats literally.
 *
 * @param condition - The condition to test
 * @param schema - The table's schema
-* @returns Whether `condition` is exact
+* @returns True if `condition` is exact; false otherwise
 */
 function matchesConditionExactly(condition, schema) {
 	if (!isString(condition.column)) return false;
-	const column = schema.columns.find((candidate) => candidate.name === condition.column);
+	const column = findColumn(condition.column, schema);
 	if (column === void 0) return false;
 	if (condition.operator === "absent" || condition.operator === "present") return !(column.optional && column.nullable);
 	if (column.optional || column.nullable) return false;
-	if (!EXACT_COLUMN_STORAGE.some((storage) => storage === column.storage)) return false;
+	if (!EXACT_COLUMN_STORAGE.includes(column.storage)) return false;
 	const first = condition.values[0];
 	const second = condition.values[1];
 	switch (condition.operator) {
@@ -157,8 +157,8 @@ function matchesConditionExactly(condition, schema) {
 		case "above":
 		case "below":
 		case "from":
-		case "to": return EXACT_RANGE_COLUMN_STORAGE.some((storage) => storage === column.storage) && matchesDeclaredStorage(first, column.storage);
-		case "between": return EXACT_RANGE_COLUMN_STORAGE.some((storage) => storage === column.storage) && matchesDeclaredStorage(first, column.storage) && matchesDeclaredStorage(second, column.storage);
+		case "to": return EXACT_RANGE_COLUMN_STORAGE.includes(column.storage) && matchesDeclaredStorage(first, column.storage);
+		case "between": return EXACT_RANGE_COLUMN_STORAGE.includes(column.storage) && matchesDeclaredStorage(first, column.storage) && matchesDeclaredStorage(second, column.storage);
 		case "any":
 		case "none": return condition.values.length > 0 && condition.values.every((value) => matchesDeclaredStorage(value, column.storage));
 		case "starts":
@@ -168,36 +168,43 @@ function matchesConditionExactly(condition, schema) {
 	}
 }
 /**
-* Whether one {@link Order} term's column compiles to an `ORDER BY` that
-* matches the engine's {@link import('@src/core').sortRows} exactly.
+* Reports whether one {@link Order} term's column compiles to an `ORDER BY`
+* that matches the engine's {@link import('@src/core').sortRows} exactly.
 *
 * @remarks
 * `false` for a nested `FieldPath`, a column absent from `schema`, or a
 * declared type outside {@link EXACT_RANGE_COLUMN_STORAGE} (`integer` / `real` /
-* `boolean`). `text` is NOT exact here: SQLite's default BINARY collation
+* `boolean`). `text` is not exact here: SQLite's default BINARY collation
 * orders TEXT by Unicode code point while the core engine's `compareValues`
 * orders JS strings by UTF-16 code unit, and the two diverge for
 * supplementary-plane characters (see {@link EXACT_COLUMN_STORAGE}'s remarks) —
-* a `text` order term REFINES through the core engine instead.
+* a `text` order term refines through the core engine instead. The column must
+* also be required and non-null: an optional or nullable column refines, because
+* SQL orders its `NULL`s ahead of every value while the core total order ranks
+* `undefined` before `null` before every other value.
 *
 * @param order - The order term to test
 * @param schema - The table's schema
-* @returns Whether `order` is exact
+* @returns True if `order` is exact; false otherwise
 */
 function matchesOrderExactly(order, schema) {
 	if (!isString(order.column)) return false;
-	const column = schema.columns.find((candidate) => candidate.name === order.column);
+	const column = findColumn(order.column, schema);
 	if (column === void 0) return false;
-	return !column.optional && !column.nullable && EXACT_RANGE_COLUMN_STORAGE.some((storage) => storage === column.storage);
+	return !column.optional && !column.nullable && EXACT_RANGE_COLUMN_STORAGE.includes(column.storage);
 }
 /**
-* Whether a whole {@link QueryInput} is exact — every condition and every order
-* term is exact. `limit` / `offset` never affect exactness (SQL `LIMIT` /
-* `OFFSET` are always engine-identical).
+* Reports whether a whole {@link QueryInput} is exact — every condition and
+* every order term is exact. `limit` / `offset` never affect exactness (SQL
+* `LIMIT` / `OFFSET` are always engine-identical).
+*
+* @remarks
+* The gate {@link import('./drivers/SQLiteDriver.js').SQLiteDriver} checks before
+* trusting a native SQL read over a full-scan refine through the core engine.
 *
 * @param input - The query input to test
 * @param schema - The table's schema
-* @returns Whether every part of `input` is exact
+* @returns True if every part of `input` is exact; false otherwise
 */
 function matchesQueryExactly(input, schema) {
 	const conditions = input.conditions ?? [];
@@ -205,25 +212,25 @@ function matchesQueryExactly(input, schema) {
 	return conditions.every((condition) => matchesConditionExactly(condition, schema)) && order.every((term) => matchesOrderExactly(term, schema));
 }
 /**
-* Determine whether SQLite can execute an aggregate exactly like the core engine.
+* Reports whether SQLite can execute an aggregate exactly like the core engine.
 *
 * @param operation - Aggregate operation
 * @param column - Aggregate field
 * @param schema - Current table schema
-* @returns Whether native aggregation is exact
+* @returns True if native aggregation is exact; false otherwise
 */
 function matchesAggregateExactly(operation, column, schema) {
 	if (operation === "count") return true;
 	if (operation === "sum" || operation === "average" || !isString(column)) return false;
-	const declared = schema.columns.find((candidate) => candidate.name === column);
+	const declared = findColumn(column, schema);
 	return declared !== void 0 && (declared.storage === "integer" || declared.storage === "real") && !(declared.optional && declared.nullable);
 }
 /**
-* Test a declared SQLite type against a portable storage affinity.
+* Checks a declared SQLite type against a portable storage affinity.
 *
 * @param declared - Native declared type
 * @param storage - Portable column storage
-* @returns Whether SQLite's official affinity rules yield the expected affinity
+* @returns True if SQLite's official affinity rules yield the expected affinity; false otherwise
 */
 function matchesSQLiteAffinity(declared, storage) {
 	if (!isString(declared)) return false;
@@ -240,7 +247,7 @@ function matchesSQLiteAffinity(declared, storage) {
 	return affinity === "REAL";
 }
 /**
-* Quote a SQL identifier (a table or column name) so any characters are literal.
+* Quotes a SQL identifier (a table or column name) so any characters are literal.
 *
 * @remarks
 * Wraps the name in double quotes and doubles any embedded quote — the standard
@@ -259,7 +266,7 @@ function quoteIdentifier(identifier) {
 	return "\"" + identifier.replaceAll("\"", "\"\"") + "\"";
 }
 /**
-* Encode a JS value to its stored {@link SQLiteValue} for a declared column.
+* Encodes a JS value to its stored {@link SQLiteValue} for a declared column.
 *
 * @remarks
 * The codec is total: a malformed value encodes to SQL `NULL`. Absence always
@@ -298,7 +305,7 @@ function encodeValue(value, column) {
 	}
 }
 /**
-* Decode a stored {@link SQLiteValue} back to its JS value for a declared column —
+* Decodes a stored {@link SQLiteValue} back to its JS value for a declared column —
 * the exact inverse of {@link encodeValue}.
 *
 * @remarks
@@ -339,7 +346,7 @@ function decodeValue(value, column) {
 	}
 }
 /**
-* Encode a whole {@link Row} to a {@link SQLiteRow} by its table's schema.
+* Encodes a whole {@link Row} to a {@link SQLiteRow} by its table's schema.
 *
 * @remarks
 * Encodes each declared column's value with {@link encodeValue}; columns the row
@@ -361,7 +368,7 @@ function encodeRow(row, schema) {
 	return result;
 }
 /**
-* Extract a stored row's values in a declared positional order.
+* Extracts a stored row's values in a declared positional order.
 *
 * @remarks
 * SQLite statements bind arrays positionally. Every requested column must be
@@ -392,7 +399,7 @@ function extractValues(row, names, table) {
 	return values;
 }
 /**
-* Decode a stored {@link SQLiteRow} back to a {@link Row} by its table's schema.
+* Decodes a stored {@link SQLiteRow} back to a {@link Row} by its table's schema.
 *
 * @remarks
 * Decodes each declared column with {@link decodeValue} and **omits** any column
@@ -421,12 +428,12 @@ function decodeRow(row, schema) {
 	return result;
 }
 /**
-* Build a collision-free SQL index name for a table + column-group index —
+* Builds a collision-free SQL index name for a table + column-group index —
 * shared by the compiler module's `schemaToIndexes` and `stepToSQL`,
 * so a plan-built index name always matches one `open` would have created.
 *
 * @remarks
-* A naive `idx_<table>_<cols joined by _>` is AMBIGUOUS: table `'a_b'` with
+* A naive `idx_<table>_<cols joined by _>` is ambiguous: table `'a_b'` with
 * column `'c'` and table `'a'` with columns `['b', 'c']` both produce
 * `idx_a_b_c`. This encodes each part (the table name, then each column name)
 * length-prefixed (`<len>_<part>`) so the boundary between parts is always
@@ -447,9 +454,39 @@ function deriveSQLiteIndexName(table, columns) {
 	return "idx_" + [table, ...columns].map((part) => String(part.length) + "_" + part).join("_");
 }
 //#endregion
+//#region src/server/inferers.ts
+/**
+* Reads the storage type a nested (`json_extract`) operand encodes as from its
+* runtime value, never as `json`.
+*
+* @remarks
+* `json_extract` returns the unquoted, natively-typed scalar (a JSON boolean as
+* `1` / `0`, a number as-is, a string as-is), so the operand must encode to that
+* same scalar to compare. A boolean → `'boolean'` (→ `1` / `0`); a number →
+* `'integer'` / `'real'`; a bigint → `'integer'`; a string → `'text'`; `null` /
+* `undefined` → `'text'` (encodes to `null`); an object / array → `'json'` (the
+* edge of comparing against a json subtree).
+*
+* @param value - The runtime operand value
+* @returns The {@link ColumnStorage} to encode it as
+*
+* @example
+* ```ts
+* inferValueStorage(true) // 'boolean'
+* inferValueStorage(9) // 'integer'
+* ```
+*/
+function inferValueStorage(value) {
+	if (typeof value === "boolean") return "boolean";
+	if (typeof value === "number") return Number.isInteger(value) ? "integer" : "real";
+	if (typeof value === "bigint") return "integer";
+	if (typeof value === "object" && value !== null) return "json";
+	return "text";
+}
+//#endregion
 //#region src/server/compilers.ts
 /**
-* Map a portable {@link ColumnStorage} to its SQLite column type.
+* Maps a portable {@link ColumnStorage} to its SQLite column type.
 *
 * @param storage - The portable column type
 * @returns The SQLite column type keyword
@@ -465,7 +502,11 @@ function compileColumnSQL(storage) {
 	}
 }
 /**
-* Compile a {@link FieldPath} to the SQL expression that reads it.
+* Compiles a {@link FieldPath} to the SQL expression that reads it.
+*
+* @remarks
+* A flat path compiles to the quoted column; a nested path compiles to a
+* `json_extract` over the head column with the rest of the path as its accessor.
 *
 * @param path - The field path
 * @returns The SQL expression selecting the value
@@ -478,7 +519,7 @@ function compileFieldSQL(path) {
 	return "json_extract(" + quoteIdentifier(column) + ", '$" + rest + "')";
 }
 /**
-* Compile an {@link AggregateOperation} over a {@link FieldPath}.
+* Compiles an {@link AggregateOperation} over a {@link FieldPath}.
 *
 * @param operation - The aggregate to compute
 * @param column - The column or nested path to aggregate
@@ -494,9 +535,9 @@ function compileAggregateSQL(operation, column) {
 	}
 }
 /**
-* Compile a NESTED {@link FieldPath} to the `json_type(<col>, <path>)` SQL
+* Compiles a nested {@link FieldPath} to the `json_type(<col>, <path>)` SQL
 * expression — the {@link compileFieldSQL} `json_extract` sibling used to tell a
-* PRESENT JSON `null` apart from an ABSENT path (both read back as SQL `NULL`
+* present JSON `null` apart from an absent path (both read back as SQL `NULL`
 * through `json_extract`, but `json_type` reports `'null'` for the former and
 * SQL `NULL` for the latter).
 *
@@ -515,83 +556,25 @@ function compileJSONTypeSQL(path) {
 	return "json_type(" + quoteIdentifier(column) + ", '$" + rest + "')";
 }
 /**
-* Escape `\`, `%`, and `_` (each with a leading `\`) so a `starts` / `ends`
-* operand is matched literally under the `LIKE … ESCAPE '\'` clause.
-*
-* @param text - The raw operand text
-* @returns The text with LIKE metacharacters escaped
-*
-* @example
-* ```ts
-* escapeLike('50%_off') // '50\\%\\_off'
-* ```
-*/
-function escapeLike(text) {
-	return text.replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_");
-}
-/**
-* The declared storage type of a flat (string) column, read from the schema.
-*
-* @param column - The column name
-* @param schema - The table's schema
-* @returns The column's {@link ColumnStorage}, or `undefined` if the schema does not carry it
-*
-* @example
-* ```ts
-* findColumnStorage('age', schema) // 'integer'
-* ```
-*/
-function findColumnStorage(column, schema) {
-	return schema.columns.find((candidate) => candidate.name === column)?.storage;
-}
-/**
-* The storage type a nested (`json_extract`) operand encodes as, derived from its
-* RUNTIME value — NOT `json`.
-*
-* @remarks
-* `json_extract` returns the unquoted, natively-typed scalar (a JSON boolean as
-* `1` / `0`, a number as-is, a string as-is), so the operand must encode to that
-* same scalar to compare. A boolean → `'boolean'` (→ `1` / `0`); a number →
-* `'integer'` / `'real'`; a bigint → `'integer'`; a string → `'text'`; `null` /
-* `undefined` → `'text'` (encodes to `null`); an object / array → `'json'` (the
-* edge of comparing against a json subtree).
-*
-* @param value - The runtime operand value
-* @returns The {@link ColumnStorage} to encode it as
-*
-* @example
-* ```ts
-* inferValueStorage(true) // 'boolean'
-* inferValueStorage(9) // 'integer'
-* ```
-*/
-function inferValueStorage(value) {
-	if (typeof value === "boolean") return "boolean";
-	if (typeof value === "number") return Number.isInteger(value) ? "integer" : "real";
-	if (typeof value === "bigint") return "integer";
-	if (typeof value === "object" && value !== null) return "json";
-	return "text";
-}
-/**
-* Compile one condition to its `<column> <operator>` SQL fragment and the parameters
+* Compiles one condition to its `<column> <operator>` SQL fragment and the parameters
 * it binds — engine-exact under SQL's three-valued NULL logic.
 *
 * @remarks
 * Every operand is run through `encodeValue`, so a bound value matches the SQL
-* the column side compiles to. A flat column encodes operands with its DECLARED
+* the column side compiles to. A flat column encodes operands with its declared
 * schema type (a flat `json` column → `JSON.stringify`); a nested `FieldPath`
-* encodes each operand as the NATIVE scalar `json_extract` returns, derived from
+* encodes each operand as the native scalar `json_extract` returns, derived from
 * the operand's runtime type (per-operand, since `between` / `any` / `none` can
 * mix types). `any` / `none` collapse an empty list to a constant (`0` matches
 * nothing, `1` matches all) with no parameters.
 *
-* The core engine's total order ranks `undefined` (rank 0) BELOW `null`
-* (rank 1) (see `compareValues`), so a MISSING/`NULL` column MATCHES
+* The core engine's total order ranks `undefined` (rank 0) below `null`
+* (rank 1) (see `compareValues`), so a missing/`NULL` column matches
 * `below` / `to` / a scalar `not` / `none` — the opposite of raw SQL, where a
 * comparison against `NULL` is `NULL` (excluded). This fragment replicates the
 * engine exactly. Truth table (`value` = the engine's decoded field read; a
-* FLAT column's stored `NULL` decodes to `undefined` per `decodeRow`, so a
-* flat `value` is NEVER a present `null` — only a NESTED path can be
+* flat column's stored `NULL` decodes to `undefined` per `decodeRow`, so a
+* flat `value` is never a present `null` — only a nested path can be
 * present-but-`null`):
 *
 * ```text
@@ -617,15 +600,15 @@ function inferValueStorage(value) {
 * refines every optional or nullable scalar comparison through the core engine.
 * This compiler still emits a total SQL fragment for direct consumers.
 *
-* A NESTED path can be present-but-`null` (a stored JSON `null`), which
-* `json_extract` reads back as SQL `NULL` — indistinguishable from an ABSENT
+* A nested path can be present-but-`null` (a stored JSON `null`), which
+* `json_extract` reads back as SQL `NULL` — indistinguishable from an absent
 * path. `json_type(col, path)` disambiguates them (`'null'` for present-null,
 * SQL `NULL` for absent), so nested `equals` / `not` against a `null` operand
 * compile through `json_type` instead of `IS NULL` / `IS NOT NULL`.
 *
 * Every other MATCH-on-null-or-absent row is expressed uniformly (flat and
 * nested alike) as `(<column> <op> ? OR <column> IS NULL)` — for a nested
-* path, `json_extract` already collapses BOTH absent and present-null to SQL
+* path, `json_extract` already collapses both absent and present-null to SQL
 * `NULL`, so `IS NULL` catches both in one clause; for a flat column there is
 * only the absent case to catch.
 *
@@ -644,7 +627,7 @@ function inferValueStorage(value) {
 function compileConditionSQL(condition, schema) {
 	const column = compileFieldSQL(condition.column);
 	const nested = !isString(condition.column);
-	const declared = isString(condition.column) ? schema.columns.find((candidate) => candidate.name === condition.column) : void 0;
+	const declared = isString(condition.column) ? findColumn(condition.column, schema) : void 0;
 	const first = condition.values[0];
 	const second = condition.values[1];
 	const nullOperand = first === null || first === void 0;
@@ -763,13 +746,13 @@ function compileConditionSQL(condition, schema) {
 	};
 }
 /**
-* Fold the conditions into one WHERE clause, parenthesizing progressively
+* Folds the conditions into one WHERE clause, parenthesizing progressively
 * left-to-right so the grouping matches the engine's `matchesQuery` fold.
 *
 * @remarks
 * The first condition's connector is ignored, per the {@link Condition} types.
 * Every fragment (see {@link compileConditionSQL}'s truth table) replicates the core
-* engine's total order EXACTLY under SQL's three-valued NULL logic, so this
+* engine's total order exactly under SQL's three-valued NULL logic, so this
 * clause matches `applyQuery` row-for-row over the same table — a native
 * `records` / `count` read never disagrees with a scan-and-filter fallback.
 *
@@ -779,11 +762,11 @@ function compileConditionSQL(condition, schema) {
 *
 * @example
 * ```ts
-* compileWhere([{ column: 'age', operator: 'from', values: [18], connector: 'and' }], schema)
+* compileWhereSQL([{ column: 'age', operator: 'from', values: [18], connector: 'and' }], schema)
 * // { sql: 'WHERE "age" >= ?', parameters: [18] }
 * ```
 */
-function compileWhere(conditions, schema) {
+function compileWhereSQL(conditions, schema) {
 	const [first, ...remaining] = conditions;
 	if (first === void 0) return {
 		sql: "",
@@ -804,14 +787,14 @@ function compileWhere(conditions, schema) {
 	};
 }
 /**
-* Compile the ORDER BY clause from the order terms, always ending with the
+* Compiles the ORDER BY clause from the order terms, always ending with the
 * primary key as the final determinant.
 *
 * @remarks
 * The native `records` read then resolves ties in key order, matching a
 * primary-key-ordered `scan` and the core engine's stable `sortRows` over a
 * key-ordered scan (and IndexedDB's key-ordered reads), so a native read equals
-* the scan path (AGENTS §21 / §22 native ↔ engine parity). SQLite without an
+* the scan path — native ↔ engine parity. SQLite without an
 * `ORDER BY` returns rowid (insertion) order, and an explicit order alone breaks
 * ties by rowid too — both diverge from every key-ordered backend. The
 * tie-breaker is ASCENDING regardless of the explicit directions: the engine's
@@ -825,17 +808,17 @@ function compileWhere(conditions, schema) {
 *
 * @example
 * ```ts
-* compileOrder([{ column: 'age', direction: 'descending' }], schema)
+* compileOrderSQL([{ column: 'age', direction: 'descending' }], schema)
 * // 'ORDER BY "age" DESC, "id"'
 * ```
 */
-function compileOrder(order, schema) {
+function compileOrderSQL(order, schema) {
 	const terms = (order ?? []).map((term) => compileFieldSQL(term.column) + (term.direction === "descending" ? " DESC" : " ASC"));
 	if (!(order ?? []).some((term) => isString(term.column) && term.column === schema.primary)) terms.push(quoteIdentifier(schema.primary));
 	return terms.length === 0 ? "" : "ORDER BY " + terms.join(", ");
 }
 /**
-* Compile the LIMIT / OFFSET clause.
+* Compiles the LIMIT / OFFSET clause.
 *
 * @remarks
 * An offset without a limit uses `LIMIT -1` (SQLite's "no limit") so OFFSET is
@@ -847,10 +830,10 @@ function compileOrder(order, schema) {
 *
 * @example
 * ```ts
-* compilePage(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', parameters: [5] }
+* compilePageSQL(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', parameters: [5] }
 * ```
 */
-function compilePage(limit, offset) {
+function compilePageSQL(limit, offset) {
 	validatePage({
 		...limit === void 0 ? {} : { limit },
 		...offset === void 0 ? {} : { offset }
@@ -873,7 +856,7 @@ function compilePage(limit, offset) {
 	};
 }
 /**
-* Compile a {@link QueryInput} into the SQL clause that follows a table name, with
+* Compiles a {@link QueryInput} into the SQL clause that follows a table name, with
 * its bound parameters in clause order.
 *
 * @remarks
@@ -883,11 +866,13 @@ function compilePage(limit, offset) {
 * over a JS `scan`. The WHERE fold is parenthesized **left-to-right** to mirror
 * the core engine's `matchesQuery` (not SQL's native AND-over-OR precedence),
 * so a native and an engine read return identical rows. Each operand is encoded
-* via `encodeValue`: a flat column uses its declared schema type, while a nested
+* through `encodeValue`: a flat column uses its declared schema type, while a nested
 * `FieldPath` (a `json_extract` read) encodes each operand as the native scalar
 * the extract returns — derived from the operand's runtime type — so it compares.
-* The 15 operators map per the databases guide's operator table, with
-* `starts` / `ends` using `LIKE … ESCAPE '\'` and an empty `any` / `none` list
+* Every operator maps per the databases guide's operator table, with
+* `starts` / `ends` compiling to a code-point `substr` slice guarded by
+* `typeof(<column>) = 'text'` (case-sensitive, matching the engine's
+* `String.prototype.startsWith` / `endsWith`) and an empty `any` / `none` list
 * collapsing to a constant. An `undefined` input (or one with no parts)
 * compiles to an empty clause.
 *
@@ -903,9 +888,9 @@ function compilePage(limit, offset) {
 */
 function compileQuerySQL(input, schema) {
 	validatePage(input);
-	const where = compileWhere(input?.conditions ?? [], schema);
-	const orderBy = compileOrder(input?.order, schema);
-	const page = compilePage(input?.limit, input?.offset);
+	const where = compileWhereSQL(input?.conditions ?? [], schema);
+	const orderBy = compileOrderSQL(input?.order, schema);
+	const page = compilePageSQL(input?.limit, input?.offset);
 	return {
 		sql: [
 			where.sql,
@@ -916,7 +901,7 @@ function compileQuerySQL(input, schema) {
 	};
 }
 /**
-* Project a {@link TableSchema} to its `CREATE TABLE IF NOT EXISTS` statement.
+* Projects a {@link TableSchema} to its `CREATE TABLE IF NOT EXISTS` statement.
 *
 * @param schema - The table schema
 * @returns The complete table declaration
@@ -926,7 +911,11 @@ function schemaToTable(schema) {
 	return "CREATE TABLE IF NOT EXISTS " + quoteIdentifier(schema.name) + " (" + columns.join(", ") + ", PRIMARY KEY (" + quoteIdentifier(schema.primary) + "))";
 }
 /**
-* Project a {@link TableSchema} to its declared SQLite indexes.
+* Projects a {@link TableSchema} to its declared SQLite indexes.
+*
+* @remarks
+* Each statement is a `CREATE INDEX IF NOT EXISTS` named by
+* {@link deriveSQLiteIndexName}, so a reopen re-issues the set safely.
 *
 * @param schema - The table schema
 * @returns One statement per declared index
@@ -935,7 +924,11 @@ function schemaToIndexes(schema) {
 	return schema.indexes.map((group) => "CREATE INDEX IF NOT EXISTS " + quoteIdentifier(deriveSQLiteIndexName(schema.name, group)) + " ON " + quoteIdentifier(schema.name) + " (" + group.map(quoteIdentifier).join(", ") + ")");
 }
 /**
-* Project one {@link MigrationStep} to SQLite DDL.
+* Projects one {@link MigrationStep} to SQLite DDL.
+*
+* @remarks
+* These are the statements the SQLite driver's `migrate` executes for the step,
+* inside whichever native transaction is active.
 *
 * @param step - The migration step
 * @returns The statements that apply the step
@@ -951,97 +944,9 @@ function stepToSQL(step) {
 	}
 }
 //#endregion
-//#region src/core/DriverIterator.ts
-/**
-* The internal continuation boundary for a root driver async iterator.
-*
-* @remarks
-* A driver transaction can begin while a caller holds an idle root iterator.
-* Every `next` therefore checks the driver's root-state guard immediately
-* before and after advancing the source. A failed continuation terminalizes the
-* iterator, discards any row produced before the post-advance guard failed, and
-* attempts source cleanup exactly once.
-*/
-var DriverIterator = class {
-	#source;
-	#guard;
-	#terminal = false;
-	#cleaned = false;
-	constructor(source, guard) {
-		this.#source = source;
-		this.#guard = guard;
-	}
-	[Symbol.asyncIterator]() {
-		return this;
-	}
-	async next() {
-		if (this.#terminal) return {
-			done: true,
-			value: void 0
-		};
-		try {
-			this.#guard();
-			const result = await this.#source.next();
-			this.#guard();
-			if (result.done === true) {
-				this.#terminal = true;
-				this.#cleaned = true;
-			}
-			return result;
-		} catch (error) {
-			this.#terminal = true;
-			await this.#discard();
-			throw error;
-		}
-	}
-	async return() {
-		if (this.#terminal) return {
-			done: true,
-			value: void 0
-		};
-		this.#terminal = true;
-		if (this.#cleaned || this.#source.return === void 0) {
-			this.#cleaned = true;
-			return {
-				done: true,
-				value: void 0
-			};
-		}
-		this.#cleaned = true;
-		return this.#source.return();
-	}
-	async throw(error) {
-		if (this.#terminal) throw error;
-		if (this.#source.throw === void 0) {
-			this.#terminal = true;
-			await this.#discard();
-			throw error;
-		}
-		try {
-			const result = await this.#source.throw(error);
-			if (result.done === true) {
-				this.#terminal = true;
-				this.#cleaned = true;
-			}
-			return result;
-		} catch (cause) {
-			this.#terminal = true;
-			await this.#discard();
-			throw cause;
-		}
-	}
-	async #discard() {
-		if (this.#cleaned) return;
-		this.#cleaned = true;
-		try {
-			await this.#source.return?.();
-		} catch {}
-	}
-};
-//#endregion
 //#region src/server/drivers/JSONDriver.ts
 /**
-* A persistent {@link DriverInterface} backed by a single JSON file — the
+* Implements a persistent {@link DriverInterface} backed by a single JSON file — the
 * reference {@link MemoryDriver} plus file load / flush.
 *
 * @remarks
@@ -1055,15 +960,15 @@ var DriverIterator = class {
 * primary (the table contract), so the key is recovered on load with
 * {@link extractKey} and the file need not store it. The parsed JSON crosses the
 * boundary as `unknown` and is narrowed with {@link isRecord} / {@link extractKey},
-* never asserted (AGENTS §14). A read that reports no document there starts empty —
+* never asserted. A read that reports no document there starts empty —
 * `ENOENT` for a plain absence, and `ENOTDIR` for a path whose parent is not a
 * directory, which no later write could find either; every other read failure or
 * invalid existing document fails closed without publication, mutation, or
-* automatic repair. It is scan-only — it implements none of
-* the optional native `records` / `aggregate` hooks, so the core engine
-* over `scan` answers every query. For development, small datasets, and portable /
-* inspectable data; for large or concurrent workloads reach for a SQLite-backed
-* driver.
+* automatic repair. It implements the optional native `stream` hook that
+* `TableInterface.scan` prefers over `scan`, and neither `records` nor
+* `aggregate`, so the core engine's `matchesQuery` answers every query on
+* either path. For development, small datasets, and portable / inspectable
+* data; for large or concurrent workloads reach for a SQLite-backed driver.
 *
 * Metadata crosses {@link cloneDriverMetadata} at parsed-file ingress, public and
 * scoped write ingress, candidate/root publication, serialization, and copy-out.
@@ -1127,7 +1032,7 @@ var JSONDriver = class {
 		return new DriverIterator(this.#scan(table)[Symbol.asyncIterator](), () => this.#root());
 	}
 	/**
-	* Natively filtered lazy iteration — delegates to the inner {@link MemoryDriver}.
+	* Iterates rows lazily with native filtering — delegates to the inner {@link MemoryDriver}.
 	*
 	* @remarks
 	* Semantics are the memory driver's own: `input.conditions` filters, `offset`
@@ -1146,7 +1051,7 @@ var JSONDriver = class {
 		await this.#enqueue(() => this.#clear(table));
 	}
 	/**
-	* Run an isolated native transaction callback over a candidate memory store.
+	* Runs an isolated native transaction callback over a candidate memory store.
 	*
 	* @remarks
 	* Single-writer: nesting and root operations while active throw `CONFLICT`.
@@ -1163,7 +1068,7 @@ var JSONDriver = class {
 		return this.#enqueue(() => this.#transact(scope));
 	}
 	/**
-	* Capture an owned row snapshot at an exact writer-queue position.
+	* Captures an owned row snapshot at an exact writer-queue position.
 	*
 	* @remarks
 	* Capture owns table names, schemas, rows, and one session-local identity per
@@ -1191,7 +1096,7 @@ var JSONDriver = class {
 		return this.#metadata === void 0 ? void 0 : cloneDriverMetadata(this.#metadata);
 	}
 	/**
-	* Persist an owned metadata snapshot for a later `metadata()` to copy out.
+	* Persists an owned metadata snapshot for a later `metadata()` to copy out.
 	*
 	* @remarks
 	* Root stamping conflicts while a transaction is active. The scoped
@@ -1206,7 +1111,7 @@ var JSONDriver = class {
 		await this.#enqueue(() => this.#stamp(owned));
 	}
 	/**
-	* Apply one atomic {@link MigrationInput} through an isolated candidate.
+	* Applies one atomic {@link MigrationInput} through an isolated candidate.
 	*
 	* @remarks
 	* The candidate receives every plan step plus optional metadata. Its complete
@@ -1420,7 +1325,8 @@ var JSONDriver = class {
 		return this.#requireCandidate(token).keys(table);
 	}
 	#scanCandidate(token, table) {
-		return new DriverIterator(this.#requireCandidate(token).scan(table)[Symbol.asyncIterator](), () => {
+		const source = this.#requireCandidate(token).scan(table);
+		return new DriverIterator(source[Symbol.asyncIterator](), () => {
 			this.#requireCandidate(token);
 		});
 	}
@@ -1667,8 +1573,8 @@ var JSONDriver = class {
 //#endregion
 //#region src/server/drivers/SQLiteDriver.ts
 /**
-* The SQLite {@link DriverInterface} — the server-native, trusted-mode backend
-* built on the published `@orkestrel/sqlite` synchronous wrapper.
+* Implements the {@link DriverInterface} over SQLite — the server-native, trusted-mode
+* backend built on the published `@orkestrel/sqlite` synchronous wrapper.
 *
 * @remarks
 * A thin adapter: it implements the storage primitives the core database layer
@@ -1679,41 +1585,40 @@ var JSONDriver = class {
 * reopen-safe), and readies a reserved `_metadata` single-row table `metadata()` /
 * `stamp()` read and write — **a user table named `_metadata` collides with it**;
 * avoid the name. Rows cross the boundary through the codecs in `helpers.ts`
-* (`json` columns store / parse JSON text, a `boolean` stores `1` / `0`), so the
-* typed layer above imposes the exact shape (AGENTS §14). `write` is an
+* (`json` columns store / parse JSON text, a `boolean` stores `1` / `0`), so
+* the typed layer above imposes the exact shape. `write` is an
 * `INSERT OR REPLACE` upsert, while `insert` uses a plain `INSERT` and maps its
 * atomic primary-key constraint failure to `CONFLICT`; every other backend
 * `SQLiteError` is contained by the same `DatabaseError` boundary described
-* below. Querying, ordering, paging, and
-* aggregation is native: `records` / `stream` compile a `QueryInput`
-* to SQL with `compileQuerySQL`, and `aggregate` runs a SQL
-* `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` (via `compileAggregateSQL`) over the same compiled
-* WHERE. `transaction` runs a callback inside native `BEGIN` / `COMMIT` /
-* `ROLLBACK`, passing a scoped storage capability that becomes invalid after
-* settlement. `migrate` runs the plan's projected DDL
-* ({@link import('../compilers.js').stepToSQL}) inside whichever native
-* transaction is active: joined into the active transaction callback
-* when one exists (the core's versioned reconcile path wraps migrate + stamp
-* in one native `BEGIN`, and node:sqlite rejects a nested `BEGIN`), or inside
-* its own `database.transaction` otherwise — a mid-plan failure rolls back
-* atomically either way, an improvement over the non-atomic `MemoryDriver` /
-* `JSONDriver` migrate; a step referencing an undeclared table throws
+* below. Querying, ordering, paging, and aggregation is native: `records` /
+* `stream` compile a `QueryInput` to SQL with `compileQuerySQL`, and
+* `aggregate` runs a SQL `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` (through
+* `compileAggregateSQL`) over the same compiled WHERE. `transaction` runs a
+* callback inside native `BEGIN` / `COMMIT` / `ROLLBACK`, passing a scoped
+* storage capability that becomes invalid after settlement. `migrate` runs the
+* plan's projected DDL ({@link import('../compilers.js').stepToSQL}) inside
+* whichever native transaction is active: joined into the active transaction
+* callback when one exists (the core's versioned reconcile path wraps migrate +
+* stamp in one native `BEGIN`, and node:sqlite rejects a nested `BEGIN`), or
+* inside its own `database.transact` otherwise — a mid-plan failure rolls
+* back atomically either way, an improvement over the non-atomic `MemoryDriver`
+* / `JSONDriver` migrate; a step referencing an undeclared table throws
 * `DatabaseError` `MIGRATION` before any DDL for that step runs. `snapshot` is
-* capture-replay (SELECT the
-* named tables' rows, replay via DELETE + INSERT OR REPLACE inside a native
-* transaction on rollback) rather than a SQL `SAVEPOINT`, since the core
-* `transaction` calls the rollback thunk only on failure with no commit-on-
-* success signal — a long-lived `SAVEPOINT` would leave the connection
-* uncommitted (lost on close). Every backend interaction runs through `#guard`,
-* which maps a thrown backend `SQLiteError` (or any unexpected non-`SQLiteError`
-* throw) to a typed {@link DatabaseError} — never a raw backend error escapes
-* `DriverInterface`: `CONSTRAINT` → `CONFLICT`, the wrapper's own `CLOSED` →
-* `CLOSED`, `BUSY` (a locked database that outlasted the configured `timeout`)
-* → a retryable `DRIVER` (`context.retryable` is `true`), and `UNKNOWN` / any
-* other throw → `DRIVER`. The original error is preserved as `context.cause`.
-* A `DatabaseError` this driver throws directly (`CLOSED` from the `#require`
-* gate, `NOT_FOUND` from `#table`, `MIGRATION` from a migration-plan fault)
-* passes through `#guard` unchanged, never re-wrapped.
+* capture-replay (SELECT the named tables' rows, replay through DELETE + INSERT OR
+* REPLACE inside a native transaction on rollback) rather than a SQL
+* `SAVEPOINT`, since the core `transaction` calls the rollback thunk only on
+* failure with no commit-on-success signal — a long-lived `SAVEPOINT` would
+* leave the connection uncommitted (lost on close). Every backend interaction
+* runs through `#guard`, which maps a thrown backend `SQLiteError` (or any
+* unexpected non-`SQLiteError` throw) to a typed {@link DatabaseError} — never
+* a raw backend error escapes `DriverInterface`: `CONSTRAINT` → `CONFLICT`, the
+* wrapper's own `CLOSED` → `CLOSED`, `BUSY` (a locked database that outlasted
+* the configured `timeout`) → a retryable `DRIVER` (`context.retryable` is
+* `true`), and `UNKNOWN` / any other throw → `DRIVER`. The original error is
+* preserved as `context.cause`. A `DatabaseError` this driver throws directly
+* (`CLOSED` from the `#require` gate, `NOT_FOUND` from `#table`, `MIGRATION`
+* from a migration-plan fault) passes through `#guard` unchanged, never
+* re-wrapped.
 */
 var SQLiteDriver = class {
 	#path;
@@ -1750,7 +1655,7 @@ var SQLiteDriver = class {
 				for (const [name, value] of Object.entries(this.#options.pragmas ?? {})) database.pragma(name, value);
 				const map = /* @__PURE__ */ new Map();
 				const identities = /* @__PURE__ */ new Map();
-				database.transaction(() => {
+				database.transact(() => {
 					this.#ensureMetadataTable(database);
 					const stored = this.#readMetadata(database);
 					const deployed = normalizeDriverSchema(stored?.schema ?? owned);
@@ -1768,11 +1673,11 @@ var SQLiteDriver = class {
 					for (const table of deployed) {
 						const absent = missing.get(table.name);
 						if (absent === void 0) {
-							database.exec(schemaToTable(table));
-							for (const sql of schemaToIndexes(table)) database.exec(sql);
+							database.execute(schemaToTable(table));
+							for (const sql of schemaToIndexes(table)) database.execute(sql);
 						} else for (const [index, group] of table.indexes.entries()) if (absent.includes(deriveSQLiteIndexName(table.name, group))) {
 							const sql = schemaToIndexes(table)[index];
-							if (sql !== void 0) database.exec(sql);
+							if (sql !== void 0) database.execute(sql);
 						}
 						identities.set(table.name, previousIdentities.get(table.name) ?? {});
 					}
@@ -1844,7 +1749,7 @@ var SQLiteDriver = class {
 		const conditionsExact = conditions.every((condition) => matchesConditionExactly(condition, schema));
 		const columnExact = matchesAggregateExactly(operation, column, schema);
 		if (conditionsExact && columnExact) return this.#guard(() => {
-			const { sql, parameters } = compileWhere(conditions, schema);
+			const { sql, parameters } = compileWhereSQL(conditions, schema);
 			const value = this.#require().prepare("SELECT " + compileAggregateSQL(operation, column) + " AS value FROM " + quoteIdentifier(table) + (sql === "" ? "" : " " + sql)).get(parameters)?.value;
 			return value === null || value === void 0 ? void 0 : Number(value);
 		});
@@ -1857,7 +1762,7 @@ var SQLiteDriver = class {
 		return new DriverIterator(this.#stream(table, input)[Symbol.asyncIterator](), () => this.#root());
 	}
 	/**
-	* Begin a native transaction — real `BEGIN`, `COMMIT`, `ROLLBACK`.
+	* Begins a native transaction — real `BEGIN`, `COMMIT`, `ROLLBACK`.
 	*
 	* @remarks
 	* The callback receives a scoped {@link StorageInterface}. Fulfillment
@@ -1904,23 +1809,22 @@ var SQLiteDriver = class {
 		}
 	}
 	/**
-	* Apply a {@link Migration} plan by executing each step's projected DDL
+	* Applies a {@link Migration} plan by executing each step's projected DDL
 	* ({@link import('../compilers.js').stepToSQL}).
 	*
 	* @remarks
-	* Atomicity is provided by whichever native transaction is active: when
-	* this driver's own `transaction()` callback is active (the
-	* core's versioned reconcile / migrate path joins migrate + stamp under
-	* one native `BEGIN`), the plan's DDL runs directly inside that enclosing
-	* transaction — a mid-plan failure rejects the callback and the driver
-	* rolls it back. node:sqlite (and SQLite
-	* generally) rejects a nested `BEGIN`, so this driver must never open a
+	* Atomicity is provided by whichever native transaction is active: when this
+	* driver's own `transaction()` callback is active (the core's versioned
+	* reconcile / migrate path joins migrate + stamp under one native `BEGIN`),
+	* the plan's DDL runs directly inside that enclosing transaction — a mid-plan
+	* failure rejects the callback and the driver rolls it back. node:sqlite (and
+	* SQLite generally) rejects a nested `BEGIN`, so this driver must never open a
 	* second native transaction while one is already open. Otherwise (no
 	* enclosing transaction), `migrate` wraps the plan in its own native
 	* `database.transaction` — atomic on its own: a mid-plan failure rolls
 	* back every DDL statement already applied by the plan. A scoped migration
 	* uses one fixed internal savepoint literal because the published SQLite
-	* wrapper intentionally exposes raw `exec` but no savepoint manager. That
+	* wrapper intentionally exposes raw `execute` but no savepoint manager. That
 	* savepoint contains a caught inner migration so the outer callback
 	* transaction remains active and may continue safely. A step referencing a
 	* table not in this driver's declared schema (and that is not itself a
@@ -1940,7 +1844,7 @@ var SQLiteDriver = class {
 			metadata: owned.metadata.schema
 		});
 		this.#guard(() => {
-			database.transaction(() => {
+			database.transact(() => {
 				this.#applyPlan(database, owned);
 				if (owned.metadata !== void 0) this.#writeMetadata(database, owned.metadata);
 			});
@@ -1949,7 +1853,7 @@ var SQLiteDriver = class {
 		this.#identities = identities;
 	}
 	/**
-	* Read the persisted {@link DriverMetadata} from the reserved `_metadata` table.
+	* Reads the persisted {@link DriverMetadata} from the reserved `_metadata` table.
 	*
 	* @returns The last-stamped `DriverMetadata`, or `undefined` when never stamped
 	*   (or the stored row is malformed)
@@ -1959,7 +1863,7 @@ var SQLiteDriver = class {
 		return this.#metadata();
 	}
 	/**
-	* Persist an owned metadata snapshot into the reserved `_metadata` table's
+	* Persists an owned metadata snapshot into the reserved `_metadata` table's
 	* single row.
 	*
 	* @param metadata - The {@link DriverMetadata} to persist
@@ -2014,11 +1918,11 @@ var SQLiteDriver = class {
 			}
 			this.#guard(() => {
 				const current = this.#require();
-				current.transaction(() => {
+				current.transact(() => {
 					for (const [name, replacement] of replacements) {
-						current.exec("DELETE FROM " + quoteIdentifier(name));
+						current.execute("DELETE FROM " + quoteIdentifier(name));
 						const statement = current.prepare("INSERT OR REPLACE INTO " + quoteIdentifier(name) + " (" + replacement.names.map(quoteIdentifier).join(", ") + ") VALUES (" + replacement.names.map(() => "?").join(", ") + ")");
-						for (const values of replacement.values) statement.run(values);
+						for (const values of replacement.values) statement.execute(values);
 					}
 				});
 			});
@@ -2039,7 +1943,7 @@ var SQLiteDriver = class {
 			const values = extractValues(encoded, names, table);
 			const statement = this.#require().prepare("INSERT OR REPLACE INTO " + quoteIdentifier(table) + " (" + names.map(quoteIdentifier).join(", ") + ") VALUES (" + names.map(() => "?").join(", ") + ")");
 			checkAbort(options?.signal);
-			statement.run(values);
+			statement.execute(values);
 		});
 	}
 	async #insert(table, key, row, options) {
@@ -2050,7 +1954,7 @@ var SQLiteDriver = class {
 			const values = extractValues(encoded, names, table);
 			const statement = this.#require().prepare("INSERT INTO " + quoteIdentifier(table) + " (" + names.map(quoteIdentifier).join(", ") + ") VALUES (" + names.map(() => "?").join(", ") + ")");
 			checkAbort(options?.signal);
-			statement.run(values);
+			statement.execute(values);
 		});
 	}
 	async #delete(table, key, options) {
@@ -2058,7 +1962,7 @@ var SQLiteDriver = class {
 		return this.#guard(() => {
 			const statement = this.#require().prepare("DELETE FROM " + quoteIdentifier(table) + " WHERE " + quoteIdentifier(schema.primary) + " = ?");
 			checkAbort(options?.signal);
-			return statement.run([this.#key(key, schema)]).changes > 0;
+			return statement.execute([this.#key(key, schema)]).changes > 0;
 		});
 	}
 	async #keys(table) {
@@ -2120,14 +2024,14 @@ var SQLiteDriver = class {
 	async #clear(table) {
 		this.#table(table);
 		this.#guard(() => {
-			this.#require().prepare("DELETE FROM " + quoteIdentifier(table)).run();
+			this.#require().prepare("DELETE FROM " + quoteIdentifier(table)).execute();
 		});
 	}
 	async #metadata() {
 		return this.#guard(() => this.#readMetadata(this.#require()));
 	}
 	#ensureMetadataTable(database) {
-		database.exec("CREATE TABLE IF NOT EXISTS " + quoteIdentifier(METADATA_TABLE) + " (\"id\" INTEGER, \"version\" INTEGER, \"schema\" TEXT, PRIMARY KEY (\"id\"))");
+		database.execute("CREATE TABLE IF NOT EXISTS " + quoteIdentifier(METADATA_TABLE) + " (\"id\" INTEGER, \"version\" INTEGER, \"schema\" TEXT, PRIMARY KEY (\"id\"))");
 	}
 	#validateTable(database, schema) {
 		const object = database.prepare("SELECT \"type\" AS \"category\" FROM \"sqlite_schema\" WHERE \"name\" = ?").get([schema.name]);
@@ -2262,7 +2166,7 @@ var SQLiteDriver = class {
 		this.#guard(() => this.#writeMetadata(database, owned));
 	}
 	#writeMetadata(database, metadata) {
-		database.prepare("INSERT OR REPLACE INTO " + quoteIdentifier(METADATA_TABLE) + " (\"id\", \"version\", \"schema\") VALUES (1, ?, ?)").run([metadata.version, JSON.stringify(metadata.schema)]);
+		database.prepare("INSERT OR REPLACE INTO " + quoteIdentifier(METADATA_TABLE) + " (\"id\", \"version\", \"schema\") VALUES (1, ?, ?)").execute([metadata.version, JSON.stringify(metadata.schema)]);
 	}
 	#capability(token) {
 		return {
@@ -2321,16 +2225,16 @@ var SQLiteDriver = class {
 			metadata: owned.metadata.schema
 		});
 		this.#guard(() => {
-			database.exec("SAVEPOINT \"_orkestrel_migration\"");
+			database.execute("SAVEPOINT \"_orkestrel_migration\"");
 			try {
 				this.#applyPlan(database, owned);
 				if (owned.metadata !== void 0) this.#writeMetadata(database, owned.metadata);
-				database.exec("RELEASE SAVEPOINT \"_orkestrel_migration\"");
+				database.execute("RELEASE SAVEPOINT \"_orkestrel_migration\"");
 			} catch (error) {
 				try {
-					database.exec("ROLLBACK TO SAVEPOINT \"_orkestrel_migration\"");
+					database.execute("ROLLBACK TO SAVEPOINT \"_orkestrel_migration\"");
 				} finally {
-					database.exec("RELEASE SAVEPOINT \"_orkestrel_migration\"");
+					database.execute("RELEASE SAVEPOINT \"_orkestrel_migration\"");
 				}
 				throw error;
 			}
@@ -2406,13 +2310,13 @@ var SQLiteDriver = class {
 		});
 	}
 	#applyPlan(database, input) {
-		for (const step of input.plan.steps) for (const sql of stepToSQL(step)) database.exec(sql);
+		for (const step of input.plan.steps) for (const sql of stepToSQL(step)) database.execute(sql);
 	}
 };
 //#endregion
 //#region src/server/factories.ts
 /**
-* Create a persistent JSON-file {@link DriverInterface} for the core database layer.
+* Creates a persistent JSON-file {@link DriverInterface} for a given path.
 *
 * @remarks
 * Pass it to `createDatabase` from `@orkestrel/database` to run the typed
@@ -2420,9 +2324,10 @@ var SQLiteDriver = class {
 * `Table` / `Query` API is unchanged; only where the bytes live changes.
 * The driver is the reference `MemoryDriver` plus JSON-file persistence: `open` loads
 * the file, every mutation flushes the whole store back, and querying runs through
-* the core engine over `scan` (it is scan-only — no native `records` / `count` /
-* `aggregate`). A missing, corrupt, or wrong-shaped file starts empty rather than
-* throwing.
+* the core engine's `matchesQuery`. The driver implements the native `stream`
+* hook and neither `records` nor `aggregate`, so the engine answers every query
+* on either path. A missing, corrupt, or wrong-shaped file starts empty rather
+* than throwing.
 *
 * @param path - The JSON file path data is loaded from and flushed to
 * @returns A {@link DriverInterface} backed by a JSON file
@@ -2444,7 +2349,8 @@ function createJSONDriver(path) {
 	return new JSONDriver(path);
 }
 /**
-* Create a trusted-mode SQLite {@link DriverInterface} for the core database layer.
+* Creates a trusted-mode, server-native SQLite {@link DriverInterface} for a database path,
+* or for `:memory:` when the options bag omits one.
 *
 * @remarks
 * Pass it to `createDatabase` from `@orkestrel/database` to run the typed
@@ -2483,6 +2389,6 @@ function createSQLiteDriver(options) {
 	return new SQLiteDriver(options);
 }
 //#endregion
-export { EXACT_COLUMN_STORAGE, EXACT_RANGE_COLUMN_STORAGE, JSONDriver, METADATA_TABLE, SQLiteDriver, compileAggregateSQL, compileColumnSQL, compileConditionSQL, compileFieldSQL, compileJSONTypeSQL, compileOrder, compilePage, compileQuerySQL, compileWhere, createJSONDriver, createSQLiteDriver, decodeRow, decodeValue, deriveSQLiteIndexName, encodeRow, encodeValue, escapeLike, extractValues, findColumnStorage, inferValueStorage, matchesAbsentPath, matchesAggregateExactly, matchesConditionExactly, matchesDeclaredStorage, matchesOrderExactly, matchesQueryExactly, matchesSQLiteAffinity, quoteIdentifier, schemaToIndexes, schemaToTable, stepToSQL };
+export { EXACT_COLUMN_STORAGE, EXACT_RANGE_COLUMN_STORAGE, JSONDriver, METADATA_TABLE, SQLiteDriver, compileAggregateSQL, compileColumnSQL, compileConditionSQL, compileFieldSQL, compileJSONTypeSQL, compileOrderSQL, compilePageSQL, compileQuerySQL, compileWhereSQL, createJSONDriver, createSQLiteDriver, decodeRow, decodeValue, deriveSQLiteIndexName, encodeRow, encodeValue, extractValues, inferValueStorage, matchesAbsentPath, matchesAggregateExactly, matchesConditionExactly, matchesDeclaredStorage, matchesOrderExactly, matchesQueryExactly, matchesSQLiteAffinity, quoteIdentifier, schemaToIndexes, schemaToTable, stepToSQL };
 
 //# sourceMappingURL=index.js.map