@orkestrel/database 0.0.5 → 0.0.7

package/dist/src/server/index.js

@@ -1,30 +1,11 @@
-import { isBoolean, isFiniteNumber, isRecord, isString } from "@orkestrel/contract";
-import { randomUUID } from "node:crypto";
-import { DatabaseError, MemoryDriver, applyCriteria, computeAggregate, extractKey, filterRows, isDriverMeta, matchesCriteria } from "../core/index.js";
+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 { 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/helpers.ts
-/**
-* Generate a fresh unique key — a v4 UUID string, backed by `node:crypto`.
-*
-* @remarks
-* Supply this as {@link import('@orkestrel/database').DatabaseOptions.key} so a table mints
-* a key when a written row lacks its primary-key value. Strings work as keys on
-* every backend; supply your own key values directly to use numeric keys instead.
-*
-* @returns A new UUID string
-*
-* @example
-* ```ts
-* const db = createDatabase({ driver, tables, key: generateKey })
-* ```
-*/
-function generateKey() {
-	return randomUUID();
-}
+//#region src/server/constants.ts
 /**
-* The declared {@link ColumnType}s whose SQL EQUALITY comparisons (`equals` /
+* 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.
@@ -39,38 +20,47 @@ function generateKey() {
 * 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 `isExactCondition`'s range family and
-* `isExactOrder` exclude `text`, refining through the core engine instead. A
-* future opt-in "trusted collation" mode (the caller vouches the column's
-* values are BMP-only, or a custom SQLite collation matching `compareValues`
-* is registered) could restore native text ranges/ordering.
+* its code point sorts ABOVE them. So `matchesConditionExactly`'s range family and
+* `matchesOrderExactly` exclude `text`, refining through the core engine instead.
 */
-var EXACT_COLUMN_TYPES = [
+var EXACT_COLUMN_STORAGE = Object.freeze([
 	"text",
 	"integer",
 	"real",
 	"boolean"
-];
+]);
 /**
-* The declared {@link ColumnType}s whose SQL RANGE comparisons
+* 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_TYPES}'s remarks for the BINARY-collation
+* excluded: see {@link EXACT_COLUMN_STORAGE}'s remarks for the BINARY-collation
 * (code-point) vs. JS `<` (code-unit) divergence on supplementary-plane
 * characters.
 */
-var EXACT_RANGE_COLUMN_TYPES = [
+var EXACT_RANGE_COLUMN_STORAGE = Object.freeze([
 	"integer",
 	"real",
 	"boolean"
-];
+]);
+/**
+* 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.
+*
+* @remarks
+* A single-row table (`id = 1`). A user table named `_metadata` collides with the
+* reservation — the caller's concern to avoid, documented on the driver class.
+*/
+var METADATA_TABLE = "_metadata";
+//#endregion
+//#region src/server/helpers.ts
 /**
 * 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`
-* fail), `boolean` ↔ boolean. Backs {@link isExactCondition}'s operand checks.
+* fail), `boolean` ↔ boolean. Backs {@link matchesConditionExactly}'s operand checks.
 *
 * @param value - The condition operand to test
 * @param type - The column's declared portable type
@@ -82,9 +72,9 @@ var EXACT_RANGE_COLUMN_TYPES = [
 * matchesDeclaredType(Number.NaN, 'integer') // false — only finite numbers
 * ```
 */
-function matchesDeclaredType(value, type) {
-	if (type === "text") return isString(value);
-	if (type === "boolean") return isBoolean(value);
+function matchesDeclaredStorage(value, storage) {
+	if (storage === "text") return isString(value);
+	if (storage === "boolean") return isBoolean(value);
 	return isFiniteNumber(value);
 }
 /**
@@ -93,28 +83,26 @@ function matchesDeclaredType(value, type) {
 * type can store.
 *
 * @remarks
-* `false` for a nested `FieldPath` (an array), a column absent from `schema`,
-* or a column whose declared type is not `text` / `integer` / `real` /
-* `boolean` (a `json` / `blob` column) — EXCEPT `absent` / `present`, which
-* compile to `IS NULL` / `IS NOT NULL` and match `decodeRow`'s "a stored NULL
-* decodes to `undefined`" rule for every column type, so they are exact
-* regardless of declared type. `equals` / `not` require a operand matching the
-* column's declared type (a `null` / `undefined` operand is never exact here —
-* `encodeRow` stores both an explicit `null` and an absent field as SQL NULL,
-* so native `IS NULL` semantics cannot match the engine's `deepEqual`-over-
-* decoded-rows truth). `above` / `below` / `from` / `to` / `between` are exact
-* ONLY for a declared type in {@link EXACT_RANGE_COLUMN_TYPES} (`integer` /
+* `false` for a nested `FieldPath` (an array) or a column absent from `schema`.
+* `absent` / `present` are exact unless a column is both optional and nullable.
+* In that combined case the storage sentinel for explicit `null` is not SQL
+* `NULL`, while the core treats both absence and explicit `null` as absent.
+* Every scalar operator refines when the column is optional
+* OR nullable, because SQL null semantics and the core total order differ.
+* 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,
 * and the two diverge for supplementary-plane characters (see
-* {@link EXACT_COLUMN_TYPES}'s remarks for the full rationale).
+* {@link EXACT_COLUMN_STORAGE}'s remarks for the full rationale).
 * `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 fragment}) —
+* string operand (case-sensitive `substr` compile, see {@link compileConditionSQL}) —
 * 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.
@@ -123,26 +111,27 @@ function matchesDeclaredType(value, type) {
 * @param schema - The table's schema
 * @returns Whether `condition` is exact
 */
-function isExactCondition(condition, schema) {
+function matchesConditionExactly(condition, schema) {
 	if (!isString(condition.column)) return false;
 	const column = schema.columns.find((candidate) => candidate.name === condition.column);
 	if (column === void 0) return false;
-	if (condition.operator === "absent" || condition.operator === "present") return true;
-	if (!EXACT_COLUMN_TYPES.some((type) => type === column.type)) 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;
 	const first = condition.values[0];
 	const second = condition.values[1];
 	switch (condition.operator) {
 		case "equals":
-		case "not": return matchesDeclaredType(first, column.type);
+		case "not": return matchesDeclaredStorage(first, column.storage);
 		case "above":
 		case "below":
 		case "from":
-		case "to": return EXACT_RANGE_COLUMN_TYPES.some((type) => type === column.type) && matchesDeclaredType(first, column.type);
-		case "between": return EXACT_RANGE_COLUMN_TYPES.some((type) => type === column.type) && matchesDeclaredType(first, column.type) && matchesDeclaredType(second, column.type);
+		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 "any":
-		case "none": return condition.values.length > 0 && condition.values.every((value) => matchesDeclaredType(value, column.type));
+		case "none": return condition.values.length > 0 && condition.values.every((value) => matchesDeclaredStorage(value, column.storage));
 		case "starts":
-		case "ends": return column.type === "text" && isString(first);
+		case "ends": return column.storage === "text" && isString(first);
 		case "like":
 		case "glob": return false;
 	}
@@ -153,65 +142,71 @@ function isExactCondition(condition, schema) {
 *
 * @remarks
 * `false` for a nested `FieldPath`, a column absent from `schema`, or a
-* declared type outside {@link EXACT_RANGE_COLUMN_TYPES} (`integer` / `real` /
+* declared type outside {@link EXACT_RANGE_COLUMN_STORAGE} (`integer` / `real` /
 * `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_TYPES}'s remarks) —
+* supplementary-plane characters (see {@link EXACT_COLUMN_STORAGE}'s remarks) —
 * a `text` order term REFINES through the core engine instead.
 *
 * @param order - The order term to test
 * @param schema - The table's schema
 * @returns Whether `order` is exact
 */
-function isExactOrder(order, schema) {
+function matchesOrderExactly(order, schema) {
 	if (!isString(order.column)) return false;
 	const column = schema.columns.find((candidate) => candidate.name === order.column);
 	if (column === void 0) return false;
-	return EXACT_RANGE_COLUMN_TYPES.some((type) => type === column.type);
+	return !column.optional && !column.nullable && EXACT_RANGE_COLUMN_STORAGE.some((storage) => storage === column.storage);
 }
 /**
-* Whether a whole {@link Criteria} is exact — every condition and every order
+* 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).
 *
-* @param criteria - The criteria to test
+* @param input - The query input to test
 * @param schema - The table's schema
-* @returns Whether every part of `criteria` is exact
+* @returns Whether every part of `input` is exact
 */
-function isExactCriteria(criteria, schema) {
-	const conditions = criteria.conditions ?? [];
-	const order = criteria.order ?? [];
-	return conditions.every((condition) => isExactCondition(condition, schema)) && order.every((term) => isExactOrder(term, schema));
+function matchesQueryExactly(input, schema) {
+	const conditions = input.conditions ?? [];
+	const order = input.order ?? [];
+	return conditions.every((condition) => matchesConditionExactly(condition, schema)) && order.every((term) => matchesOrderExactly(term, schema));
 }
 /**
-* Map a portable {@link ColumnType} to its SQLite column type.
+* Determine whether SQLite can execute an aggregate exactly like the core engine.
 *
-* @remarks
-* `text` / `json` → `TEXT` (JSON is stored as text and read back with
-* `json_extract` for nested-field queries); `integer` / `boolean` → `INTEGER`
-* (a boolean stores `1` / `0`); `real` → `REAL`; `blob` → `BLOB`. No `NOT NULL`
-* is ever emitted — the contract validates required-ness; the database is just
-* storage (AGENTS §14, the typed layer above imposes the shape).
-*
-* @param type - The portable column type
-* @returns The SQLite column type keyword
+* @param operation - Aggregate operation
+* @param column - Aggregate field
+* @param schema - Current table schema
+* @returns Whether native aggregation is exact
+*/
+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);
+	return declared !== void 0 && (declared.storage === "integer" || declared.storage === "real") && !(declared.optional && declared.nullable);
+}
+/**
+* Test a declared SQLite type against a portable storage affinity.
 *
-* @example
-* ```ts
-* columnSQL('integer') // 'INTEGER'
-* columnSQL('json') // 'TEXT'
-* ```
+* @param declared - Native declared type
+* @param storage - Portable column storage
+* @returns Whether SQLite's official affinity rules yield the expected affinity
 */
-function columnSQL(type) {
-	switch (type) {
-		case "text":
-		case "json": return "TEXT";
-		case "integer":
-		case "boolean": return "INTEGER";
-		case "real": return "REAL";
-		case "blob": return "BLOB";
-	}
+function matchesSQLiteAffinity(declared, storage) {
+	if (!isString(declared)) return false;
+	const type = declared.toUpperCase();
+	let affinity;
+	if (type.includes("INT")) affinity = "INTEGER";
+	else if (type.includes("CHAR") || type.includes("CLOB") || type.includes("TEXT")) affinity = "TEXT";
+	else if (type === "" || type.includes("BLOB")) affinity = "BLOB";
+	else if (type.includes("REAL") || type.includes("FLOA") || type.includes("DOUB")) affinity = "REAL";
+	else affinity = "NUMERIC";
+	if (storage === "integer" || storage === "boolean") return affinity === "INTEGER";
+	if (storage === "text" || storage === "json") return affinity === "TEXT";
+	if (storage === "blob") return affinity === "BLOB";
+	return affinity === "REAL";
 }
 /**
 * Quote a SQL identifier (a table or column name) so any characters are literal.
@@ -226,127 +221,90 @@ function columnSQL(type) {
 *
 * @example
 * ```ts
-* quote('order') // '"order"'
+* quoteIdentifier('order') // '"order"'
 * ```
 */
-function quote(identifier) {
+function quoteIdentifier(identifier) {
 	return "\"" + identifier.replaceAll("\"", "\"\"") + "\"";
 }
 /**
-* Compile a {@link FieldPath} to the SQL expression that reads it.
-*
-* @remarks
-* A single string is ONE column — `quote(path)`. An array descends a JSON column:
-* the first element is the (quoted) column, the rest a `json_extract` path
-* (`json_extract("payload", '$.user.id')`), matching the guide's nested-field
-* examples (simple identifier keys). The string's value is never split on `.`
-* (AGENTS — `FieldPath` semantics): a dotted string is one column literally.
-*
-* @param path - The field path (a column, or a column + nested keys)
-* @returns The SQL expression selecting the value
-*
-* @example
-* ```ts
-* fieldColumn('payload') // '"payload"'
-* fieldColumn(['payload', 'user', 'id']) // 'json_extract("payload", \'$.user.id\')'
-* ```
-*/
-function fieldColumn(path) {
-	if (isString(path)) return quote(path);
-	const rest = path.slice(1).map((key) => "." + key.replaceAll("'", "''")).join("");
-	return "json_extract(" + quote(path[0]) + ", '$" + rest + "')";
-}
-/**
-* Compile an {@link AggregateFunction} over a {@link FieldPath} to its SQL
-* aggregate expression — the SELECT body the SQLite driver's native `aggregate`
-* runs.
+* Encode a JS value to its stored {@link SQLiteValue} for a declared column.
 *
 * @remarks
-* `count` → `COUNT(*)` (counting all matched ROWS, not non-null column values —
-* mirroring the engine's `computeAggregate('count')`, which is `rows.length`); the
-* numeric aggregates wrap the column's read expression (a flat column, or a nested
-* `json_extract` path) in `SUM` / `AVG` / `MIN` / `MAX`. Over zero matched rows
-* `COUNT(*)` is `0` and the numeric aggregates are SQL `NULL` (→ `undefined`),
-* matching the engine.
-*
-* @param operation - The aggregate to compute
-* @param column - The column (or nested path) to aggregate
-* @returns The SQL aggregate expression
-*
-* @example
-* ```ts
-* aggregateSQL('count', 'age') // 'COUNT(*)'
-* aggregateSQL('sum', 'age') // 'SUM("age")'
-* aggregateSQL('average', ['payload', 'score']) // 'AVG(json_extract("payload", \'$.score\'))'
-* ```
-*/
-function aggregateSQL(operation, column) {
-	switch (operation) {
-		case "count": return "COUNT(*)";
-		case "sum": return "SUM(" + fieldColumn(column) + ")";
-		case "average": return "AVG(" + fieldColumn(column) + ")";
-		case "minimum": return "MIN(" + fieldColumn(column) + ")";
-		case "maximum": return "MAX(" + fieldColumn(column) + ")";
-	}
-}
-/**
-* Encode a JS value to its stored {@link SQLiteValue} for a column's type.
-*
-* @remarks
-* The forward half of the bridge, total (AGENTS §14): a value that does not fit
-* its column's storage type encodes to `null` rather than throwing. A `boolean`
-* column stores `1` / `0` (and `null` / `undefined` → `null`); a `json` column
-* stores `JSON.stringify` (or `null` for `null` / `undefined`); `integer` /
-* `real` keep a `number` / `bigint`, else `null`; `text` keeps a `string`, else
-* `null`; `blob` keeps a `Uint8Array`, else `null`. Narrowed with `typeof` /
-* `instanceof`, never `as`.
+* The codec is total: a malformed value encodes to SQL `NULL`. Absence always
+* uses SQL `NULL`. A nullable-only column also uses SQL `NULL` for explicit
+* `null`; an optional-and-nullable column uses a storage-class sentinel so
+* absence and explicit `null` remain distinct.
 *
 * @param value - The JS value to store
-* @param type - The column's portable storage type
+* @param column - The declared storage and absence/null contract
 * @returns The value SQLite stores
 *
 * @example
 * ```ts
-* encodeValue(true, 'boolean') // 1
-* encodeValue({ a: 1 }, 'json') // '{"a":1}'
+* encodeValue(true, booleanColumn) // 1
+* encodeValue({ a: 1 }, jsonColumn) // '{"a":1}'
 * ```
 */
-function encodeValue(value, type) {
-	switch (type) {
-		case "boolean": return value === void 0 || value === null ? null : value === true ? 1 : 0;
-		case "json": return value === void 0 || value === null ? null : JSON.stringify(value);
-		case "integer":
-		case "real": return typeof value === "number" || typeof value === "bigint" ? value : null;
+function encodeValue(value, column) {
+	if (value === void 0) return null;
+	if (value === null) {
+		if (!column.nullable) return null;
+		if (!column.optional) return null;
+		return column.storage === "text" || column.storage === "json" ? /* @__PURE__ */ new Uint8Array() : String(null);
+	}
+	switch (column.storage) {
+		case "boolean": return typeof value === "boolean" ? value ? 1 : 0 : null;
+		case "json": try {
+			return JSON.stringify(cloneJSONValue(value));
+		} catch {
+			return null;
+		}
+		case "integer": return typeof value === "bigint" || typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) ? value : null;
+		case "real": return typeof value === "bigint" || typeof value === "number" && Number.isFinite(value) ? value : null;
 		case "text": return typeof value === "string" ? value : null;
 		case "blob": return value instanceof Uint8Array ? value : null;
 	}
 }
 /**
-* Decode a stored {@link SQLiteValue} back to its JS value for a column's type —
+* Decode a stored {@link SQLiteValue} back to its JS value for a declared column —
 * the exact inverse of {@link encodeValue}.
 *
 * @remarks
-* A `boolean` column reads `1` / `0` back to `true` / `false` (a stored `null`
-* → `undefined`); a `json` column `JSON.parse`s a string (anything else →
-* `undefined`); every other type passes the value through, mapping a stored
-* `NULL` to `undefined`. NULL decodes to `undefined` so {@link decodeRow} can
-* omit absent columns.
+* Stored values must use the declared SQLite storage class. SQL `NULL` decodes
+* to explicit `null` only for nullable-only columns and otherwise to absence.
+* Optional-and-nullable sentinels decode to explicit `null`; malformed values
+* decode to `undefined` so {@link decodeRow} omits them.
 *
 * @param value - The stored SQLite value
-* @param type - The column's portable storage type
-* @returns The decoded JS value (`undefined` for a stored `NULL`)
+* @param column - The declared storage and absence/null contract
+* @returns The decoded JS value, or `undefined` for absence/malformed storage
 *
 * @example
 * ```ts
-* decodeValue(1, 'boolean') // true
-* decodeValue('{"a":1}', 'json') // { a: 1 }
+* decodeValue(1, booleanColumn) // true
+* decodeValue('{"a":1}', jsonColumn) // { a: 1 }
 * ```
 */
-function decodeValue(value, type) {
-	switch (type) {
-		case "boolean": return value === null ? void 0 : value !== 0;
-		case "json": return typeof value === "string" ? JSON.parse(value) : void 0;
-		default: return value === null ? void 0 : value;
+function decodeValue(value, column) {
+	if (value === null) return column.nullable && !column.optional ? null : void 0;
+	if (column.optional && column.nullable && (column.storage === "text" || column.storage === "json" ? value instanceof Uint8Array && value.byteLength === 0 : value === String(null))) return null;
+	switch (column.storage) {
+		case "boolean":
+			if (value === 0 || value === 0n) return false;
+			if (value === 1 || value === 1n) return true;
+			return;
+		case "json":
+			if (typeof value !== "string") return void 0;
+			try {
+				return structuredClone(cloneJSONValue(JSON.parse(value)));
+			} catch {
+				return;
+			}
+		case "integer": return typeof value === "bigint" || typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) ? value : void 0;
+		case "real": return typeof value === "bigint" || typeof value === "number" && Number.isFinite(value) ? value : void 0;
+		case "text": return typeof value === "string" ? value : void 0;
+		case "blob": return value instanceof Uint8Array ? value : void 0;
 	}
 }
 /**
@@ -368,19 +326,49 @@ function decodeValue(value, type) {
 */
 function encodeRow(row, schema) {
 	const result = {};
-	for (const column of schema.columns) result[column.name] = encodeValue(row[column.name], column.type);
+	for (const column of schema.columns) result[column.name] = encodeValue(row[column.name], column);
 	return result;
 }
 /**
+* Extract a stored row's values in a declared positional order.
+*
+* @remarks
+* SQLite statements bind arrays positionally. Every requested column must be
+* present in `row`; an incomplete backend row is a typed `DRIVER` fault carrying
+* the table and missing column in its context.
+*
+* @param row - The stored SQLite row
+* @param names - The column names in binding order
+* @param table - The owning table name for fault context
+* @returns The row values in the same order as `names`
+* @throws A `DRIVER` {@link DatabaseError} when a requested column is missing
+*
+* @example
+* ```ts
+* extractValues({ id: 'u1', age: 36 }, ['age', 'id'], 'users') // [36, 'u1']
+* ```
+*/
+function extractValues(row, names, table) {
+	const values = [];
+	for (const name of names) {
+		const value = row[name];
+		if (value === void 0) throw new DatabaseError("DRIVER", "SQLite row is missing a declared column", {
+			table,
+			column: name
+		});
+		values.push(value);
+	}
+	return values;
+}
+/**
 * Decode 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
 * whose decoded value is `undefined` — so an absent / `NULL` optional column does
 * not surface as `{ bio: undefined }`, matching how the contract's optional
-* columns expect absence. A known, documented edge: a non-optional `nullableShape`
-* column storing `null` round-trips to absent (a `null` cell decodes to
-* `undefined`, and an `undefined` value is omitted).
+* columns expect absence. Nullable-only SQL `NULL` cells remain explicit
+* `null`; optional-and-nullable columns use their storage-class sentinel.
 *
 * @param row - The stored SQLite row
 * @param schema - The table's schema
@@ -394,37 +382,16 @@ function encodeRow(row, schema) {
 function decodeRow(row, schema) {
 	const result = {};
 	for (const column of schema.columns) {
-		const decoded = decodeValue(row[column.name], column.type);
+		const value = row[column.name];
+		if (value === void 0) continue;
+		const decoded = decodeValue(value, column);
 		if (decoded !== void 0) result[column.name] = decoded;
 	}
 	return result;
 }
 /**
-* Project a {@link TableSchema} to the `CREATE TABLE IF NOT EXISTS` statement a
-* SQLite driver's `open` issues for it.
-*
-* @remarks
-* Each column compiles to `<quoted name> <columnSQL(type)>`; the statement ends
-* with `PRIMARY KEY (<quoted primary>)`. No `NOT NULL` is emitted — the contract
-* validates required-ness, the database is just storage (AGENTS §14).
-*
-* @param schema - The table's schema
-* @returns The `CREATE TABLE IF NOT EXISTS …` statement
-*
-* @example
-* ```ts
-* schemaToTable(schema)
-* // 'CREATE TABLE IF NOT EXISTS "users" ("id" TEXT, "age" INTEGER, PRIMARY KEY ("id"))'
-* ```
-*/
-function schemaToTable(schema) {
-	const columns = schema.columns.map((column) => quote(column.name) + " " + columnSQL(column.type));
-	return "CREATE TABLE IF NOT EXISTS " + quote(schema.name) + " (" + columns.join(", ") + ", PRIMARY KEY (" + quote(schema.primary) + "))";
-}
-/**
 * Build a collision-free SQL index name for a table + column-group index —
-* shared by {@link schemaToIndexes} (an `open`-time `CREATE INDEX`) and
-* {@link stepToSQL}'s `index.add` / `index.remove` (a migration-time DDL),
+* shared by the compiler module's `schemaToIndexes` and `stepToSQL`,
 * so a plan-built index name always matches one `open` would have created.
 *
 * @remarks
@@ -440,120 +407,64 @@ function schemaToTable(schema) {
 *
 * @example
 * ```ts
-* indexName('users', ['name']) // 'idx_5_users_4_name'
-* indexName('a_b', ['c']) // 'idx_3_a_b_1_c'
-* indexName('a', ['b', 'c']) // 'idx_1_a_1_b_1_c'
+* deriveSQLiteIndexName('users', ['name']) // 'idx_5_users_4_name'
+* deriveSQLiteIndexName('a_b', ['c']) // 'idx_3_a_b_1_c'
+* deriveSQLiteIndexName('a', ['b', 'c']) // 'idx_1_a_1_b_1_c'
 * ```
 */
-function indexName(table, columns) {
+function deriveSQLiteIndexName(table, columns) {
 	return "idx_" + [table, ...columns].map((part) => String(part.length) + "_" + part).join("_");
 }
+//#endregion
+//#region src/server/compilers.ts
 /**
-* Project a {@link TableSchema} to the `CREATE INDEX IF NOT EXISTS` statements a
-* SQLite driver's `open` issues for its declared indexes.
+* Map a portable {@link ColumnStorage} to its SQLite column type.
 *
-* @remarks
-* One statement per index group; the index name is built by {@link indexName}
-* (collision-free and deterministic), matching the driver's naming so a
-* repeated `open` is idempotent.
-*
-* @param schema - The table's schema
-* @returns One `CREATE INDEX IF NOT EXISTS …` statement per declared index
-*
-* @example
-* ```ts
-* schemaToIndexes(schema)
-* // ['CREATE INDEX IF NOT EXISTS "idx_5_users_4_name" ON "users" ("name")']
-* ```
+* @param storage - The portable column type
+* @returns The SQLite column type keyword
 */
-function schemaToIndexes(schema) {
-	return schema.indexes.map((group) => "CREATE INDEX IF NOT EXISTS " + quote(indexName(schema.name, group)) + " ON " + quote(schema.name) + " (" + group.map(quote).join(", ") + ")");
+function compileColumnSQL(storage) {
+	switch (storage) {
+		case "text":
+		case "json": return "TEXT";
+		case "integer":
+		case "boolean": return "INTEGER";
+		case "real": return "REAL";
+		case "blob": return "BLOB";
+	}
 }
 /**
-* Project one {@link MigrationStep} to the DDL statement(s) a SQLite driver's
-* `migrate` executes for it.
-*
-* @remarks
-* `table.add` emits the `CREATE TABLE` plus one `CREATE INDEX` per declared
-* index (via {@link schemaToTable} / {@link schemaToIndexes}); `table.remove`
-* emits `DROP TABLE IF EXISTS`; `column.add` / `column.remove` emit `ALTER
-* TABLE … ADD COLUMN` / `… DROP COLUMN`; `index.add` / `index.remove` emit
-* `CREATE INDEX IF NOT EXISTS` / `DROP INDEX IF EXISTS`, naming the index the
-* same way `schemaToIndexes` does (`idx_<table>_<columns joined by _>`) so a
-* plan-built index matches one `open` would have created. Whether the named
-* table actually exists is the caller's concern (a driver's `migrate` checks
-* its own declared schema before running these statements) — this projection
-* is pure and never inspects live state.
-*
-* @param step - The migration step to project
-* @returns The DDL statement(s) that apply the step
+* Compile a {@link FieldPath} to the SQL expression that reads it.
 *
-* @example
-* ```ts
-* stepToSQL({ operation: 'column.remove', table: 'users', column: 'legacy' })
-* // ['ALTER TABLE "users" DROP COLUMN "legacy"']
-* ```
+* @param path - The field path
+* @returns The SQL expression selecting the value
 */
-function stepToSQL(step) {
-	switch (step.operation) {
-		case "table.add": return [schemaToTable(step.table), ...schemaToIndexes(step.table)];
-		case "table.remove": return ["DROP TABLE IF EXISTS " + quote(step.table)];
-		case "column.add": return ["ALTER TABLE " + quote(step.table) + " ADD COLUMN " + quote(step.column.name) + " " + columnSQL(step.column.type)];
-		case "column.remove": return ["ALTER TABLE " + quote(step.table) + " DROP COLUMN " + quote(step.column)];
-		case "index.add": return ["CREATE INDEX IF NOT EXISTS " + quote(indexName(step.table, step.index)) + " ON " + quote(step.table) + " (" + step.index.map(quote).join(", ") + ")"];
-		case "index.remove": return ["DROP INDEX IF EXISTS " + quote(indexName(step.table, step.index))];
-	}
+function compileFieldSQL(path) {
+	if (isString(path)) return quoteIdentifier(path);
+	const [column, ...nested] = path;
+	if (column === void 0) throw new DatabaseError("VALIDATION", "A field path must contain at least one column");
+	const rest = nested.map((key) => "." + key.replaceAll("'", "''")).join("");
+	return "json_extract(" + quoteIdentifier(column) + ", '$" + rest + "')";
 }
 /**
-* Project one {@link MigrationStep} onto its table's declared {@link TableSchema}
-* — the bookkeeping counterpart to {@link stepToSQL} (which projects the DDL a
-* driver's `migrate` runs against the live database).
-*
-* @remarks
-* `column.add` / `column.remove` add / filter the named column;
-* `index.add` / `index.remove` add / filter the matching index group (an exact
-* ordered match on `index`). `table.add` / `table.remove` act on a WHOLE
-* schema map rather than one table's shape, so they are the caller's concern
-* (a driver's `migrate` applies them directly against its table map) — passed
-* here, they return `schema` unchanged.
-*
-* @param schema - The table's current declared schema
-* @param step - The migration step to project onto it
-* @returns The table's schema after the step
+* Compile an {@link AggregateOperation} over a {@link FieldPath}.
 *
-* @example
-* ```ts
-* stepToSchema(schema, { operation: 'column.remove', table: 'users', column: 'legacy' })
-* // schema with the 'legacy' column dropped from `columns`
-* ```
+* @param operation - The aggregate to compute
+* @param column - The column or nested path to aggregate
+* @returns The SQL aggregate expression
 */
-function stepToSchema(schema, step) {
-	switch (step.operation) {
-		case "column.add": return {
-			...schema,
-			columns: [...schema.columns, step.column]
-		};
-		case "column.remove": return {
-			...schema,
-			columns: schema.columns.filter((column) => column.name !== step.column)
-		};
-		case "index.add": return {
-			...schema,
-			indexes: [...schema.indexes, step.index]
-		};
-		case "index.remove": return {
-			...schema,
-			indexes: schema.indexes.filter((group) => !(group.length === step.index.length && group.every((name, position) => name === step.index[position])))
-		};
-		case "table.add":
-		case "table.remove": return schema;
+function compileAggregateSQL(operation, column) {
+	switch (operation) {
+		case "count": return "COUNT(*)";
+		case "sum": return "SUM(" + compileFieldSQL(column) + ")";
+		case "average": return "AVG(" + compileFieldSQL(column) + ")";
+		case "minimum": return "MIN(" + compileFieldSQL(column) + ")";
+		case "maximum": return "MAX(" + compileFieldSQL(column) + ")";
 	}
 }
-//#endregion
-//#region src/server/compilers.ts
 /**
 * Compile a NESTED {@link FieldPath} to the `json_type(<col>, <path>)` SQL
-* expression — the {@link fieldColumn} `json_extract` sibling used to tell a
+* 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`
 * through `json_extract`, but `json_type` reports `'null'` for the former and
 * SQL `NULL` for the latter).
@@ -563,12 +474,14 @@ function stepToSchema(schema, step) {
 *
 * @example
 * ```ts
-* jsonTypeColumn(['payload', 'user', 'id']) // "json_type(\"payload\", '$.user.id')"
+* compileJSONTypeSQL(['payload', 'user', 'id']) // "json_type(\"payload\", '$.user.id')"
 * ```
 */
-function jsonTypeColumn(path) {
-	const rest = path.slice(1).map((key) => "." + key.replaceAll("'", "''")).join("");
-	return "json_type(" + quote(path[0]) + ", '$" + rest + "')";
+function compileJSONTypeSQL(path) {
+	const [column, ...nested] = path;
+	if (column === void 0) throw new DatabaseError("VALIDATION", "A field path must contain at least one column");
+	const rest = nested.map((key) => "." + key.replaceAll("'", "''")).join("");
+	return "json_type(" + quoteIdentifier(column) + ", '$" + rest + "')";
 }
 /**
 * Escape `\`, `%`, and `_` (each with a leading `\`) so a `starts` / `ends`
@@ -590,15 +503,15 @@ function escapeLike(text) {
 *
 * @param column - The column name
 * @param schema - The table's schema
-* @returns The column's {@link ColumnType}, or `undefined` if the schema does not carry it
+* @returns The column's {@link ColumnStorage}, or `undefined` if the schema does not carry it
 *
 * @example
 * ```ts
-* declaredType('age', schema) // 'integer'
+* findColumnStorage('age', schema) // 'integer'
 * ```
 */
-function declaredType(column, schema) {
-	return schema.columns.find((candidate) => candidate.name === column)?.type;
+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
@@ -613,15 +526,15 @@ function declaredType(column, schema) {
 * edge of comparing against a json subtree).
 *
 * @param value - The runtime operand value
-* @returns The {@link ColumnType} to encode it as
+* @returns The {@link ColumnStorage} to encode it as
 *
 * @example
 * ```ts
-* valueType(true) // 'boolean'
-* valueType(9) // 'integer'
+* inferValueStorage(true) // 'boolean'
+* inferValueStorage(9) // 'integer'
 * ```
 */
-function valueType(value) {
+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";
@@ -629,7 +542,7 @@ function valueType(value) {
 	return "text";
 }
 /**
-* Compile one condition to its `<column> <operator>` SQL fragment and the params
+* Compile one condition to its `<column> <operator>` SQL fragment and the parameters
 * it binds — engine-exact under SQL's three-valued NULL logic.
 *
 * @remarks
@@ -639,7 +552,7 @@ function valueType(value) {
 * 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 params.
+* 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
@@ -667,13 +580,11 @@ function valueType(value) {
 * absent                | true                           | true                      | false
 * ```
 *
-* Because a flat column's `NULL` always decodes to `undefined`, `equals`
-* against a `null` operand needs no special flat compilation (`col = ?`
-* binding a `NULL` param is already always-false in SQL, matching "no match"
-* above) — but flat `not` against `null` must match EVERY row (both the
-* absent and the scalar rows), which `col != ? OR col IS NULL` cannot express
-* (it only catches the `IS NULL` row), so a flat `not`-with-`null`-operand
-* compiles to the constant `1`.
+* A flat SQL `NULL` represents absence or explicit null according to its
+* {@link ColumnSchema}; optional-and-nullable columns use a storage-class
+* sentinel to distinguish the two. The native exactness gate therefore
+* 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
@@ -693,135 +604,142 @@ function valueType(value) {
 *
 * @example
 * ```ts
-* fragment({ column: 'age', operator: 'above', values: [18], connector: 'and' }, schema)
-* // { sql: '"age" > ?', params: [18] }
-* fragment({ column: 'age', operator: 'below', values: [18], connector: 'and' }, schema)
-* // { sql: '("age" < ? OR "age" IS NULL)', params: [18] }
+* compileConditionSQL({ column: 'age', operator: 'above', values: [18], connector: 'and' }, schema)
+* // { sql: '"age" > ?', parameters: [18] }
+* compileConditionSQL({ column: 'age', operator: 'below', values: [18], connector: 'and' }, schema)
+* // { sql: '("age" < ? OR "age" IS NULL)', parameters: [18] }
 * ```
 */
-function fragment(condition, schema) {
-	const column = fieldColumn(condition.column);
+function compileConditionSQL(condition, schema) {
+	const column = compileFieldSQL(condition.column);
 	const nested = !isString(condition.column);
-	const declared = isString(condition.column) ? declaredType(condition.column, schema) : void 0;
-	const encode = (value) => encodeValue(value, nested ? valueType(value) : declared ?? "json");
+	const declared = isString(condition.column) ? schema.columns.find((candidate) => candidate.name === condition.column) : void 0;
 	const first = condition.values[0];
 	const second = condition.values[1];
 	const nullOperand = first === null || first === void 0;
-	const jsonType = !isString(condition.column) ? jsonTypeColumn(condition.column) : "";
+	const jsonType = !isString(condition.column) ? compileJSONTypeSQL(condition.column) : "";
+	let sql;
+	let values;
 	switch (condition.operator) {
 		case "equals":
 			if (nullOperand && nested) return {
 				sql: jsonType + " = 'null'",
-				params: []
-			};
-			return {
-				sql: column + " = ?",
-				params: [encode(first)]
+				parameters: []
 			};
+			sql = column + " = ?";
+			values = [first];
+			break;
 		case "not":
 			if (nullOperand) {
 				if (nested) return {
 					sql: "(" + jsonType + " IS NULL OR " + jsonType + " != 'null')",
-					params: []
+					parameters: []
 				};
 				return {
 					sql: "1",
-					params: []
+					parameters: []
 				};
 			}
-			return {
-				sql: "(" + column + " != ? OR " + column + " IS NULL)",
-				params: [encode(first)]
-			};
-		case "above": return {
-			sql: column + " > ?",
-			params: [encode(first)]
-		};
-		case "below": return {
-			sql: "(" + column + " < ? OR " + column + " IS NULL)",
-			params: [encode(first)]
-		};
-		case "from": return {
-			sql: column + " >= ?",
-			params: [encode(first)]
-		};
-		case "to": return {
-			sql: "(" + column + " <= ? OR " + column + " IS NULL)",
-			params: [encode(first)]
-		};
-		case "between": return {
-			sql: column + " BETWEEN ? AND ?",
-			params: [encode(first), encode(second)]
-		};
-		case "like": return {
-			sql: column + " LIKE ?",
-			params: [encode(first)]
-		};
-		case "glob": return {
-			sql: column + " GLOB ?",
-			params: [encode(first)]
-		};
+			sql = "(" + column + " != ? OR " + column + " IS NULL)";
+			values = [first];
+			break;
+		case "above":
+			sql = column + " > ?";
+			values = [first];
+			break;
+		case "below":
+			sql = "(" + column + " < ? OR " + column + " IS NULL)";
+			values = [first];
+			break;
+		case "from":
+			sql = column + " >= ?";
+			values = [first];
+			break;
+		case "to":
+			sql = "(" + column + " <= ? OR " + column + " IS NULL)";
+			values = [first];
+			break;
+		case "between":
+			sql = column + " BETWEEN ? AND ?";
+			values = [first, second];
+			break;
+		case "like":
+			sql = column + " LIKE ?";
+			values = [first];
+			break;
+		case "glob":
+			sql = column + " GLOB ?";
+			values = [first];
+			break;
 		case "starts": {
 			const text = isString(first) ? first : "";
 			if (text === "") return {
 				sql: "typeof(" + column + ") = 'text'",
-				params: []
+				parameters: []
 			};
 			const length = Array.from(text).length;
-			return {
-				sql: "(typeof(" + column + ") = 'text' AND substr(" + column + ", 1, " + length + ") = ?)",
-				params: [encode(first)]
-			};
+			sql = "(typeof(" + column + ") = 'text' AND substr(" + column + ", 1, " + length + ") = ?)";
+			values = [first];
+			break;
 		}
 		case "ends": {
 			const text = isString(first) ? first : "";
 			if (text === "") return {
 				sql: "typeof(" + column + ") = 'text'",
-				params: []
+				parameters: []
 			};
 			const length = Array.from(text).length;
-			return {
-				sql: "(typeof(" + column + ") = 'text' AND substr(" + column + ", -" + length + ") = ?)",
-				params: [encode(first)]
-			};
+			sql = "(typeof(" + column + ") = 'text' AND substr(" + column + ", -" + length + ") = ?)";
+			values = [first];
+			break;
 		}
 		case "any":
 			if (condition.values.length === 0) return {
 				sql: "0",
-				params: []
-			};
-			return {
-				sql: column + " IN (" + condition.values.map(() => "?").join(", ") + ")",
-				params: condition.values.map(encode)
+				parameters: []
 			};
+			sql = column + " IN (" + condition.values.map(() => "?").join(", ") + ")";
+			values = condition.values;
+			break;
 		case "none":
 			if (condition.values.length === 0) return {
 				sql: "1",
-				params: []
-			};
-			return {
-				sql: "(" + column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ") OR " + column + " IS NULL)",
-				params: condition.values.map(encode)
+				parameters: []
 			};
+			sql = "(" + column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ") OR " + column + " IS NULL)";
+			values = condition.values;
+			break;
 		case "absent": return {
 			sql: column + " IS NULL",
-			params: []
+			parameters: []
 		};
 		case "present": return {
 			sql: column + " IS NOT NULL",
-			params: []
+			parameters: []
 		};
 	}
+	return {
+		sql,
+		parameters: values.map((value) => {
+			const storage = nested ? inferValueStorage(value) : declared?.storage ?? "json";
+			return encodeValue(value, declared ?? {
+				name: "",
+				storage,
+				optional: false,
+				nullable: false
+			});
+		})
+	};
 }
 /**
 * Fold the conditions into one WHERE clause, parenthesizing progressively
-* left-to-right so the grouping matches the engine's `matchesCriteria` fold.
+* 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 fragment}'s truth table) replicates the core
+* 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
-* clause matches `applyCriteria` row-for-row over the same table — a native
+* clause matches `applyQuery` row-for-row over the same table — a native
 * `records` / `count` read never disagrees with a scan-and-filter fallback.
 *
 * @param conditions - The conditions to fold
@@ -831,26 +749,27 @@ function fragment(condition, schema) {
 * @example
 * ```ts
 * compileWhere([{ column: 'age', operator: 'from', values: [18], connector: 'and' }], schema)
-* // { sql: 'WHERE "age" >= ?', params: [18] }
+* // { sql: 'WHERE "age" >= ?', parameters: [18] }
 * ```
 */
 function compileWhere(conditions, schema) {
-	if (conditions.length === 0) return {
+	const [first, ...remaining] = conditions;
+	if (first === void 0) return {
 		sql: "",
-		params: []
+		parameters: []
 	};
-	const head = fragment(conditions[0], schema);
+	const head = compileConditionSQL(first, schema);
 	let clause = head.sql;
-	const params = [...head.params];
-	for (let index = 1; index < conditions.length; index += 1) {
-		const next = fragment(conditions[index], schema);
-		const operator = conditions[index].connector === "or" ? "OR" : "AND";
+	const parameters = [...head.parameters];
+	for (const condition of remaining) {
+		const next = compileConditionSQL(condition, schema);
+		const operator = condition.connector === "or" ? "OR" : "AND";
 		clause = "(" + clause + " " + operator + " " + next.sql + ")";
-		params.push(...next.params);
+		parameters.push(...next.parameters);
 	}
 	return {
 		sql: "WHERE " + clause,
-		params
+		parameters
 	};
 }
 /**
@@ -880,8 +799,8 @@ function compileWhere(conditions, schema) {
 * ```
 */
 function compileOrder(order, schema) {
-	const terms = (order ?? []).map((term) => fieldColumn(term.column) + (term.direction === "descending" ? " DESC" : " ASC"));
-	if (!(order ?? []).some((term) => isString(term.column) && term.column === schema.primary)) terms.push(quote(schema.primary));
+	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(", ");
 }
 /**
@@ -897,29 +816,33 @@ function compileOrder(order, schema) {
 *
 * @example
 * ```ts
-* compilePage(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', params: [5] }
+* compilePage(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', parameters: [5] }
 * ```
 */
 function compilePage(limit, offset) {
+	validatePage({
+		...limit === void 0 ? {} : { limit },
+		...offset === void 0 ? {} : { offset }
+	});
 	if (limit !== void 0 && offset !== void 0) return {
 		sql: "LIMIT ? OFFSET ?",
-		params: [limit, offset]
+		parameters: [limit, offset]
 	};
 	if (limit !== void 0) return {
 		sql: "LIMIT ?",
-		params: [limit]
+		parameters: [limit]
 	};
 	if (offset !== void 0) return {
 		sql: "LIMIT -1 OFFSET ?",
-		params: [offset]
+		parameters: [offset]
 	};
 	return {
 		sql: "",
-		params: []
+		parameters: []
 	};
 }
 /**
-* Compile a {@link Criteria} into the SQL clause that follows a table name, with
+* Compile a {@link QueryInput} into the SQL clause that follows a table name, with
 * its bound parameters in clause order.
 *
 * @remarks
@@ -927,51 +850,163 @@ function compilePage(limit, offset) {
 * `[where, orderBy, limitOffset]` (each possibly empty) into one clause so a
 * `SELECT * FROM <table> <clause>` runs the whole read in the engine instead of
 * over a JS `scan`. The WHERE fold is parenthesized **left-to-right** to mirror
-* the core engine's `matchesCriteria` (not SQL's native AND-over-OR precedence),
+* 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
 * `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
-* collapsing to a constant. A `undefined` criteria (or one with no parts)
+* collapsing to a constant. An `undefined` input (or one with no parts)
 * compiles to an empty clause.
 *
-* @param criteria - The read specification, or `undefined` for all rows
+* @param input - The read specification, or `undefined` for all rows
 * @param schema - The table's schema (column types for operand encoding)
 * @returns The SQL tail and its bound parameters
 *
 * @example
 * ```ts
-* compileCriteria({ conditions: [{ column: 'age', operator: 'from', values: [18], connector: 'and' }] }, schema)
-* // { sql: 'WHERE "age" >= ? ORDER BY "id"', params: [18] }
+* compileQuerySQL({ conditions: [{ column: 'age', operator: 'from', values: [18], connector: 'and' }] }, schema)
+* // { sql: 'WHERE "age" >= ? ORDER BY "id"', parameters: [18] }
 * ```
 */
-function compileCriteria(criteria, schema) {
-	const where = compileWhere(criteria?.conditions ?? [], schema);
-	const orderBy = compileOrder(criteria?.order, schema);
-	const page = compilePage(criteria?.limit, criteria?.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);
 	return {
 		sql: [
 			where.sql,
 			orderBy,
 			page.sql
 		].filter((part) => part !== "").join(" "),
-		params: [...where.params, ...page.params]
+		parameters: [...where.parameters, ...page.parameters]
 	};
 }
+/**
+* Project a {@link TableSchema} to its `CREATE TABLE IF NOT EXISTS` statement.
+*
+* @param schema - The table schema
+* @returns The complete table declaration
+*/
+function schemaToTable(schema) {
+	const columns = schema.columns.map((column) => quoteIdentifier(column.name) + " " + compileColumnSQL(column.storage) + (column.optional || column.nullable ? "" : " NOT NULL"));
+	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.
+*
+* @param schema - The table schema
+* @returns One statement per declared index
+*/
+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.
+*
+* @param step - The migration step
+* @returns The statements that apply the step
+*/
+function stepToSQL(step) {
+	switch (step.operation) {
+		case "table.add": return [schemaToTable(step.table), ...schemaToIndexes(step.table)];
+		case "table.remove": return ["DROP TABLE IF EXISTS " + quoteIdentifier(step.table)];
+		case "column.add": return ["ALTER TABLE " + quoteIdentifier(step.table) + " ADD COLUMN " + quoteIdentifier(step.column.name) + " " + compileColumnSQL(step.column.storage) + (step.column.optional || step.column.nullable ? "" : " NOT NULL")];
+		case "column.remove": return ["ALTER TABLE " + quoteIdentifier(step.table) + " DROP COLUMN " + quoteIdentifier(step.column)];
+		case "index.add": return ["CREATE INDEX IF NOT EXISTS " + quoteIdentifier(deriveSQLiteIndexName(step.table, step.index)) + " ON " + quoteIdentifier(step.table) + " (" + step.index.map(quoteIdentifier).join(", ") + ")"];
+		case "index.remove": return ["DROP INDEX IF EXISTS " + quoteIdentifier(deriveSQLiteIndexName(step.table, step.index))];
+	}
+}
 //#endregion
-//#region src/server/constants.ts
+//#region src/core/DriverIterator.ts
 /**
-* The reserved metadata table the {@link SQLiteDriver} creates on `open` to
-* persist its stamped `DriverMeta` (`version` + declared schema JSON) — the
-* SQLite realization of the `meta` / `stamp` driver hooks.
+* The internal continuation boundary for a root driver async iterator.
 *
 * @remarks
-* A single-row table (`id = 1`). A user table named `_meta` collides with the
-* reservation — the caller's concern to avoid, documented on the driver class.
+* 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 META_TABLE = "_meta";
+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
 /**
@@ -979,229 +1014,619 @@ var META_TABLE = "_meta";
 * reference {@link MemoryDriver} plus file load / flush.
 *
 * @remarks
-* A decorator, not a reimplementation: every primitive delegates to an inner
-* {@link MemoryDriver}, so querying, key-order `scan` / `keys`, and capture-replay
-* `snapshot` are inherited unchanged — this layer adds only persistence. `open`
+* A decorator, not a reimplementation: storage primitives delegate to an inner
+* {@link MemoryDriver}, while this layer owns persistence, writer ordering,
+* isolated transactions, and queued row-snapshot restoration. `open`
 * loads the file into memory; every mutation (`write` / `delete` / `clear`) flushes
-* the whole store back. The file is one JSON object, `{ meta?: DriverMeta, tables: {
-* [name]: rows } }` — `meta` is present only once the store has been `stamp`ed
-* (an unstamped store serializes the old `{ tables }` shape, preserving
-* backward compatibility); a per-table array of rows, each row carrying its own
+* the whole store back. The file is one JSON object, `{ metadata?: DriverMetadata, tables: {
+* [name]: rows } }` — `metadata` is present only once the store has been `stamp`ed
+* (an unstamped store omits `metadata`); a per-table array of rows, each row carrying its own
 * 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 missing, corrupt, or wrong-shaped file starts
-* empty rather than throwing, and a malformed row (or malformed `meta`) is
-* skipped/dropped rather than thrown on. It is scan-only — it implements none of
-* the optional native `records` / `count` / `aggregate` hooks, so the core engine
+* never asserted (AGENTS §14). Only an `ENOENT` read starts empty; 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.
 *
-* A failure in the write path ({@link JSONDriver.#serialize} — `mkdir` /
-* `writeFile` / `rename`) is wrapped and rethrown as `DatabaseError` `DRIVER`,
-* carrying the target `path` in its context; the read path ({@link
-* JSONDriver.#load}) tolerance above is a separate, deliberate contract and is
-* never touched by this wrapping.
+* Metadata crosses {@link cloneDriverMetadata} at parsed-file ingress, public and
+* scoped write ingress, candidate/root publication, serialization, and copy-out.
+* Callers therefore cannot mutate queued metadata, and `metadata()` always returns a
+* distinct deeply frozen snapshot. A failure in the write path ({@link
+* JSONDriver.#serialize} — `mkdir` / `writeFile` / `rename`) is wrapped and
+* rethrown as `DatabaseError` `DRIVER`, carrying the target `path` and native
+* `cause` in its context. If temporary-file cleanup also fails, the top-level
+* `DRIVER` context additionally carries `temp` and `cleanup`; a precommit abort
+* remains an `ABORTED` `DatabaseError` in `context.cause`. The fail-closed read path
+* ({@link JSONDriver.#document}) remains separate from this write-error contract.
 */
 var JSONDriver = class {
 	#path;
 	#memory = new MemoryDriver();
+	#identities = /* @__PURE__ */ new Map();
 	#schema = [];
-	#meta;
+	#metadata;
 	#flushCount = 0;
 	#chain = Promise.resolve();
-	#deferring = false;
+	#transaction;
+	#candidate;
+	#candidateIdentities;
+	#candidateSchema;
 	constructor(path) {
 		this.#path = path;
 	}
 	async open(schema) {
-		this.#schema = schema;
-		await this.#memory.open(schema);
-		await this.#load();
+		this.#root();
+		const owned = normalizeDriverSchema(schema);
+		await this.#enqueue(() => this.#open(owned));
 	}
 	async close() {
+		this.#root();
+		await this.#chain;
 		await this.#memory.close();
 	}
 	async read(table, key) {
+		this.#root();
+		await this.#chain;
 		return this.#memory.read(table, key);
 	}
-	async write(table, key, row) {
-		await this.#memory.write(table, key, row);
-		if (!this.#deferring) await this.#flush();
+	async write(table, key, row, options) {
+		this.#root();
+		await this.#enqueue(() => this.#write(table, key, row, options), options?.signal);
+	}
+	async insert(table, key, row, options) {
+		this.#root();
+		await this.#enqueue(() => this.#insert(table, key, row, options), options?.signal);
 	}
-	async delete(table, key) {
-		const removed = await this.#memory.delete(table, key);
-		if (!this.#deferring) await this.#flush();
-		return removed;
+	async delete(table, key, options) {
+		this.#root();
+		return this.#enqueue(() => this.#delete(table, key, options), options?.signal);
 	}
-	keys(table) {
+	async keys(table) {
+		this.#root();
+		await this.#chain;
 		return this.#memory.keys(table);
 	}
 	scan(table) {
-		return this.#memory.scan(table);
+		return new DriverIterator(this.#scan(table)[Symbol.asyncIterator](), () => this.#root());
 	}
 	/**
 	* Natively filtered lazy iteration — delegates to the inner {@link MemoryDriver}.
 	*
 	* @remarks
-	* Semantics are the memory driver's own: `criteria.conditions` filters, `offset`
-	* / `limit` page lazily, and `criteria.order` is ignored (streaming yields key
+	* Semantics are the memory driver's own: `input.conditions` filters, `offset`
+	* / `limit` page lazily, and `input.order` is ignored (streaming yields key
 	* order; sorted output is `records()`'s job).
 	*
 	* @param table - The table to stream
-	* @param criteria - The filter / offset / limit to apply lazily
+	* @param input - The filter / offset / limit to apply lazily
 	*/
-	stream(table, criteria) {
-		return this.#memory.stream(table, criteria);
+	stream(table, input) {
+		validatePage(input);
+		return new DriverIterator(this.#stream(table, input)[Symbol.asyncIterator](), () => this.#root());
 	}
 	async clear(table) {
-		await this.#memory.clear(table);
-		if (!this.#deferring) await this.#flush();
+		this.#root();
+		await this.#enqueue(() => this.#clear(table));
 	}
 	/**
-	* Begin a native transaction — flush-coalescing over the inner {@link MemoryDriver}.
+	* Run an isolated native transaction callback over a candidate memory store.
 	*
 	* @remarks
-	* Single-writer: throws `DatabaseError` `CONFLICT` if a transaction is already
-	* active — this driver does not support nesting. On begin, captures the inner
-	* memory rollback thunk via `#memory.snapshot()` and suppresses per-mutation
-	* `#flush` — `write` / `delete` / `clear` still mutate memory but no longer
-	* touch the file, so N mutations under the handle cost ONE file write instead
-	* of N. `commit()` releases the suppression and performs that one atomic
-	* `#flush()`, persisting the transaction's net state. `rollback()` restores
-	* memory via the captured snapshot thunk, then `#flush()`s so the file reflects
-	* the restored state. Outside a transaction, behavior is unchanged — every
-	* mutation flushes on its own. Calling `commit` / `rollback` a second time (on
-	* either method, in either order) throws `DatabaseError` `CONFLICT`.
+	* Single-writer: nesting and root operations while active throw `CONFLICT`.
+	* The callback receives a capability over cloned rows, schema, and metadata.
+	* Fulfillment atomically serializes that candidate and publishes it to root
+	* memory only after file replacement succeeds. Rejection or persistence
+	* failure discards the candidate, and every captured capability call after
+	* settlement throws `CONFLICT`.
 	*
-	* @returns A {@link TransactionInterface} handle to `commit` or `rollback`
+	* @returns The callback's resolved value
 	*/
-	async transaction() {
-		if (this.#deferring) throw new DatabaseError("CONFLICT", "A transaction is already active on this driver", {});
-		const rollback = await this.#memory.snapshot();
-		this.#deferring = true;
-		let settled = false;
-		return {
-			commit: async () => {
-				if (settled) throw new DatabaseError("CONFLICT", "Transaction already settled", {});
-				settled = true;
-				this.#deferring = false;
-				await this.#flush();
-			},
-			rollback: async () => {
-				if (settled) throw new DatabaseError("CONFLICT", "Transaction already settled", {});
-				settled = true;
-				await rollback();
-				this.#deferring = false;
-				await this.#flush();
-			}
-		};
+	async transaction(scope) {
+		this.#root();
+		return this.#enqueue(() => this.#transact(scope));
 	}
+	/**
+	* Capture an owned row snapshot at an exact writer-queue position.
+	*
+	* @remarks
+	* Capture owns table names, schemas, rows, and one session-local identity per
+	* table. Rollback is repeatable: it clones the then-current root into a
+	* candidate, adapts captured rows to each surviving same-identity table
+	* through the portable migration engine, persists the candidate with current
+	* metadata, and publishes memory only after file replacement succeeds.
+	* Removed, replaced, uncaptured, and later-added tables remain untouched.
+	*
+	* @param tables - Existing tables to capture; omitted captures every current table
+	* @returns A repeatable rollback operation
+	*/
 	async snapshot(tables) {
-		const rollback = await this.#memory.snapshot(tables);
+		this.#root();
+		const names = tables === void 0 ? void 0 : [...tables];
+		const captured = await this.#enqueue(() => this.#capture(names));
 		return async () => {
-			await rollback();
-			await this.#flush();
+			this.#root();
+			await this.#enqueue(() => this.#restore(captured));
 		};
 	}
-	async meta() {
-		return this.#meta;
+	async metadata() {
+		this.#root();
+		await this.#chain;
+		return this.#metadata === void 0 ? void 0 : cloneDriverMetadata(this.#metadata);
 	}
 	/**
-	* Persist `meta` verbatim for a later `meta()` to return.
+	* Persist an owned metadata snapshot for a later `metadata()` to copy out.
 	*
 	* @remarks
-	* Respects the same defer-flush suppression as `write` / `delete` / `clear`
-	* (see {@link JSONDriver.transaction} @remarks) — stamping inside an active
-	* transaction updates memory but does not flush until the transaction settles.
+	* Root stamping conflicts while a transaction is active. The scoped
+	* {@link StorageInterface.stamp} updates candidate metadata and publishes
+	* with the candidate rows on callback fulfillment.
 	*
-	* @param meta - The {@link DriverMeta} to persist
+	* @param metadata - The {@link DriverMetadata} to persist
 	*/
-	async stamp(meta) {
-		this.#meta = meta;
-		if (!this.#deferring) await this.#flush();
+	async stamp(metadata) {
+		this.#root();
+		const owned = cloneDriverMetadata(metadata);
+		await this.#enqueue(() => this.#stamp(owned));
 	}
 	/**
-	* Apply a {@link Migration} plan by delegating to the inner {@link MemoryDriver},
-	* then persist the migrated state.
+	* Apply one atomic {@link MigrationInput} through an isolated candidate.
 	*
 	* @remarks
-	* The inner `MemoryDriver.migrate` applies each step (adding/removing tables,
-	* adding/removing columns from stored rows, no-op index steps) and throws
-	* `DatabaseError` `MIGRATION` for a step referencing an unknown table — that
-	* error propagates untouched. `table.add` / `table.remove` steps also update
-	* this driver's own declared `#schema`, mirroring the bookkeeping `open` does,
-	* so a subsequent `#flush` / `#load` round-trip includes (or drops) the table.
-	* A successful migration ends with one atomic `#flush()` so the new state
-	* survives a close and reopen. A multi-step plan applies its steps
-	* sequentially and is NOT atomic — a failure partway through a plan leaves
-	* the earlier steps already applied.
+	* The candidate receives every plan step plus optional metadata. Its complete
+	* rows, derived schema, and metadata serialize through one atomic file
+	* replacement before root memory changes. Any migration or persistence failure
+	* therefore leaves root state and the prior file exact.
 	*
-	* @param plan - The migration plan to apply
+	* @param input - The plan and optional metadata to settle together
 	*/
-	async migrate(plan) {
-		await this.#memory.migrate?.(plan);
-		let schema = this.#schema;
-		for (const step of plan.steps) if (step.operation === "table.add") schema = schema.some((table) => table.name === step.table.name) ? schema : [...schema, step.table];
-		else if (step.operation === "table.remove") schema = schema.filter((table) => table.name !== step.table);
-		this.#schema = schema;
-		await this.#flush();
+	async migrate(input) {
+		this.#root();
+		const owned = cloneMigrationInput(input);
+		await this.#enqueue(() => this.#migrate(owned));
 	}
-	async #load() {
-		let raw;
-		try {
-			raw = await readFile(this.#path, "utf-8");
-		} catch {
-			return;
+	async *#scan(table) {
+		await this.#chain;
+		for await (const row of this.#memory.scan(table)) yield row;
+	}
+	async *#stream(table, input) {
+		await this.#chain;
+		for await (const row of this.#memory.stream(table, input)) yield row;
+	}
+	async #open(declared) {
+		const parsed = await this.#document();
+		let stored;
+		let tables;
+		if (parsed === void 0) {
+			const fresh = {};
+			for (const table of declared) fresh[table.name] = [];
+			tables = fresh;
+		} else {
+			if (!isRecord(parsed) || !Object.hasOwn(parsed, "tables") || Object.keys(parsed).some((key) => key !== "tables" && key !== "metadata")) throw new DatabaseError("DRIVER", "Stored JSON database document is invalid", {
+				path: this.#path,
+				aspect: "document"
+			});
+			if (!isRecord(parsed.tables)) throw new DatabaseError("DRIVER", "Stored JSON tables are invalid", {
+				path: this.#path,
+				aspect: "tables"
+			});
+			tables = parsed.tables;
+			if (Object.hasOwn(parsed, "metadata")) try {
+				stored = cloneDriverMetadata(parsed.metadata);
+			} catch {
+				const cause = new DatabaseError("VALIDATION", "Stored JSON metadata failed validation", { path: "metadata" });
+				throw new DatabaseError("DRIVER", "Stored JSON metadata is invalid", {
+					path: this.#path,
+					aspect: "metadata",
+					cause
+				});
+			}
 		}
-		let parsed;
+		const schema = normalizeDriverSchema(stored?.schema ?? declared);
+		const names = new Set(schema.map((table) => table.name));
+		for (const table of schema) if (!Object.hasOwn(tables, table.name)) throw new DatabaseError("DRIVER", "Stored JSON table set is invalid", {
+			path: this.#path,
+			table: table.name,
+			aspect: "missing"
+		});
+		const unknown = Object.keys(tables).filter((name) => !names.has(name)).length;
+		if (unknown > 0) throw new DatabaseError("DRIVER", "Stored JSON table set is invalid", {
+			path: this.#path,
+			aspect: "unknown",
+			count: unknown
+		});
+		const memory = new MemoryDriver();
+		await memory.open(schema);
+		await this.#hydrate(memory, schema, tables);
+		if (stored !== void 0) await memory.stamp(stored);
+		this.#memory = memory;
+		this.#schema = schema;
+		this.#identities = this.#alignIdentities(schema);
+		const metadata = await memory.metadata();
+		this.#metadata = metadata === void 0 ? void 0 : cloneDriverMetadata(metadata);
+	}
+	async #migrate(input) {
+		const candidate = await this.#clone();
+		const identities = this.#projectIdentities(this.#identities, input.plan.steps);
+		const schema = await this.#apply(candidate, this.#schema, input);
+		const metadata = await candidate.metadata();
+		await this.#serialize(void 0, candidate, schema, metadata);
+		this.#memory = candidate;
+		this.#identities = identities;
+		this.#schema = schema;
+		this.#metadata = metadata === void 0 ? void 0 : cloneDriverMetadata(metadata);
+	}
+	async #apply(memory, current, input) {
+		const schema = projectMigrationSchema(current, input.plan.steps);
+		if (input.metadata !== void 0 && !equalsValue(normalizeDriverSchema(input.metadata.schema), schema)) throw new DatabaseError("MIGRATION", "Migration metadata schema does not match the plan", {
+			projected: schema,
+			metadata: input.metadata.schema
+		});
+		await memory.migrate(input);
+		return schema;
+	}
+	async #transact(scope) {
+		this.#root();
+		const candidate = await this.#clone();
+		const token = {};
+		this.#transaction = token;
+		this.#candidate = candidate;
+		this.#candidateIdentities = new Map(this.#identities);
+		this.#candidateSchema = this.#schema;
 		try {
-			parsed = JSON.parse(raw);
-		} catch {
-			return;
-		}
-		if (!isRecord(parsed) || !isRecord(parsed.tables)) return;
-		const tables = parsed.tables;
-		for (const table of this.#schema) {
-			const rows = tables[table.name];
-			if (!Array.isArray(rows)) continue;
-			for (const entry of rows) {
-				if (!isRecord(entry)) continue;
-				const key = extractKey(entry, table.primary);
-				if (key === void 0) continue;
-				await this.#memory.write(table.name, key, entry);
+			const value = await scope(this.#capability(token));
+			const schema = this.#candidateSchema;
+			const identities = this.#candidateIdentities;
+			if (schema === void 0 || identities === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+			this.#candidate = void 0;
+			this.#candidateIdentities = void 0;
+			this.#candidateSchema = void 0;
+			const metadata = await candidate.metadata();
+			await this.#serialize(void 0, candidate, schema, metadata);
+			this.#memory = candidate;
+			this.#identities = identities;
+			this.#schema = schema;
+			this.#metadata = metadata === void 0 ? void 0 : cloneDriverMetadata(metadata);
+			return value;
+		} finally {
+			if (this.#transaction === token) {
+				this.#transaction = void 0;
+				this.#candidate = void 0;
+				this.#candidateIdentities = void 0;
+				this.#candidateSchema = void 0;
 			}
 		}
-		if (isDriverMeta(parsed.meta)) this.#meta = parsed.meta;
 	}
-	async #flush() {
-		const next = this.#chain.then(() => this.#serialize());
-		this.#chain = next.catch(() => {});
-		await next;
+	async #clone() {
+		const candidate = new MemoryDriver();
+		await candidate.open(this.#schema);
+		for (const table of this.#schema) for await (const row of this.#memory.scan(table.name)) {
+			const key = extractKey(row, table.primary);
+			if (key !== void 0) await candidate.write(table.name, key, row);
+		}
+		if (this.#metadata !== void 0) await candidate.stamp(cloneDriverMetadata(this.#metadata));
+		return candidate;
 	}
-	async #serialize() {
-		const tables = {};
+	async #capture(names) {
+		const selected = names === void 0 ? void 0 : new Set(names);
+		const captured = /* @__PURE__ */ new Map();
 		for (const table of this.#schema) {
+			if (selected !== void 0 && !selected.has(table.name)) continue;
+			const identity = this.#identities.get(table.name);
+			if (identity === void 0) continue;
 			const rows = [];
 			for await (const row of this.#memory.scan(table.name)) rows.push(row);
-			tables[table.name] = rows;
+			captured.set(table.name, {
+				identity,
+				schema: table,
+				rows
+			});
+		}
+		return captured;
+	}
+	async #restore(captured) {
+		const replacements = /* @__PURE__ */ new Map();
+		for (const [name, capture] of captured) {
+			const current = this.#schema.find((table) => table.name === name);
+			if (current === void 0 || this.#identities.get(name) !== capture.identity) continue;
+			const plan = planMigration([capture.schema], [current]);
+			const migrated = migrateRows(capture.rows, plan.steps);
+			if (migrated.length !== capture.rows.length) throw new DatabaseError("MIGRATION", "Snapshot row count changed during migration", { table: name });
+			const rows = /* @__PURE__ */ new Map();
+			for (const [index, row] of migrated.entries()) {
+				const key = extractKey(row, current.primary);
+				if (key === void 0) throw new DatabaseError("MIGRATION", `migrate: captured row is missing primary column '${current.primary}'`, {
+					table: name,
+					column: current.primary,
+					index
+				});
+				rows.set(key, bindRowKey(row, current.primary, key));
+			}
+			replacements.set(name, rows);
+		}
+		const candidate = await this.#clone();
+		for (const [name, rows] of replacements) {
+			await candidate.clear(name);
+			for (const [key, row] of rows) await candidate.write(name, key, row);
+		}
+		const metadata = await candidate.metadata();
+		await this.#serialize(void 0, candidate, this.#schema, metadata);
+		this.#memory = candidate;
+		this.#metadata = metadata === void 0 ? void 0 : cloneDriverMetadata(metadata);
+	}
+	#capability(token) {
+		return {
+			read: this.#readCandidate.bind(this, token),
+			write: this.#writeCandidate.bind(this, token),
+			insert: this.#insertCandidate.bind(this, token),
+			delete: this.#deleteCandidate.bind(this, token),
+			keys: this.#keysCandidate.bind(this, token),
+			scan: this.#scanCandidate.bind(this, token),
+			clear: this.#clearCandidate.bind(this, token),
+			migrate: this.#migrateCandidate.bind(this, token),
+			metadata: this.#metadataCandidate.bind(this, token),
+			stamp: this.#stampCandidate.bind(this, token)
+		};
+	}
+	async #readCandidate(token, table, key) {
+		return this.#requireCandidate(token).read(table, key);
+	}
+	async #writeCandidate(token, table, key, row, options) {
+		await this.#requireCandidate(token).write(table, key, row, options);
+	}
+	async #insertCandidate(token, table, key, row, options) {
+		await this.#requireCandidate(token).insert(table, key, row, options);
+	}
+	async #deleteCandidate(token, table, key, options) {
+		return this.#requireCandidate(token).delete(table, key, options);
+	}
+	async #keysCandidate(token, table) {
+		return this.#requireCandidate(token).keys(table);
+	}
+	#scanCandidate(token, table) {
+		return new DriverIterator(this.#requireCandidate(token).scan(table)[Symbol.asyncIterator](), () => {
+			this.#requireCandidate(token);
+		});
+	}
+	async #clearCandidate(token, table) {
+		await this.#requireCandidate(token).clear(table);
+	}
+	async #migrateCandidate(token, input) {
+		const memory = this.#requireCandidate(token);
+		const schema = this.#candidateSchema;
+		const identities = this.#candidateIdentities;
+		if (schema === void 0 || identities === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+		const owned = cloneMigrationInput(input);
+		const projected = this.#projectIdentities(identities, owned.plan.steps);
+		this.#candidateSchema = await this.#apply(memory, schema, owned);
+		this.#candidateIdentities = projected;
+	}
+	async #metadataCandidate(token) {
+		const metadata = await this.#requireCandidate(token).metadata();
+		return metadata === void 0 ? void 0 : cloneDriverMetadata(metadata);
+	}
+	async #stampCandidate(token, metadata) {
+		const memory = this.#requireCandidate(token);
+		const owned = cloneDriverMetadata(metadata);
+		await memory.stamp(owned);
+	}
+	#requireCandidate(token) {
+		if (this.#transaction !== token || this.#candidate === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+		return this.#candidate;
+	}
+	#alignIdentities(schema) {
+		const aligned = /* @__PURE__ */ new Map();
+		for (const table of schema) aligned.set(table.name, this.#identities.get(table.name) ?? {});
+		return aligned;
+	}
+	#projectIdentities(identities, steps) {
+		const projected = new Map(identities);
+		for (const step of steps) {
+			if (step.operation === "table.add") projected.set(step.table.name, {});
+			if (step.operation === "table.remove") projected.delete(step.table);
+		}
+		return projected;
+	}
+	#root() {
+		if (this.#transaction !== void 0) throw new DatabaseError("CONFLICT", "A transaction is active on this driver");
+	}
+	async #document() {
+		let raw;
+		try {
+			raw = await readFile(this.#path, "utf-8");
+		} catch (error) {
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return;
+			throw new DatabaseError("DRIVER", "Failed to read the JSON database file", {
+				path: this.#path,
+				cause: error
+			});
+		}
+		try {
+			return JSON.parse(raw);
+		} catch {
+			throw new DatabaseError("DRIVER", "Stored JSON database is invalid JSON", {
+				path: this.#path,
+				aspect: "syntax"
+			});
+		}
+	}
+	async #hydrate(memory, schema, tables) {
+		for (const table of schema) {
+			const rows = tables[table.name];
+			if (!Array.isArray(rows)) throw new DatabaseError("DRIVER", "Stored JSON table is invalid", {
+				path: this.#path,
+				table: table.name,
+				aspect: "container"
+			});
+			const keys = /* @__PURE__ */ new Set();
+			for (const [index, entry] of rows.entries()) {
+				if (!isRecord(entry)) throw new DatabaseError("DRIVER", "Stored JSON row is invalid", {
+					path: this.#path,
+					table: table.name,
+					index,
+					aspect: "record"
+				});
+				const key = extractKey(entry, table.primary);
+				if (key === void 0) throw new DatabaseError("DRIVER", "Stored JSON row is invalid", {
+					path: this.#path,
+					table: table.name,
+					index,
+					aspect: "primary"
+				});
+				if (keys.has(key)) throw new DatabaseError("DRIVER", "Stored JSON row is invalid", {
+					path: this.#path,
+					table: table.name,
+					index,
+					aspect: "duplicate"
+				});
+				keys.add(key);
+				await memory.write(table.name, key, entry);
+			}
+		}
+	}
+	async #enqueue(operation, signal) {
+		checkAbort(signal);
+		let started = false;
+		const next = this.#chain.then(async () => {
+			started = true;
+			checkAbort(signal);
+			return operation();
+		});
+		this.#chain = next.then(() => {}, () => {});
+		if (signal === void 0) return next;
+		const cleanup = new AbortController();
+		return new Promise((resolve, reject) => {
+			signal.addEventListener("abort", () => {
+				if (started) return;
+				try {
+					checkAbort(signal);
+				} catch (error) {
+					reject(error);
+				}
+			}, {
+				once: true,
+				signal: cleanup.signal
+			});
+			next.then((result) => {
+				cleanup.abort();
+				resolve(result);
+			}, (error) => {
+				cleanup.abort();
+				reject(error);
+			});
+		});
+	}
+	async #write(table, key, row, options) {
+		const previous = await this.#memory.read(table, key);
+		await this.#memory.write(table, key, row, options);
+		try {
+			await this.#serialize(options?.signal);
+		} catch (error) {
+			if (previous === void 0) await this.#memory.delete(table, key);
+			else await this.#memory.write(table, key, previous);
+			throw error;
+		}
+	}
+	async #insert(table, key, row, options) {
+		await this.#memory.insert(table, key, row, options);
+		try {
+			await this.#serialize(options?.signal);
+		} catch (error) {
+			await this.#memory.delete(table, key);
+			throw error;
+		}
+	}
+	async #delete(table, key, options) {
+		const previous = await this.#memory.read(table, key);
+		if (previous === void 0) {
+			checkAbort(options?.signal);
+			return false;
+		}
+		await this.#memory.delete(table, key, options);
+		try {
+			await this.#serialize(options?.signal);
+		} catch (error) {
+			await this.#memory.write(table, key, previous);
+			throw error;
+		}
+		return true;
+	}
+	async #clear(table) {
+		const rollback = await this.#memory.snapshot([table]);
+		await this.#memory.clear(table);
+		try {
+			await this.#serialize();
+		} catch (error) {
+			await rollback();
+			throw error;
+		}
+	}
+	async #stamp(metadata) {
+		const previous = this.#metadata;
+		this.#metadata = cloneDriverMetadata(metadata);
+		try {
+			await this.#serialize();
+		} catch (error) {
+			this.#metadata = previous;
+			throw error;
 		}
+	}
+	async #serialize(signal, memory = this.#memory, schema = this.#schema, metadata = this.#metadata) {
+		const owned = metadata === void 0 ? void 0 : cloneDriverMetadata(metadata);
+		const tables = {};
+		checkAbort(signal);
+		for (const table of schema) {
+			const rows = [];
+			for await (const row of memory.scan(table.name)) {
+				checkAbort(signal);
+				rows.push(row);
+			}
+			tables[table.name] = rows;
+		}
+		checkAbort(signal);
 		this.#flushCount += 1;
 		const temp = `${this.#path}.${process.pid}.${this.#flushCount}.tmp`;
-		const payload = this.#meta === void 0 ? { tables } : {
-			meta: this.#meta,
+		const payload = owned === void 0 ? { tables } : {
+			metadata: owned,
 			tables
 		};
+		let dispatched = false;
 		try {
 			await mkdir(dirname(this.#path), { recursive: true });
-			await writeFile(temp, JSON.stringify(payload, null, 2), "utf-8");
+			const serialized = JSON.stringify(payload, null, 2);
+			checkAbort(signal);
+			await writeFile(temp, serialized, {
+				encoding: "utf-8",
+				flush: true,
+				signal
+			});
+			checkAbort(signal);
+			dispatched = true;
 			await rename(temp, this.#path);
 		} catch (error) {
-			await rm(temp, { force: true }).catch(() => {});
+			let cause = error;
+			if (!dispatched) try {
+				checkAbort(signal);
+			} catch (abort) {
+				cause = abort;
+			}
+			try {
+				await rm(temp, { force: true });
+			} catch (cleanup) {
+				throw new DatabaseError("DRIVER", "Failed to persist and clean the database file", {
+					path: this.#path,
+					temp,
+					cause,
+					cleanup
+				});
+			}
+			if (isDatabaseError(cause) && cause.code === "ABORTED") throw cause;
 			throw new DatabaseError("DRIVER", "Failed to persist the database file", {
 				path: this.#path,
-				cause: error
+				cause
 			});
 		}
 	}
@@ -1218,21 +1643,23 @@ var JSONDriver = class {
 * raw `node:sqlite`. `open` issues `CREATE TABLE IF NOT EXISTS` with real typed
 * columns (mapped from each {@link TableSchema}'s portable column types) and a
 * `PRIMARY KEY`, plus a `CREATE INDEX IF NOT EXISTS` per declared index (both
-* reopen-safe), and readies a reserved `_meta` single-row table `meta()` /
-* `stamp()` read and write — **a user table named `_meta` collides with it**;
+* 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
-* `INSERT OR REPLACE` upsert — the `Table` layer detects a `CONFLICT` via a
-* prior `has`, so this never translates a constraint error; a backend
-* `SQLiteError` otherwise propagates unchanged. Querying, ordering, paging, and
-* aggregation are native: `records` / `count` / `stream` compile a `Criteria`
-* to SQL with `compileCriteria`, and `aggregate` runs a SQL
-* `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` (via `aggregateSQL`) over the same compiled
-* WHERE. `transaction` wraps native `BEGIN` / `COMMIT` / `ROLLBACK` with
-* double-settle guards. `migrate` runs the plan's projected DDL
-* ({@link import('../helpers.js').stepToSQL}) inside whichever native
-* transaction is active: joined into an already-open `transaction()` handle
+* `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
@@ -1260,278 +1687,641 @@ var SQLiteDriver = class {
 	#options;
 	#database;
 	#schema = /* @__PURE__ */ new Map();
-	#transacting = false;
-	constructor(path, options) {
-		this.#path = path;
-		this.#options = options ?? {};
+	#identities = /* @__PURE__ */ new Map();
+	#transaction;
+	#candidateSchema;
+	#candidateIdentities;
+	constructor(options = {}) {
+		this.#path = options.path ?? ":memory:";
+		this.#options = options;
 	}
 	async open(schema) {
-		if (schema.some((table) => table.name === "_meta")) throw new DatabaseError("VALIDATION", `A declared table cannot be named '${META_TABLE}' — it is reserved for driver metadata`, { table: META_TABLE });
+		this.#root();
+		const owned = normalizeDriverSchema(schema);
+		if (owned.some((table) => table.name === "_metadata")) throw new DatabaseError("VALIDATION", `A declared table cannot be named '${METADATA_TABLE}' — it is reserved for driver metadata`, { table: METADATA_TABLE });
 		this.#guard(() => {
-			this.#database?.close();
+			const current = this.#database;
+			const previousIdentities = this.#identities;
+			this.#database = void 0;
+			this.#schema = /* @__PURE__ */ new Map();
+			this.#identities = /* @__PURE__ */ new Map();
+			current?.close();
 			const database = createSQLiteDatabase({
 				path: this.#path,
-				readonly: this.#options.readonly,
-				timeout: this.#options.timeout,
-				foreignKeys: this.#options.foreignKeys
+				...this.#options.readonly !== void 0 ? { readonly: this.#options.readonly } : {},
+				...this.#options.timeout !== void 0 ? { timeout: this.#options.timeout } : {},
+				...this.#options.references !== void 0 ? { foreignKeys: this.#options.references } : {}
 			});
-			database.connect();
-			for (const [name, value] of Object.entries(this.#options.pragmas ?? {})) database.pragma(name, value);
-			const map = /* @__PURE__ */ new Map();
-			for (const table of schema) {
-				map.set(table.name, table);
-				database.exec(schemaToTable(table));
-				for (const sql of schemaToIndexes(table)) database.exec(sql);
+			try {
+				database.connect();
+				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(() => {
+					this.#ensureMetadataTable(database);
+					const stored = this.#readMetadata(database);
+					const deployed = normalizeDriverSchema(stored?.schema ?? owned);
+					const missing = /* @__PURE__ */ new Map();
+					for (const table of deployed) {
+						map.set(table.name, table);
+						missing.set(table.name, this.#validateTable(database, table));
+					}
+					if (stored !== void 0) {
+						for (const table of stored.schema) if (missing.get(table.name) === void 0) throw new DatabaseError("DRIVER", "Stored SQLite table is missing", {
+							table: table.name,
+							aspect: "missing"
+						});
+					}
+					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);
+						} 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);
+						}
+						identities.set(table.name, previousIdentities.get(table.name) ?? {});
+					}
+				});
+				this.#schema = map;
+				this.#identities = identities;
+				this.#database = database;
+			} catch (error) {
+				try {
+					database.close();
+				} catch {}
+				this.#schema = /* @__PURE__ */ new Map();
+				this.#identities = /* @__PURE__ */ new Map();
+				throw error;
 			}
-			database.exec("CREATE TABLE IF NOT EXISTS " + quote(META_TABLE) + " (\"id\" INTEGER, \"version\" INTEGER, \"schema\" TEXT, PRIMARY KEY (\"id\"))");
-			this.#schema = map;
-			this.#database = database;
 		});
 	}
 	async close() {
-		this.#database?.close();
-		this.#database = void 0;
+		this.#root();
+		this.#guard(() => {
+			this.#database?.close();
+			this.#database = void 0;
+		});
 	}
 	async read(table, key) {
-		const schema = this.#table(table);
-		return this.#guard(() => {
-			const row = this.#require().prepare("SELECT * FROM " + quote(table) + " WHERE " + quote(schema.primary) + " = ?").get([this.#key(key, schema)]);
-			return row === void 0 ? void 0 : decodeRow(row, schema);
-		});
+		this.#root();
+		return this.#read(table, key);
 	}
-	async write(table, key, row) {
-		const schema = this.#table(table);
-		this.#guard(() => {
-			const encoded = encodeRow({
-				...row,
-				[schema.primary]: key
-			}, schema);
-			const names = schema.columns.map((column) => column.name);
-			const values = names.map((name) => encoded[name]);
-			this.#require().prepare("INSERT OR REPLACE INTO " + quote(table) + " (" + names.map(quote).join(", ") + ") VALUES (" + names.map(() => "?").join(", ") + ")").run(values);
-		});
+	async write(table, key, row, options) {
+		this.#root();
+		await this.#write(table, key, row, options);
 	}
-	async delete(table, key) {
-		const schema = this.#table(table);
-		return this.#guard(() => {
-			return this.#require().prepare("DELETE FROM " + quote(table) + " WHERE " + quote(schema.primary) + " = ?").run([this.#key(key, schema)]).changes > 0;
-		});
+	async insert(table, key, row, options) {
+		this.#root();
+		await this.#insert(table, key, row, options);
+	}
+	async delete(table, key, options) {
+		this.#root();
+		return this.#delete(table, key, options);
 	}
 	async keys(table) {
-		const schema = this.#table(table);
-		return this.#guard(() => {
-			const primary = quote(schema.primary);
-			const rows = this.#require().prepare("SELECT " + primary + " FROM " + quote(table) + " ORDER BY " + primary).all();
-			const keys = [];
-			for (const row of rows) {
-				const value = row[schema.primary];
-				if (typeof value === "string" || typeof value === "number") keys.push(value);
-			}
-			return keys;
-		});
+		this.#root();
+		return this.#keys(table);
 	}
-	async *scan(table) {
-		const schema = this.#table(table);
-		const iterator = this.#guard(() => this.#require().prepare("SELECT * FROM " + quote(table) + " ORDER BY " + quote(schema.primary)).iterate())[Symbol.iterator]();
-		while (true) {
-			const step = this.#guard(() => iterator.next());
-			if (step.done === true) return;
-			yield this.#guard(() => decodeRow(step.value, schema));
-		}
+	scan(table) {
+		return new DriverIterator(this.#scan(table)[Symbol.asyncIterator](), () => this.#root());
 	}
 	async clear(table) {
-		this.#table(table);
-		this.#guard(() => {
-			this.#require().prepare("DELETE FROM " + quote(table)).run();
-		});
+		this.#root();
+		await this.#clear(table);
 	}
-	async records(table, criteria) {
+	async records(table, input) {
+		validatePage(input);
+		this.#root();
 		const schema = this.#table(table);
-		if (isExactCriteria(criteria, schema)) return this.#guard(() => {
-			const { sql, params } = compileCriteria(criteria, schema);
-			return this.#require().prepare("SELECT * FROM " + quote(table) + (sql === "" ? "" : " " + sql)).all(params).map((row) => decodeRow(row, schema));
+		if (matchesQueryExactly(input, schema)) return this.#guard(() => {
+			const { sql, parameters } = compileQuerySQL(input, schema);
+			return this.#require().prepare("SELECT * FROM " + quoteIdentifier(table) + (sql === "" ? "" : " " + sql)).all(parameters).map((row) => decodeRow(row, schema));
 		});
 		const rows = [];
-		for await (const row of this.scan(table)) rows.push(row);
-		return applyCriteria(rows, criteria);
+		for await (const row of this.#scan(table)) rows.push(row);
+		return applyQuery(rows, input);
 	}
-	async count(table, criteria) {
+	async aggregate(table, operation, column, input) {
+		validatePage(input);
+		this.#root();
 		const schema = this.#table(table);
-		const conditions = criteria.conditions ?? [];
-		if (conditions.every((condition) => isExactCondition(condition, schema))) return this.#guard(() => {
-			const { sql, params } = compileWhere(conditions, schema);
-			const value = this.#require().prepare("SELECT COUNT(*) AS count FROM " + quote(table) + (sql === "" ? "" : " " + sql)).get(params)?.count;
-			return typeof value === "number" || typeof value === "bigint" ? Number(value) : 0;
-		});
-		const rows = [];
-		for await (const row of this.scan(table)) rows.push(row);
-		return filterRows(rows, conditions).length;
-	}
-	async aggregate(table, operation, column, criteria) {
-		const schema = this.#table(table);
-		const conditions = criteria.conditions ?? [];
-		const conditionsExact = conditions.every((condition) => isExactCondition(condition, schema));
-		const columnExact = operation === "count" || isString(column) && schema.columns.some((candidate) => candidate.name === column && (candidate.type === "integer" || candidate.type === "real"));
+		const conditions = input.conditions ?? [];
+		const conditionsExact = conditions.every((condition) => matchesConditionExactly(condition, schema));
+		const columnExact = matchesAggregateExactly(operation, column, schema);
 		if (conditionsExact && columnExact) return this.#guard(() => {
-			const { sql, params } = compileWhere(conditions, schema);
-			const value = this.#require().prepare("SELECT " + aggregateSQL(operation, column) + " AS value FROM " + quote(table) + (sql === "" ? "" : " " + sql)).get(params)?.value;
+			const { sql, parameters } = compileWhere(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);
 		});
 		const rows = [];
-		for await (const row of this.scan(table)) rows.push(row);
+		for await (const row of this.#scan(table)) rows.push(row);
 		return computeAggregate(filterRows(rows, conditions), operation, column);
 	}
-	async *stream(table, criteria) {
-		const schema = this.#table(table);
-		const conditions = criteria.conditions ?? [];
-		if (conditions.every((condition) => isExactCondition(condition, schema))) {
-			const compiled = compileCriteria({
-				conditions,
-				limit: criteria.limit,
-				offset: criteria.offset
-			}, schema);
-			for (const row of this.#require().prepare("SELECT * FROM " + quote(table) + (compiled.sql === "" ? "" : " " + compiled.sql)).iterate(compiled.params)) yield decodeRow(row, schema);
-			return;
-		}
-		const offset = criteria.offset ?? 0;
-		const limit = criteria.limit;
-		let skipped = 0;
-		let yielded = 0;
-		for await (const row of this.scan(table)) {
-			if (limit !== void 0 && yielded >= limit) return;
-			if (conditions.length > 0 && !matchesCriteria(row, conditions)) continue;
-			if (skipped < offset) {
-				skipped += 1;
-				continue;
-			}
-			yield row;
-			yielded += 1;
-		}
+	stream(table, input) {
+		validatePage(input);
+		return new DriverIterator(this.#stream(table, input)[Symbol.asyncIterator](), () => this.#root());
 	}
 	/**
 	* Begin a native transaction — real `BEGIN`, `COMMIT`, `ROLLBACK`.
 	*
 	* @remarks
-	* Calling `commit` or `rollback` a second time (on either method, in either
-	* order) throws `DatabaseError` `CONFLICT`.
+	* The callback receives a scoped {@link StorageInterface}. Fulfillment
+	* commits and returns its value; rejection rolls back and preserves the
+	* original error. Root operations and nesting conflict while active, and a
+	* captured capability conflicts after settlement.
 	*
-	* @returns A {@link TransactionInterface} handle to `commit` or `rollback`
+	* @returns The callback's resolved value
 	*/
-	async transaction() {
+	async transaction(scope) {
+		this.#root();
 		const database = this.#require();
-		this.#guard(() => database.exec("BEGIN"));
-		let settled = false;
-		this.#transacting = true;
-		return {
-			commit: async () => {
-				if (settled) throw new DatabaseError("CONFLICT", "Transaction already settled", {});
-				settled = true;
-				this.#transacting = false;
-				this.#guard(() => database.exec("COMMIT"));
-			},
-			rollback: async () => {
-				if (settled) throw new DatabaseError("CONFLICT", "Transaction already settled", {});
-				settled = true;
-				this.#transacting = false;
-				this.#guard(() => database.exec("ROLLBACK"));
+		this.#guard(() => database.begin());
+		const token = {};
+		this.#transaction = token;
+		this.#candidateSchema = new Map(this.#schema);
+		this.#candidateIdentities = new Map(this.#identities);
+		try {
+			let value;
+			try {
+				value = await scope(this.#capability(token));
+			} catch (error) {
+				this.#guard(() => database.rollback());
+				throw error;
 			}
-		};
+			try {
+				this.#guard(() => database.commit());
+			} catch (error) {
+				if (database.transacting) this.#guard(() => database.rollback());
+				throw error;
+			}
+			const schema = this.#candidateSchema;
+			const identities = this.#candidateIdentities;
+			if (schema === void 0 || identities === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+			this.#schema = schema;
+			this.#identities = identities;
+			return value;
+		} finally {
+			if (this.#transaction === token) {
+				this.#transaction = void 0;
+				this.#candidateSchema = void 0;
+				this.#candidateIdentities = void 0;
+			}
+		}
 	}
 	/**
 	* Apply a {@link Migration} plan by executing each step's projected DDL
-	* ({@link import('../helpers.js').stepToSQL}).
+	* ({@link import('../compilers.js').stepToSQL}).
 	*
 	* @remarks
 	* Atomicity is provided by whichever native transaction is active: when
-	* this driver's own `transaction()` hook already has a handle open (the
+	* 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 propagates out and the CALLER's
-	* `commit`/`rollback` provides atomicity. node:sqlite (and SQLite
+	* 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 step
-	* referencing a table not in this driver's declared schema (and that is
-	* not itself a `table.add`) throws `DatabaseError` `MIGRATION` before any
-	* DDL for that step runs, propagating out of whichever transaction is
-	* active (which rolls back on a throw).
+	* 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
+	* 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
+	* `table.add`) throws `DatabaseError` `MIGRATION` before any DDL for that
+	* step runs.
 	*
-	* @param plan - The migration plan to apply
+	* @param input - The migration plan and optional metadata stamp to apply atomically
 	*/
-	async migrate(plan) {
+	async migrate(input) {
+		this.#root();
 		const database = this.#require();
-		const schema = new Map(this.#schema);
+		const owned = cloneMigrationInput(input);
+		const projected = projectMigrationSchema([...this.#schema.values()], owned.plan.steps);
+		const identities = this.#projectIdentities(this.#identities, owned.plan.steps);
+		if (owned.metadata !== void 0 && !equalsValue(normalizeDriverSchema(owned.metadata.schema), projected)) throw new DatabaseError("MIGRATION", "Migration metadata schema does not match the plan", {
+			projected,
+			metadata: owned.metadata.schema
+		});
 		this.#guard(() => {
-			if (this.#transacting) this.#applyPlan(database, plan, schema);
-			else database.transaction(() => this.#applyPlan(database, plan, schema));
+			database.transaction(() => {
+				this.#applyPlan(database, owned);
+				if (owned.metadata !== void 0) this.#writeMetadata(database, owned.metadata);
+			});
 		});
-		this.#schema = schema;
+		this.#schema = new Map(projected.map((table) => [table.name, table]));
+		this.#identities = identities;
 	}
 	/**
-	* Read the persisted {@link DriverMeta} from the reserved `_meta` table.
+	* Read the persisted {@link DriverMetadata} from the reserved `_metadata` table.
 	*
-	* @returns The last-stamped `DriverMeta`, or `undefined` when never stamped
+	* @returns The last-stamped `DriverMetadata`, or `undefined` when never stamped
 	*   (or the stored row is malformed)
 	*/
-	async meta() {
-		const row = this.#guard(() => this.#require().prepare("SELECT \"version\", \"schema\" FROM " + quote(META_TABLE) + " WHERE \"id\" = 1").get());
+	async metadata() {
+		this.#root();
+		return this.#metadata();
+	}
+	/**
+	* Persist an owned metadata snapshot into the reserved `_metadata` table's
+	* single row.
+	*
+	* @param metadata - The {@link DriverMetadata} to persist
+	*/
+	async stamp(metadata) {
+		this.#root();
+		await this.#stamp(metadata);
+	}
+	async snapshot(tables) {
+		this.#root();
+		const captured = this.#guard(() => {
+			const database = this.#require();
+			const names = tables === void 0 ? [...this.#schema.keys()] : [...new Set(tables)];
+			const snapshots = /* @__PURE__ */ new Map();
+			for (const name of names) {
+				const schema = this.#schema.get(name);
+				const identity = this.#identities.get(name);
+				if (schema === void 0 || identity === void 0) continue;
+				snapshots.set(name, {
+					identity,
+					rows: database.prepare("SELECT * FROM " + quoteIdentifier(name)).all().map((row) => decodeRow(row, schema)),
+					schema
+				});
+			}
+			return snapshots;
+		});
+		return async () => {
+			this.#root();
+			const replacements = /* @__PURE__ */ new Map();
+			for (const [name, capture] of captured) {
+				const schema = this.#schema.get(name);
+				if (schema === void 0 || this.#identities.get(name) !== capture.identity) continue;
+				const plan = planMigration([capture.schema], [schema]);
+				const rows = migrateRows(capture.rows, plan.steps);
+				if (rows.length !== capture.rows.length) throw new DatabaseError("MIGRATION", "Snapshot row count changed during migration", { table: name });
+				const names = schema.columns.map((column) => column.name);
+				const values = [];
+				for (const [index, row] of rows.entries()) {
+					const key = extractKey(row, schema.primary);
+					if (!isKey(key)) throw new DatabaseError("MIGRATION", "Snapshot row has no usable primary key", {
+						table: name,
+						column: schema.primary,
+						index
+					});
+					const encoded = encodeRow(bindRowKey(row, schema.primary, key), schema);
+					values.push(extractValues(encoded, names, name));
+				}
+				replacements.set(name, {
+					names,
+					values
+				});
+			}
+			this.#guard(() => {
+				const current = this.#require();
+				current.transaction(() => {
+					for (const [name, replacement] of replacements) {
+						current.exec("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);
+					}
+				});
+			});
+		};
+	}
+	async #read(table, key) {
+		const schema = this.#table(table);
+		return this.#guard(() => {
+			const row = this.#require().prepare("SELECT * FROM " + quoteIdentifier(table) + " WHERE " + quoteIdentifier(schema.primary) + " = ?").get([this.#key(key, schema)]);
+			return row === void 0 ? void 0 : decodeRow(row, schema);
+		});
+	}
+	async #write(table, key, row, options) {
+		const schema = this.#table(table);
+		this.#guard(() => {
+			const encoded = encodeRow(bindRowKey(row, schema.primary, key), schema);
+			const names = schema.columns.map((column) => column.name);
+			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);
+		});
+	}
+	async #insert(table, key, row, options) {
+		const schema = this.#table(table);
+		this.#guard(() => {
+			const encoded = encodeRow(bindRowKey(row, schema.primary, key), schema);
+			const names = schema.columns.map((column) => column.name);
+			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);
+		});
+	}
+	async #delete(table, key, options) {
+		const schema = this.#table(table);
+		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;
+		});
+	}
+	async #keys(table) {
+		const schema = this.#table(table);
+		return this.#guard(() => {
+			const primary = quoteIdentifier(schema.primary);
+			const rows = this.#require().prepare("SELECT " + primary + " FROM " + quoteIdentifier(table) + " ORDER BY " + primary).all();
+			const keys = [];
+			for (const row of rows) {
+				const value = row[schema.primary];
+				if (typeof value === "string" || typeof value === "number") keys.push(value);
+			}
+			return keys;
+		});
+	}
+	async *#scan(table) {
+		const schema = this.#table(table);
+		for await (const row of this.#iterate(schema, "SELECT * FROM " + quoteIdentifier(table) + " ORDER BY " + quoteIdentifier(schema.primary))) yield row;
+	}
+	async *#stream(table, input) {
+		const schema = this.#table(table);
+		const conditions = input.conditions ?? [];
+		if (conditions.every((condition) => matchesConditionExactly(condition, schema))) {
+			const compiled = compileQuerySQL({
+				conditions,
+				...input.limit !== void 0 ? { limit: input.limit } : {},
+				...input.offset !== void 0 ? { offset: input.offset } : {}
+			}, schema);
+			for await (const row of this.#iterate(schema, "SELECT * FROM " + quoteIdentifier(table) + (compiled.sql === "" ? "" : " " + compiled.sql), compiled.parameters)) yield row;
+			return;
+		}
+		const offset = input.offset ?? 0;
+		const limit = input.limit;
+		let skipped = 0;
+		let yielded = 0;
+		for await (const row of this.#scan(table)) {
+			if (limit !== void 0 && yielded >= limit) return;
+			if (conditions.length > 0 && !matchesQuery(row, conditions)) continue;
+			if (skipped < offset) {
+				skipped += 1;
+				continue;
+			}
+			yield row;
+			yielded += 1;
+		}
+	}
+	async *#iterate(schema, sql, parameters = []) {
+		const iterator = this.#guard(() => this.#require().prepare(sql).iterate(parameters)[Symbol.iterator]());
+		try {
+			while (true) {
+				const step = this.#guard(() => iterator.next());
+				if (step.done === true) return;
+				yield this.#guard(() => decodeRow(step.value, schema));
+			}
+		} finally {
+			if (iterator.return !== void 0) this.#guard(() => iterator.return?.());
+		}
+	}
+	async #clear(table) {
+		this.#table(table);
+		this.#guard(() => {
+			this.#require().prepare("DELETE FROM " + quoteIdentifier(table)).run();
+		});
+	}
+	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\"))");
+	}
+	#validateTable(database, schema) {
+		const object = database.prepare("SELECT \"type\" AS \"category\" FROM \"sqlite_schema\" WHERE \"name\" = ?").get([schema.name]);
+		if (object === void 0) return void 0;
+		if (object.category !== "table") throw new DatabaseError("DRIVER", "SQLite object is not a table", {
+			table: schema.name,
+			aspect: "object",
+			actual: object.category
+		});
+		const trigger = database.prepare("SELECT \"name\" FROM \"sqlite_schema\" WHERE \"type\" = ? AND \"tbl_name\" = ? LIMIT 1").get(["trigger", schema.name]);
+		if (trigger !== void 0) throw new DatabaseError("DRIVER", "SQLite table has an undeclared trigger", {
+			table: schema.name,
+			aspect: "trigger",
+			actual: trigger.name
+		});
+		const columns = database.prepare("SELECT * FROM pragma_table_xinfo(?)").all([schema.name]);
+		if (columns.length !== schema.columns.length) throw new DatabaseError("DRIVER", "SQLite table has different columns", {
+			table: schema.name,
+			aspect: "columns",
+			expected: schema.columns.map((column) => column.name),
+			actual: columns.map((column) => column.name)
+		});
+		for (const declared of schema.columns) {
+			const column = columns.find((candidate) => candidate.name === declared.name);
+			if (column === void 0) throw new DatabaseError("DRIVER", "SQLite table is missing a declared column", {
+				table: schema.name,
+				aspect: "column",
+				column: declared.name
+			});
+			const expectedRequired = !declared.optional && !declared.nullable;
+			const required = column.notnull === 1 || column.notnull === 1n;
+			const expectedPrimary = declared.name === schema.primary ? 1 : 0;
+			const primary = column.pk === expectedPrimary || column.pk === BigInt(expectedPrimary);
+			const hidden = column.hidden === 0 || column.hidden === 0n;
+			if (!matchesSQLiteAffinity(column.type, declared.storage) || required !== expectedRequired || !primary || !hidden) throw new DatabaseError("DRIVER", "SQLite column does not match its declaration", {
+				table: schema.name,
+				aspect: "column",
+				column: declared.name,
+				expected: declared,
+				actual: column
+			});
+		}
+		const indexes = database.prepare("SELECT * FROM pragma_index_list(?)").all([schema.name]);
+		for (const index of indexes) if ((index.unique === 1 || index.unique === 1n) && index.origin !== "pk") throw new DatabaseError("DRIVER", "SQLite table has an undeclared unique constraint", {
+			table: schema.name,
+			aspect: "index",
+			actual: index.name
+		});
+		const missing = [];
+		for (const group of schema.indexes) {
+			const name = deriveSQLiteIndexName(schema.name, group);
+			const index = indexes.find((candidate) => candidate.name === name);
+			if (index === void 0) {
+				missing.push(name);
+				continue;
+			}
+			const ordinary = index.unique === 0 || index.unique === 0n;
+			const complete = index.partial === 0 || index.partial === 0n;
+			if (!ordinary || !complete || index.origin !== "c") throw new DatabaseError("DRIVER", "SQLite index does not match its declaration", {
+				table: schema.name,
+				aspect: "index",
+				index: name,
+				actual: index
+			});
+			const entries = database.prepare("SELECT * FROM pragma_index_xinfo(?)").all([name]).filter((entry) => entry.key === 1 || entry.key === 1n);
+			if (entries.length !== group.length) throw new DatabaseError("DRIVER", "SQLite index has different columns", {
+				table: schema.name,
+				aspect: "index",
+				index: name,
+				expected: group,
+				actual: entries.map((entry) => entry.name)
+			});
+			for (const [position, column] of group.entries()) {
+				const entry = entries.find((candidate) => candidate.seqno === position || candidate.seqno === BigInt(position));
+				const stored = entry !== void 0 && (typeof entry.cid === "number" && Number.isInteger(entry.cid) && entry.cid >= 0 || typeof entry.cid === "bigint" && entry.cid >= 0n);
+				if (entry === void 0 || entry.name !== column || !stored || entry.desc !== 0 && entry.desc !== 0n || entry.coll !== "BINARY") throw new DatabaseError("DRIVER", "SQLite index column does not match its declaration", {
+					table: schema.name,
+					aspect: "index",
+					index: name,
+					column,
+					actual: entry
+				});
+			}
+		}
+		return missing;
+	}
+	#readMetadata(database) {
+		const row = database.prepare("SELECT \"version\", \"schema\" FROM " + quoteIdentifier(METADATA_TABLE) + " WHERE \"id\" = 1").get();
 		if (row === void 0) return void 0;
 		const version = row.version;
 		const text = row.schema;
-		if (typeof text !== "string") return void 0;
-		if (typeof version !== "number" && typeof version !== "bigint") return void 0;
+		if (typeof text !== "string") throw new DatabaseError("DRIVER", "Stored SQLite metadata schema is invalid", {
+			table: METADATA_TABLE,
+			aspect: "metadata"
+		});
+		if (typeof version !== "number" && typeof version !== "bigint") throw new DatabaseError("DRIVER", "Stored SQLite metadata version is invalid", {
+			table: METADATA_TABLE,
+			aspect: "metadata"
+		});
 		let parsed;
 		try {
 			parsed = JSON.parse(text);
-		} catch {
-			return;
+		} catch (error) {
+			throw new DatabaseError("DRIVER", "Stored SQLite metadata JSON is invalid", {
+				table: METADATA_TABLE,
+				aspect: "metadata",
+				cause: error
+			});
 		}
+		if (!Array.isArray(parsed)) throw new DatabaseError("DRIVER", "Stored SQLite metadata schema is invalid", {
+			table: METADATA_TABLE,
+			aspect: "metadata"
+		});
 		const candidate = {
 			version: Number(version),
 			schema: parsed
 		};
-		if (!isDriverMeta(candidate)) return void 0;
-		return candidate;
+		try {
+			return cloneDriverMetadata(candidate);
+		} catch (error) {
+			if (isDatabaseError(error) && error.code === "VALIDATION") throw new DatabaseError("DRIVER", "Stored SQLite metadata is invalid", {
+				table: METADATA_TABLE,
+				aspect: "metadata",
+				cause: error
+			});
+			throw error;
+		}
 	}
-	/**
-	* Persist `meta` verbatim (as JSON) into the reserved `_meta` table's single
-	* row.
-	*
-	* @param meta - The {@link DriverMeta} to persist
-	*/
-	async stamp(meta) {
-		this.#guard(() => {
-			this.#require().prepare("INSERT OR REPLACE INTO " + quote(META_TABLE) + " (\"id\", \"version\", \"schema\") VALUES (1, ?, ?)").run([meta.version, JSON.stringify(meta.schema)]);
+	async #stamp(metadata) {
+		const database = this.#require();
+		const owned = cloneDriverMetadata(metadata);
+		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)]);
+	}
+	#capability(token) {
+		return {
+			read: this.#readTransaction.bind(this, token),
+			write: this.#writeTransaction.bind(this, token),
+			insert: this.#insertTransaction.bind(this, token),
+			delete: this.#deleteTransaction.bind(this, token),
+			keys: this.#keysTransaction.bind(this, token),
+			scan: this.#scanTransaction.bind(this, token),
+			clear: this.#clearTransaction.bind(this, token),
+			migrate: this.#migrateTransaction.bind(this, token),
+			metadata: this.#metadataTransaction.bind(this, token),
+			stamp: this.#stampTransaction.bind(this, token)
+		};
+	}
+	async #readTransaction(token, table, key) {
+		this.#requireTransaction(token);
+		return this.#read(table, key);
+	}
+	async #writeTransaction(token, table, key, row, options) {
+		this.#requireTransaction(token);
+		await this.#write(table, key, row, options);
+	}
+	async #insertTransaction(token, table, key, row, options) {
+		this.#requireTransaction(token);
+		await this.#insert(table, key, row, options);
+	}
+	async #deleteTransaction(token, table, key, options) {
+		this.#requireTransaction(token);
+		return this.#delete(table, key, options);
+	}
+	async #keysTransaction(token, table) {
+		this.#requireTransaction(token);
+		return this.#keys(table);
+	}
+	#scanTransaction(token, table) {
+		return new DriverIterator(this.#scan(table)[Symbol.asyncIterator](), () => {
+			this.#requireTransaction(token);
 		});
 	}
-	async snapshot(tables) {
+	async #clearTransaction(token, table) {
+		this.#requireTransaction(token);
+		await this.#clear(table);
+	}
+	async #migrateTransaction(token, input) {
+		this.#requireTransaction(token);
 		const database = this.#require();
-		const names = tables ?? [...this.#schema.keys()];
-		const captured = /* @__PURE__ */ new Map();
-		for (const name of names) {
-			const schema = this.#schema.get(name);
-			if (schema === void 0) continue;
-			captured.set(name, {
-				names: schema.columns.map((column) => column.name),
-				rows: database.prepare("SELECT * FROM " + quote(name)).all()
-			});
-		}
-		return async () => {
-			const current = this.#require();
-			current.transaction(() => {
-				for (const [name, snapshot] of captured) {
-					current.exec("DELETE FROM " + quote(name));
-					const statement = current.prepare("INSERT OR REPLACE INTO " + quote(name) + " (" + snapshot.names.map(quote).join(", ") + ") VALUES (" + snapshot.names.map(() => "?").join(", ") + ")");
-					for (const row of snapshot.rows) statement.run(snapshot.names.map((column) => row[column]));
+		const owned = cloneMigrationInput(input);
+		const candidate = this.#candidateSchema;
+		const identities = this.#candidateIdentities;
+		if (candidate === void 0 || identities === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+		const projected = projectMigrationSchema([...candidate.values()], owned.plan.steps);
+		const projectedIdentities = this.#projectIdentities(identities, owned.plan.steps);
+		if (owned.metadata !== void 0 && !equalsValue(normalizeDriverSchema(owned.metadata.schema), projected)) throw new DatabaseError("MIGRATION", "Migration metadata schema does not match the plan", {
+			projected,
+			metadata: owned.metadata.schema
+		});
+		this.#guard(() => {
+			database.exec("SAVEPOINT \"_orkestrel_migration\"");
+			try {
+				this.#applyPlan(database, owned);
+				if (owned.metadata !== void 0) this.#writeMetadata(database, owned.metadata);
+				database.exec("RELEASE SAVEPOINT \"_orkestrel_migration\"");
+			} catch (error) {
+				try {
+					database.exec("ROLLBACK TO SAVEPOINT \"_orkestrel_migration\"");
+				} finally {
+					database.exec("RELEASE SAVEPOINT \"_orkestrel_migration\"");
 				}
-			});
-		};
+				throw error;
+			}
+		});
+		this.#candidateSchema = new Map(projected.map((table) => [table.name, table]));
+		this.#candidateIdentities = projectedIdentities;
+	}
+	async #metadataTransaction(token) {
+		this.#requireTransaction(token);
+		return this.#metadata();
 	}
-	#guard(run) {
+	async #stampTransaction(token, metadata) {
+		this.#requireTransaction(token);
+		await this.#stamp(metadata);
+	}
+	#requireTransaction(token) {
+		if (this.#transaction !== token) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+	}
+	#root() {
+		if (this.#transaction !== void 0) throw new DatabaseError("CONFLICT", "A transaction is active on this driver");
+	}
+	#guard(operation) {
 		try {
-			return run();
+			return operation();
 		} catch (error) {
 			if (error instanceof DatabaseError) throw error;
 			if (isSQLiteError(error)) {
@@ -1560,28 +2350,30 @@ var SQLiteDriver = class {
 		if (this.#database === void 0) throw new DatabaseError("CLOSED", `SQLite database '${this.#path}' is not open`, { path: this.#path });
 		return this.#database;
 	}
+	#projectIdentities(identities, steps) {
+		const projected = new Map(identities);
+		for (const step of steps) {
+			if (step.operation === "table.add") projected.set(step.table.name, {});
+			if (step.operation === "table.remove") projected.delete(step.table);
+		}
+		return projected;
+	}
 	#table(name) {
 		this.#require();
-		const schema = this.#schema.get(name);
+		const schema = (this.#candidateSchema ?? this.#schema).get(name);
 		if (schema === void 0) throw new DatabaseError("NOT_FOUND", `Table '${name}' is not in the schema`, { table: name });
 		return schema;
 	}
 	#key(key, schema) {
-		const primary = schema.columns.find((column) => column.name === schema.primary);
-		return encodeValue(key, primary === void 0 ? "text" : primary.type);
-	}
-	#applyPlan(database, plan, schema) {
-		for (const step of plan.steps) {
-			const table = step.operation === "table.add" ? step.table.name : step.table;
-			if (step.operation !== "table.add" && !schema.has(table)) throw new DatabaseError("MIGRATION", `migrate: unknown table '${table}'`, { table });
-			for (const sql of stepToSQL(step)) database.exec(sql);
-			if (step.operation === "table.add") schema.set(step.table.name, step.table);
-			else if (step.operation === "table.remove") schema.delete(step.table);
-			else {
-				const existing = schema.get(table);
-				if (existing !== void 0) schema.set(table, stepToSchema(existing, step));
-			}
-		}
+		return encodeValue(key, schema.columns.find((column) => column.name === schema.primary) ?? {
+			name: schema.primary,
+			storage: "text",
+			optional: false,
+			nullable: false
+		});
+	}
+	#applyPlan(database, input) {
+		for (const step of input.plan.steps) for (const sql of stepToSQL(step)) database.exec(sql);
 	}
 };
 //#endregion
@@ -1590,9 +2382,9 @@ var SQLiteDriver = class {
 * Create a persistent JSON-file {@link DriverInterface} for the core database layer.
 *
 * @remarks
-* Pass it to `createDatabase` from `@orkestrel/database` to run the whole typed database +
-* relations stack against a single JSON file instead of memory — the `Database` /
-* `Table` / `Query` / relations API is unchanged; only where the bytes live changes.
+* Pass it to `createDatabase` from `@orkestrel/database` to run the typed
+* database against a single JSON file instead of memory — the `Database` /
+* `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` /
@@ -1622,19 +2414,20 @@ function createJSONDriver(path) {
 * Create a trusted-mode SQLite {@link DriverInterface} for the core database layer.
 *
 * @remarks
-* Pass it to `createDatabase` from `@orkestrel/database` to run the whole typed database +
-* relations stack against a real SQLite database — the `Database` / `Table` /
-* `Query` / relations API is unchanged; only where the bytes live changes. Built
+* Pass it to `createDatabase` from `@orkestrel/database` to run the typed
+* database against a real SQLite database — the `Database` / `Table` /
+* `Query` API is unchanged; only where the bytes live changes. Built
 * on the published `@orkestrel/sqlite` synchronous wrapper: `open` issues real
 * typed `CREATE TABLE` / `CREATE INDEX` statements (reopen-safe) plus a reserved
-* `_meta` table for `meta()` / `stamp()` — avoid naming a table `_meta`.
+* `_metadata` table for `metadata()` / `stamp()` — avoid naming a table `_metadata`.
 * Querying, paging, and aggregation run natively (`records` / `count` /
 * `aggregate` / `stream`); `transaction` and `migrate` use real `BEGIN` /
 * `COMMIT` / `ROLLBACK`, so `migrate` is atomic even mid-plan.
 *
-* @param options - A bare database file path (`':memory:'` by default, for
-*   back-compat), or a full {@link SQLiteDriverOptions} bag (`path`,
-*   `readonly`, `timeout`, `foreignKeys`, `pragmas`)
+* @param options - The {@link SQLiteDriverOptions} bag (`path`, `readonly`,
+*   `timeout`, `references`, `pragmas`); `references` directly enables or
+*   disables foreign-key enforcement, and omission retains the upstream
+*   default; omit the whole bag for an in-memory database
 * @returns A {@link DriverInterface} backed by SQLite
 *
 * @example
@@ -1644,20 +2437,19 @@ function createJSONDriver(path) {
 * import { createSQLiteDriver } from '@orkestrel/database/server'
 *
 * const db = createDatabase({
-* 	driver: createSQLiteDriver('data/app.sqlite'),
+* 	driver: createSQLiteDriver({ path: 'data/app.sqlite' }),
 * 	tables: { users: { id: stringShape(), name: stringShape() } },
 * })
 * await db.table('users').set({ id: 'u1', name: 'Ada' }) // persisted to app.sqlite
 *
-* // Or with options:
+* // Or with additional options:
 * createSQLiteDriver({ path: 'data/app.sqlite', pragmas: { journal_mode: 'WAL' } })
 * ```
 */
-function createSQLiteDriver(options = ":memory:") {
-	const resolved = isString(options) ? { path: options } : options;
-	return new SQLiteDriver(resolved.path ?? ":memory:", resolved);
+function createSQLiteDriver(options) {
+	return new SQLiteDriver(options);
 }
 //#endregion
-export { EXACT_COLUMN_TYPES, EXACT_RANGE_COLUMN_TYPES, JSONDriver, META_TABLE, SQLiteDriver, aggregateSQL, columnSQL, compileCriteria, compileOrder, compilePage, compileWhere, createJSONDriver, createSQLiteDriver, declaredType, decodeRow, decodeValue, encodeRow, encodeValue, escapeLike, fieldColumn, fragment, generateKey, indexName, isExactCondition, isExactCriteria, isExactOrder, jsonTypeColumn, matchesDeclaredType, quote, schemaToIndexes, schemaToTable, stepToSQL, stepToSchema, valueType };
+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, matchesAggregateExactly, matchesConditionExactly, matchesDeclaredStorage, matchesOrderExactly, matchesQueryExactly, matchesSQLiteAffinity, quoteIdentifier, schemaToIndexes, schemaToTable, stepToSQL };
 
 //# sourceMappingURL=index.js.map