@orkestrel/database 0.0.13 → 0.0.15

package/dist/src/core/index.js

@@ -1,8 +1,8 @@
-import { cloneJSONRecord, cloneJSONValue, compileGuard, compileSchema, createContract, isArray, isRecord, isString, objectShape, parseNumber, resolveField } from "@orkestrel/contract";
+import { arrayOf, cloneJSONRecord, cloneJSONValue, compileGuard, compileSchema, createContract, holds, isArray, isBoolean, isError, isFiniteNumber, isInstance, isInteger, isNumber, isRecord, isString, objectShape, parseNumber, resolveField } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /**
-* Supplies the primary-key column assumed when {@link PrimaryMap} does not name one.
+* Supplies the primary-key column, `'id'`, assumed when {@link PrimaryMap} does not name one.
 *
 * @remarks
 * `id` is the convention IndexedDB (`keyPath: 'id'`) and SQL (`id` / rowid) both
@@ -10,12 +10,13 @@ import { Emitter } from "@orkestrel/emitter";
 */
 var DEFAULT_PRIMARY = "id";
 /**
-* Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts before rejecting it.
+* Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts, 1024 characters, before
+* rejecting it.
 *
 * @remarks
 * A `LIKE` / `GLOB` pattern is a caller-supplied operand, so
 * `matchesLikePattern` / `matchesGlobPattern` run patterns this package cannot
-* trust. The matcher is the LINEAR greedy two-pointer wildcard match — never a
+* trust. 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 ×
 * pattern). Capping the pattern length bounds that pattern factor, leaving a match
@@ -89,11 +90,13 @@ var CONFORMANCE_POSTS_SCHEMA = Object.freeze({
 	indexes: Object.freeze([])
 });
 /**
-* Holds the fixed two-table schema every driver-conformance phase opens.
+* Holds the fixed `users` and `posts` schema every driver-conformance phase opens.
 *
 * @remarks
 * Each phase mints a fresh driver and opens this exact schema, so a finding
-* names a violated invariant rather than a setup difference between phases.
+* names a violated invariant rather than a setup difference between phases. The
+* array and each schema in it are frozen, so a consumer holding it cannot change
+* what a later phase opens.
 */
 var CONFORMANCE_SCHEMA = Object.freeze([CONFORMANCE_USERS_SCHEMA, CONFORMANCE_POSTS_SCHEMA]);
 //#endregion
