@orkestrel/database 0.0.6 → 0.0.7

package/dist/src/core/index.cjs

@@ -3,11 +3,11 @@ let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 //#region src/core/constants.ts
 /**
-* The primary-key column assumed when {@link TableKeys} does not name one.
+* The primary-key column assumed when {@link PrimaryMap} does not name one.
 *
 * @remarks
 * `id` is the convention IndexedDB (`keyPath: 'id'`) and SQL (`id` / rowid) both
-* lean on, so a table that omits `key` keys its rows by `id`.
+* lean on, so a table without a `primary` override keys its rows by `id`.
 */
 var DEFAULT_PRIMARY = "id";
 /**
@@ -15,7 +15,7 @@ var DEFAULT_PRIMARY = "id";
 *
 * @remarks
 * A ReDoS bound (AGENTS §6.5): the SA1–SA4 migration lets a model supply `list`
-* criteria over the wire, so `likeMatch` / `globMatch` run attacker-controlled
+* input over the wire, so `matchesLikePattern` / `matchesGlobPattern` run attacker-controlled
 * patterns. The matcher is the LINEAR greedy two-pointer wildcard match — never a
 * backtracking regex (`.*`-segments-separated-by-literals against a long input is the
 * catastrophic shape JS cannot bound without atomic groups), so it is O(value ×
@@ -24,10 +24,6 @@ var DEFAULT_PRIMARY = "id";
 * `VALIDATION` {@link DatabaseError}; the cap is generous for any legitimate search.
 */
 var MAX_PATTERN_LENGTH = 1024;
-/** The number of bytes encoded by an RFC 4122 UUID. */
-var UUID_BYTE_COUNT = 16;
-/** The number of distinct values one UUID byte may hold. */
-var UUID_BYTE_RANGE = 256;
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -37,8 +33,8 @@ var UUID_BYTE_RANGE = 256;
 * Carries a {@link DatabaseErrorCode} and an optional `context` bag naming the
 * offending table / key. Thrown for: operating on a closed database (`CLOSED`), a
 * `resolve` miss (`NOT_FOUND`), an `add` onto an existing key (`CONFLICT`), a
-* row that fails its table's contract (`VALIDATION`), a cancelled operation whose
-* {@link ReadOptions.signal} aborted (`ABORTED`, carrying `signal.reason` in
+* row that fails its table's contract (`VALIDATION`), an aborted operation whose
+* {@link OperationOptions.signal} aborted (`ABORTED`, carrying `signal.reason` in
 * `context`), an inapplicable {@link Migration} plan (`MIGRATION`), a
 * driver that violates a {@link DriverInterface} invariant, thrown by the
 * `conformDriver` helper (`CONFORMANCE`), and an unexpected infrastructure
@@ -75,6 +71,219 @@ function isDatabaseError(value) {
 	return value instanceof DatabaseError;
 }
 //#endregion
+//#region src/core/validators.ts
+/**
+* Validate the paging fields of a portable query.
+*
+* @remarks
+* A present `limit` or `offset` must be a finite nonnegative integer; zero is
+* valid. Validation is deterministic (`limit` before `offset`). Non-finite
+* values are rendered as strings in error context so JSON serialization cannot
+* collapse `NaN` or infinity to `null`.
+*
+* @param input - The portable query whose paging fields to validate
+* @throws {@link DatabaseError} `VALIDATION` when a paging field is invalid
+*/
+function validatePage(input) {
+	const limit = input?.limit;
+	if (limit !== void 0 && (!Number.isInteger(limit) || limit < 0)) throw new DatabaseError("VALIDATION", "Query limit must be a nonnegative integer", {
+		field: "limit",
+		value: Number.isFinite(limit) ? limit : String(limit)
+	});
+	const offset = input?.offset;
+	if (offset !== void 0 && (!Number.isInteger(offset) || offset < 0)) throw new DatabaseError("VALIDATION", "Query offset must be a nonnegative integer", {
+		field: "offset",
+		value: Number.isFinite(offset) ? offset : String(offset)
+	});
+}
+/**
+* Test whether a value is a usable database key.
+*
+* @param value - The value to test
+* @returns Whether `value` is a string or finite number
+*/
+function isKey(value) {
+	return typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+}
+/**
+* Test whether a value is a portable column schema.
+*
+* @param value - The value to test
+* @returns Whether `value` is a complete {@link ColumnSchema}
+*/
+function isColumnSchema(value) {
+	try {
+		const column = (0, _orkestrel_contract.cloneJSONRecord)(value);
+		const keys = Object.keys(column);
+		return keys.length === 4 && keys.includes("name") && keys.includes("storage") && keys.includes("optional") && keys.includes("nullable") && typeof column.name === "string" && column.name.length > 0 && (column.storage === "text" || column.storage === "integer" || column.storage === "real" || column.storage === "boolean" || column.storage === "json" || column.storage === "blob") && typeof column.optional === "boolean" && typeof column.nullable === "boolean";
+	} catch {
+		return false;
+	}
+}
+/**
+* Test whether a value is a portable table schema.
+*
+* @param value - The value to test
+* @returns Whether `value` is a complete {@link TableSchema}
+*/
+function isTableSchema(value) {
+	try {
+		const table = (0, _orkestrel_contract.cloneJSONRecord)(value);
+		const keys = Object.keys(table);
+		if (keys.length !== 4 || !keys.includes("name") || !keys.includes("primary") || !keys.includes("columns") || !keys.includes("indexes") || typeof table.name !== "string" || table.name.length === 0 || typeof table.primary !== "string" || table.primary.length === 0 || !Array.isArray(table.columns) || !Array.isArray(table.indexes) || !table.columns.every(isColumnSchema)) return false;
+		const names = table.columns.map((column) => column.name);
+		if (new Set(names).size !== names.length || !names.includes(table.primary) || !table.indexes.every((index) => Array.isArray(index) && index.length > 0 && index.every((column) => typeof column === "string" && names.includes(column)))) return false;
+		const indexes = table.indexes.map((index) => JSON.stringify(index));
+		return new Set(indexes).size === indexes.length;
+	} catch {
+		return false;
+	}
+}
+/**
+* Test whether a value is a complete portable driver schema.
+*
+* @param value - The value to test
+* @returns Whether `value` is a table-schema collection with unique table names
+*/
+function isDriverSchema(value) {
+	try {
+		const schema = (0, _orkestrel_contract.cloneJSONValue)(value);
+		if (!Array.isArray(schema) || !schema.every(isTableSchema)) return false;
+		const names = schema.map((table) => table.name);
+		return new Set(names).size === names.length;
+	} catch {
+		return false;
+	}
+}
+/**
+* Test whether a value is one ordered migration step.
+*
+* @param value - The value to test
+* @returns Whether `value` is a complete {@link MigrationStep}
+*/
+function isMigrationStep(value) {
+	try {
+		const step = (0, _orkestrel_contract.cloneJSONRecord)(value);
+		if (typeof step.operation !== "string") return false;
+		const keys = Object.keys(step);
+		switch (step.operation) {
+			case "table.add": return keys.length === 2 && keys.includes("operation") && keys.includes("table") && isTableSchema(step.table);
+			case "table.remove": return keys.length === 2 && keys.includes("operation") && keys.includes("table") && typeof step.table === "string" && step.table.length > 0;
+			case "column.add": return keys.length === 3 && keys.includes("operation") && keys.includes("table") && keys.includes("column") && typeof step.table === "string" && step.table.length > 0 && isColumnSchema(step.column);
+			case "column.remove": return keys.length === 3 && keys.includes("operation") && keys.includes("table") && keys.includes("column") && typeof step.table === "string" && step.table.length > 0 && typeof step.column === "string" && step.column.length > 0;
+			case "index.add":
+			case "index.remove": return keys.length === 3 && keys.includes("operation") && keys.includes("table") && keys.includes("index") && typeof step.table === "string" && step.table.length > 0 && Array.isArray(step.index) && step.index.length > 0 && step.index.every((column) => typeof column === "string" && column.length > 0);
+			default: return false;
+		}
+	} catch {
+		return false;
+	}
+}
+/**
+* Test whether a value is an ordered migration plan.
+*
+* @param value - The value to test
+* @returns Whether `value` is a complete {@link Migration}
+*/
+function isMigration(value) {
+	try {
+		const migration = (0, _orkestrel_contract.cloneJSONRecord)(value);
+		const keys = Object.keys(migration);
+		return keys.length === 3 && keys.includes("from") && keys.includes("to") && keys.includes("steps") && typeof migration.from === "number" && Number.isFinite(migration.from) && typeof migration.to === "number" && Number.isFinite(migration.to) && Array.isArray(migration.steps) && migration.steps.every(isMigrationStep);
+	} catch {
+		return false;
+	}
+}
+/**
+* Test whether a value is persisted driver metadata.
+*
+* @param value - The value to test
+* @returns Whether `value` is complete {@link DriverMetadata}
+*/
+function isDriverMetadata(value) {
+	try {
+		const metadata = (0, _orkestrel_contract.cloneJSONRecord)(value);
+		const keys = Object.keys(metadata);
+		return keys.length === 2 && keys.includes("version") && keys.includes("schema") && typeof metadata.version === "number" && Number.isFinite(metadata.version) && isDriverSchema(metadata.schema);
+	} catch {
+		return false;
+	}
+}
+/**
+* Test whether a value is one atomic migration request.
+*
+* @param value - The value to test
+* @returns Whether `value` is a complete {@link MigrationInput}
+*/
+function isMigrationInput(value) {
+	try {
+		const input = (0, _orkestrel_contract.cloneJSONRecord)(value);
+		const keys = Object.keys(input);
+		return (keys.length === 1 || keys.length === 2) && keys.includes("plan") && (keys.length === 1 || keys.includes("metadata")) && isMigration(input.plan) && (input.metadata === void 0 || isDriverMetadata(input.metadata));
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/core/cloners.ts
+/**
+* Clone unknown driver metadata into a distinct deeply frozen snapshot.
+*
+* @param value - Unknown metadata
+* @returns Owned driver metadata
+*/
+function cloneDriverMetadata(value) {
+	try {
+		const metadata = (0, _orkestrel_contract.cloneJSONRecord)(value);
+		if (isDriverMetadata(metadata)) return metadata;
+		throw new DatabaseError("VALIDATION", "Driver metadata is invalid", { path: "metadata" });
+	} catch (error) {
+		if (error instanceof DatabaseError) throw error;
+		throw new DatabaseError("VALIDATION", "Driver metadata is invalid", {
+			path: "metadata",
+			cause: error
+		});
+	}
+}
+/**
+* Clone unknown driver schema into a distinct deeply frozen snapshot.
+*
+* @param value - Unknown table schema collection
+* @returns Owned driver schema
+*/
+function cloneDriverSchema(value) {
+	try {
+		const schema = (0, _orkestrel_contract.cloneJSONValue)(value);
+		if (isDriverSchema(schema)) return schema;
+		throw new DatabaseError("VALIDATION", "Driver schema is invalid", { path: "schema" });
+	} catch (error) {
+		if (error instanceof DatabaseError) throw error;
+		throw new DatabaseError("VALIDATION", "Driver schema is invalid", {
+			path: "schema",
+			cause: error
+		});
+	}
+}
+/**
+* Clone unknown migration input into a distinct deeply frozen snapshot.
+*
+* @param value - Unknown migration input
+* @returns Owned migration input
+*/
+function cloneMigrationInput(value) {
+	try {
+		const input = (0, _orkestrel_contract.cloneJSONRecord)(value);
+		if (isMigrationInput(input)) return input;
+		throw new DatabaseError("VALIDATION", "Migration input is invalid", { path: "migration" });
+	} catch (error) {
+		if (error instanceof DatabaseError) throw error;
+		throw new DatabaseError("VALIDATION", "Migration input is invalid", {
+			path: "migration",
+			cause: error
+		});
+	}
+}
+//#endregion
 //#region src/core/helpers.ts
 /**
 * A total ordering over arbitrary values — the comparator behind sorting and the
@@ -107,14 +316,15 @@ function compareValues(left, right) {
 *
 * @remarks
 * Primitives compare by SameValueZero (`NaN` equals itself; `+0` equals `-0`).
-* Arrays compare by index (same length, every element `deepEqual`). Plain
+* Arrays compare by index (same length, every element `equalsValue`). Plain
 * records (via `isRecord`) compare by their OWN enumerable keys: same key
 * COUNT and, for every key in `left`, `right` has that key (`Object.hasOwn`)
-* with a `deepEqual` value — so a key present with value `undefined` is NOT
+* with a `equalsValue` value — so a key present with value `undefined` is NOT
 * equal to that key being absent (both differ in `Object.keys` membership).
 * Anything else (functions, class instances, mismatched shapes) falls through
-* to `false`. There is no cycle detection — a cyclic input recurses forever;
-* callers pass acyclic data (rows, plans, config).
+* to `false`. Container pairs are tracked iteratively, so self-referential and
+* mutually cyclic arrays/records terminate without consuming the call stack.
+* Hostile proxy traps and accessors are contained as a non-match.
 *
 * @param left - The left value
 * @param right - The right value
@@ -122,32 +332,67 @@ function compareValues(left, right) {
 *
 * @example
 * ```ts
-* deepEqual(Number.NaN, Number.NaN) // true
-* deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
-* deepEqual({ a: undefined }, {}) // false — present-undefined ≠ absent
+* equalsValue(Number.NaN, Number.NaN) // true
+* equalsValue({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
+* equalsValue({ a: undefined }, {}) // false — present-undefined ≠ absent
 * ```
 */
-function deepEqual(left, right) {
-	if (typeof left === "number" && typeof right === "number") return Number.isNaN(left) && Number.isNaN(right) || left === right;
-	if (left === right) return true;
-	if (Array.isArray(left) && Array.isArray(right)) return left.length === right.length && left.every((item, index) => deepEqual(item, right[index]));
-	if ((0, _orkestrel_contract.isRecord)(left) && (0, _orkestrel_contract.isRecord)(right)) {
-		const leftKeys = Object.keys(left);
-		const rightKeys = Object.keys(right);
-		if (leftKeys.length !== rightKeys.length) return false;
-		return leftKeys.every((key) => Object.hasOwn(right, key) && deepEqual(left[key], right[key]));
-	}
-	return false;
+function equalsValue(left, right) {
+	const pending = [[left, right]];
+	const compared = /* @__PURE__ */ new WeakMap();
+	try {
+		while (pending.length > 0) {
+			const pair = pending.pop();
+			if (pair === void 0) continue;
+			const [currentLeft, currentRight] = pair;
+			if (typeof currentLeft === "number" && typeof currentRight === "number") {
+				if (Number.isNaN(currentLeft) && Number.isNaN(currentRight) || currentLeft === currentRight) continue;
+				return false;
+			}
+			if (currentLeft === currentRight) continue;
+			const leftArray = Array.isArray(currentLeft);
+			const rightArray = Array.isArray(currentRight);
+			const leftRecord = (0, _orkestrel_contract.isRecord)(currentLeft);
+			const rightRecord = (0, _orkestrel_contract.isRecord)(currentRight);
+			if (leftArray !== rightArray || leftRecord !== rightRecord) return false;
+			if (!leftArray && !leftRecord || !rightArray && !rightRecord) return false;
+			const prior = compared.get(currentLeft);
+			if (prior?.has(currentRight)) continue;
+			if (prior === void 0) compared.set(currentLeft, new WeakSet([currentRight]));
+			else prior.add(currentRight);
+			if (leftArray && rightArray) {
+				if (currentLeft.length !== currentRight.length) return false;
+				for (let index = 0; index < currentLeft.length; index += 1) {
+					const leftOwn = Object.hasOwn(currentLeft, index);
+					if (leftOwn !== Object.hasOwn(currentRight, index)) return false;
+					if (leftOwn) pending.push([currentLeft[index], currentRight[index]]);
+				}
+				continue;
+			}
+			if (leftRecord && rightRecord) {
+				const leftKeys = Object.keys(currentLeft);
+				const rightKeys = Object.keys(currentRight);
+				if (leftKeys.length !== rightKeys.length) return false;
+				for (const key of leftKeys) {
+					if (!Object.hasOwn(currentRight, key)) return false;
+					pending.push([currentLeft[key], currentRight[key]]);
+				}
+			}
+		}
+		return true;
+	} catch {
+		return false;
+	}
 }
 /**
 * Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
-* engine behind {@link likeMatch} and {@link globMatch}.
+* engine behind {@link matchesLikePattern} and {@link matchesGlobPattern}.
 *
 * @remarks
 * A backtracking RegExp (`a%b%c` → `^a.*b.*c$`) is CATASTROPHIC on a hostile pattern:
 * `.*` segments separated by literals, matched against a long non-matching input, blow
 * up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it
-* (AGENTS §6.5, now that the authed server runs model-supplied `list` criteria over the
+* (AGENTS §6.5, now that the authed server runs model-supplied `list` input over the
 * wire). So this builds NO regex. It runs the classic GREEDY TWO-POINTER wildcard match:
 * the `any` wildcard records its position and, on a later mismatch, backtracks ONLY to
 * that last `any` (letting it absorb one more char) — so the work is O(value × pattern),
@@ -170,7 +415,7 @@ function deepEqual(left, right) {
 * @returns Whether `value` matches `pattern`
 * @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
 */
-function wildcardMatch(value, pattern, any, single, fold) {
+function matchesWildcardPattern(value, pattern, any, single, fold) {
 	if (pattern.length > 1024) throw new DatabaseError("VALIDATION", `Pattern exceeds the maximum length of ${MAX_PATTERN_LENGTH}`, {
 		length: pattern.length,
 		limit: MAX_PATTERN_LENGTH
@@ -199,11 +444,11 @@ function wildcardMatch(value, pattern, any, single, fold) {
 	while (pi < needle.length && needle[pi] === any) pi += 1;
 	return pi === needle.length;
 }
-function likeMatch(value, pattern) {
-	return wildcardMatch(value, pattern, "%", "_", true);
+function matchesLikePattern(value, pattern) {
+	return matchesWildcardPattern(value, pattern, "%", "_", true);
 }
-function globMatch(value, pattern) {
-	return wildcardMatch(value, pattern, "*", "?", false);
+function matchesGlobPattern(value, pattern) {
+	return matchesWildcardPattern(value, pattern, "*", "?", false);
 }
 /**
 * Evaluate one {@link Condition} against a row — the per-operator predicate.
@@ -213,10 +458,10 @@ function globMatch(value, pattern) {
 * string is one column; an array descends a nested value) — and applies the
 * operator. Range operators (`above` / `below` / `from` / `to` / `between`) use
 * {@link compareValues}, the total order; the equality family (`equals` / `not`
-* / `any` / `none`) uses {@link deepEqual} — STRUCTURAL equality, not the total
+* / `any` / `none`) uses {@link equalsValue} — STRUCTURAL equality, not the total
 * order's rank-5-collapses-all-objects behavior, so `equals` on an object/array
 * operand only matches a structurally-equal value, never every row holding any
-* object. This is a semantics change from ranking: `deepEqual` is SameValueZero
+* object. This is a semantics change from ranking: `equalsValue` is SameValueZero
 * on leaves, so `NaN` now equals `NaN` under `equals` / `any` (it never matched
 * anything under the old rank-based comparison). `like` / `glob` / `starts` /
 * `ends` match only strings; `absent` / `present` test nullishness. Total — a
@@ -231,19 +476,19 @@ function matchesCondition(row, condition) {
 	const first = condition.values[0];
 	const second = condition.values[1];
 	switch (condition.operator) {
-		case "equals": return deepEqual(value, first);
-		case "not": return !deepEqual(value, first);
+		case "equals": return equalsValue(value, first);
+		case "not": return !equalsValue(value, first);
 		case "above": return compareValues(value, first) > 0;
 		case "below": return compareValues(value, first) < 0;
 		case "from": return compareValues(value, first) >= 0;
 		case "to": return compareValues(value, first) <= 0;
 		case "between": return compareValues(value, first) >= 0 && compareValues(value, second) <= 0;
-		case "like": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && likeMatch(value, first);
-		case "glob": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && globMatch(value, first);
+		case "like": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && matchesLikePattern(value, first);
+		case "glob": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && matchesGlobPattern(value, first);
 		case "starts": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && value.startsWith(first);
 		case "ends": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && value.endsWith(first);
-		case "any": return condition.values.some((candidate) => deepEqual(value, candidate));
-		case "none": return !condition.values.some((candidate) => deepEqual(value, candidate));
+		case "any": return condition.values.some((candidate) => equalsValue(value, candidate));
+		case "none": return !condition.values.some((candidate) => equalsValue(value, candidate));
 		case "absent": return value === void 0 || value === null;
 		case "present": return value !== void 0 && value !== null;
 	}
@@ -261,7 +506,7 @@ function matchesCondition(row, condition) {
 * @param conditions - The conditions to fold
 * @returns Whether the row satisfies the combined conditions
 */
-function matchesCriteria(row, conditions) {
+function matchesQuery(row, conditions) {
 	let result = true;
 	let seeded = false;
 	for (const condition of conditions) {
@@ -275,11 +520,11 @@ function matchesCriteria(row, conditions) {
 }
 /**
 * Filter rows by a list of conditions — the shared basis for a table's count
-* and aggregate paths (no sort/page, unlike {@link applyCriteria}).
+* and aggregate paths (no sort/page, unlike {@link applyQuery}).
 *
 * @remarks
 * An empty condition list matches every row (returned as-is, no copy). Folds
-* each row through {@link matchesCriteria}.
+* each row through {@link matchesQuery}.
 *
 * @param rows - The rows to filter
 * @param conditions - The conditions to apply (empty matches everything)
@@ -295,7 +540,7 @@ function matchesCriteria(row, conditions) {
 */
 function filterRows(rows, conditions) {
 	if (conditions.length === 0) return rows;
-	return rows.filter((row) => matchesCriteria(row, conditions));
+	return rows.filter((row) => matchesQuery(row, conditions));
 }
 /**
 * Sort rows by an ordering specification, leaving the input untouched.
@@ -320,26 +565,27 @@ function sortRows(rows, order) {
 	return sorted;
 }
 /**
-* Apply a {@link Criteria} to rows — filter, then sort, then page.
+* Apply a {@link QueryInput} to rows — filter, then sort, then page.
 *
 * @remarks
 * The whole portable read pipeline in one place: conditions filter, `order`
 * sorts, and `offset` / `limit` window the result. Each step is skipped when its
-* part of the criteria is absent. The reference {@link DriverInterface} backends
+* part of the input is absent. The reference {@link DriverInterface} backends
 * lean on this rather than each re-deriving it.
 *
 * @param rows - The rows to process (typically a table's full `scan`)
-* @param criteria - The read specification, or `undefined` for all rows as-is
+* @param input - The read specification, or `undefined` for all rows as-is
 * @returns The filtered, sorted, paged rows
 */
-function applyCriteria(rows, criteria) {
+function applyQuery(rows, input) {
+	validatePage(input);
 	let result = rows;
-	const conditions = criteria?.conditions;
-	if (conditions !== void 0 && conditions.length > 0) result = result.filter((row) => matchesCriteria(row, conditions));
-	const order = criteria?.order;
+	const conditions = input?.conditions;
+	if (conditions !== void 0 && conditions.length > 0) result = result.filter((row) => matchesQuery(row, conditions));
+	const order = input?.order;
 	if (order !== void 0 && order.length > 0) result = sortRows(result, order);
-	const offset = criteria?.offset ?? 0;
-	const limit = criteria?.limit;
+	const offset = input?.offset ?? 0;
+	const limit = input?.limit;
 	if (offset > 0 || limit !== void 0) result = result.slice(offset, limit !== void 0 ? offset + limit : void 0);
 	return result;
 }
@@ -381,11 +627,24 @@ function computeAggregate(rows, operation, column) {
 */
 function extractKey(row, column) {
 	const value = row[column];
-	if ((0, _orkestrel_contract.isString)(value)) return value;
-	if ((0, _orkestrel_contract.isFiniteNumber)(value)) return value;
+	return isKey(value) ? value : void 0;
+}
+/**
+* Return a fresh row whose primary column is authoritatively bound to its storage key.
+*
+* @param row - The caller row
+* @param primary - The primary column
+* @param key - The authoritative storage key
+* @returns A fresh row with the bound primary
+*/
+function bindRowKey(row, primary, key) {
+	return {
+		...row,
+		[primary]: key
+	};
 }
 /**
-* Map a column's {@link ContractShape} to its portable {@link ColumnType} — the
+* Map a column's {@link ContractShape} to its portable {@link ColumnStorage} — the
 * value a `TableSchema` carries so a native backend can declare a real column.
 *
 * @remarks
@@ -402,13 +661,13 @@ function extractKey(row, column) {
 *
 * @example
 * ```ts
-* shapeToColumnType(stringShape()) // 'text'
-* shapeToColumnType(integerShape()) // 'integer'
-* shapeToColumnType(optionalShape(integerShape())) // 'integer'
-* shapeToColumnType(objectShape({ a: stringShape() })) // 'json'
+* shapeToColumnStorage(stringShape()) // 'text'
+* shapeToColumnStorage(integerShape()) // 'integer'
+* shapeToColumnStorage(optionalShape(integerShape())) // 'integer'
+* shapeToColumnStorage(objectShape({ a: stringShape() })) // 'json'
 * ```
 */
-function shapeToColumnType(shape) {
+function shapeToColumnStorage(shape) {
 	switch (shape.type) {
 		case "string": return "text";
 		case "number": return shape.integer === true ? "integer" : "real";
@@ -418,7 +677,7 @@ function shapeToColumnType(shape) {
 			if (shape.values.every((value) => typeof value === "number")) return shape.values.every((value) => Number.isInteger(value)) ? "integer" : "real";
 			return "text";
 		case "optional":
-		case "nullable": return shapeToColumnType(shape.inner);
+		case "nullable": return shapeToColumnStorage(shape.inner);
 		case "null":
 		case "object":
 		case "array":
@@ -428,48 +687,31 @@ function shapeToColumnType(shape) {
 	}
 }
 /**
-* Whether a value is a well-formed {@link DriverMeta} — the boundary guard a
-* versioning driver's `meta()` narrows a stored (structured-clone or
-* `JSON.parse`d) value through before trusting it, replacing the per-driver
-* duplicated narrowing every backend used to hand-roll (AGENTS §14: never `as`).
-*
-* @remarks
-* Total and total-recursive over the whole shape: a finite `version`, and a
-* `schema` array of well-formed {@link TableSchema} entries — each a `name` /
-* `primary` string pair, a `columns` array of well-formed {@link ColumnSchema}
-* entries (a `name` string, a {@link ColumnType} literal, a `nullable`
-* boolean), and an `indexes` array of string arrays. Anything off-shape
-* (including a non-record) returns `false` rather than throwing.
+* Project one contract shape into a portable column schema.
 *
-* @param value - The value to test
-* @returns `true` when `value` is a well-formed `DriverMeta`
-*
-* @example
-* ```ts
-* isDriverMeta({ version: 1, schema: [] }) // true
-* isDriverMeta({ version: 1, schema: [{ name: 'users' }] }) // false
-* ```
+* @param name - The column name
+* @param shape - The column contract shape
+* @returns The portable storage and independent absence/null acceptance
 */
-function isDriverMeta(value) {
-	return (0, _orkestrel_contract.isRecord)(value) && (0, _orkestrel_contract.isFiniteNumber)(value.version) && (0, _orkestrel_contract.isArray)(value.schema) && value.schema.every((table) => (0, _orkestrel_contract.isRecord)(table) && (0, _orkestrel_contract.isString)(table.name) && (0, _orkestrel_contract.isString)(table.primary) && (0, _orkestrel_contract.isArray)(table.columns) && table.columns.every((column) => (0, _orkestrel_contract.isRecord)(column) && (0, _orkestrel_contract.isString)(column.name) && (0, _orkestrel_contract.isString)(column.type) && [
-		"text",
-		"integer",
-		"real",
-		"boolean",
-		"json",
-		"blob"
-	].some((type) => type === column.type) && (0, _orkestrel_contract.isBoolean)(column.nullable)) && (0, _orkestrel_contract.isArray)(table.indexes) && table.indexes.every((index) => (0, _orkestrel_contract.isArray)(index) && index.every((column) => (0, _orkestrel_contract.isString)(column))));
+function shapeToColumnSchema(name, shape) {
+	const isColumn = (0, _orkestrel_contract.compileGuard)((0, _orkestrel_contract.objectShape)({ value: shape }));
+	return {
+		name,
+		storage: shapeToColumnStorage(shape),
+		optional: isColumn({}),
+		nullable: isColumn({ value: null })
+	};
 }
 /**
-* Throw when an {@link ReadOptions.signal | AbortSignal} has fired — the shared
-* cancellation gate checked at operation boundaries and between streamed rows.
+* Throw when an {@link OperationOptions.signal | AbortSignal} has fired — the shared
+* abort gate checked at operation boundaries and between streamed rows.
 *
 * @remarks
 * A no-op for `undefined` or a live signal, so callers thread `options?.signal`
 * straight through. When the signal has aborted, throws an `ABORTED`
 * {@link DatabaseError} carrying the signal's `reason` in its context — callers
-* mint signals with whatever tool they like (`AbortSignal.timeout(ms)`,
-* `new AbortController()`, `@orkestrel/abort`).
+* mint signals with native APIs such as `AbortSignal.timeout(ms)` or
+* `new AbortController()`.
 *
 * @param signal - The signal to check, if any
 * @returns Nothing — returns normally while the signal is live
@@ -501,11 +743,12 @@ function checkAbort(signal) {
 * `column.remove` / `index.add` / `index.remove` steps. Step order is
 * deterministic: every `table.remove`, then every `table.add`, then each
 * shared table's column/index changes in `declared` order. `from` / `to` are
-* plan labels only — version tracking itself is deferred to persistent
-* backends.
+* plan labels only; versioning drivers persist and reconcile them through
+* {@link DriverMetadata}.
 *
 * A column present in BOTH schemas under the same name but with a different
-* `type` or `nullable` throws a `MIGRATION` {@link DatabaseError} naming the
+* `storage`, `optional`, or `nullable` value throws a `MIGRATION`
+* {@link DatabaseError} naming the
 * table, the column, and the from→to difference — a name-only diff would
 * otherwise silently produce NO step for the drift, and versioned
 * reconciliation would stamp over it. There is no automatic in-place
@@ -518,42 +761,66 @@ function checkAbort(signal) {
 * @param from - The plan's source version label (defaults to `0`)
 * @param to - The plan's target version label (defaults to `1`)
 * @returns The migration plan moving `deployed` toward `declared`
-* @throws A `MIGRATION` {@link DatabaseError} when a shared column's `type` or
-* `nullable` differs between `deployed` and `declared`
+* @throws A `MIGRATION` {@link DatabaseError} when a shared table's primary or
+* a shared column's `storage`, `optional`, or `nullable` differs, or when a
+* required non-null column would be added to an existing table without a
+* portable backfill
 *
 * @example
 * ```ts
 * const plan = planMigration(
-* 	[{ name: 'users', primary: 'id', columns: [], indexes: [] }],
-* 	[{ name: 'users', primary: 'id', columns: [{ name: 'age', type: 'integer', nullable: false }], indexes: [] }],
+* 	[{ name: 'users', primary: 'id', columns: [{ name: 'id', storage: 'text', optional: false, nullable: false }], indexes: [] }],
+* 	[{ name: 'users', primary: 'id', columns: [{ name: 'id', storage: 'text', optional: false, nullable: false }, { name: 'age', storage: 'integer', optional: true, nullable: false }], indexes: [] }],
 * )
 * // plan.steps === [{ operation: 'column.add', table: 'users', column: { name: 'age', ... } }]
 * ```
 */
 function planMigration(deployed, declared, from = 0, to = 1) {
-	const deployedByName = new Map(deployed.map((table) => [table.name, table]));
-	const declaredByName = new Map(declared.map((table) => [table.name, table]));
+	if (!Number.isFinite(from) || !Number.isFinite(to)) throw new DatabaseError("MIGRATION", "Migration versions must be finite", {
+		from,
+		to
+	});
+	let beforeSchema;
+	let targetSchema;
+	try {
+		beforeSchema = normalizeDriverSchema(deployed);
+		targetSchema = normalizeDriverSchema(declared);
+	} catch (error) {
+		throw new DatabaseError("MIGRATION", "Migration schema is invalid", { cause: error });
+	}
+	const deployedByName = new Map(beforeSchema.map((table) => [table.name, table]));
+	const declaredByName = new Map(targetSchema.map((table) => [table.name, table]));
 	const steps = [];
-	for (const table of deployed) if (!declaredByName.has(table.name)) steps.push({
+	for (const table of beforeSchema) if (!declaredByName.has(table.name)) steps.push({
 		operation: "table.remove",
 		table: table.name
 	});
-	for (const table of declared) if (!deployedByName.has(table.name)) steps.push({
+	for (const table of targetSchema) if (!deployedByName.has(table.name)) steps.push({
 		operation: "table.add",
 		table
 	});
-	for (const table of declared) {
+	for (const table of targetSchema) {
 		const before = deployedByName.get(table.name);
 		if (before === void 0) continue;
-		const beforeColumns = new Map(before.columns.map((column) => [column.name, column]));
-		const afterColumns = new Map(table.columns.map((column) => [column.name, column]));
-		for (const column of before.columns) if (!afterColumns.has(column.name)) steps.push({
+		if (before.primary !== table.primary) throw new DatabaseError("MIGRATION", `planMigration: primary column on table '${table.name}' changed from '${before.primary}' to '${table.primary}'`, {
+			table: table.name,
+			from: before.primary,
+			to: table.primary
+		});
+		const beforeColumnMap = new Map(before.columns.map((column) => [column.name, column]));
+		const afterColumnMap = new Map(table.columns.map((column) => [column.name, column]));
+		for (const index of before.indexes) if (!table.indexes.some((candidate) => equalsValue(candidate, index))) steps.push({
+			operation: "index.remove",
+			table: table.name,
+			index
+		});
+		for (const column of before.columns) if (!afterColumnMap.has(column.name)) steps.push({
 			operation: "column.remove",
 			table: table.name,
 			column: column.name
 		});
 		for (const column of table.columns) {
-			const previous = beforeColumns.get(column.name);
+			const previous = beforeColumnMap.get(column.name);
 			if (previous === void 0) {
 				steps.push({
 					operation: "column.add",
@@ -562,35 +829,158 @@ function planMigration(deployed, declared, from = 0, to = 1) {
 				});
 				continue;
 			}
-			if (previous.type !== column.type || previous.nullable !== column.nullable) throw new DatabaseError("MIGRATION", `planMigration: column '${column.name}' on table '${table.name}' changed shape (type ${previous.type}→${column.type}, nullable ${previous.nullable}→${column.nullable}) — in-place type/nullability changes are not auto-migrated; add a new column, copy/convert the data, then remove the old column`, {
+			if (previous.storage !== column.storage || previous.optional !== column.optional || previous.nullable !== column.nullable) throw new DatabaseError("MIGRATION", `planMigration: column '${column.name}' on table '${table.name}' changed shape (storage ${previous.storage}→${column.storage}, optional ${previous.optional}→${column.optional}, nullable ${previous.nullable}→${column.nullable}) — in-place storage/optionality/nullability changes are not auto-migrated; add a new column, copy/convert the data, then remove the old column`, {
 				table: table.name,
 				column: column.name,
 				from: {
-					type: previous.type,
+					storage: previous.storage,
+					optional: previous.optional,
 					nullable: previous.nullable
 				},
 				to: {
-					type: column.type,
+					storage: column.storage,
+					optional: column.optional,
 					nullable: column.nullable
 				}
 			});
 		}
-		for (const index of before.indexes) if (!table.indexes.some((candidate) => deepEqual(candidate, index))) steps.push({
-			operation: "index.remove",
-			table: table.name,
-			index
-		});
-		for (const index of table.indexes) if (!before.indexes.some((candidate) => deepEqual(candidate, index))) steps.push({
+		for (const index of table.indexes) if (!before.indexes.some((candidate) => equalsValue(candidate, index))) steps.push({
 			operation: "index.add",
 			table: table.name,
 			index
 		});
 	}
-	return {
+	const projected = projectMigrationSchema(beforeSchema, steps);
+	if (!equalsValue(projected, targetSchema)) throw new DatabaseError("MIGRATION", "Migration plan does not project to the declared schema", {
+		projected,
+		declared: targetSchema
+	});
+	return cloneMigrationInput({ plan: {
 		from,
 		to,
 		steps
-	};
+	} }).plan;
+}
+/**
+* Sequentially project migration steps over a canonical validated owned schema.
+* Adding a required non-null column to an existing table rejects with
+* `MIGRATION`; optional-only and nullable-only additions remain portable.
+*
+* @param schema - The initial deployed schema
+* @param steps - The ordered migration steps
+* @returns A fresh owned final schema
+*/
+function projectMigrationSchema(schema, steps) {
+	let owned;
+	let projectedSteps;
+	try {
+		owned = normalizeDriverSchema(schema);
+		projectedSteps = cloneMigrationInput({ plan: {
+			from: 0,
+			to: 1,
+			steps
+		} }).plan.steps;
+	} catch (error) {
+		throw new DatabaseError("MIGRATION", "Migration input is invalid", { cause: error });
+	}
+	const tables = new Map(owned.map((table) => [table.name, table]));
+	for (const step of projectedSteps) {
+		if (step.operation === "table.add") {
+			if (tables.has(step.table.name)) throw new DatabaseError("MIGRATION", `migrate: table '${step.table.name}' already exists`, { table: step.table.name });
+			tables.set(step.table.name, step.table);
+			continue;
+		}
+		const table = tables.get(step.table);
+		if (table === void 0) throw new DatabaseError("MIGRATION", `migrate: table '${step.table}' does not exist`, { table: step.table });
+		if (step.operation === "table.remove") {
+			tables.delete(step.table);
+			continue;
+		}
+		if (step.operation === "column.add") {
+			if (table.columns.some((column) => column.name === step.column.name)) throw new DatabaseError("MIGRATION", `migrate: column '${step.column.name}' already exists`, {
+				table: step.table,
+				column: step.column.name
+			});
+			if (!step.column.optional && !step.column.nullable) throw new DatabaseError("MIGRATION", `migrate: required non-null column '${step.column.name}' cannot be added automatically to existing table '${step.table}'`, {
+				table: step.table,
+				column: step.column.name
+			});
+			tables.set(step.table, {
+				...table,
+				columns: [...table.columns, step.column]
+			});
+			continue;
+		}
+		if (step.operation === "column.remove") {
+			if (!table.columns.some((column) => column.name === step.column)) throw new DatabaseError("MIGRATION", `migrate: column '${step.column}' does not exist`, {
+				table: step.table,
+				column: step.column
+			});
+			if (table.primary === step.column) throw new DatabaseError("MIGRATION", "migrate: cannot remove the primary column", {
+				table: step.table,
+				column: step.column
+			});
+			if (table.indexes.some((index) => index.includes(step.column))) throw new DatabaseError("MIGRATION", "migrate: cannot remove an indexed column", {
+				table: step.table,
+				column: step.column
+			});
+			tables.set(step.table, {
+				...table,
+				columns: table.columns.filter((column) => column.name !== step.column)
+			});
+			continue;
+		}
+		if (step.operation === "index.add") {
+			if (step.index.length === 0 || step.index.some((name) => !table.columns.some((column) => column.name === name))) throw new DatabaseError("MIGRATION", "migrate: index references a missing column", {
+				table: step.table,
+				index: step.index
+			});
+			if (table.indexes.some((index) => equalsValue(index, step.index))) throw new DatabaseError("MIGRATION", "migrate: index already exists", {
+				table: step.table,
+				index: step.index
+			});
+			tables.set(step.table, {
+				...table,
+				indexes: [...table.indexes, step.index]
+			});
+			continue;
+		}
+		if (!table.indexes.some((index) => equalsValue(index, step.index))) throw new DatabaseError("MIGRATION", "migrate: index does not exist", {
+			table: step.table,
+			index: step.index
+		});
+		tables.set(step.table, {
+			...table,
+			indexes: table.indexes.filter((index) => !equalsValue(index, step.index))
+		});
+	}
+	try {
+		return normalizeDriverSchema([...tables.values()]);
+	} catch (error) {
+		throw new DatabaseError("MIGRATION", "Projected migration schema is invalid", { cause: error });
+	}
+}
+/**
+* Canonicalize an unknown driver schema into a distinct deeply frozen snapshot.
+*
+* @remarks
+* Table and column lists are sorted by name. The index list is sorted by the
+* complete serialized tuple while column order inside each compound index is
+* preserved because it carries index semantics. Validation and ownership flow
+* through {@link cloneDriverSchema} before and after projection.
+*
+* @param value - Unknown driver schema
+* @returns A validated, owned canonical schema
+*/
+function normalizeDriverSchema(value) {
+	const tables = cloneDriverSchema(value).map((table) => ({
+		name: table.name,
+		primary: table.primary,
+		columns: [...table.columns].sort((left, right) => compareValues(left.name, right.name)),
+		indexes: [...table.indexes].sort((left, right) => compareValues(JSON.stringify(left), JSON.stringify(right)))
+	}));
+	tables.sort((left, right) => compareValues(left.name, right.name));
+	return cloneDriverSchema(tables);
 }
 /**
 * Apply one table's {@link MigrationStep}s to its rows — a pure row transform.
@@ -638,21 +1028,24 @@ function migrateRows(rows, steps) {
 * `read` of a missing key returns `undefined`; `write`/`read` round-trip with
 * DEEP copy-in/copy-out isolation (mutating the caller's row — including a
 * NESTED field — after `write`, or a row `read` returns, never perturbs
-* stored state) and upsert-overwrite; `delete` returns `true` then `false`;
+* stored state) and upsert-overwrite; simultaneous same-key `insert` calls
+* produce exactly one commit and one `CONFLICT`; pre-aborted `write`,
+* `insert`, and `delete` calls leave storage unchanged; `delete` returns
+* `true` then `false`;
 * `keys`/`scan` yield in ascending key order; `clear` empties only its target
 * table; `snapshot`'s rollback thunk restores pre-snapshot state, including a
 * NESTED field mutated in place on a read-back row between capture and
 * restore; a scoped `snapshot(['users'])` rolls back only the named table,
 * leaving a concurrent mutation to another table intact; a
 * non-`id` primary key (`posts.slug`) round-trips; a nested-object row
-* round-trips structurally (via {@link deepEqual}). The optional surface is
+* round-trips structurally (via {@link equalsValue}). The optional surface is
 * presence-gated: when `migrate` exists, a `column.remove` plan strips the
 * column from stored rows and a plan referencing an unknown table throws
 * `DatabaseError` `MIGRATION`; when `stream` exists, it yields only
 * condition-matching rows and honors `offset`/`limit`; when `transaction`
-* exists, `commit` persists and `rollback` restores; when both `meta` and
-* `stamp` exist, a fresh store's `meta()` is `undefined`, and after
-* `stamp({ version, schema })`, `meta()` returns the exact stamped value.
+* exists, `commit` persists and `rollback` restores; when both `metadata` and
+* `stamp` exist, a fresh store's `metadata()` is `undefined`, and after
+* `stamp({ version, schema })`, `metadata()` returns the exact stamped value.
 *
 * Each phase runs within a `try`/`catch`: an EXPECTED mismatch yields a
 * finding built from the assertion, while an UNEXPECTED throw (a driver
@@ -684,23 +1077,27 @@ async function* driverFindings(factory) {
 		columns: [
 			{
 				name: "id",
-				type: "text",
+				storage: "text",
+				optional: false,
 				nullable: false
 			},
 			{
 				name: "name",
-				type: "text",
+				storage: "text",
+				optional: false,
 				nullable: false
 			},
 			{
 				name: "age",
-				type: "integer",
-				nullable: true
+				storage: "integer",
+				optional: true,
+				nullable: false
 			},
 			{
 				name: "meta",
-				type: "json",
-				nullable: true
+				storage: "json",
+				optional: true,
+				nullable: false
 			}
 		],
 		indexes: []
@@ -710,11 +1107,13 @@ async function* driverFindings(factory) {
 		primary: "slug",
 		columns: [{
 			name: "slug",
-			type: "text",
+			storage: "text",
+			optional: false,
 			nullable: false
 		}, {
 			name: "title",
-			type: "text",
+			storage: "text",
+			optional: false,
 			nullable: false
 		}],
 		indexes: []
@@ -756,7 +1155,7 @@ async function* driverFindings(factory) {
 		const driver = factory();
 		await driver.open(CONFORMANCE_SCHEMA);
 		const input = {
-			id: "u1",
+			id: "caller",
 			name: "Ada",
 			age: 30,
 			meta: { tags: ["a"] }
@@ -771,7 +1170,7 @@ async function* driverFindings(factory) {
 			age: 30,
 			meta: { tags: ["a"] }
 		};
-		if (stored === void 0 || !deepEqual(stored, original)) {
+		if (stored === void 0 || !equalsValue(stored, original)) {
 			await driver.close();
 			yield {
 				check: "copy-in",
@@ -787,7 +1186,7 @@ async function* driverFindings(factory) {
 		stored.name = "Mutated after read";
 		if ((0, _orkestrel_contract.isRecord)(stored.meta) && Array.isArray(stored.meta.tags)) stored.meta.tags.push("mutated");
 		const reread = await driver.read("users", "u1");
-		if (reread === void 0 || !deepEqual(reread, original)) {
+		if (reread === void 0 || !equalsValue(reread, original)) {
 			await driver.close();
 			yield {
 				check: "copy-out",
@@ -801,19 +1200,23 @@ async function* driverFindings(factory) {
 			break writeRead;
 		}
 		const overwrite = {
-			id: "u1",
+			id: "caller",
 			name: "Ada Overwritten",
 			age: 31
 		};
 		await driver.write("users", "u1", overwrite);
 		const overwritten = await driver.read("users", "u1");
 		await driver.close();
-		if (overwritten === void 0 || !deepEqual(overwritten, overwrite)) yield {
+		const expectedOverwrite = {
+			...overwrite,
+			id: "u1"
+		};
+		if (overwritten === void 0 || !equalsValue(overwritten, expectedOverwrite)) yield {
 			check: "upsert",
 			message: "write must upsert-overwrite an existing key",
 			context: {
 				table: "users",
-				expected: overwrite,
+				expected: expectedOverwrite,
 				actual: overwritten
 			}
 		};
@@ -824,6 +1227,47 @@ async function* driverFindings(factory) {
 			context: { error }
 		};
 	}
+	try {
+		const driver = factory();
+		await driver.open(CONFORMANCE_SCHEMA);
+		const outcomes = await Promise.allSettled([driver.insert("users", "u1", {
+			id: "u1",
+			name: "Ada",
+			age: 30
+		}), driver.insert("users", "u1", {
+			id: "u1",
+			name: "Grace",
+			age: 40
+		})]);
+		let fulfilled = 0;
+		let conflicted = 0;
+		for (const outcome of outcomes) if (outcome.status === "fulfilled") fulfilled += 1;
+		else if (isDatabaseError(outcome.reason) && outcome.reason.code === "CONFLICT") conflicted += 1;
+		const keys = await driver.keys("users");
+		await driver.close();
+		if (fulfilled !== 1 || conflicted !== 1 || !equalsValue(keys, ["u1"])) yield {
+			check: "insert-atomic",
+			message: "concurrent same-key inserts must produce one commit and one CONFLICT",
+			context: {
+				expected: {
+					fulfilled: 1,
+					conflicted: 1,
+					keys: ["u1"]
+				},
+				actual: {
+					fulfilled,
+					conflicted,
+					keys
+				}
+			}
+		};
+	} catch (error) {
+		yield {
+			check: "insert-atomic",
+			message: error instanceof Error ? error.message : String(error),
+			context: { error }
+		};
+	}
 	deletePhase: try {
 		const driver = factory();
 		await driver.open(CONFORMANCE_SCHEMA);
@@ -864,6 +1308,69 @@ async function* driverFindings(factory) {
 			context: { error }
 		};
 	}
+	try {
+		const driver = factory();
+		await driver.open(CONFORMANCE_SCHEMA);
+		await driver.write("users", "u1", {
+			id: "u1",
+			name: "Ada",
+			age: 30
+		});
+		const controller = new AbortController();
+		controller.abort("conformance abort");
+		let writeError;
+		let insertError;
+		let deleteError;
+		try {
+			await driver.write("users", "u2", {
+				id: "u2",
+				name: "Grace",
+				age: 40
+			}, { signal: controller.signal });
+		} catch (error) {
+			writeError = error;
+		}
+		try {
+			await driver.insert("users", "u2", {
+				id: "u2",
+				name: "Grace",
+				age: 40
+			}, { signal: controller.signal });
+		} catch (error) {
+			insertError = error;
+		}
+		try {
+			await driver.delete("users", "u1", { signal: controller.signal });
+		} catch (error) {
+			deleteError = error;
+		}
+		const keys = await driver.keys("users");
+		await driver.close();
+		if (!isDatabaseError(writeError) || writeError.code !== "ABORTED" || !isDatabaseError(insertError) || insertError.code !== "ABORTED" || !isDatabaseError(deleteError) || deleteError.code !== "ABORTED" || !equalsValue(keys, ["u1"])) yield {
+			check: "mutation-abort",
+			message: "pre-aborted write/insert/delete must reject ABORTED without changing rows",
+			context: {
+				expected: {
+					write: "ABORTED",
+					insert: "ABORTED",
+					delete: "ABORTED",
+					keys: ["u1"]
+				},
+				actual: {
+					write: isDatabaseError(writeError) ? writeError.code : writeError,
+					insert: isDatabaseError(insertError) ? insertError.code : insertError,
+					delete: isDatabaseError(deleteError) ? deleteError.code : deleteError,
+					keys
+				}
+			}
+		};
+	} catch (error) {
+		yield {
+			check: "mutation-abort",
+			message: error instanceof Error ? error.message : String(error),
+			context: { error }
+		};
+	}
 	orderPhase: try {
 		const driver = factory();
 		await driver.open(CONFORMANCE_SCHEMA);
@@ -890,7 +1397,7 @@ async function* driverFindings(factory) {
 			"c"
 		];
 		const keys = [...await driver.keys("users")];
-		if (!deepEqual(keys, expected)) {
+		if (!equalsValue(keys, expected)) {
 			await driver.close();
 			yield {
 				check: "keys-order",
@@ -907,7 +1414,7 @@ async function* driverFindings(factory) {
 		for await (const row of driver.scan("users")) scanned.push(row);
 		const scannedIds = scanned.map((row) => row.id);
 		await driver.close();
-		if (!deepEqual(scannedIds, expected)) yield {
+		if (!equalsValue(scannedIds, expected)) yield {
 			check: "scan-order",
 			message: "scan must yield rows in ascending key order",
 			context: {
@@ -985,7 +1492,7 @@ async function* driverFindings(factory) {
 		await driver.delete("users", "u1");
 		await rollback();
 		const keys = [...await driver.keys("users")];
-		if (!deepEqual(keys, ["u1"])) {
+		if (!equalsValue(keys, ["u1"])) {
 			await driver.close();
 			yield {
 				check: "snapshot-rollback",
@@ -1000,7 +1507,7 @@ async function* driverFindings(factory) {
 		}
 		const restored = await driver.read("users", "u1");
 		await driver.close();
-		if (restored === void 0 || !deepEqual(restored, original)) yield {
+		if (restored === void 0 || !equalsValue(restored, original)) yield {
 			check: "snapshot-rollback-value",
 			message: "snapshot rollback must restore pre-snapshot row values",
 			context: {
@@ -1038,7 +1545,7 @@ async function* driverFindings(factory) {
 		await rollback();
 		const restored = await driver.read("users", "u3");
 		await driver.close();
-		if (restored === void 0 || !deepEqual(restored, original)) yield {
+		if (restored === void 0 || !equalsValue(restored, original)) yield {
 			check: "snapshot-nested",
 			message: "snapshot rollback must restore pre-snapshot nested field values, unaffected by a later in-place mutation of a read-back row",
 			context: {
@@ -1058,7 +1565,7 @@ async function* driverFindings(factory) {
 		const driver = factory();
 		await driver.open(CONFORMANCE_SCHEMA);
 		await driver.write("posts", "hello-world", {
-			slug: "hello-world",
+			slug: "caller",
 			title: "Hello"
 		});
 		const post = await driver.read("posts", "hello-world");
@@ -1095,7 +1602,7 @@ async function* driverFindings(factory) {
 		await driver.write("users", "u3", nested);
 		const readBack = await driver.read("users", "u3");
 		await driver.close();
-		if (readBack === void 0 || !deepEqual(readBack, nested)) yield {
+		if (readBack === void 0 || !equalsValue(readBack, nested)) yield {
 			check: "nested-roundtrip",
 			message: "a nested-object row must round-trip structurally",
 			context: {
@@ -1118,8 +1625,9 @@ async function* driverFindings(factory) {
 			...CONFORMANCE_USERS_SCHEMA,
 			columns: [...CONFORMANCE_USERS_SCHEMA.columns, {
 				name: "legacy",
-				type: "boolean",
-				nullable: true
+				storage: "boolean",
+				optional: true,
+				nullable: false
 			}]
 		};
 		await driver.open([deployedUsers, CONFORMANCE_POSTS_SCHEMA]);
@@ -1130,7 +1638,7 @@ async function* driverFindings(factory) {
 			legacy: true
 		});
 		const removePlan = planMigration([deployedUsers], [CONFORMANCE_USERS_SCHEMA]);
-		await driver.migrate(removePlan);
+		await driver.migrate({ plan: removePlan });
 		const migrated = await driver.read("users", "u1");
 		if (migrated === void 0 || "legacy" in migrated) {
 			await driver.close();
@@ -1147,14 +1655,14 @@ async function* driverFindings(factory) {
 		}
 		let caught;
 		try {
-			await driver.migrate({
+			await driver.migrate({ plan: {
 				from: 0,
 				to: 1,
 				steps: [{
 					operation: "table.remove",
 					table: "ghost"
 				}]
-			});
+			} });
 		} catch (error) {
 			caught = error;
 		}
@@ -1196,16 +1704,16 @@ async function* driverFindings(factory) {
 				age: 30
 			}
 		]) await driver.write("users", row.id, row);
-		const criteria = { conditions: [{
+		const input = { conditions: [{
 			column: "age",
 			operator: "above",
 			values: [10],
 			connector: "and"
 		}] };
 		const matched = [];
-		for await (const row of driver.stream("users", criteria)) matched.push(row);
+		for await (const row of driver.stream("users", input)) matched.push(row);
 		const matchedIds = matched.map((row) => row.id).sort();
-		if (!deepEqual(matchedIds, ["b", "c"])) {
+		if (!equalsValue(matchedIds, ["b", "c"])) {
 			await driver.close();
 			yield {
 				check: "stream-match",
@@ -1249,15 +1757,15 @@ async function* driverFindings(factory) {
 			name: "Ada",
 			age: 30
 		});
-		const committing = await driver.transaction();
-		await driver.write("users", "u2", {
-			id: "u2",
-			name: "Grace",
-			age: 40
+		await driver.transaction(async (transaction) => {
+			await transaction.write("users", "u2", {
+				id: "u2",
+				name: "Grace",
+				age: 40
+			});
 		});
-		await committing.commit();
 		const afterCommit = [...await driver.keys("users")].sort();
-		if (!deepEqual(afterCommit, ["u1", "u2"])) {
+		if (!equalsValue(afterCommit, ["u1", "u2"])) {
 			await driver.close();
 			yield {
 				check: "transaction-commit",
@@ -1270,16 +1778,22 @@ async function* driverFindings(factory) {
 			};
 			break transactionPhase;
 		}
-		const rollingBack = await driver.transaction();
-		await driver.write("users", "u3", {
-			id: "u3",
-			name: "Marie",
-			age: 50
-		});
-		await rollingBack.rollback();
+		const reason = {};
+		try {
+			await driver.transaction(async (transaction) => {
+				await transaction.write("users", "u3", {
+					id: "u3",
+					name: "Marie",
+					age: 50
+				});
+				throw reason;
+			});
+		} catch (error) {
+			if (error !== reason) throw error;
+		}
 		const afterRollback = [...await driver.keys("users")].sort();
 		await driver.close();
-		if (!deepEqual(afterRollback, ["u1", "u2"])) yield {
+		if (!equalsValue(afterRollback, ["u1", "u2"])) yield {
 			check: "transaction-rollback",
 			message: "transaction rollback must restore pre-transaction state",
 			context: {
@@ -1295,33 +1809,33 @@ async function* driverFindings(factory) {
 			context: { error }
 		};
 	}
-	metaPhase: try {
+	metadataPhase: try {
 		const driver = factory();
-		if (driver.meta === void 0 || driver.stamp === void 0) break metaPhase;
+		if (driver.metadata === void 0 || driver.stamp === void 0) break metadataPhase;
 		await driver.open(CONFORMANCE_SCHEMA);
-		const fresh = await driver.meta();
+		const fresh = await driver.metadata();
 		if (fresh !== void 0) {
 			await driver.close();
 			yield {
-				check: "meta-fresh",
-				message: "a fresh store must report undefined meta",
+				check: "metadata-fresh",
+				message: "a fresh store must report undefined metadata",
 				context: {
 					expected: void 0,
 					actual: fresh
 				}
 			};
-			break metaPhase;
+			break metadataPhase;
 		}
 		const stamped = {
 			version: 1,
 			schema: CONFORMANCE_SCHEMA
 		};
 		await driver.stamp(stamped);
-		const read = await driver.meta();
+		const read = await driver.metadata();
 		await driver.close();
-		if (read === void 0 || !deepEqual(read, stamped)) yield {
-			check: "meta-stamp",
-			message: "meta() must return exactly the last-stamped value",
+		if (read === void 0 || !equalsValue(read, stamped)) yield {
+			check: "metadata-stamp",
+			message: "metadata() must return exactly the last-stamped value",
 			context: {
 				expected: stamped,
 				actual: read
@@ -1329,7 +1843,7 @@ async function* driverFindings(factory) {
 		};
 	} catch (error) {
 		yield {
-			check: "meta-stamp",
+			check: "metadata-stamp",
 			message: error instanceof Error ? error.message : String(error),
 			context: { error }
 		};
@@ -1358,7 +1872,7 @@ async function* driverFindings(factory) {
 		});
 		await rollback();
 		const usersKeys = [...await driver.keys("users")];
-		if (!deepEqual(usersKeys, ["u1"])) {
+		if (!equalsValue(usersKeys, ["u1"])) {
 			await driver.close();
 			yield {
 				check: "snapshot-scoped-users",
@@ -1373,7 +1887,7 @@ async function* driverFindings(factory) {
 		}
 		const postsKeys = [...await driver.keys("posts")].sort();
 		await driver.close();
-		if (!deepEqual(postsKeys, ["p1", "p2"])) yield {
+		if (!equalsValue(postsKeys, ["p1", "p2"])) yield {
 			check: "snapshot-scoped-posts",
 			message: "a scoped snapshot must leave an unnamed table's mutations intact",
 			context: {
@@ -1446,62 +1960,451 @@ async function auditDriver(factory) {
 	for await (const finding of driverFindings(factory)) findings.push(finding);
 	return findings;
 }
-/**
-* Generate an RFC 4122 version 4 UUID from a number source — no host crypto global.
-*
-* @remarks
-* Draws exactly {@link UUID_BYTE_COUNT} values from `random`, one per byte, then
-* forces the version (`4`) and variant (`10xx`) bits. The default source is
-* `Math.random` — a pure-ECMAScript intrinsic, so generation works on every host;
-* pass a seeded source (`seededRandom` from `@orkestrel/contract`) and reuse it
-* across calls for reproducible sequences in tests and fixtures — production
-* identifiers should keep the default source, whose engine entropy is far larger
-* than a 32-bit seed. Each byte is floored and masked, so a source straying
-* outside `[0, 1)` (negative, `>= 1`, `NaN`, `Infinity`) can never yield a
-* malformed UUID. Suitable as a collision-resistant record identifier — not a
-* cryptographic token; never use one as a secret.
-*
-* @param random - A number source returning values in the half-open range `[0, 1)` (defaults to `Math.random`)
-* @returns A lowercase RFC 4122 version 4 UUID
-*
-* @example
-* ```ts
-* import { generateUUID } from '@orkestrel/database'
-* import { seededRandom } from '@orkestrel/contract'
-*
-* generateUUID() // e.g. '9b2f7c1e-3d4a-4f6b-8e2d-5a1c0b9f8e7d'
-* generateUUID(seededRandom(42)) // the same UUID on every run
-* ```
-*/
-function generateUUID(random = Math.random) {
-	const hex = Array.from({ length: 16 }, (_, index) => {
-		const byte = Math.floor(random() * 256) & 255;
-		if (index === 6) return byte & 15 | 64;
-		if (index === 8) return byte & 63 | 128;
-		return byte;
-	}).map((byte) => byte.toString(16).padStart(2, "0"));
-	return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
-}
 //#endregion
-//#region src/core/Cursor.ts
+//#region src/core/TransactionIterator.ts
 /**
-* A forward row cursor for bulk in-place mutation.
+* The internal continuation boundary for one transaction-scoped async iterable.
 *
 * @remarks
-* Iterates a snapshot of the table's keys captured when the cursor was opened,
-* reading each row lazily through the owning table — so a mutation made during
-* iteration cannot corrupt the walk, and a key removed mid-iteration is simply
-* skipped. `update` and `remove` act on the row at the current position.
+* Each active continuation enters the owning transaction ledger independently,
+* so an idle iterator never pins settlement. A continuation requested after
+* admission closes rejects while still attempting source cleanup exactly once.
 */
-var Cursor = class {
-	#table;
-	#keys;
-	#index = -1;
+var TransactionIterator = class {
+	#source;
+	#scope;
+	#cleaned = false;
+	constructor(source, scope) {
+		this.#source = source[Symbol.asyncIterator]();
+		this.#scope = scope;
+	}
+	[Symbol.asyncIterator]() {
+		return this;
+	}
+	next() {
+		return this.#continue(() => this.#next());
+	}
+	return() {
+		return this.#continue(() => this.#return());
+	}
+	throw(error) {
+		return this.#continue(() => this.#throw(error));
+	}
+	async #next() {
+		if (this.#cleaned) return {
+			done: true,
+			value: void 0
+		};
+		const result = await this.#source.next();
+		if (result.done === true) this.#cleaned = true;
+		return result;
+	}
+	async #return() {
+		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.#source.throw !== void 0) {
+			const result = await this.#source.throw(error);
+			if (result.done === true) this.#cleaned = true;
+			return result;
+		}
+		try {
+			await this.#return();
+		} catch {}
+		throw error;
+	}
+	#continue(operation) {
+		if (!this.#scope.accepting) this.#cleanup();
+		return this.#scope.track(operation);
+	}
+	#cleanup() {
+		if (this.#cleaned) return;
+		this.#cleaned = true;
+		try {
+			(this.#source.return?.())?.catch(() => {});
+		} catch {}
+	}
+};
+//#endregion
+//#region src/core/TransactionScope.ts
+/**
+* The internal lifetime boundary for one database transaction callback.
+*
+* @remarks
+* Promise operations enter synchronously through {@link track}. Closing stops new
+* work while {@link drain} contains every operation already accepted, including
+* work the callback started without awaiting. {@link stream} applies the same
+* boundary to each iterator continuation without retaining an idle iterator.
+*/
+var TransactionScope = class {
+	#operations = /* @__PURE__ */ new Set();
+	#accepting = true;
+	#failed = false;
+	#error;
+	get accepting() {
+		return this.#accepting;
+	}
+	check() {
+		if (!this.#accepting) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+	}
+	track(operation) {
+		try {
+			this.check();
+		} catch (error) {
+			return Promise.reject(error);
+		}
+		let promise;
+		try {
+			promise = operation();
+		} catch (error) {
+			promise = Promise.reject(error);
+		}
+		this.#operations.add(promise);
+		promise.then(() => {
+			this.#operations.delete(promise);
+		}, (error) => {
+			this.#operations.delete(promise);
+			if (!this.#failed) {
+				this.#failed = true;
+				this.#error = error;
+			}
+		});
+		return promise;
+	}
+	stream(source) {
+		return new TransactionIterator(source, this);
+	}
+	stop() {
+		this.#accepting = false;
+	}
+	async drain() {
+		while (this.#operations.size > 0) await Promise.allSettled(this.#operations);
+		if (this.#failed) throw this.#error;
+	}
+};
+//#endregion
+//#region src/core/DatabaseContext.ts
+/**
+* The internal shared owner behind every typed view of one database.
+*
+* @remarks
+* A context owns the driver, merged physical schema, lifecycle, observation,
+* migration, and single transaction admission. It is deliberately omitted from
+* the public barrel; {@link Database} is the consumer-facing typed view.
+*/
+var DatabaseContext = class {
+	#driver;
+	#name;
+	#version;
+	#error;
+	#emitter;
+	#operations = /* @__PURE__ */ new Set();
+	#schema = [];
+	#transaction;
+	#status = "idle";
+	#ready;
+	#failure;
+	constructor(options) {
+		this.#driver = options.driver;
+		this.#name = options.name ?? "database";
+		this.#version = options.version;
+		this.#error = options.error;
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			...options.on === void 0 ? {} : { on: options.on },
+			...options.error === void 0 ? {} : { error: options.error }
+		});
+	}
+	get driver() {
+		return this.#driver;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get error() {
+		return this.#error;
+	}
+	get name() {
+		return this.#name;
+	}
+	get accepting() {
+		return this.#status !== "closed" && this.#transaction === void 0;
+	}
+	get status() {
+		return this.#status;
+	}
+	get version() {
+		return this.#version;
+	}
+	register(schema) {
+		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
+		if (this.#ready !== void 0 || this.#transaction !== void 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' cannot import tables after opening has started`, {
+			name: this.#name,
+			status: this.#status
+		});
+		const registered = normalizeDriverSchema(schema);
+		const merged = [...this.#schema];
+		for (const table of registered) {
+			const existing = merged.find((candidate) => candidate.name === table.name);
+			if (existing === void 0) {
+				merged.push(table);
+				continue;
+			}
+			if (!equalsValue(existing, table)) throw new DatabaseError("VALIDATION", `Table '${table.name}' conflicts with its registered schema`, { table: table.name });
+		}
+		this.#schema = normalizeDriverSchema(merged);
+	}
+	async open() {
+		this.#outside();
+		await this.connect();
+	}
+	async close() {
+		this.#outside();
+		if (this.#status === "closed") return;
+		this.#status = "closed";
+		await this.#drain();
+		const ready = this.#ready;
+		if (ready !== void 0) await ready.catch(() => {});
+		this.#ready = void 0;
+		await this.#driver.close();
+		this.#emitter.emit("close");
+	}
+	connect() {
+		return this.#connect();
+	}
+	track(operation) {
+		try {
+			this.#admit();
+		} catch (error) {
+			return Promise.reject(error);
+		}
+		let promise;
+		try {
+			promise = operation();
+		} catch (error) {
+			promise = Promise.reject(error);
+		}
+		this.#operations.add(promise);
+		promise.then(() => {
+			this.#operations.delete(promise);
+		}, () => {
+			this.#operations.delete(promise);
+		});
+		return promise;
+	}
+	async transaction(scope, options) {
+		checkAbort(options?.signal);
+		this.#admit();
+		const token = {};
+		this.#transaction = token;
+		try {
+			await this.#drain();
+			await this.#connect();
+			if (this.#driver.transaction !== void 0) {
+				const rejection = {
+					rejected: false,
+					error: void 0,
+					marker: {}
+				};
+				try {
+					const value = await this.#driver.transaction(async (storage) => {
+						this.#emitter.emit("transaction");
+						const outcome = await scope(storage, new TransactionScope());
+						if (!outcome.success) {
+							rejection.rejected = true;
+							rejection.error = outcome.error;
+							throw rejection.marker;
+						}
+						return outcome.value;
+					});
+					this.#emitter.emit("commit");
+					return value;
+				} catch (error) {
+					if (rejection.rejected) {
+						if (Object.is(error, rejection.marker)) {
+							this.#emitter.emit("rollback", rejection.error);
+							throw rejection.error;
+						}
+						throw this.#rollbackError(rejection.error, error);
+					}
+					throw error;
+				}
+			}
+			const rollback = await this.#driver.snapshot();
+			this.#emitter.emit("transaction");
+			const outcome = await scope(this.#driver, new TransactionScope());
+			if (outcome.success) {
+				this.#emitter.emit("commit");
+				return outcome.value;
+			}
+			try {
+				await rollback();
+			} catch (cause) {
+				throw this.#rollbackError(outcome.error, cause);
+			}
+			this.#emitter.emit("rollback", outcome.error);
+			throw outcome.error;
+		} finally {
+			if (this.#transaction === token) this.#transaction = void 0;
+		}
+	}
+	async migrate(deployed, options) {
+		checkAbort(options?.signal);
+		this.#outside();
+		if (this.#ready !== void 0 || this.#status !== "idle") throw new DatabaseError("CONFLICT", `Database '${this.#name}' cannot apply an explicit deployed schema after opening`, {
+			name: this.#name,
+			status: this.#status
+		});
+		if (this.#driver.migrate === void 0) throw new DatabaseError("MIGRATION", `Database '${this.#name}' driver does not support migration`, { name: this.#name });
+		const plan = planMigration(deployed, this.#schema);
+		const readiness = this.#transition(deployed, plan).catch((error) => {
+			if (this.#ready === readiness) this.#ready = void 0;
+			this.#failure = { error };
+			throw error;
+		});
+		this.#failure = void 0;
+		this.#ready = readiness;
+		await readiness;
+		return plan;
+	}
+	#admit() {
+		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
+		if (this.#transaction !== void 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' has an active transaction`, { name: this.#name });
+		if (this.#failure !== void 0) throw this.#failure.error;
+	}
+	#outside() {
+		if (this.#transaction !== void 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' has an active transaction`, { name: this.#name });
+	}
+	#connect() {
+		if (this.#ready !== void 0) return this.#ready;
+		if (this.#failure !== void 0) throw this.#failure.error;
+		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
+		const readiness = this.#driver.open(this.#schema).then(async () => {
+			if (this.#status === "idle") {
+				this.#status = "open";
+				this.#emitter.emit("open");
+			}
+			await this.#reconcile();
+		}).catch((error) => {
+			if (this.#ready === readiness) this.#ready = void 0;
+			throw error;
+		});
+		this.#ready = readiness;
+		return readiness;
+	}
+	async #drain() {
+		if (this.#operations.size === 0) return;
+		await Promise.allSettled(this.#operations);
+	}
+	async #reconcile() {
+		if (this.#version === void 0 || this.#driver.metadata === void 0 || this.#driver.stamp === void 0) return;
+		const metadata = await this.#driver.metadata();
+		if (metadata === void 0) {
+			await this.#stamp();
+			return;
+		}
+		if (metadata.version > this.#version) throw new DatabaseError("MIGRATION", `Database '${this.#name}' store version ${metadata.version} is newer than declared version ${this.#version}`, {
+			name: this.#name,
+			stored: metadata.version,
+			declared: this.#version
+		});
+		if (metadata.version === this.#version) {
+			if (!equalsValue(normalizeDriverSchema(metadata.schema), this.#schema)) throw new DatabaseError("MIGRATION", `Database '${this.#name}' stored schema differs at version ${this.#version}`, {
+				name: this.#name,
+				version: this.#version
+			});
+			return;
+		}
+		const plan = planMigration(metadata.schema, this.#schema, metadata.version, this.#version);
+		if (plan.steps.length > 0 && this.#driver.migrate === void 0) throw new DatabaseError("MIGRATION", `Database '${this.#name}' driver does not support migration`, {
+			name: this.#name,
+			stored: metadata.version,
+			declared: this.#version
+		});
+		await this.#apply(plan);
+	}
+	async #apply(plan) {
+		if (this.#driver.transaction !== void 0) {
+			await this.#driver.transaction(async (storage) => {
+				if (plan.steps.length > 0 && storage.migrate === void 0) throw new DatabaseError("MIGRATION", `Database '${this.#name}' transaction does not support migration`, { name: this.#name });
+				if (storage.migrate === void 0) await this.#stamp(storage);
+				else await storage.migrate(this.#migration(plan));
+			});
+			this.#emitter.emit("migrate", plan);
+			return;
+		}
+		if (this.#driver.migrate === void 0) await this.#stamp();
+		else await this.#driver.migrate(this.#migration(plan));
+		this.#emitter.emit("migrate", plan);
+	}
+	async #transition(deployed, plan) {
+		await this.#driver.open(deployed);
+		await this.#apply(plan);
+		if (this.#status === "idle") {
+			this.#status = "open";
+			this.#emitter.emit("open");
+		}
+	}
+	async #stamp(storage) {
+		const target = storage ?? this.#driver;
+		if (this.#version === void 0 || target.stamp === void 0) return;
+		const metadata = {
+			version: this.#version,
+			schema: this.#schema
+		};
+		await target.stamp(metadata);
+	}
+	#migration(plan) {
+		if (this.#version === void 0) return { plan };
+		return {
+			plan,
+			metadata: {
+				version: this.#version,
+				schema: this.#schema
+			}
+		};
+	}
+	#rollbackError(transaction, cause) {
+		return new DatabaseError("DRIVER", `Database '${this.#name}' rollback failed`, {
+			cause,
+			transaction
+		});
+	}
+};
+//#endregion
+//#region src/core/Cursor.ts
+/**
+* A forward row cursor for bulk in-place mutation.
+*
+* @remarks
+* Iterates a snapshot of the table's keys captured when the cursor was opened,
+* reading each row lazily through the owning table — so a mutation made during
+* iteration cannot corrupt the walk, and a key removed mid-iteration is simply
+* skipped. `update` and `remove` act on the row at the current position.
+*/
+var Cursor = class {
+	#keys;
+	#read;
+	#update;
+	#remove;
+	#track;
+	#tail = Promise.resolve();
+	#index = -1;
 	#value;
 	#closed = false;
-	constructor(table, keys) {
-		this.#table = table;
+	constructor(keys, read, update, remove, track) {
 		this.#keys = keys;
+		this.#read = read;
+		this.#update = update;
+		this.#remove = remove;
+		this.#track = track;
 	}
 	get value() {
 		return this.#value;
@@ -1512,16 +2415,31 @@ var Cursor = class {
 	get done() {
 		return this.#closed || this.#index >= this.#keys.length;
 	}
-	async next() {
+	next() {
+		return this.#track(() => this.#queue(() => this.#advance()));
+	}
+	update(changes) {
+		return this.#track(() => this.#queue(() => this.#revise(changes)));
+	}
+	remove() {
+		return this.#track(() => this.#queue(() => this.#delete()));
+	}
+	close() {
+		this.#closed = true;
+		this.#value = void 0;
+	}
+	async #advance() {
 		if (this.#closed) return;
 		this.#index += 1;
 		while (this.#index < this.#keys.length) {
+			if (this.#closed) return;
 			const key = this.#keys[this.#index];
 			if (key === void 0) {
 				this.#index += 1;
 				continue;
 			}
-			const row = await this.#table.get(key);
+			const row = await this.#read(key);
+			if (this.#closed) return;
 			if (row !== void 0) {
 				this.#value = row;
 				return;
@@ -1530,97 +2448,103 @@ var Cursor = class {
 		}
 		this.#value = void 0;
 	}
-	async update(changes) {
+	async #revise(changes) {
 		if (this.#closed || this.#value === void 0) return;
 		const key = this.#keys[this.#index];
 		if (key === void 0) return;
-		await this.#table.update(key, changes);
-		this.#value = await this.#table.get(key);
+		await this.#update(key, changes);
+		if (this.#closed) return;
+		const row = await this.#read(key);
+		if (this.#closed) return;
+		this.#value = row;
 	}
-	async remove() {
+	async #delete() {
 		if (this.#closed || this.#value === void 0) return;
 		const key = this.#keys[this.#index];
 		if (key === void 0) return;
-		await this.#table.remove(key);
+		await this.#remove(key);
+		if (this.#closed) return;
 		this.#value = void 0;
 	}
-	close() {
-		this.#closed = true;
-		this.#value = void 0;
+	#queue(operation) {
+		const result = this.#tail.then(operation);
+		this.#tail = result.then(() => void 0, () => void 0);
+		return result;
 	}
 };
 //#endregion
-//#region src/core/Clause.ts
+//#region src/core/DatabaseIterator.ts
 /**
-* A pending condition opened by a query's `where` / `and` / `or`.
+* The internal continuation admission boundary for a root database stream.
 *
 * @remarks
-* Holds the column, the connector that will join this condition to the ones
-* before it, and a recorder the owning query supplies. Each operator builds the
-* {@link Condition}, hands it to the recorder, and returns the query — so the
-* fluent chain flows straight back into the builder without exposing a mutator.
+* Each continuation enters the shared root operation ledger independently, so
+* an idle iterator never delays a transaction or close. A continuation rejected
+* after transaction or close admission closes attempts source cleanup exactly
+* once and leaves the iterator terminal.
 */
-var Clause = class {
-	#record;
-	#column;
-	#connector;
-	constructor(record, column, connector) {
-		this.#record = record;
-		this.#column = column;
-		this.#connector = connector;
-	}
-	equals(value) {
-		return this.#apply("equals", [value]);
-	}
-	not(value) {
-		return this.#apply("not", [value]);
-	}
-	above(value) {
-		return this.#apply("above", [value]);
-	}
-	below(value) {
-		return this.#apply("below", [value]);
-	}
-	from(value) {
-		return this.#apply("from", [value]);
-	}
-	to(value) {
-		return this.#apply("to", [value]);
-	}
-	between(lower, upper) {
-		return this.#apply("between", [lower, upper]);
-	}
-	like(pattern) {
-		return this.#apply("like", [pattern]);
-	}
-	glob(pattern) {
-		return this.#apply("glob", [pattern]);
+var DatabaseIterator = class {
+	#source;
+	#context;
+	#cleaned = false;
+	constructor(source, context) {
+		this.#source = source[Symbol.asyncIterator]();
+		this.#context = context;
+	}
+	[Symbol.asyncIterator]() {
+		return this;
 	}
-	starts(prefix) {
-		return this.#apply("starts", [prefix]);
+	next() {
+		return this.#continue(() => this.#next());
 	}
-	ends(suffix) {
-		return this.#apply("ends", [suffix]);
+	return() {
+		return this.#continue(() => this.#return());
 	}
-	any(values) {
-		return this.#apply("any", values);
+	throw(error) {
+		return this.#continue(() => this.#throw(error));
 	}
-	none(values) {
-		return this.#apply("none", values);
+	async #next() {
+		if (this.#cleaned) return {
+			done: true,
+			value: void 0
+		};
+		await this.#context.connect();
+		const result = await this.#source.next();
+		if (result.done === true) this.#cleaned = true;
+		return result;
 	}
-	absent() {
-		return this.#apply("absent", []);
+	async #return() {
+		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.#source.throw !== void 0) {
+			const result = await this.#source.throw(error);
+			if (result.done === true) this.#cleaned = true;
+			return result;
+		}
+		try {
+			await this.#return();
+		} catch {}
+		throw error;
 	}
-	present() {
-		return this.#apply("present", []);
+	#continue(operation) {
+		if (!this.#context.accepting) this.#cleanup();
+		return this.#context.track(operation);
 	}
-	#apply(operator, values) {
-		return this.#record({
-			column: this.#column,
-			operator,
-			values,
-			connector: this.#connector
-		});
+	#cleanup() {
+		if (this.#cleaned) return;
+		this.#cleaned = true;
+		try {
+			(this.#source.return?.())?.catch(() => {});
+		} catch {}
 	}
 };
 //#endregion
@@ -1629,12 +2553,9 @@ var Clause = class {
 * A fluent query builder bound to one table.
 *
 * @remarks
-* Accumulates conditions, ordering, JS filters, and a page; each builder method
-* mutates and returns the same instance, so a chain reads as one statement. The
-* portable parts (conditions, order, page) compile into a {@link Criteria} the
-* table resolves; a `filter` predicate is applied in memory after the read and
-* before paging, so it composes with the rest without a backend ever seeing a
-* JS callback.
+* Accumulates typed conditions, ordering, JS filters, and a page. Each builder
+* method mutates and returns the same instance. Portable inputs flow to the
+* table, while predicates remain an in-memory refinement.
 */
 var Query = class {
 	#table;
@@ -1646,42 +2567,29 @@ var Query = class {
 	constructor(table) {
 		this.#table = table;
 	}
-	where(column) {
-		return this.#clause(column, "and");
-	}
-	and(column) {
-		return this.#clause(column, "and");
-	}
-	or(column) {
-		return this.#clause(column, "or");
-	}
-	filter(predicate) {
-		this.#filters.push(predicate);
+	condition(input) {
+		this.#conditions.push(input);
 		return this;
 	}
-	ascending(column) {
-		this.#orders.push({
-			column,
-			direction: "ascending"
-		});
+	order(input) {
+		this.#orders.push(input);
 		return this;
 	}
-	descending(column) {
-		this.#orders.push({
-			column,
-			direction: "descending"
-		});
+	filter(predicate) {
+		this.#filters.push(predicate);
 		return this;
 	}
 	limit(count) {
+		validatePage({ limit: count });
 		this.#limit = count;
 		return this;
 	}
 	offset(count) {
+		validatePage({ offset: count });
 		this.#offset = count;
 		return this;
 	}
-	async all() {
+	async collect() {
 		if (this.#filters.length === 0) return this.#table.records({
 			conditions: this.#conditions,
 			order: this.#orders,
@@ -1694,8 +2602,8 @@ var Query = class {
 		});
 		return this.#page(this.#filtered(fetched));
 	}
-	async first() {
-		return (await this.all())[0];
+	async find() {
+		return (await this.collect())[0];
 	}
 	async count() {
 		if (this.#filters.length === 0) return this.#table.count({ conditions: this.#conditions });
@@ -1703,17 +2611,10 @@ var Query = class {
 		return this.#filtered(fetched).length;
 	}
 	/**
-	* Lazy per-row evaluation of this query's conditions / filters / offset /
-	* limit.
-	*
-	* @remarks
-	* `order` and its comparators are IGNORED (streaming yields unsorted, as rows
-	* are evaluated one at a time). Same abort semantics as
-	* `TableInterface.scan`: the signal (if any) is checked before each yield,
-	* and breaking out early closes the underlying source.
+	* Lazily evaluate conditions, filters, offset, and limit.
 	*
-	* @param options - `signal` to cancel the iteration; checked before each yield
-	* @returns An async iterable of matching rows
+	* @param options - Optional abort options
+	* @returns Matching rows in storage order
 	*/
 	async *stream(options) {
 		if (this.#filters.length === 0) {
@@ -1748,24 +2649,6 @@ var Query = class {
 		if (this.#filters.length === 0) return this.#table.aggregate(operation, column, { conditions: this.#conditions });
 		return this.#table.records({ conditions: this.#conditions }).then((fetched) => computeAggregate(this.#filtered(fetched), operation, column));
 	}
-	sum(column) {
-		return this.aggregate("sum", column);
-	}
-	average(column) {
-		return this.aggregate("average", column);
-	}
-	minimum(column) {
-		return this.aggregate("minimum", column);
-	}
-	maximum(column) {
-		return this.aggregate("maximum", column);
-	}
-	#clause(column, connector) {
-		return new Clause((condition) => {
-			this.#conditions.push(condition);
-			return this;
-		}, column, connector);
-	}
 	#filtered(rows) {
 		let result = rows;
 		for (const predicate of this.#filters) result = result.filter(predicate);
@@ -1808,8 +2691,10 @@ var Table = class {
 	#contract;
 	#guard;
 	#generate;
+	#context;
+	#scope;
 	#emitter;
-	constructor(ready, driver, name, key, contract, generate, on, error) {
+	constructor(ready, driver, name, key, contract, generate, error, context, scope) {
 		this.#ready = ready;
 		this.#driver = driver;
 		this.#name = name;
@@ -1817,10 +2702,9 @@ var Table = class {
 		this.#contract = contract;
 		this.#guard = contract.is;
 		this.#generate = generate;
-		this.#emitter = new _orkestrel_emitter.Emitter({
-			...on !== void 0 ? { on } : {},
-			...error !== void 0 ? { error } : {}
-		});
+		this.#context = context;
+		this.#scope = scope;
+		this.#emitter = new _orkestrel_emitter.Emitter({ ...error !== void 0 ? { error } : {} });
 	}
 	get emitter() {
 		return this.#emitter;
@@ -1834,58 +2718,77 @@ var Table = class {
 	get contract() {
 		return this.#contract;
 	}
-	async get(keys) {
-		await this.#ready();
-		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#read(key));
-		return this.#read(keys);
+	get(keys) {
+		return this.#track(async () => {
+			await this.#ready();
+			if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#read(key));
+			return this.#read(keys);
+		});
 	}
-	async resolve(keys) {
-		await this.#ready();
-		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#resolveOne(key));
-		return this.#resolveOne(keys);
+	resolve(keys) {
+		return this.#track(async () => {
+			await this.#ready();
+			if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#resolveOne(key));
+			return this.#resolveOne(keys);
+		});
 	}
-	async has(keys) {
-		await this.#ready();
-		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, async (key) => await this.#read(key) !== void 0);
-		return await this.#read(keys) !== void 0;
+	has(keys) {
+		return this.#track(async () => {
+			await this.#ready();
+			if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, async (key) => await this.#read(key) !== void 0);
+			return await this.#read(keys) !== void 0;
+		});
 	}
-	async keys() {
-		await this.#ready();
-		return this.#driver.keys(this.#name);
+	keys() {
+		return this.#track(async () => {
+			await this.#ready();
+			return this.#driver.keys(this.#name);
+		});
 	}
-	async records(criteria, options) {
-		checkAbort(options?.signal);
-		await this.#ready();
-		const source = await this.#driver.records?.(this.#name, criteria ?? {}) ?? applyCriteria(await this.#collect(), criteria);
-		const rows = [];
-		for (const row of source) if (this.#guard(row)) rows.push(row);
-		return rows;
+	async records(input, options) {
+		validatePage(input);
+		return this.#track(async () => {
+			checkAbort(options?.signal);
+			await this.#ready();
+			const candidate = {
+				...input?.conditions === void 0 ? {} : { conditions: input.conditions },
+				...input?.order === void 0 ? {} : { order: input.order }
+			};
+			const source = await this.#driver.records?.(this.#name, candidate) ?? applyQuery(await this.#collect(), candidate);
+			const rows = [];
+			for (const row of source) if (this.#guard(row)) rows.push(row);
+			const offset = input?.offset ?? 0;
+			const limit = input?.limit;
+			return rows.slice(offset, limit === void 0 ? void 0 : offset + limit);
+		});
 	}
 	/**
-	* Count rows matching `criteria`'s conditions.
+	* Count contract-valid rows matching `input`'s conditions.
 	*
 	* @remarks
-	* Unlike {@link records}, which narrows every row through the table's
-	* contract guard before returning it, `count` operates on STORED rows
-	* WITHOUT that guard (both the native `driver.count` hook and the
-	* `filterRows`-over-`#collect()` fallback count raw storage) — so it can
-	* exceed `(await records(criteria)).length` when storage holds rows that
-	* no longer conform to the table's contract (legacy or migrated data).
+	* Paging is ignored. Candidate rows use the driver's native `records` hook
+	* when present, then the table contract guard determines the count so legacy
+	* invalid rows cannot make `count()` disagree with `records()`.
 	*
-	* @param criteria - Optional conditions to filter by (paging is ignored)
+	* @param input - Optional conditions to filter by (paging is ignored)
 	* @param options - `{ signal }` to abort
-	* @returns The count of matching stored rows
+	* @returns The count of matching contract-valid rows
 	*/
-	async count(criteria, options) {
-		checkAbort(options?.signal);
-		await this.#ready();
-		const conditions = criteria?.conditions;
-		const native = await this.#driver.count?.(this.#name, conditions ? { conditions } : {});
-		if (native !== void 0) return native;
-		return filterRows(await this.#collect(), criteria?.conditions ?? []).length;
+	async count(input, options) {
+		validatePage(input);
+		return this.#track(async () => {
+			checkAbort(options?.signal);
+			await this.#ready();
+			const conditions = input?.conditions;
+			const candidate = conditions === void 0 ? {} : { conditions };
+			const rows = await this.#driver.records?.(this.#name, candidate) ?? filterRows(await this.#collect(), conditions ?? []);
+			let count = 0;
+			for (const row of rows) if (this.#guard(row)) count += 1;
+			return count;
+		});
 	}
 	/**
-	* Compute an aggregate over `column` across rows matching `criteria`'s
+	* Compute an aggregate over `column` across rows matching `input`'s
 	* conditions.
 	*
 	* @remarks
@@ -1897,115 +2800,138 @@ var Table = class {
 	*
 	* @param operation - The aggregate to compute
 	* @param column - The column to aggregate
-	* @param criteria - Optional conditions to filter by (paging is ignored)
+	* @param input - Optional conditions to filter by (paging is ignored)
 	* @param options - `{ signal }` to abort
 	* @returns The aggregate value, or `undefined` when undefined for the inputs
 	*/
-	async aggregate(operation, column, criteria, options) {
-		checkAbort(options?.signal);
-		await this.#ready();
-		const conditions = criteria?.conditions;
-		const filter = conditions ? { conditions } : {};
-		const native = this.#driver.aggregate?.(this.#name, operation, column, filter);
-		if (native !== void 0) return native;
-		return computeAggregate(await this.#driver.records?.(this.#name, filter) ?? filterRows(await this.#collect(), criteria?.conditions ?? []), operation, column);
+	async aggregate(operation, column, input, options) {
+		validatePage(input);
+		return this.#track(async () => {
+			checkAbort(options?.signal);
+			await this.#ready();
+			const conditions = input?.conditions;
+			const filter = conditions ? { conditions } : {};
+			const native = this.#driver.aggregate?.(this.#name, operation, column, filter);
+			if (native !== void 0) return native;
+			return computeAggregate(await this.#driver.records?.(this.#name, filter) ?? filterRows(await this.#collect(), input?.conditions ?? []), operation, column);
+		});
 	}
 	/**
-	* Stream the table's rows matching `criteria`, applying offset/limit paging.
+	* Stream the table's rows matching `input`, applying offset/limit paging.
 	*
 	* @remarks
-	* `criteria.limit` counts rows that pass BOTH the criteria conditions AND the
-	* table's contract guard (a stored row that fails the guard is skipped and
-	* does not count toward `limit`) — this can differ from {@link records}'s
-	* `limit`, which a driver's optional native `records` hook applies BEFORE
-	* the contract guard runs, when storage holds rows that no longer conform
-	* to the table's contract.
+	* `input.limit` counts rows that pass both the input conditions and the
+	* table's contract guard. Native streams receive only the conditions; this
+	* table rechecks them, narrows each candidate, and applies offset/limit last,
+	* matching {@link records} when storage contains legacy invalid rows.
 	*
-	* @param criteria - Optional conditions plus offset/limit paging
+	* @param input - Optional conditions plus offset/limit paging
 	* @param options - `{ signal }` to abort mid-stream
 	* @returns An async iterable of matching, guard-conforming rows
 	*/
-	async *scan(criteria, options) {
-		checkAbort(options?.signal);
-		await this.#ready();
-		if (this.#driver.stream !== void 0) {
-			for await (const row of this.#driver.stream(this.#name, criteria ?? {})) {
-				checkAbort(options?.signal);
-				const narrowed = this.#cast(row);
-				if (narrowed !== void 0) yield narrowed;
-			}
-			return;
-		}
-		const conditions = criteria?.conditions;
-		const offset = criteria?.offset ?? 0;
-		const limit = criteria?.limit;
-		let matched = 0;
-		let yielded = 0;
-		for await (const row of this.#driver.scan(this.#name)) {
-			checkAbort(options?.signal);
-			if (limit !== void 0 && yielded >= limit) break;
-			if (conditions !== void 0 && conditions.length > 0 && !matchesCriteria(row, conditions)) continue;
-			if (matched < offset) {
-				matched += 1;
-				continue;
-			}
-			matched += 1;
-			const narrowed = this.#cast(row);
-			if (narrowed !== void 0) {
-				yielded += 1;
-				yield narrowed;
-			}
-		}
-	}
-	async set(rows, options) {
-		checkAbort(options?.signal);
-		await this.#ready();
-		if ((0, _orkestrel_contract.isArray)(rows)) return this.#each(rows, (row) => this.#put(row, false), options?.signal);
-		return this.#put(rows, false);
+	scan(input, options) {
+		validatePage(input);
+		const source = this.#scan(input, options);
+		if (this.#context !== void 0) return new DatabaseIterator(source, this.#context);
+		return this.#scope === void 0 ? source : this.#scope.stream(source);
+	}
+	set(rows, options) {
+		return this.#track(async () => {
+			await this.#wait(options?.signal);
+			if ((0, _orkestrel_contract.isArray)(rows)) return this.#each(rows, (row) => this.#put(row, false, options), options?.signal);
+			return this.#put(rows, false, options);
+		});
 	}
-	async add(rows, options) {
-		checkAbort(options?.signal);
-		await this.#ready();
-		if ((0, _orkestrel_contract.isArray)(rows)) return this.#each(rows, (row) => this.#put(row, true), options?.signal);
-		return this.#put(rows, true);
+	add(rows, options) {
+		return this.#track(async () => {
+			await this.#wait(options?.signal);
+			if ((0, _orkestrel_contract.isArray)(rows)) return this.#each(rows, (row) => this.#put(row, true, options), options?.signal);
+			return this.#put(rows, true, options);
+		});
 	}
-	async update(keys, changes, options) {
-		checkAbort(options?.signal);
-		await this.#ready();
-		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#updateOne(key, changes), options?.signal);
-		return this.#updateOne(keys, changes);
+	update(keys, changes, options) {
+		return this.#track(async () => {
+			await this.#wait(options?.signal);
+			if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#updateOne(key, changes, options), options?.signal);
+			return this.#updateOne(keys, changes, options);
+		});
 	}
-	async remove(keys, options) {
-		checkAbort(options?.signal);
-		await this.#ready();
-		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#delete(key), options?.signal);
-		return this.#delete(keys);
+	remove(keys, options) {
+		return this.#track(async () => {
+			await this.#wait(options?.signal);
+			if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#delete(key, options), options?.signal);
+			return this.#delete(keys, options);
+		});
 	}
-	async clear() {
-		await this.#ready();
-		await this.#driver.clear(this.#name);
-		this.#emitter.emit("clear");
+	clear() {
+		return this.#track(async () => {
+			await this.#ready();
+			await this.#driver.clear(this.#name);
+			this.#emitter.emit("clear");
+		});
 	}
 	query() {
 		return new Query(this);
 	}
-	async cursor() {
+	cursor() {
+		return this.#track(async () => {
+			await this.#ready();
+			let initializing = true;
+			const cursor = new Cursor(await this.#driver.keys(this.#name), (key) => this.#readCursor(key), (key, changes) => this.#updateCursor(key, changes), (key) => this.#deleteCursor(key), (operation) => initializing ? operation() : this.#track(operation));
+			await cursor.next();
+			initializing = false;
+			return cursor;
+		});
+	}
+	async *#scan(input, options) {
+		checkAbort(options?.signal);
 		await this.#ready();
-		const cursor = new Cursor(this, await this.#driver.keys(this.#name));
-		await cursor.next();
-		return cursor;
+		const conditions = input?.conditions;
+		const offset = input?.offset ?? 0;
+		const limit = input?.limit;
+		let matched = 0;
+		let yielded = 0;
+		const iterator = (this.#driver.stream === void 0 ? this.#driver.scan(this.#name) : this.#driver.stream(this.#name, conditions === void 0 ? {} : { conditions }))[Symbol.asyncIterator]();
+		try {
+			while (true) {
+				await this.#ready();
+				checkAbort(options?.signal);
+				if (limit !== void 0 && yielded >= limit) return;
+				const step = await iterator.next();
+				await this.#ready();
+				checkAbort(options?.signal);
+				if (step.done === true) return;
+				const row = step.value;
+				if (conditions !== void 0 && conditions.length > 0 && !matchesQuery(row, conditions)) continue;
+				const narrowed = this.#cast(row);
+				if (narrowed === void 0) continue;
+				if (matched < offset) {
+					matched += 1;
+					continue;
+				}
+				matched += 1;
+				yielded += 1;
+				yield narrowed;
+			}
+		} finally {
+			await iterator.return?.();
+		}
 	}
-	async #each(items, operation, signal) {
+	async #each(elements, operation, signal) {
 		const results = [];
-		for (const item of items) {
+		for (const element of elements) {
 			checkAbort(signal);
-			results.push(await operation(item));
+			results.push(await operation(element));
 		}
 		return results;
 	}
 	async #read(key) {
 		return this.#cast(await this.#driver.read(this.#name, key));
 	}
+	async #readCursor(key) {
+		await this.#ready();
+		return this.#read(key);
+	}
 	async #resolveOne(key) {
 		const row = await this.#read(key);
 		if (row === void 0) throw new DatabaseError("NOT_FOUND", `No row '${key}' in table '${this.#name}'`, {
@@ -2014,29 +2940,79 @@ var Table = class {
 		});
 		return row;
 	}
-	async #put(row, exclusive) {
+	async #put(row, insert, options) {
 		const validated = this.#validate(this.#prepare(row));
 		const key = this.#resolveKey(validated);
-		if (exclusive && await this.#driver.read(this.#name, key) !== void 0) throw new DatabaseError("CONFLICT", `Row '${key}' already exists in table '${this.#name}'`, {
-			table: this.#name,
-			key
-		});
-		await this.#driver.write(this.#name, key, validated);
+		if (insert) await this.#driver.insert(this.#name, key, validated, options);
+		else await this.#driver.write(this.#name, key, validated, options);
 		this.#emitter.emit("write", key);
 		return key;
 	}
-	async #updateOne(key, changes) {
+	async #updateOne(key, changes, options) {
 		const existing = await this.#driver.read(this.#name, key);
-		if (existing === void 0) return false;
-		await this.#driver.write(this.#name, key, this.#validate(Object.assign({}, existing, changes)));
+		if (existing === void 0) {
+			checkAbort(options?.signal);
+			return false;
+		}
+		const input = changes;
+		if ((0, _orkestrel_contract.isRecord)(input) && Object.hasOwn(input, this.#key) && !equalsValue(input[this.#key], key)) throw new DatabaseError("VALIDATION", `Update cannot change primary column '${this.#key}' on table '${this.#name}'`, {
+			table: this.#name,
+			column: this.#key,
+			key
+		});
+		await this.#driver.write(this.#name, key, this.#validate(Object.assign({}, existing, changes)), options);
 		this.#emitter.emit("write", key);
 		return true;
 	}
-	async #delete(key) {
-		const removed = await this.#driver.delete(this.#name, key);
+	async #updateCursor(key, changes) {
+		await this.#wait(void 0);
+		return this.#updateOne(key, changes);
+	}
+	async #delete(key, options) {
+		const removed = await this.#driver.delete(this.#name, key, options);
 		if (removed) this.#emitter.emit("remove", key);
 		return removed;
 	}
+	async #deleteCursor(key) {
+		await this.#wait(void 0);
+		return this.#delete(key);
+	}
+	async #wait(signal) {
+		checkAbort(signal);
+		const ready = this.#ready();
+		if (signal === void 0) {
+			await ready;
+			return;
+		}
+		const cleanup = new AbortController();
+		try {
+			await new Promise((resolve, reject) => {
+				signal.addEventListener("abort", () => {
+					ready.catch(() => {});
+					try {
+						checkAbort(signal);
+					} catch (error) {
+						reject(error);
+					}
+				}, {
+					once: true,
+					signal: cleanup.signal
+				});
+				ready.then(resolve, reject);
+				if (signal.aborted) {
+					ready.catch(() => {});
+					try {
+						checkAbort(signal);
+					} catch (error) {
+						reject(error);
+					}
+				}
+			});
+		} finally {
+			cleanup.abort();
+		}
+		checkAbort(signal);
+	}
 	async #collect() {
 		const rows = [];
 		for await (const row of this.#driver.scan(this.#name)) rows.push(row);
@@ -2045,21 +3021,38 @@ var Table = class {
 	#prepare(row) {
 		if (!(0, _orkestrel_contract.isRecord)(row)) throw new DatabaseError("VALIDATION", `Row for table '${this.#name}' is not a record`, { table: this.#name });
 		const prepared = { ...row };
-		if (prepared[this.#key] === void 0) {
-			if (this.#generate === void 0) throw new DatabaseError("VALIDATION", `Row for table '${this.#name}' is missing its key column '${this.#key}' and no key factory was provided`, {
+		if (prepared[this.#key] === void 0) if (this.#generate !== void 0) try {
+			prepared[this.#key] = this.#generate();
+		} catch (cause) {
+			throw new DatabaseError("VALIDATION", `Failed to generate primary column '${this.#key}' for table '${this.#name}'`, {
 				table: this.#name,
-				column: this.#key
+				column: this.#key,
+				cause
+			});
+		}
+		else try {
+			prepared[this.#key] = crypto.randomUUID();
+		} catch (cause) {
+			throw new DatabaseError("DRIVER", `Host failed to generate primary column '${this.#key}' for table '${this.#name}'`, {
+				table: this.#name,
+				column: this.#key,
+				cause
 			});
-			prepared[this.#key] = this.#generate();
 		}
 		return prepared;
 	}
 	#validate(row) {
 		const parsed = this.#contract.parse(row);
-		if (parsed === void 0 || !(0, _orkestrel_contract.isRecord)(parsed)) throw new DatabaseError("VALIDATION", `Row failed the '${this.#name}' contract`, {
-			table: this.#name,
-			row
-		});
+		if (parsed === void 0 || !(0, _orkestrel_contract.isRecord)(parsed)) {
+			const [fault] = this.#contract.explain(row);
+			throw new DatabaseError("VALIDATION", `Row failed the '${this.#name}' contract`, {
+				table: this.#name,
+				...fault === void 0 ? {} : {
+					field: fault.path,
+					reason: fault.reason
+				}
+			});
+		}
 		return parsed;
 	}
 	#resolveKey(row) {
@@ -2073,80 +3066,99 @@ var Table = class {
 	#cast(row) {
 		return row !== void 0 && this.#guard(row) ? row : void 0;
 	}
+	#track(operation) {
+		if (this.#context !== void 0) return this.#context.track(operation);
+		return this.#scope === void 0 ? operation() : this.#scope.track(operation);
+	}
 };
 //#endregion
-//#region src/core/Database.ts
+//#region src/core/DatabaseTransaction.ts
 /**
-* A database — the ergonomic entry point over a {@link DriverInterface}.
+* A table-only database view bound to one driver transaction scope.
+*
+* @typeParam T - The declared table shape map
 *
 * @remarks
-* Owns the driver and a `tables` shape map, connecting the driver lazily on first
-* use so a freshly created database is immediately usable. `table(name)` returns
-* a table typed by that table's shape `Infer`. `import` registers more tables and
-* returns a database re-typed with them over the **same** driver and storage;
-* `export` emits a portable {@link TableExport} per table. `transaction` snapshots
-* the driver, runs the scope, and rolls every table back if it throws — an
-* optimistic model that works uniformly across backends rather than reconciling
-* SQL's and IndexedDB's incompatible native transactions.
+* The view gives transaction work the same typed tables as its owning database
+* while enforcing a materially narrower contract and lifetime. `table` and
+* every table operation call the owning scope check, so a captured capability
+* cannot escape its transaction.
+*/
+var DatabaseTransaction = class {
+	#driver;
+	#tables;
+	#primary;
+	#generate;
+	#error;
+	#scope;
+	constructor(driver, tables, primary, generate, error, scope) {
+		this.#driver = driver;
+		this.#tables = tables;
+		this.#primary = primary;
+		this.#generate = generate;
+		this.#error = error;
+		this.#scope = scope;
+	}
+	table(name) {
+		this.#scope.check();
+		const columns = this.#columns(name);
+		return this.#build(name, this.#key(name), (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.objectShape)(columns)));
+	}
+	#build(name, key, contract) {
+		return new Table(() => Promise.resolve(), this.#driver, name, key, contract, this.#generate, this.#error, void 0, this.#scope);
+	}
+	#key(name) {
+		return this.#primary[name] ?? "id";
+	}
+	#columns(name) {
+		const columns = this.#tables[name];
+		if (columns === void 0) throw new DatabaseError("NOT_FOUND", `Table '${name}' is not declared`, { table: name });
+		return columns;
+	}
+};
+//#endregion
+//#region src/core/Database.ts
+/**
+* A typed database view over one shared internal lifecycle and storage context.
 *
 * @remarks
-* - **Versioned (optional).** When {@link DatabaseOptions.version} is set and the driver
-*   implements both {@link DriverInterface.meta} and {@link DriverInterface.stamp},
-*   `open()` reconciles the driver's persisted {@link DriverMeta} against the declared
-*   version INSIDE the same lazy-connect chain, AFTER the `open` event fires — see
-*   {@link DatabaseOptions.version} for the full reconciliation contract.
-* - **Observable (§13).** The owned {@link emitter} ({@link DatabaseEventMap}) carries the
-*   connection + transaction lifecycle — `open` / `close` / `transaction` / `commit` /
-*   `rollback` — for fire-and-forget observers, ALONGSIDE each table's per-row events. Every
-*   event is emitted directly, strictly AFTER the relevant transition: `commit` only after
-*   the scope succeeds, `rollback` only after every table is restored. The `rollback` emit
-*   OBSERVES the propagated error — it never swallows it (the original throw propagates
-*   exactly as before). The emitter isolates a listener throw and routes it to its `error`
-*   handler (the `error` option), so observation can never reorder, throw into, or corrupt
-*   the snapshot / commit / rollback flow.
+* Each view owns only its table contracts, primary columns, indexes, and key
+* generator. Imported views register their physical schemas with the same
+* internal context before opening begins, so every view observes one driver,
+* merged schema, emitter, status, transaction boundary, and terminal close.
 */
 var Database = class Database {
-	#driver;
+	#context;
 	#tables;
-	#keys;
+	#primary;
 	#indexes;
-	#name;
 	#generate;
-	#version;
-	#emitter;
-	#status = "idle";
-	#ready;
 	constructor(options) {
-		this.#driver = options.driver;
 		this.#tables = options.tables;
-		this.#keys = options.keys ?? {};
+		this.#primary = options.primary ?? {};
 		this.#indexes = options.indexes ?? {};
-		this.#name = options.name ?? "database";
-		this.#generate = options.key;
-		this.#version = options.version;
-		this.#emitter = new _orkestrel_emitter.Emitter({
-			...options.on !== void 0 ? { on: options.on } : {},
-			...options.error !== void 0 ? { error: options.error } : {}
-		});
+		this.#generate = options.generator;
+		this.#context = new DatabaseContext(options);
+		this.#context.register(this.#schema());
 	}
 	get emitter() {
-		return this.#emitter;
+		return this.#context.emitter;
 	}
 	get name() {
-		return this.#name;
+		return this.#context.name;
 	}
 	get status() {
-		return this.#status;
+		return this.#context.status;
 	}
 	table(name) {
-		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
+		if (this.#context.status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#context.name}' is closed`, { name: this.#context.name });
 		const columns = this.#columns(name);
 		return this.#build(name, this.#key(name), (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.objectShape)(columns)));
 	}
-	import(tables, keys) {
+	import(tables, primary) {
 		return this.#spawn(tables, {
-			...this.#keys,
-			...keys
+			...this.#primary,
+			...primary
 		});
 	}
 	export() {
@@ -2154,109 +3166,44 @@ var Database = class Database {
 		for (const name of Object.keys(this.#tables)) {
 			const columns = this.#columns(name);
 			result[name] = {
-				key: this.#key(name),
+				primary: this.#key(name),
 				columns,
 				schema: (0, _orkestrel_contract.compileSchema)((0, _orkestrel_contract.objectShape)(columns))
 			};
 		}
 		return result;
 	}
-	async open() {
-		await this.#connect();
+	open() {
+		return this.#context.open();
 	}
-	async close() {
-		this.#status = "closed";
-		this.#ready = void 0;
-		await this.#driver.close();
-		this.#emitter.emit("close");
+	close() {
+		return this.#context.close();
 	}
-	/**
-	* Run `scope` transactionally: commit its writes on success, roll every table
-	* back if it throws.
-	*
-	* @remarks
-	* When the driver implements the optional native {@link DriverInterface.transaction}
-	* hook, that native `commit` / `rollback` handle drives the transaction; otherwise
-	* the universal snapshot floor (`driver.snapshot()`) runs unchanged. Either path
-	* emits the same `transaction` / `commit` / `rollback` lifecycle (AGENTS §13).
-	* `options.signal` is checked ONCE at entry, before connecting or starting any
-	* transactional work — an already-aborted signal throws `ABORTED` and neither the
-	* native hook nor the snapshot floor is invoked. Nesting is unguarded and
-	* unsupported exactly as before: this is a single-writer model, not reentrant.
-	* On the native path, a `scope` throw rolls back via the native handle; a
-	* native `commit` failure propagates as-is with no rollback attempt — the
-	* engine owns transaction state after a failed COMMIT.
-	*
-	* @param scope - The transactional work to run
-	* @param options - `{ signal }` to abort before the transaction starts
-	* @returns The scope's resolved value
-	* @throws An `ABORTED` {@link DatabaseError} when `options.signal` has already fired
-	*/
-	async transaction(scope, options) {
-		checkAbort(options?.signal);
-		await this.#connect();
-		const native = await this.#driver.transaction?.();
-		if (native !== void 0) {
-			this.#emitter.emit("transaction");
-			let value;
-			try {
-				value = await scope();
-			} catch (error) {
-				await native.rollback();
-				this.#emitter.emit("rollback", error);
-				throw error;
-			}
-			await native.commit();
-			this.#emitter.emit("commit");
-			return value;
-		}
-		const rollback = await this.#driver.snapshot();
-		this.#emitter.emit("transaction");
-		try {
-			const value = await scope();
-			this.#emitter.emit("commit");
-			return value;
-		} catch (error) {
-			await rollback();
-			this.#emitter.emit("rollback", error);
-			throw error;
-		}
+	transaction(scope, options) {
+		return this.#context.transaction(async (storage, lifetime) => {
+			const transaction = new DatabaseTransaction(storage, this.#tables, this.#primary, this.#generate, this.#context.error, lifetime);
+			return this.#settle(scope, transaction, lifetime);
+		}, options);
 	}
-	/**
-	* Diff `deployed` against this database's declared schema and apply the
-	* resulting plan through the driver's optional `migrate` hook.
-	*
-	* @param deployed - The schema currently deployed, as {@link TableSchema}s
-	* @param options - `{ signal }` to abort before the migration starts
-	* @returns The applied {@link Migration} plan
-	* @throws A `MIGRATION` {@link DatabaseError} when the driver does not
-	* implement `migrate`, or when a step references an unknown table
-	* (propagated from the driver)
-	* @throws An `ABORTED` {@link DatabaseError} when `options.signal` has
-	* already fired at entry
-	*/
-	async migrate(deployed, options) {
-		checkAbort(options?.signal);
-		await this.#connect();
-		const plan = planMigration(deployed, this.#schema());
-		if (this.#driver.migrate === void 0) throw new DatabaseError("MIGRATION", `Database '${this.#name}' driver does not support migration`, { name: this.#name });
-		await this.#apply(plan);
-		return plan;
+	migrate(deployed, options) {
+		return this.#context.migrate(deployed, options);
 	}
 	#build(name, key, contract) {
-		return new Table(() => this.#connect(), this.#driver, name, key, contract, this.#generate);
+		return new Table(() => this.#context.connect(), this.#context.driver, name, key, contract, this.#generate, this.#context.error, this.#context);
 	}
-	#spawn(tables, keys) {
-		return new Database({
-			driver: this.#driver,
+	#spawn(tables, primary) {
+		return Database.#attach({
+			driver: this.#context.driver,
 			tables,
-			keys,
-			name: this.#name,
-			...this.#generate === void 0 ? {} : { key: this.#generate }
-		});
+			primary,
+			name: this.#context.name,
+			...this.#context.error === void 0 ? {} : { error: this.#context.error },
+			...this.#generate === void 0 ? {} : { generator: this.#generate },
+			...this.#context.version === void 0 ? {} : { version: this.#context.version }
+		}, this.#context);
 	}
 	#key(name) {
-		return this.#keys[name] ?? "id";
+		return this.#primary[name] ?? "id";
 	}
 	#columns(name) {
 		const columns = this.#tables[name];
@@ -2269,74 +3216,36 @@ var Database = class Database {
 			return {
 				name,
 				primary: this.#key(name),
-				columns: Object.entries(columns).map(([column, shape]) => {
-					return {
-						name: column,
-						type: shapeToColumnType(shape),
-						nullable: shape.type === "optional" || shape.type === "nullable"
-					};
-				}),
+				columns: Object.entries(columns).map(([column, shape]) => shapeToColumnSchema(column, shape)),
 				indexes: this.#indexes[name] ?? []
 			};
 		});
 	}
-	#connect() {
-		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
-		if (this.#ready === void 0) this.#ready = this.#driver.open(this.#schema()).then(async () => {
-			if (this.#status === "idle") this.#status = "open";
-			this.#emitter.emit("open");
-			await this.#reconcile();
-		});
-		return this.#ready;
-	}
-	async #reconcile() {
-		if (this.#version === void 0 || this.#driver.meta === void 0) return;
-		const declared = this.#schema();
-		const meta = await this.#driver.meta();
-		if (meta === void 0) {
-			await this.#stamp();
-			return;
-		}
-		if (meta.version > this.#version) throw new DatabaseError("MIGRATION", `Database '${this.#name}' store version ${meta.version} is newer than declared version ${this.#version}`, {
-			name: this.#name,
-			stored: meta.version,
-			declared: this.#version
-		});
-		if (meta.version < this.#version) {
-			const plan = planMigration(meta.schema, declared, meta.version, this.#version);
-			if (plan.steps.length > 0 && this.#driver.migrate === void 0) throw new DatabaseError("MIGRATION", `Database '${this.#name}' driver does not support migration`, {
-				name: this.#name,
-				stored: meta.version,
-				declared: this.#version
-			});
-			await this.#apply(plan);
-		}
-	}
-	async #apply(plan) {
-		const native = await this.#driver.transaction?.();
-		if (native !== void 0) {
-			try {
-				await this.#driver.migrate?.(plan);
-				await this.#stamp();
-			} catch (error) {
-				await native.rollback();
-				throw error;
-			}
-			await native.commit();
-			this.#emitter.emit("migrate", plan);
-			return;
-		}
-		await this.#driver.migrate?.(plan);
-		await this.#stamp();
-		this.#emitter.emit("migrate", plan);
-	}
-	async #stamp() {
-		if (this.#version === void 0 || this.#driver.stamp === void 0) return;
-		const meta = {
-			version: this.#version,
-			schema: this.#schema()
-		};
-		await this.#driver.stamp(meta);
+	async #settle(scope, transaction, lifetime) {
+		const outcome = await Promise.resolve().then(() => scope(transaction)).then((value) => ({
+			success: true,
+			value
+		}), (error) => ({
+			success: false,
+			error
+		}));
+		lifetime.stop();
+		const drained = await lifetime.drain().then(() => ({
+			success: true,
+			value: void 0
+		}), (error) => ({
+			success: false,
+			error
+		}));
+		if (!outcome.success) return outcome;
+		if (!drained.success) return drained;
+		return outcome;
+	}
+	static #attach(options, context) {
+		const database = new Database(options);
+		database.#context = context;
+		context.register(database.#schema());
+		return database;
 	}
 };
 //#endregion
@@ -2352,29 +3261,54 @@ var Database = class Database {
 * snapshot capture and restore — so a caller mutating a nested field of an input
 * row, a returned row, or a row mutated in place between snapshot and rollback
 * can never perturb stored state (AGENTS §11); a shallow `{ ...row }` spread
-* would still share nested object/array references. `snapshot`
+* would still share nested object/array references. Metadata instead routes
+* through `cloneDriverMetadata`: `stamp` and migration snapshot exact JSON at
+* ingress, and `metadata` returns a distinct deeply frozen owned copy. `snapshot`
 * clones every table to give transactions an exact rollback point. `scan` and
 * `keys` yield in key order — sorted by the core {@link compareValues} total
 * order, the same contract the SQLite (`ORDER BY`) and IndexedDB (key-ordered
 * reads) backends honor, so an unordered read agrees across every backend rather
 * than leaking Map insertion order. A persistent backend (IndexedDB, SQLite)
-* implements the same nine methods over real storage.
+* implements the same required methods over real storage.
 */
 var MemoryDriver = class {
 	#tables = /* @__PURE__ */ new Map();
-	#meta;
+	#identities = /* @__PURE__ */ new Map();
+	#schema = [];
+	#metadata;
 	async open(schema) {
-		for (const table of schema) if (!this.#tables.has(table.name)) this.#tables.set(table.name, /* @__PURE__ */ new Map());
+		const owned = normalizeDriverSchema(schema);
+		const deployed = normalizeDriverSchema(this.#metadata?.schema ?? owned);
+		const names = new Set(deployed.map((table) => table.name));
+		for (const name of this.#identities.keys()) if (!names.has(name)) this.#identities.delete(name);
+		for (const table of deployed) {
+			if (!this.#tables.has(table.name)) this.#tables.set(table.name, /* @__PURE__ */ new Map());
+			if (!this.#identities.has(table.name)) this.#identities.set(table.name, {});
+		}
+		this.#schema = deployed;
 	}
 	async close() {}
 	async read(table, key) {
 		const row = this.#store(table).get(key);
 		return row === void 0 ? void 0 : structuredClone(row);
 	}
-	async write(table, key, row) {
-		this.#store(table).set(key, structuredClone(row));
+	async write(table, key, row, options) {
+		checkAbort(options?.signal);
+		const primary = this.#table(table).primary;
+		this.#store(table).set(key, structuredClone(bindRowKey(row, primary, key)));
+	}
+	async insert(table, key, row, options) {
+		checkAbort(options?.signal);
+		const store = this.#store(table);
+		if (store.has(key)) throw new DatabaseError("CONFLICT", `Row '${key}' already exists in table '${table}'`, {
+			table,
+			key
+		});
+		const primary = this.#table(table).primary;
+		store.set(key, structuredClone(bindRowKey(row, primary, key)));
 	}
-	async delete(table, key) {
+	async delete(table, key, options) {
+		checkAbort(options?.signal);
 		return this.#store(table).delete(key);
 	}
 	async keys(table) {
@@ -2393,17 +3327,17 @@ var MemoryDriver = class {
 	* @remarks
 	* Iterates the table's keys in the same key order `scan` and `keys` yield
 	* (sorted by {@link compareValues}), testing each row against
-	* `criteria.conditions` (via {@link matchesCriteria}) before counting it
+	* `input.conditions` (via {@link matchesQuery}) before counting it
 	* toward `offset` / `limit`. Both are applied lazily as matches are found —
 	* `offset` matches are skipped without being yielded, and iteration stops the
 	* instant `limit` yields have been produced, so a large table is never fully
-	* walked for a small page. `criteria.order` is IGNORED (the same contract as
+	* walked for a small page. `input.order` is IGNORED (the same contract as
 	* `TableInterface.scan` and `QueryInterface.stream`): streaming yields key
 	* order, sorted output is `records()`'s job. Rows yield copy-out (AGENTS
 	* §11), and an unknown table mirrors `scan`'s empty-yield behavior.
 	*
 	* @param table - The table to stream
-	* @param criteria - The filter / offset / limit to apply lazily
+	* @param input - The filter / offset / limit to apply lazily
 	*
 	* @example
 	* ```ts
@@ -2412,18 +3346,22 @@ var MemoryDriver = class {
 	* }
 	* ```
 	*/
-	async *stream(table, criteria) {
+	stream(table, input) {
+		validatePage(input);
+		return this.#stream(table, input);
+	}
+	async *#stream(table, input) {
 		const store = this.#store(table);
-		const conditions = criteria.conditions;
-		const offset = criteria.offset ?? 0;
-		const limit = criteria.limit;
+		const conditions = input.conditions;
+		const offset = input.offset ?? 0;
+		const limit = input.limit;
 		let skipped = 0;
 		let yielded = 0;
 		for (const key of this.#ordered(table)) {
 			if (limit !== void 0 && yielded >= limit) return;
 			const row = store.get(key);
 			if (row === void 0) continue;
-			if (conditions !== void 0 && conditions.length > 0 && !matchesCriteria(row, conditions)) continue;
+			if (conditions !== void 0 && conditions.length > 0 && !matchesQuery(row, conditions)) continue;
 			if (skipped < offset) {
 				skipped += 1;
 				continue;
@@ -2439,90 +3377,149 @@ var MemoryDriver = class {
 	* Capture the current state and return a thunk that rolls back to it.
 	*
 	* @remarks
-	* `tables` omitted clones and restores the WHOLE store, byte-identical to the
-	* prior whole-store behavior. `tables` provided clones ONLY the named tables,
-	* and the returned thunk restores ONLY those — every other table keeps
-	* whatever it was mutated to after the snapshot was taken.
+	* Capture owns rows, schema, and one session-local table identity. Replay
+	* adapts rows to each surviving same-identity table's current schema before
+	* changing storage. Removed or replaced tables are skipped; uncaptured and
+	* later-added tables retain their current rows. Schema and metadata are never
+	* restored.
 	*
 	* @param tables - The table names to scope the snapshot to; omitted captures every table
 	* @returns A thunk that restores the captured tables
 	*/
 	async snapshot(tables) {
-		if (tables === void 0) {
-			const copy = /* @__PURE__ */ new Map();
-			for (const [name, store] of this.#tables) {
-				const cloned = /* @__PURE__ */ new Map();
-				for (const [key, row] of store) cloned.set(key, structuredClone(row));
-				copy.set(name, cloned);
-			}
-			return async () => {
-				this.#tables.clear();
-				for (const [name, store] of copy) {
-					const restored = /* @__PURE__ */ new Map();
-					for (const [key, row] of store) restored.set(key, structuredClone(row));
-					this.#tables.set(name, restored);
-				}
-			};
-		}
-		const copy = /* @__PURE__ */ new Map();
-		for (const name of tables) {
+		const names = tables === void 0 ? this.#schema.map((table) => table.name) : [...new Set(tables)].filter((name) => this.#schema.some((table) => table.name === name));
+		const captured = /* @__PURE__ */ new Map();
+		for (const name of names) {
+			const schema = this.#schema.find((table) => table.name === name);
 			const store = this.#tables.get(name);
-			if (store === void 0) continue;
-			const cloned = /* @__PURE__ */ new Map();
-			for (const [key, row] of store) cloned.set(key, structuredClone(row));
-			copy.set(name, cloned);
+			const identity = this.#identities.get(name);
+			if (schema === void 0 || store === void 0 || identity === void 0) continue;
+			const rows = /* @__PURE__ */ new Map();
+			for (const [key, row] of store) rows.set(key, structuredClone(row));
+			captured.set(name, {
+				identity,
+				rows,
+				schema
+			});
 		}
 		return async () => {
-			for (const [name, store] of copy) {
-				const restored = /* @__PURE__ */ new Map();
-				for (const [key, row] of store) restored.set(key, structuredClone(row));
-				this.#tables.set(name, restored);
+			const replacements = /* @__PURE__ */ new Map();
+			for (const [name, capture] of captured) {
+				const schema = this.#schema.find((table) => table.name === name);
+				const store = this.#tables.get(name);
+				if (schema === void 0 || store === void 0 || this.#identities.get(name) !== capture.identity) continue;
+				const plan = planMigration([capture.schema], [schema]);
+				const entries = [...capture.rows.entries()];
+				const migrated = migrateRows(entries.map(([, row]) => row), plan.steps);
+				if (migrated.length !== entries.length) throw new DatabaseError("MIGRATION", "Snapshot row count changed during migration", { table: name });
+				const rows = /* @__PURE__ */ new Map();
+				for (const [index, [key]] of entries.entries()) {
+					const row = migrated[index];
+					if (!isKey(key) || row === void 0) throw new DatabaseError("MIGRATION", "Snapshot row has no usable primary key", {
+						table: name,
+						column: schema.primary,
+						index
+					});
+					rows.set(key, structuredClone(bindRowKey(row, schema.primary, key)));
+				}
+				replacements.set(store, rows);
+			}
+			for (const [store, rows] of replacements) {
+				store.clear();
+				for (const [key, row] of rows) store.set(key, row);
 			}
 		};
 	}
 	/**
-	* Return the persisted {@link DriverMeta}, or `undefined` when the store has
+	* Return the persisted {@link DriverMetadata}, or `undefined` when the store has
 	* never been stamped.
 	*
 	* @remarks
 	* In-process only — the metadata lives in this instance's memory, exactly
-	* like the rest of this driver's storage. A driver-conformance-valid
-	* implementation of the optional `meta` / `stamp` pair.
+	* like the rest of this driver's storage. The returned value is a distinct
+	* deeply frozen owned snapshot. A driver-conformance-valid implementation of
+	* the optional `metadata` / `stamp` pair.
 	*
-	* @returns The last-stamped {@link DriverMeta}, or `undefined`
+	* @returns The last-stamped {@link DriverMetadata}, or `undefined`
 	*/
-	async meta() {
-		return this.#meta;
+	async metadata() {
+		return this.#metadata === void 0 ? void 0 : cloneDriverMetadata(this.#metadata);
 	}
 	/**
-	* Persist `meta` verbatim for a later `meta()` to return.
+	* Persist an owned snapshot for a later `metadata()` to return.
 	*
-	* @param meta - The {@link DriverMeta} to persist
+	* @param metadata - The {@link DriverMetadata} to persist
 	*/
-	async stamp(meta) {
-		this.#meta = meta;
+	async stamp(metadata) {
+		this.#metadata = cloneDriverMetadata(metadata);
 	}
 	/**
 	* Apply a {@link Migration} plan's steps against the in-memory store.
 	*
 	* @remarks
-	* A multi-step plan applies its steps sequentially and is NOT atomic — a
-	* failure partway through a plan leaves the earlier steps already applied.
+	* Steps apply against an isolated candidate. Rows, schema changes, and
+	* optional metadata publish together only after the whole request succeeds.
 	*
-	* @param plan - The migration plan to apply
+	* @param input - The migration plan and optional metadata to settle atomically
 	*/
-	async migrate(plan) {
-		for (const step of plan.steps) switch (step.operation) {
+	async migrate(input) {
+		const owned = cloneMigrationInput(input);
+		const schema = projectMigrationSchema(this.#schema, owned.plan.steps);
+		if (owned.metadata !== void 0 && !equalsValue(normalizeDriverSchema(owned.metadata.schema), schema)) throw new DatabaseError("MIGRATION", "Migration metadata schema does not match the plan", {
+			projected: schema,
+			metadata: owned.metadata.schema
+		});
+		const candidate = this.#copy(this.#tables);
+		const identities = this.#projectIdentities(this.#identities, owned.plan.steps);
+		for (const step of owned.plan.steps) this.#migrate(candidate, step);
+		this.#tables.clear();
+		for (const [name, store] of candidate) this.#tables.set(name, store);
+		this.#identities = identities;
+		this.#schema = schema;
+		if (owned.metadata !== void 0) this.#metadata = owned.metadata;
+	}
+	#ordered(table) {
+		return [...this.#store(table).keys()].sort(compareValues);
+	}
+	#require(tables, table) {
+		const store = tables.get(table);
+		if (store === void 0) throw new DatabaseError("MIGRATION", `migrate: unknown table '${table}'`, { table });
+		return store;
+	}
+	#copy(tables) {
+		const copy = /* @__PURE__ */ new Map();
+		for (const [name, store] of tables) {
+			const cloned = /* @__PURE__ */ new Map();
+			for (const [key, row] of store) cloned.set(key, structuredClone(row));
+			copy.set(name, cloned);
+		}
+		return copy;
+	}
+	#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) {
+		const schema = this.#schema.find((table) => table.name === name);
+		if (schema === void 0) throw new DatabaseError("NOT_FOUND", `Unknown table '${name}'`, { table: name });
+		return schema;
+	}
+	#migrate(tables, step) {
+		switch (step.operation) {
 			case "table.add":
-				if (!this.#tables.has(step.table.name)) this.#tables.set(step.table.name, /* @__PURE__ */ new Map());
+				if (!tables.has(step.table.name)) tables.set(step.table.name, /* @__PURE__ */ new Map());
 				break;
 			case "table.remove":
-				this.#require(step.table);
-				this.#tables.delete(step.table);
+				this.#require(tables, step.table);
+				tables.delete(step.table);
 				break;
 			case "column.add":
 			case "column.remove": {
-				const store = this.#require(step.table);
+				const store = this.#require(tables, step.table);
 				const rows = [...store.entries()];
 				const migrated = migrateRows(rows.map(([, row]) => row), [step]);
 				for (const [index, [key]] of rows.entries()) {
@@ -2536,25 +3533,13 @@ var MemoryDriver = class {
 				break;
 			}
 			case "index.add":
-			case "index.remove":
-				this.#require(step.table);
-				break;
+			case "index.remove": this.#require(tables, step.table);
 		}
 	}
-	#ordered(table) {
-		return [...this.#store(table).keys()].sort(compareValues);
-	}
-	#require(table) {
-		const store = this.#tables.get(table);
-		if (store === void 0) throw new DatabaseError("MIGRATION", `migrate: unknown table '${table}'`, { table });
-		return store;
-	}
 	#store(table) {
-		let store = this.#tables.get(table);
-		if (store === void 0) {
-			store = /* @__PURE__ */ new Map();
-			this.#tables.set(table, store);
-		}
+		this.#table(table);
+		const store = this.#tables.get(table);
+		if (store === void 0) throw new DatabaseError("NOT_FOUND", `Table '${table}' has no backing store`, { table });
 		return store;
 	}
 };
@@ -2569,10 +3554,10 @@ var MemoryDriver = class {
 * level. The `const` type parameter captures the literal names and columns, so
 * `db.table('users')` is checked against the schema and typed by `Infer` of its
 * columns — no annotations. Name a non-`id` primary-key column per table via the
-* optional `keys` map.
+* optional `primary` and `indexes` maps.
 *
-* @param options - The driver, the `tables` column map, optional `keys`, and an
-*                   optional `name`
+* @param options - The driver, `tables`, and optional `primary`, `indexes`,
+*   `name`, `generator`, `version`, and emitter hooks
 * @returns A typed {@link DatabaseInterface}
 *
 * @example
@@ -2586,7 +3571,7 @@ var MemoryDriver = class {
 * 		users: { id: stringShape(), age: integerShape() },
 * 		posts: { slug: stringShape(), title: stringShape() },
 * 	},
-* 	keys: { posts: 'slug' },
+* 	primary: { posts: 'slug' },
 * })
 * await db.table('users').set({ id: 'u1', age: 36 }) // typed; coerced + validated
 * ```
@@ -2607,40 +3592,48 @@ function createMemoryDriver() {
 	return new MemoryDriver();
 }
 //#endregion
-exports.Clause = Clause;
-exports.Cursor = Cursor;
 exports.DEFAULT_PRIMARY = DEFAULT_PRIMARY;
 exports.Database = Database;
 exports.DatabaseError = DatabaseError;
 exports.MAX_PATTERN_LENGTH = MAX_PATTERN_LENGTH;
 exports.MemoryDriver = MemoryDriver;
-exports.Query = Query;
-exports.Table = Table;
-exports.UUID_BYTE_COUNT = UUID_BYTE_COUNT;
-exports.UUID_BYTE_RANGE = UUID_BYTE_RANGE;
-exports.applyCriteria = applyCriteria;
+exports.applyQuery = applyQuery;
 exports.auditDriver = auditDriver;
+exports.bindRowKey = bindRowKey;
 exports.checkAbort = checkAbort;
+exports.cloneDriverMetadata = cloneDriverMetadata;
+exports.cloneDriverSchema = cloneDriverSchema;
+exports.cloneMigrationInput = cloneMigrationInput;
 exports.compareValues = compareValues;
 exports.computeAggregate = computeAggregate;
 exports.conformDriver = conformDriver;
 exports.createDatabase = createDatabase;
 exports.createMemoryDriver = createMemoryDriver;
-exports.deepEqual = deepEqual;
 exports.driverFindings = driverFindings;
+exports.equalsValue = equalsValue;
 exports.extractKey = extractKey;
 exports.filterRows = filterRows;
-exports.generateUUID = generateUUID;
-exports.globMatch = globMatch;
+exports.isColumnSchema = isColumnSchema;
 exports.isDatabaseError = isDatabaseError;
-exports.isDriverMeta = isDriverMeta;
-exports.likeMatch = likeMatch;
+exports.isDriverMetadata = isDriverMetadata;
+exports.isDriverSchema = isDriverSchema;
+exports.isKey = isKey;
+exports.isMigration = isMigration;
+exports.isMigrationInput = isMigrationInput;
+exports.isMigrationStep = isMigrationStep;
+exports.isTableSchema = isTableSchema;
 exports.matchesCondition = matchesCondition;
-exports.matchesCriteria = matchesCriteria;
+exports.matchesGlobPattern = matchesGlobPattern;
+exports.matchesLikePattern = matchesLikePattern;
+exports.matchesQuery = matchesQuery;
+exports.matchesWildcardPattern = matchesWildcardPattern;
 exports.migrateRows = migrateRows;
+exports.normalizeDriverSchema = normalizeDriverSchema;
 exports.planMigration = planMigration;
-exports.shapeToColumnType = shapeToColumnType;
+exports.projectMigrationSchema = projectMigrationSchema;
+exports.shapeToColumnSchema = shapeToColumnSchema;
+exports.shapeToColumnStorage = shapeToColumnStorage;
 exports.sortRows = sortRows;
-exports.wildcardMatch = wildcardMatch;
+exports.validatePage = validatePage;
 
 //# sourceMappingURL=index.cjs.map