@@ -140,7 +143,7 @@ var DatabaseError = class extends Error {
 * ```
 */
 function isDatabaseError(value) {
-	return value instanceof DatabaseError;
+	return isInstance(value, DatabaseError);
 }
 //#endregion
 //#region src/core/validators.ts
@@ -151,132 +154,153 @@ function isDatabaseError(value) {
 * @returns True if `value` is a string or a finite number; false otherwise
 */
 function isKey(value) {
-	return typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+	return isString(value) || isFiniteNumber(value);
 }
 /**
 * Checks whether a value is a portable column schema.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link ColumnSchema}; false otherwise
 */
 function isColumnSchema(value) {
-	try {
+	return holds(() => {
 		const column = 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;
-	}
+		return keys.length === 4 && keys.includes("name") && keys.includes("storage") && keys.includes("optional") && keys.includes("nullable") && isString(column.name) && column.name.length > 0 && (column.storage === "text" || column.storage === "integer" || column.storage === "real" || column.storage === "boolean" || column.storage === "json" || column.storage === "blob") && isBoolean(column.optional) && isBoolean(column.nullable);
+	});
 }
 /**
 * Checks whether a value is a portable table schema.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link TableSchema}; false otherwise
 */
 function isTableSchema(value) {
-	try {
+	return holds(() => {
 		const table = 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;
+		if (keys.length !== 4 || !keys.includes("name") || !keys.includes("primary") || !keys.includes("columns") || !keys.includes("indexes") || !isString(table.name) || table.name.length === 0 || !isString(table.primary) || table.primary.length === 0 || !arrayOf(isColumnSchema)(table.columns) || !isArray(table.indexes)) 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;
+		if (new Set(names).size !== names.length || !names.includes(table.primary) || !table.indexes.every((index) => isArray(index) && index.length > 0 && index.every((column) => isString(column) && names.includes(column)))) return false;
 		const indexes = table.indexes.map((index) => JSON.stringify(index));
 		return new Set(indexes).size === indexes.length;
-	} catch {
-		return false;
-	}
+	});
 }
 /**
 * Checks whether a value is a complete portable driver schema.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a table-schema collection with unique table names; false otherwise
 */
 function isDriverSchema(value) {
-	try {
+	return holds(() => {
 		const schema = cloneJSONValue(value);
-		if (!Array.isArray(schema) || !schema.every(isTableSchema)) return false;
+		if (!arrayOf(isTableSchema)(schema)) return false;
 		const names = schema.map((table) => table.name);
 		return new Set(names).size === names.length;
-	} catch {
-		return false;
-	}
+	});
 }
 /**
 * Checks whether a value is one ordered migration step.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link MigrationStep}; false otherwise
 */
 function isMigrationStep(value) {
-	try {
+	return holds(() => {
 		const step = cloneJSONRecord(value);
-		if (typeof step.operation !== "string") return false;
+		if (!isString(step.operation)) 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 "table.remove": return keys.length === 2 && keys.includes("operation") && keys.includes("table") && isString(step.table) && step.table.length > 0;
+			case "column.add": return keys.length === 3 && keys.includes("operation") && keys.includes("table") && keys.includes("column") && isString(step.table) && step.table.length > 0 && isColumnSchema(step.column);
+			case "column.remove": return keys.length === 3 && keys.includes("operation") && keys.includes("table") && keys.includes("column") && isString(step.table) && step.table.length > 0 && isString(step.column) && 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);
+			case "index.remove": return keys.length === 3 && keys.includes("operation") && keys.includes("table") && keys.includes("index") && isString(step.table) && step.table.length > 0 && isArray(step.index) && step.index.length > 0 && step.index.every((column) => isString(column) && column.length > 0);
 			default: return false;
 		}
-	} catch {
-		return false;
-	}
+	});
 }
 /**
 * Checks whether a value is an ordered migration plan.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link Migration}; false otherwise
 */
 function isMigration(value) {
-	try {
+	return holds(() => {
 		const migration = 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;
-	}
+		return keys.length === 3 && keys.includes("from") && keys.includes("to") && keys.includes("steps") && isFiniteNumber(migration.from) && isFiniteNumber(migration.to) && isArray(migration.steps) && migration.steps.every(isMigrationStep);
+	});
 }
 /**
 * Checks whether a value is persisted driver metadata.
 *
+* @remarks
+* The boundary check a versioning driver's `metadata()` narrows a stored or
+* deserialized record through, so no call site needs an assertion. Total over any
+* input: a hostile getter, a revoked proxy, or a cyclic value is contained as a
+* non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is complete {@link DriverMetadata}; false otherwise
 */
 function isDriverMetadata(value) {
-	try {
+	return holds(() => {
 		const metadata = 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;
-	}
+		return keys.length === 2 && keys.includes("version") && keys.includes("schema") && isFiniteNumber(metadata.version) && isDriverSchema(metadata.schema);
+	});
 }
 /**
 * Checks whether a value is one atomic migration request.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link MigrationInput}; false otherwise
 */
 function isMigrationInput(value) {
-	try {
+	return holds(() => {
 		const input = 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
 /**
 * Clones unknown driver metadata into a distinct deeply frozen snapshot.
 *
+* @remarks
+* The clone is validated as {@link DriverMetadata} before it is returned, so a
+* malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+* `context.path === 'metadata'` rather than surfacing a raw Contract or caller error.
+*
 * @param value - Unknown metadata
 * @returns Owned driver metadata
 */
@@ -286,7 +310,7 @@ function cloneDriverMetadata(value) {
 		if (isDriverMetadata(metadata)) return metadata;
 		throw new DatabaseError("VALIDATION", "Driver metadata is invalid", { path: "metadata" });
 	} catch (error) {
-		if (error instanceof DatabaseError) throw error;
+		if (isDatabaseError(error)) throw error;
 		throw new DatabaseError("VALIDATION", "Driver metadata is invalid", {
 			path: "metadata",
 			cause: error
@@ -296,6 +320,11 @@ function cloneDriverMetadata(value) {
 /**
 * Clones unknown driver schema into a distinct deeply frozen snapshot.
 *
+* @remarks
+* The clone is validated as a table-schema collection before it is returned, so a
+* malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+* `context.path === 'schema'` rather than surfacing a raw Contract or caller error.
+*
 * @param value - Unknown table schema collection
 * @returns Owned driver schema
 */
@@ -305,7 +334,7 @@ function cloneDriverSchema(value) {
 		if (isDriverSchema(schema)) return schema;
 		throw new DatabaseError("VALIDATION", "Driver schema is invalid", { path: "schema" });
 	} catch (error) {
-		if (error instanceof DatabaseError) throw error;
+		if (isDatabaseError(error)) throw error;
 		throw new DatabaseError("VALIDATION", "Driver schema is invalid", {
 			path: "schema",
 			cause: error
@@ -315,6 +344,11 @@ function cloneDriverSchema(value) {
 /**
 * Clones unknown migration input into a distinct deeply frozen snapshot.
 *
+* @remarks
+* The clone is validated as a {@link MigrationInput} before it is returned, so a
+* malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+* `context.path === 'migration'` rather than surfacing a raw Contract or caller error.
+*
 * @param value - Unknown migration input
 * @returns Owned migration input
 */
@@ -324,7 +358,7 @@ function cloneMigrationInput(value) {
 		if (isMigrationInput(input)) return input;
 		throw new DatabaseError("VALIDATION", "Migration input is invalid", { path: "migration" });
 	} catch (error) {
-		if (error instanceof DatabaseError) throw error;
+		if (isDatabaseError(error)) throw error;
 		throw new DatabaseError("VALIDATION", "Migration input is invalid", {
 			path: "migration",
 			cause: error
@@ -347,14 +381,14 @@ function cloneMigrationInput(value) {
 */
 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", {
+	if (limit !== void 0 && (!isInteger(limit) || limit < 0)) throw new DatabaseError("VALIDATION", "Query limit must be a nonnegative integer", {
 		field: "limit",
-		value: Number.isFinite(limit) ? limit : String(limit)
+		value: isFiniteNumber(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", {
+	if (offset !== void 0 && (!isInteger(offset) || offset < 0)) throw new DatabaseError("VALIDATION", "Query offset must be a nonnegative integer", {
 		field: "offset",
-		value: Number.isFinite(offset) ? offset : String(offset)
+		value: isFiniteNumber(offset) ? offset : String(offset)
 	});
 }
 /**
@@ -372,14 +406,14 @@ function validatePage(input) {
 * @returns `-1`, `0`, or `1`
 */
 function compareValues(left, right) {
-	const [leftRank = 5, rightRank = 5] = [left, right].map((value) => value === void 0 ? 0 : value === null ? 1 : typeof value === "boolean" ? 2 : typeof value === "number" ? 3 : typeof value === "string" ? 4 : 5);
+	const [leftRank = 5, rightRank = 5] = [left, right].map((value) => value === void 0 ? 0 : value === null ? 1 : isBoolean(value) ? 2 : isNumber(value) ? 3 : isString(value) ? 4 : 5);
 	if (leftRank !== rightRank) return leftRank < rightRank ? -1 : 1;
-	if (typeof left === "number" && typeof right === "number") {
+	if (isNumber(left) && isNumber(right)) {
 		if (Number.isNaN(left) || Number.isNaN(right)) return Number.isNaN(left) ? Number.isNaN(right) ? 0 : 1 : -1;
 		return left < right ? -1 : left > right ? 1 : 0;
 	}
-	if (typeof left === "string" && typeof right === "string") return left < right ? -1 : left > right ? 1 : 0;
-	if (typeof left === "boolean" && typeof right === "boolean") return left === right ? 0 : left ? 1 : -1;
+	if (isString(left) && isString(right)) return left < right ? -1 : left > right ? 1 : 0;
+	if (isBoolean(left) && isBoolean(right)) return left === right ? 0 : left ? 1 : -1;
 	return 0;
 }
 /**
@@ -390,9 +424,9 @@ function compareValues(left, right) {
 * @remarks
 * Primitives compare by SameValueZero (`NaN` equals itself; `+0` equals `-0`).
 * Arrays compare by index (same length, every element `equalsValue`). Plain
-* records (through `isRecord`) compare by their OWN enumerable keys: same key
-* COUNT and, for every key in `left`, `right` has that key (`Object.hasOwn`)
-* with a `equalsValue` value — so a key present with value `undefined` is NOT
+* records (through `isRecord`) compare by their own enumerable keys: same key
+* count and, for every key in `left`, `right` has that key (`Object.hasOwn`)
+* 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`. Container pairs are tracked iteratively, so self-referential and
@@ -418,13 +452,13 @@ function equalsValue(left, right) {
 			const pair = pending.pop();
 			if (pair === void 0) continue;
 			const [currentLeft, currentRight] = pair;
-			if (typeof currentLeft === "number" && typeof currentRight === "number") {
+			if (isNumber(currentLeft) && isNumber(currentRight)) {
 				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 leftArray = isArray(currentLeft);
+			const rightArray = isArray(currentRight);
 			const leftRecord = isRecord(currentLeft);
 			const rightRecord = isRecord(currentRight);
 			if (leftArray !== rightArray || leftRecord !== rightRecord) return false;
@@ -458,16 +492,16 @@ function equalsValue(left, right) {
 	}
 }
 /**
-* Matches a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
+* Matches a value against a wildcard pattern in linear time — the shared, ReDoS-safe
 * engine behind {@link matchesLikePattern} and {@link matchesGlobPattern}.
 *
 * @remarks
-* A backtracking RegExp (`a%b%c` → `^a.*b.*c$`) is CATASTROPHIC on a hostile pattern:
+* 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,
 * while a `LIKE` / `GLOB` pattern is a caller-supplied operand this package cannot
-* trust. 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
+* trust. 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),
 * never the exponential / polynomial backtracking a regex would do. The pattern length
 * is capped at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it),
@@ -475,16 +509,16 @@ function equalsValue(left, right) {
 * pattern.
 *
 * The `any` wildcard matches any run (including empty); `single` matches exactly one
-* char; every other pattern char matches itself LITERALLY (a pattern `.` / `(` / `\` is
+* char; every other pattern char matches itself literally (a pattern `.` / `(` / `\` is
 * a literal — the regex-metacharacter hazard is gone with the regex). `any` is tested
-* BEFORE a literal match, so a value that literally contains the wildcard char never
-* shadows the wildcard. Case folding is applied to BOTH sides when `fold` is set.
+* before a literal match, so a value that literally contains the wildcard char never
+* shadows the wildcard. Case folding is applied to both sides when `fold` is set.
 *
 * @param value - The value to test
 * @param pattern - The wildcard pattern
 * @param any - The any-run wildcard char (`%` for `LIKE`, `*` for `GLOB`)
 * @param single - The single-char wildcard char (`_` for `LIKE`, `?` for `GLOB`)
-* @param fold - Whether to match case-INSENSITIVELY (`LIKE` folds; `GLOB` does not)
+* @param fold - Whether to match case-insensitively (`LIKE` folds; `GLOB` does not)
 * @returns True if `value` matches `pattern`; false otherwise
 * @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
 */
@@ -546,7 +580,7 @@ function matchesLikePattern(value, pattern) {
 * @remarks
 * `*` matches any run of characters (including none) and `?` matches exactly one
 * character; every other pattern character matches itself literally, so a
-* character class such as `[a-z]` is NOT interpreted. Runs on
+* character class such as `[a-z]` is not interpreted. Runs on
 * {@link matchesWildcardPattern}, so the match is linear in the value length and
 * the pattern is capped at {@link MAX_PATTERN_LENGTH}.
 *
@@ -572,7 +606,7 @@ function matchesGlobPattern(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 equalsValue} — 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: `equalsValue` is SameValueZero
@@ -730,7 +764,9 @@ function computeAggregate(rows, operation, column) {
 		const total = numbers.reduce((sum, value) => sum + value, 0);
 		return operation === "average" ? total / numbers.length : total;
 	}
-	return operation === "minimum" ? Math.min(...numbers) : Math.max(...numbers);
+	let result = operation === "minimum" ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+	for (const value of numbers) result = operation === "minimum" ? Math.min(result, value) : Math.max(result, value);
+	return result;
 }
 /**
 * Reads a row's primary key from a column, when it is a usable {@link Key}.
@@ -787,8 +823,8 @@ function shapeToColumnStorage(shape) {
 		case "number": return shape.integer === true ? "integer" : "real";
 		case "boolean": return "boolean";
 		case "literal":
-			if (shape.values.every((value) => typeof value === "boolean")) return "boolean";
-			if (shape.values.every((value) => typeof value === "number")) return shape.values.every((value) => Number.isInteger(value)) ? "integer" : "real";
+			if (shape.values.every((value) => isBoolean(value))) return "boolean";
+			if (shape.values.every((value) => isNumber(value))) return shape.values.every((value) => isInteger(value)) ? "integer" : "real";
 			return "text";
 		case "optional":
 		case "nullable": return shapeToColumnStorage(shape.inner);
@@ -908,16 +944,16 @@ function checkAbort(signal) {
 * 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
+* A column present in both schemas under the same name but with a different
 * `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
+* 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 type-change step: the manual path is to add a new column,
 * copy/convert the data at the application layer, then remove the old column —
 * two separate plans, never a single implicit "alter" step.
 *
-* @param deployed - The table schemas currently applied
+* @param deployed - The already-applied table schemas
 * @param declared - The table schemas the caller wants applied
 * @param from - The plan's source version label (defaults to `0`)
 * @param to - The plan's target version label (defaults to `1`)
@@ -937,7 +973,7 @@ function checkAbort(signal) {
 * ```
 */
 function planMigration(deployed, declared, from = 0, to = 1) {
-	if (!Number.isFinite(from) || !Number.isFinite(to)) throw new DatabaseError("MIGRATION", "Migration versions must be finite", {
+	if (!isFiniteNumber(from) || !isFiniteNumber(to)) throw new DatabaseError("MIGRATION", "Migration versions must be finite", {
 		from,
 		to
 	});
@@ -1024,6 +1060,8 @@ function planMigration(deployed, declared, from = 0, to = 1) {
 }
 /**
 * Projects migration steps sequentially over a canonical validated owned schema.
+*
+* @remarks
 * Adding a required non-null column to an existing table rejects with
 * `MIGRATION`; optional-only and nullable-only additions remain portable.
 *
@@ -1187,14 +1225,14 @@ function migrateRows(rows, steps) {
 * default `id`, `posts` keyed by a non-id `slug`) and, calling `factory()`
 * fresh for each phase so failures stay isolated, verifies: `open`/`close`;
 * `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
+* 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; 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
+* 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
@@ -1208,12 +1246,12 @@ function migrateRows(rows, steps) {
 * 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
+* Each phase runs within a `try`/`catch`: an expected mismatch yields a
+* finding built from the assertion, while an unexpected throw (a driver
 * crash mid-phase) is caught and yielded as a finding too, naming the phase
 * as `check` and carrying the caught error in `context.error` — a broken
 * driver can never escape the battery as an unhandled rejection. Within a
-* phase, the FIRST violated assertion yields and the phase stops (matching
+* phase, the first violated assertion yields and the phase stops (matching
 * the historical fail-fast shape at phase granularity); the generator then
 * moves on to the next phase regardless. Because this is a **generator**,
 * consuming only the first yielded value reproduces true fail-fast (later
@@ -1239,7 +1277,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "open-close",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1260,7 +1298,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "read-missing",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1336,7 +1374,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "write-read",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1377,7 +1415,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "insert-atomic",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1417,7 +1455,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "delete",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1480,7 +1518,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "mutation-abort",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1539,7 +1577,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "order",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1583,7 +1621,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "clear",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1632,7 +1670,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "snapshot",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1670,7 +1708,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "snapshot-nested",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1696,7 +1734,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "non-id-primary",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1727,7 +1765,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "nested-roundtrip",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1792,7 +1830,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "migrate",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1857,7 +1895,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "stream",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1918,7 +1956,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "transaction",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -1957,7 +1995,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "metadata-stamp",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -2012,7 +2050,7 @@ async function* scanDriver(factory) {
 	} catch (error) {
 		yield {
 			check: "snapshot-scoped",
-			message: error instanceof Error ? error.message : String(error),
+			message: isError(error) ? error.message : String(error),
 			context: { error }
 		};
 	}
@@ -2024,11 +2062,13 @@ async function* scanDriver(factory) {
 *
 * @remarks
 * Consumes only the first value {@link scanDriver} yields: because that
-* generator is lazy, every LATER phase never runs — true fail-fast, not
+* generator is lazy, every later phase never runs — true fail-fast, not
 * merely "report only the first". The
 * thrown error is byte-compatible with the historical shape: a
 * `CONFORMANCE` {@link DatabaseError} whose `message` is the finding's
-* `message` and whose `context` is `{ check, ...finding.context }`.
+* `message` and whose `context` is `{ check, ...finding.context }`. The battery
+* takes a driver factory and reports through a throw, so it binds no test
+* framework and runs from any runner.
 *
 * @param factory - Mints a fresh, unopened driver instance (called once per phase)
 * @returns Nothing — resolves once every phase has passed
@@ -2048,7 +2088,7 @@ async function conformDriver(factory) {
 	});
 }
 /**
-* Runs the FULL driver-conformance battery and collects every violation — the
+* Runs the full driver-conformance battery and collects every violation — the
 * audit entry point for a driver author who wants a complete report rather
 * than a single fail-fast throw.
 *
@@ -2718,10 +2758,10 @@ var Query = class {
 * @remarks
 * - **Observable.** The owned {@link emitter} ({@link TableEventMap}) carries the
 *   per-row mutation moments — `write` (set / add / update), `remove`, `clear` — for
-*   fire-and-forget observers (cache invalidation, sync, an audit log), ALONGSIDE the
-*   database-level lifecycle. Events carry the affected KEY only (no value payload, to
+*   fire-and-forget observers (cache invalidation, sync, an audit log), alongside the
+*   database-level lifecycle. Events carry the affected key only (no value payload, to
 *   keep fan-out lean); reads / queries / counts are not emitted. Every event is emitted
-*   directly, strictly AFTER the driver write / delete / clear completes; the emitter
+*   directly, strictly after the driver write / delete / clear completes; the emitter
 *   isolates a listener throw and routes it to its `error` handler (the `error` option),
 *   so a buggy observer can never corrupt a write or perturb a transaction.
 */
@@ -2834,7 +2874,7 @@ var Table = class {
 	* conditions.
 	*
 	* @remarks
-	* Unlike {@link count}, `aggregate` operates on STORED rows WITHOUT the
+	* Unlike {@link count}, `aggregate` operates on stored rows without the
 	* contract guard {@link records} / {@link scan} apply — a non-conforming
 	* stored row still contributes to the computed aggregate when it matches
 	* the conditions, even though it would never appear in `records()`'s
@@ -3162,6 +3202,10 @@ var DatabaseTransaction = class {
 * 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.
+*
+* The view owns the driver and its declared `tables`, connects that driver lazily on
+* first use, `import`s further tables and `export`s their portable definitions, and
+* runs `transaction` scopes over the shared context.
 */
 var Database = class Database {
 	#context;
@@ -3284,7 +3328,7 @@ var Database = class Database {
 * @remarks
 * The in-between made concrete: it runs identically in a browser or on a server,
 * so it is the storage behind tests, ephemeral caches, and any code that wants
-* the database API without a persistent backend. Rows are DEEP-copied (through
+* the database API without a persistent backend. Rows are deep-copied (through
 * `structuredClone`) in and out — at `write`, `read`, `scan`, `stream`, and both
 * 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
@@ -3359,7 +3403,7 @@ var MemoryDriver = class {
 	* 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. `input.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, and an
 	* unknown table mirrors `scan`'s empty-yield behavior.
@@ -3588,20 +3632,29 @@ var MemoryDriver = class {
 *   `name`, `generator`, `version`, and emitter hooks
 * @returns A typed {@link DatabaseInterface}
 *
-* @example
+* @example Create a database
 * ```ts
 * import { createDatabase, createMemoryDriver } from '@orkestrel/database'
 * import { integerShape, stringShape } from '@orkestrel/contract'
 *
 * const db = createDatabase({
-* 	driver: createMemoryDriver(),
+* 	driver: createMemoryDriver(), // any DriverInterface — a persistent backend swaps in, same API
 * 	tables: {
-* 		users: { id: stringShape(), age: integerShape() },
+* 		users: { id: stringShape(), name: stringShape(), age: integerShape() },
 * 		posts: { slug: stringShape(), title: stringShape() },
 * 	},
-* 	primary: { posts: 'slug' },
+* 	primary: { posts: 'slug' }, // non-`id` primary-key columns, per table
 * })
-* await db.table('users').set({ id: 'u1', age: 36 }) // typed; coerced + validated
+*
+* const users = db.table('users') // hold the handle; TableInterface<{ id; name; age }>
+*
+* await users.set({ id: 'u1', name: 'Ada', age: 36 }) // coerced + validated through the contract
+* await users.get('u1') // typed { id; name; age } | undefined — narrowed, never `as`
+* await users
+* 	.query()
+* 	.condition({ column: 'age', operator: 'from', values: [18], connector: 'and' })
+* 	.order({ column: 'age', direction: 'descending' })
+* 	.collect() // typed rows
 * ```
 */
 function createDatabase(options) {