@orkestrel/database 0.0.12 → 0.0.14

package/dist/src/core/index.js

@@ -2,7 +2,7 @@ import { cloneJSONRecord, cloneJSONValue, compileGuard, compileSchema, createCon
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /**
-* 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";
 /**
-* 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 ReDoS bound (AGENTS §6.5): the SA1–SA4 migration lets a model supply `list`
-* input over the wire, so `matchesLikePattern` / `matchesGlobPattern` run attacker-controlled
-* patterns. The matcher is the LINEAR greedy two-pointer wildcard match — never a
+* 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
 * 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
@@ -23,10 +24,85 @@ var DEFAULT_PRIMARY = "id";
 * `VALIDATION` {@link DatabaseError}; the cap is generous for any legitimate search.
 */
 var MAX_PATTERN_LENGTH = 1024;
+/**
+* Describes the `users` table the driver-conformance battery opens — keyed by the default
+* `id` primary column.
+*
+* @remarks
+* `age` is optional and `meta` is a declared `json` column, so the battery's
+* nested-round-trip phase is fair to a typed-column backend: a SQL driver
+* persists only declared columns, while a schemaless backend ignores the
+* declarations entirely.
+*/
+var CONFORMANCE_USERS_SCHEMA = Object.freeze({
+	name: "users",
+	primary: "id",
+	columns: Object.freeze([
+		{
+			name: "id",
+			storage: "text",
+			optional: false,
+			nullable: false
+		},
+		{
+			name: "name",
+			storage: "text",
+			optional: false,
+			nullable: false
+		},
+		{
+			name: "age",
+			storage: "integer",
+			optional: true,
+			nullable: false
+		},
+		{
+			name: "meta",
+			storage: "json",
+			optional: true,
+			nullable: false
+		}
+	]),
+	indexes: Object.freeze([])
+});
+/**
+* Describes the `posts` table the driver-conformance battery opens — keyed by a non-`id`
+* `slug` primary column.
+*
+* @remarks
+* Pairs with {@link CONFORMANCE_USERS_SCHEMA} so one battery exercises both
+* primary-key shapes: the default `id` and an explicit override.
+*/
+var CONFORMANCE_POSTS_SCHEMA = Object.freeze({
+	name: "posts",
+	primary: "slug",
+	columns: Object.freeze([{
+		name: "slug",
+		storage: "text",
+		optional: false,
+		nullable: false
+	}, {
+		name: "title",
+		storage: "text",
+		optional: false,
+		nullable: false
+	}]),
+	indexes: Object.freeze([])
+});
+/**
+* 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. 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
 //#region src/core/errors.ts
 /**
-* An error thrown by the database layer.
+* Represents an error thrown by the database layer.
 *
 * @remarks
 * Carries a {@link DatabaseErrorCode} and an optional `context` bag naming the
@@ -37,7 +113,7 @@ var MAX_PATTERN_LENGTH = 1024;
 * `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
-* fault surfaced by a driver seam — e.g. a filesystem failure while
+* fault surfaced by a driver seam — for example a filesystem failure while
 * persisting (`DRIVER`) — as opposed to expected domain conditions, which
 * keep their specific codes.
 */
@@ -52,10 +128,10 @@ var DatabaseError = class extends Error {
 	}
 };
 /**
-* Narrow an unknown caught value to a {@link DatabaseError}.
+* Narrows an unknown caught value to a {@link DatabaseError}.
 *
 * @param value - The value to test (typically a `catch` binding)
-* @returns `true` when `value` is a {@link DatabaseError}
+* @returns True if `value` is a {@link DatabaseError}; false otherwise
 *
 * @example
 * ```ts
@@ -72,43 +148,23 @@ function isDatabaseError(value) {
 //#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.
+* Checks whether a value is a usable database key.
 *
 * @param value - The value to test
-* @returns Whether `value` is a string or finite number
+* @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);
 }
 /**
-* Test whether a value is a portable column schema.
+* 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 Whether `value` is a complete {@link ColumnSchema}
+* @returns True if `value` is a complete {@link ColumnSchema}; false otherwise
 */
 function isColumnSchema(value) {
 	try {
@@ -120,10 +176,14 @@ function isColumnSchema(value) {
 	}
 }
 /**
-* Test whether a value is a portable table schema.
+* 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 Whether `value` is a complete {@link TableSchema}
+* @returns True if `value` is a complete {@link TableSchema}; false otherwise
 */
 function isTableSchema(value) {
 	try {
@@ -139,10 +199,14 @@ function isTableSchema(value) {
 	}
 }
 /**
-* Test whether a value is a complete portable driver schema.
+* 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 Whether `value` is a table-schema collection with unique table names
+* @returns True if `value` is a table-schema collection with unique table names; false otherwise
 */
 function isDriverSchema(value) {
 	try {
@@ -155,10 +219,14 @@ function isDriverSchema(value) {
 	}
 }
 /**
-* Test whether a value is one ordered migration step.
+* 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 Whether `value` is a complete {@link MigrationStep}
+* @returns True if `value` is a complete {@link MigrationStep}; false otherwise
 */
 function isMigrationStep(value) {
 	try {
@@ -179,10 +247,14 @@ function isMigrationStep(value) {
 	}
 }
 /**
-* Test whether a value is an ordered migration plan.
+* 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 Whether `value` is a complete {@link Migration}
+* @returns True if `value` is a complete {@link Migration}; false otherwise
 */
 function isMigration(value) {
 	try {
@@ -194,10 +266,16 @@ function isMigration(value) {
 	}
 }
 /**
-* Test whether a value is persisted driver metadata.
+* 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 Whether `value` is complete {@link DriverMetadata}
+* @returns True if `value` is complete {@link DriverMetadata}; false otherwise
 */
 function isDriverMetadata(value) {
 	try {
@@ -209,10 +287,14 @@ function isDriverMetadata(value) {
 	}
 }
 /**
-* Test whether a value is one atomic migration request.
+* 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 Whether `value` is a complete {@link MigrationInput}
+* @returns True if `value` is a complete {@link MigrationInput}; false otherwise
 */
 function isMigrationInput(value) {
 	try {
@@ -226,7 +308,12 @@ function isMigrationInput(value) {
 //#endregion
 //#region src/core/cloners.ts
 /**
-* Clone unknown driver metadata into a distinct deeply frozen snapshot.
+* 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
@@ -245,7 +332,12 @@ function cloneDriverMetadata(value) {
 	}
 }
 /**
-* Clone unknown driver schema into a distinct deeply frozen snapshot.
+* 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
@@ -264,7 +356,12 @@ function cloneDriverSchema(value) {
 	}
 }
 /**
-* Clone unknown migration input into a distinct deeply frozen snapshot.
+* 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
@@ -285,8 +382,32 @@ function cloneMigrationInput(value) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* A total ordering over arbitrary values — the comparator behind sorting and the
-* range operators.
+* Validates 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)
+	});
+}
+/**
+* Compares two arbitrary values under one total order — the comparator behind
+* sorting and the range operators.
 *
 * @remarks
 * Values of different types order by a fixed type rank (`undefined` < `null` <
@@ -310,15 +431,16 @@ function compareValues(left, right) {
 	return 0;
 }
 /**
-* Structural equality by SameValueZero leaves — the comparator behind conformance
-* checks and any test/fixture that needs "same data", not "same reference".
+* Compares two values structurally by SameValueZero leaves — the comparator
+* behind conformance checks and any test/fixture that needs "same data", not
+* "same reference".
 *
 * @remarks
 * Primitives compare by SameValueZero (`NaN` equals itself; `+0` equals `-0`).
 * 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 `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
@@ -327,7 +449,7 @@ function compareValues(left, right) {
 *
 * @param left - The left value
 * @param right - The right value
-* @returns Whether `left` and `right` are structurally equal
+* @returns True if `left` and `right` are structurally equal; false otherwise
 *
 * @example
 * ```ts
@@ -384,47 +506,16 @@ function equalsValue(left, right) {
 	}
 }
 /**
-* Match a query against a value as a case-insensitive ordered subsequence.
-*
-* @remarks
-* Every query character must appear in order in the value, but the characters
-* do not need to be contiguous. Query characters are literal, including
-* whitespace. Matching applies JavaScript `toLowerCase()` to both inputs
-* without locale-specific folding or Unicode normalization. An empty query
-* matches every value.
-*
-* @param value - The text searched for the query's characters
-* @param query - The characters that must all appear in order
-* @returns Whether the case-folded query is a subsequence of the case-folded value
-*
-* @example
-* ```ts
-* matchesFuzzy('Database', 'dbe') // true
-* matchesFuzzy('Database', 'abd') // false
-* ```
-*/
-function matchesFuzzy(value, query) {
-	const folded = value.toLowerCase();
-	const wanted = query.toLowerCase();
-	let cursor = 0;
-	for (const char of wanted) {
-		const found = folded.indexOf(char, cursor);
-		if (found === -1) return false;
-		cursor = found + 1;
-	}
-	return true;
-}
-/**
-* Match 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
-* (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
+* 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
 * 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),
@@ -432,17 +523,17 @@ function matchesFuzzy(value, query) {
 * 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)
-* @returns Whether `value` matches `pattern`
+* @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}
 */
 function matchesWildcardPattern(value, pattern, any, single, fold) {
@@ -474,32 +565,73 @@ function matchesWildcardPattern(value, pattern, any, single, fold) {
 	while (pi < needle.length && needle[pi] === any) pi += 1;
 	return pi === needle.length;
 }
+/**
+* Matches a value against a SQL `LIKE` pattern, folding case.
+*
+* @remarks
+* `%` matches any run of characters (including none) and `_` matches exactly one
+* character; every other pattern character matches itself literally. Runs on
+* {@link matchesWildcardPattern}, so the match is linear in the value length and
+* the pattern is capped at {@link MAX_PATTERN_LENGTH}.
+*
+* @param value - The value to test
+* @param pattern - The `LIKE` pattern
+* @returns True if `value` matches `pattern` under case folding; false otherwise
+* @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
+*
+* @example
+* ```ts
+* matchesLikePattern('Hello', 'h%o') // true — `%` spans any run, and case folds
+* matchesLikePattern('Hello', 'h_llo') // true — `_` matches exactly one character
+* ```
+*/
 function matchesLikePattern(value, pattern) {
 	return matchesWildcardPattern(value, pattern, "%", "_", true);
 }
+/**
+* Matches a value against a `GLOB` pattern, preserving case.
+*
+* @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
+* {@link matchesWildcardPattern}, so the match is linear in the value length and
+* the pattern is capped at {@link MAX_PATTERN_LENGTH}.
+*
+* @param value - The value to test
+* @param pattern - The `GLOB` pattern
+* @returns True if `value` matches `pattern` case-sensitively; false otherwise
+* @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
+*
+* @example
+* ```ts
+* matchesGlobPattern('hello', 'h*o') // true — `*` spans any run
+* matchesGlobPattern('Hello', 'h*o') // false — `GLOB` is case-sensitive
+* ```
+*/
 function matchesGlobPattern(value, pattern) {
 	return matchesWildcardPattern(value, pattern, "*", "?", false);
 }
 /**
-* Evaluate one {@link Condition} against a row — the per-operator predicate.
+* Evaluates one {@link Condition} against a row — the per-operator predicate.
 *
 * @remarks
 * Reads the condition's column — a `FieldPath`, resolved with `resolveField` (a
 * 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
 * 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
-* type mismatch is simply a non-match.
+* type mismatch is a non-match.
 *
 * @param row - The row to test
 * @param condition - The condition to apply
-* @returns Whether the row satisfies the condition
+* @returns True if the row satisfies the condition; false otherwise
 */
 function matchesCondition(row, condition) {
 	const value = resolveField(row, condition.column);
@@ -524,7 +656,7 @@ function matchesCondition(row, condition) {
 	}
 }
 /**
-* Fold a row through a list of conditions, joining each by its connector.
+* Folds a row through a list of conditions, joining each by its connector.
 *
 * @remarks
 * Evaluated left-to-right: the first condition seeds the result, and each later
@@ -534,7 +666,7 @@ function matchesCondition(row, condition) {
 *
 * @param row - The row to test
 * @param conditions - The conditions to fold
-* @returns Whether the row satisfies the combined conditions
+* @returns True if the row satisfies the combined conditions; false otherwise
 */
 function matchesQuery(row, conditions) {
 	let result = true;
@@ -549,7 +681,7 @@ function matchesQuery(row, conditions) {
 	return result;
 }
 /**
-* Filter rows by a list of conditions — the shared basis for a table's count
+* Filters rows by a list of conditions — the shared basis for a table's count
 * and aggregate paths (no sort/page, unlike {@link applyQuery}).
 *
 * @remarks
@@ -573,7 +705,7 @@ function filterRows(rows, conditions) {
 	return rows.filter((row) => matchesQuery(row, conditions));
 }
 /**
-* Sort rows by an ordering specification, leaving the input untouched.
+* Sorts rows by an ordering specification, leaving the input untouched.
 *
 * @remarks
 * Applies the terms in priority order — the first term that distinguishes two
@@ -595,7 +727,7 @@ function sortRows(rows, order) {
 	return sorted;
 }
 /**
-* Apply a {@link QueryInput} to rows — filter, then sort, then page.
+* Applies a {@link QueryInput} to rows — filter, then sort, then page.
 *
 * @remarks
 * The whole portable read pipeline in one place: conditions filter, `order`
@@ -620,7 +752,7 @@ function applyQuery(rows, input) {
 	return result;
 }
 /**
-* Compute an aggregate over a column across rows.
+* Computes an aggregate over a column across rows.
 *
 * @remarks
 * `count` returns the row count. The numeric aggregates coerce each cell with
@@ -646,10 +778,12 @@ 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;
 }
 /**
-* Read a row's primary key from a column, when it is a usable {@link Key}.
+* Reads a row's primary key from a column, when it is a usable {@link Key}.
 *
 * @param row - The row to read
 * @param column - The primary-key column name
@@ -660,7 +794,7 @@ function extractKey(row, column) {
 	return isKey(value) ? value : void 0;
 }
 /**
-* Return a fresh row whose primary column is authoritatively bound to its storage key.
+* Returns a fresh row whose primary column is authoritatively bound to its storage key.
 *
 * @param row - The caller row
 * @param primary - The primary column
@@ -674,7 +808,7 @@ function bindRowKey(row, primary, key) {
 	};
 }
 /**
-* Map a column's {@link ContractShape} to its portable {@link ColumnStorage} — the
+* Maps 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
@@ -698,7 +832,7 @@ function bindRowKey(row, primary, key) {
 * ```
 */
 function shapeToColumnStorage(shape) {
-	switch (shape.type) {
+	switch (shape.category) {
 		case "string": return "text";
 		case "number": return shape.integer === true ? "integer" : "real";
 		case "boolean": return "boolean";
@@ -717,7 +851,7 @@ function shapeToColumnStorage(shape) {
 	}
 }
 /**
-* Project one contract shape into a portable column schema.
+* Projects one contract shape into a portable column schema.
 *
 * @param name - The column name
 * @param shape - The column contract shape
@@ -733,7 +867,55 @@ function shapeToColumnSchema(name, shape) {
 	};
 }
 /**
-* Throw when an {@link OperationOptions.signal | AbortSignal} has fired — the shared
+* Reads one flat column's declaration out of a table schema.
+*
+* @remarks
+* The single lookup behind every declared-column question — storage type,
+* optionality, and nullability all come off the returned {@link ColumnSchema},
+* so a caller that needs more than one of them reads them from one result. A
+* nested {@link FieldPath} names no declared column, so resolve the path's head
+* before calling. A schema that does not declare the column returns `undefined`.
+*
+* @param name - The flat column name
+* @param schema - The table's schema
+* @returns The column's {@link ColumnSchema}, or `undefined` when the schema does not declare it
+*
+* @example
+* ```ts
+* findColumn('age', schema)?.storage // 'integer'
+* findColumn('absent', schema) // undefined
+* ```
+*/
+function findColumn(name, schema) {
+	return schema.columns.find((candidate) => candidate.name === name);
+}
+/**
+* Resolves the primary-key column one table keys its rows by.
+*
+* @remarks
+* A table absent from the {@link PrimaryMap} keys its rows by
+* {@link DEFAULT_PRIMARY}, so this is total over any table name.
+*
+* @param primary - The per-table primary-key overrides
+* @param name - The table name
+* @returns The table's primary-key column
+*
+* @example
+* ```ts
+* resolvePrimary({ posts: 'slug' }, 'posts') // 'slug'
+* resolvePrimary({ posts: 'slug' }, 'users') // 'id' — the default primary
+* ```
+*/
+function resolvePrimary(primary, name) {
+	return primary[name] ?? "id";
+}
+function requireColumns(tables, name) {
+	const columns = tables[name];
+	if (columns === void 0) throw new DatabaseError("NOT_FOUND", `Table '${name}' is not declared`, { table: name });
+	return columns;
+}
+/**
+* Throws when an {@link OperationOptions.signal | AbortSignal} has fired — the shared
 * abort gate checked at operation boundaries and between streamed rows.
 *
 * @remarks
@@ -761,7 +943,7 @@ function checkAbort(signal) {
 	if (signal?.aborted) throw new DatabaseError("ABORTED", "Operation aborted", { reason: signal.reason });
 }
 /**
-* Structurally diff a deployed and a declared table set into a {@link Migration}
+* Diffs a deployed and a declared table set structurally into a {@link Migration}
 * plan.
 *
 * @remarks
@@ -776,17 +958,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 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
+* {@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 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 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`)
@@ -892,7 +1073,9 @@ function planMigration(deployed, declared, from = 0, to = 1) {
 	} }).plan;
 }
 /**
-* Sequentially project migration steps over a canonical validated owned schema.
+* 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.
 *
@@ -991,7 +1174,7 @@ function projectMigrationSchema(schema, steps) {
 	}
 }
 /**
-* Canonicalize an unknown driver schema into a distinct deeply frozen snapshot.
+* Canonicalizes 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
@@ -1013,11 +1196,11 @@ function normalizeDriverSchema(value) {
 	return cloneDriverSchema(tables);
 }
 /**
-* Apply one table's {@link MigrationStep}s to its rows — a pure row transform.
+* Applies one table's {@link MigrationStep}s to its rows — a pure row transform.
 *
 * @remarks
 * `column.remove` drops that field from every row (a fresh copy — inputs are
-* never mutated, AGENTS §11); `column.add` leaves rows as-is (an absent field
+* never mutated); `column.add` leaves rows as-is (an absent field
 * reads as `undefined`, backfill is application policy). `table.add` /
 * `table.remove` / `index.add` / `index.remove` are no-ops here (they operate
 * on storage shape, not row shape). Steps for tables other than the one
@@ -1044,7 +1227,7 @@ function migrateRows(rows, steps) {
 	});
 }
 /**
-* Run the driver-conformance battery against a fresh {@link DriverInterface}
+* Walks the driver-conformance battery against a fresh {@link DriverInterface}
 * per phase, yielding one {@link ConformanceFinding} per violated invariant —
 * the shared invariant suite every backend (in-memory, SQLite, IndexedDB)
 * must uphold to be a drop-in {@link DriverInterface}.
@@ -1055,34 +1238,34 @@ function migrateRows(rows, steps) {
 * driver's own README. Opens a fixed two-table schema (`users` keyed by the
 * 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 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 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 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 `metadata` and
-* `stamp` exist, a fresh store's `metadata()` is `undefined`, and after
+* `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; 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
+* (through {@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 `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
+* 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
@@ -1093,62 +1276,14 @@ function migrateRows(rows, steps) {
 *
 * @example
 * ```ts
-* import { createMemoryDriver, driverFindings } from '@orkestrel/database'
+* import { createMemoryDriver, scanDriver } from '@orkestrel/database'
 *
-* for await (const finding of driverFindings(() => createMemoryDriver())) {
+* for await (const finding of scanDriver(() => createMemoryDriver())) {
 * 	console.log(finding.check, finding.message)
 * }
 * ```
 */
-async function* driverFindings(factory) {
-	const CONFORMANCE_USERS_SCHEMA = {
-		name: "users",
-		primary: "id",
-		columns: [
-			{
-				name: "id",
-				storage: "text",
-				optional: false,
-				nullable: false
-			},
-			{
-				name: "name",
-				storage: "text",
-				optional: false,
-				nullable: false
-			},
-			{
-				name: "age",
-				storage: "integer",
-				optional: true,
-				nullable: false
-			},
-			{
-				name: "meta",
-				storage: "json",
-				optional: true,
-				nullable: false
-			}
-		],
-		indexes: []
-	};
-	const CONFORMANCE_POSTS_SCHEMA = {
-		name: "posts",
-		primary: "slug",
-		columns: [{
-			name: "slug",
-			storage: "text",
-			optional: false,
-			nullable: false
-		}, {
-			name: "title",
-			storage: "text",
-			optional: false,
-			nullable: false
-		}],
-		indexes: []
-	};
-	const CONFORMANCE_SCHEMA = [CONFORMANCE_USERS_SCHEMA, CONFORMANCE_POSTS_SCHEMA];
+async function* scanDriver(factory) {
 	try {
 		const driver = factory();
 		await driver.open(CONFORMANCE_SCHEMA);
@@ -1935,17 +2070,19 @@ async function* driverFindings(factory) {
 	}
 }
 /**
-* Run the driver-conformance battery, throwing on the first violated
+* Runs the driver-conformance battery, throwing on the first violated
 * invariant — the fail-fast entry point most callers (test setup, CI smoke
 * checks) want.
 *
 * @remarks
-* A thin driver over {@link driverFindings}: because that generator is
-* lazy, consuming only its first yielded value means every LATER phase
-* never runs — true fail-fast, not merely "report only the first". The
+* Consumes only the first value {@link scanDriver} yields: because that
+* 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
@@ -1959,18 +2096,18 @@ async function* driverFindings(factory) {
 * ```
 */
 async function conformDriver(factory) {
-	for await (const finding of driverFindings(factory)) throw new DatabaseError("CONFORMANCE", finding.message, {
+	for await (const finding of scanDriver(factory)) throw new DatabaseError("CONFORMANCE", finding.message, {
 		check: finding.check,
 		...finding.context
 	});
 }
 /**
-* Run the FULL driver-conformance battery and collect 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.
 *
 * @remarks
-* Drains {@link driverFindings} to completion: every phase runs regardless
+* Drains {@link scanDriver} to completion: every phase runs regardless
 * of earlier violations, so a driver breaking two independent invariants
 * reports both. An empty array means the driver is fully conformant.
 *
@@ -1987,26 +2124,32 @@ async function conformDriver(factory) {
 */
 async function auditDriver(factory) {
 	const findings = [];
-	for await (const finding of driverFindings(factory)) findings.push(finding);
+	for await (const finding of scanDriver(factory)) findings.push(finding);
 	return findings;
 }
 //#endregion
-//#region src/core/TransactionIterator.ts
+//#region src/core/ScopedIterator.ts
 /**
-* The internal continuation boundary for one transaction-scoped async iterable.
+* Forms the internal continuation admission boundary for one scoped async iterable.
 *
 * @remarks
-* 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.
+* Each continuation enters the owning {@link AdmissionInterface} ledger
+* independently, so an idle iterator never delays a transaction, a settlement,
+* or a close. `ready` runs inside the tracked continuation before the source
+* advances, which is where a root stream re-establishes the lazy connection and
+* a transaction-scoped stream does nothing. A continuation requested after
+* admission closes attempts source cleanup exactly once and leaves the iterator
+* terminal.
 */
-var TransactionIterator = class {
+var ScopedIterator = class {
 	#source;
-	#scope;
+	#admission;
+	#ready;
 	#cleaned = false;
-	constructor(source, scope) {
+	constructor(source, admission, ready) {
 		this.#source = source[Symbol.asyncIterator]();
-		this.#scope = scope;
+		this.#admission = admission;
+		this.#ready = ready;
 	}
 	[Symbol.asyncIterator]() {
 		return this;
@@ -2025,6 +2168,7 @@ var TransactionIterator = class {
 			done: true,
 			value: void 0
 		};
+		await this.#ready();
 		const result = await this.#source.next();
 		if (result.done === true) this.#cleaned = true;
 		return result;
@@ -2052,8 +2196,8 @@ var TransactionIterator = class {
 		throw error;
 	}
 	#continue(operation) {
-		if (!this.#scope.accepting) this.#cleanup();
-		return this.#scope.track(operation);
+		if (!this.#admission.accepting) this.#cleanup();
+		return this.#admission.track(operation);
 	}
 	#cleanup() {
 		if (this.#cleaned) return;
@@ -2066,7 +2210,7 @@ var TransactionIterator = class {
 //#endregion
 //#region src/core/TransactionScope.ts
 /**
-* The internal lifetime boundary for one database transaction callback.
+* Forms the internal lifetime boundary for one database transaction callback.
 *
 * @remarks
 * Promise operations enter synchronously through {@link track}. Closing stops new
@@ -2110,7 +2254,7 @@ var TransactionScope = class {
 		return promise;
 	}
 	stream(source) {
-		return new TransactionIterator(source, this);
+		return new ScopedIterator(source, this, () => Promise.resolve());
 	}
 	stop() {
 		this.#accepting = false;
@@ -2123,7 +2267,7 @@ var TransactionScope = class {
 //#endregion
 //#region src/core/DatabaseContext.ts
 /**
-* The internal shared owner behind every typed view of one database.
+* Owns the internal shared state behind every typed view of one database.
 *
 * @remarks
 * A context owns the driver, merged physical schema, lifecycle, observation,
@@ -2207,7 +2351,21 @@ var DatabaseContext = class {
 		this.#emitter.emit("close");
 	}
 	connect() {
-		return this.#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;
 	}
 	track(operation) {
 		try {
@@ -2236,7 +2394,7 @@ var DatabaseContext = class {
 		this.#transaction = token;
 		try {
 			await this.#drain();
-			await this.#connect();
+			await this.connect();
 			if (this.#driver.transaction !== void 0) {
 				const rejection = {
 					rejected: false,
@@ -2312,23 +2470,6 @@ var DatabaseContext = class {
 	#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);
@@ -2411,12 +2552,12 @@ var DatabaseContext = class {
 //#endregion
 //#region src/core/Cursor.ts
 /**
-* A forward row cursor for bulk in-place mutation.
+* Walks a table's rows forward 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
+* iteration cannot corrupt the walk, and a key removed mid-iteration is
 * skipped. `update` and `remove` act on the row at the current position.
 */
 var Cursor = class {
@@ -2503,84 +2644,9 @@ var Cursor = class {
 	}
 };
 //#endregion
-//#region src/core/DatabaseIterator.ts
-/**
-* The internal continuation admission boundary for a root database stream.
-*
-* @remarks
-* 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 DatabaseIterator = class {
-	#source;
-	#context;
-	#cleaned = false;
-	constructor(source, context) {
-		this.#source = source[Symbol.asyncIterator]();
-		this.#context = context;
-	}
-	[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
-		};
-		await this.#context.connect();
-		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.#context.accepting) this.#cleanup();
-		return this.#context.track(operation);
-	}
-	#cleanup() {
-		if (this.#cleaned) return;
-		this.#cleaned = true;
-		try {
-			(this.#source.return?.())?.catch(() => {});
-		} catch {}
-	}
-};
-//#endregion
 //#region src/core/Query.ts
 /**
-* A fluent query builder bound to one table.
+* Builds a read against one table through a fluent chain.
 *
 * @remarks
 * Accumulates typed conditions, ordering, JS filters, and a page. Each builder
@@ -2641,7 +2707,7 @@ var Query = class {
 		return this.#filtered(fetched).length;
 	}
 	/**
-	* Lazily evaluate conditions, filters, offset, and limit.
+	* Evaluates conditions, filters, offset, and limit lazily.
 	*
 	* @param options - Optional abort options
 	* @returns Matching rows in storage order
@@ -2693,23 +2759,23 @@ var Query = class {
 //#endregion
 //#region src/core/Table.ts
 /**
-* A table — typed keyed CRUD plus fluent query and cursor access over a driver.
+* Exposes typed keyed CRUD plus fluent query and cursor access over a driver.
 *
 * @remarks
 * The table's contract is the load-bearing piece: writes go through `parse`
 * (coercing inputs and rejecting rows that don't fit with a `VALIDATION` throw),
 * reads come back through the contract guard (narrowing a stored {@link Row} to
-* the table's type — no assertion, AGENTS §1), and `contract` is exposed for
+* the table's type — no assertion), and `contract` is exposed for
 * introspection and seeding. The driver only stores and scans; all querying is
 * the shared core engine in `helpers.ts`.
 *
 * @remarks
-* - **Observable (§13).** The owned {@link emitter} ({@link TableEventMap}) carries the
+* - **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.
 */
@@ -2793,7 +2859,7 @@ var Table = class {
 		});
 	}
 	/**
-	* Count contract-valid rows matching `input`'s conditions.
+	* Counts contract-valid rows matching `input`'s conditions.
 	*
 	* @remarks
 	* Paging is ignored. Candidate rows use the driver's native `records` hook
@@ -2818,11 +2884,11 @@ var Table = class {
 		});
 	}
 	/**
-	* Compute an aggregate over `column` across rows matching `input`'s
+	* Computes an aggregate over `column` across rows matching `input`'s
 	* conditions.
 	*
 	* @remarks
-	* Like {@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
@@ -2847,7 +2913,7 @@ var Table = class {
 		});
 	}
 	/**
-	* Stream the table's rows matching `input`, applying offset/limit paging.
+	* Streams the table's rows matching `input`, applying offset/limit paging.
 	*
 	* @remarks
 	* `input.limit` counts rows that pass both the input conditions and the
@@ -2862,7 +2928,7 @@ var Table = class {
 	scan(input, options) {
 		validatePage(input);
 		const source = this.#scan(input, options);
-		if (this.#context !== void 0) return new DatabaseIterator(source, this.#context);
+		if (this.#context !== void 0) return new ScopedIterator(source, this.#context, this.#ready);
 		return this.#scope === void 0 ? source : this.#scope.stream(source);
 	}
 	set(rows, options) {
@@ -3106,7 +3172,7 @@ var Table = class {
 //#endregion
 //#region src/core/DatabaseTransaction.ts
 /**
-* A table-only database view bound to one driver transaction scope.
+* Binds a table-only database view to one driver transaction scope.
 *
 * @typeParam T - The declared table shape map
 *
@@ -3133,31 +3199,27 @@ var DatabaseTransaction = class {
 	}
 	table(name) {
 		this.#scope.check();
-		const columns = this.#columns(name);
-		return this.#build(name, this.#key(name), createContract(objectShape(columns)));
+		const columns = requireColumns(this.#tables, name);
+		return this.#build(name, resolvePrimary(this.#primary, name), createContract(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.
+* Exposes a typed view over one shared internal lifecycle and storage context.
 *
 * @remarks
 * 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.
+*
+* 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;
@@ -3184,8 +3246,8 @@ var Database = class Database {
 	}
 	table(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), createContract(objectShape(columns)));
+		const columns = requireColumns(this.#tables, name);
+		return this.#build(name, resolvePrimary(this.#primary, name), createContract(objectShape(columns)));
 	}
 	import(tables, primary) {
 		return this.#spawn(tables, {
@@ -3196,9 +3258,9 @@ var Database = class Database {
 	export() {
 		const result = {};
 		for (const name of Object.keys(this.#tables)) {
-			const columns = this.#columns(name);
+			const columns = requireColumns(this.#tables, name);
 			result[name] = {
-				primary: this.#key(name),
+				primary: resolvePrimary(this.#primary, name),
 				columns,
 				schema: compileSchema(objectShape(columns))
 			};
@@ -3234,20 +3296,12 @@ var Database = class Database {
 			...this.#context.version === void 0 ? {} : { version: this.#context.version }
 		}, this.#context);
 	}
-	#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;
-	}
 	#schema() {
 		return Object.keys(this.#tables).map((name) => {
-			const columns = this.#columns(name);
+			const columns = requireColumns(this.#tables, name);
 			return {
 				name,
-				primary: this.#key(name),
+				primary: resolvePrimary(this.#primary, name),
 				columns: Object.entries(columns).map(([column, shape]) => shapeToColumnSchema(column, shape)),
 				indexes: this.#indexes[name] ?? []
 			};
@@ -3283,16 +3337,16 @@ var Database = class Database {
 //#endregion
 //#region src/core/drivers/MemoryDriver.ts
 /**
-* The reference {@link DriverInterface} — nested maps, no I/O.
+* Implements the reference {@link DriverInterface} — nested maps, no I/O.
 *
 * @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 (via
+* 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
-* can never perturb stored state (AGENTS §11); a shallow `{ ...row }` spread
+* can never perturb stored state; a shallow `{ ...row }` spread
 * 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`
@@ -3354,19 +3408,19 @@ var MemoryDriver = class {
 		}
 	}
 	/**
-	* Natively filtered lazy iteration — the {@link DriverInterface.stream} hook.
+	* Iterates rows lazily with native filtering — the {@link DriverInterface.stream} hook.
 	*
 	* @remarks
 	* Iterates the table's keys in the same key order `scan` and `keys` yield
 	* (sorted by {@link compareValues}), testing each row against
-	* `input.conditions` (via {@link matchesQuery}) before counting it
+	* `input.conditions` (through {@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. `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 (AGENTS
-	* §11), and an unknown table mirrors `scan`'s empty-yield behavior.
+	* order, sorted output is `records()`'s job. Rows yield copy-out, and an
+	* unknown table mirrors `scan`'s empty-yield behavior.
 	*
 	* @param table - The table to stream
 	* @param input - The filter / offset / limit to apply lazily
@@ -3382,31 +3436,11 @@ var MemoryDriver = class {
 		validatePage(input);
 		return this.#stream(table, input);
 	}
-	async *#stream(table, input) {
-		const store = this.#store(table);
-		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 && !matchesQuery(row, conditions)) continue;
-			if (skipped < offset) {
-				skipped += 1;
-				continue;
-			}
-			yield structuredClone(row);
-			yielded += 1;
-		}
-	}
 	async clear(table) {
 		this.#store(table).clear();
 	}
 	/**
-	* Capture the current state and return a thunk that rolls back to it.
+	* Captures the current state and returns a thunk that rolls back to it.
 	*
 	* @remarks
 	* Capture owns rows, schema, and one session-local table identity. Replay
@@ -3463,7 +3497,7 @@ var MemoryDriver = class {
 		};
 	}
 	/**
-	* Return the persisted {@link DriverMetadata}, or `undefined` when the store has
+	* Returns the persisted {@link DriverMetadata}, or `undefined` when the store has
 	* never been stamped.
 	*
 	* @remarks
@@ -3478,7 +3512,7 @@ var MemoryDriver = class {
 		return this.#metadata === void 0 ? void 0 : cloneDriverMetadata(this.#metadata);
 	}
 	/**
-	* Persist an owned snapshot for a later `metadata()` to return.
+	* Persists an owned snapshot for a later `metadata()` to return.
 	*
 	* @param metadata - The {@link DriverMetadata} to persist
 	*/
@@ -3486,7 +3520,7 @@ var MemoryDriver = class {
 		this.#metadata = cloneDriverMetadata(metadata);
 	}
 	/**
-	* Apply a {@link Migration} plan's steps against the in-memory store.
+	* Applies a {@link Migration} plan's steps against the in-memory store.
 	*
 	* @remarks
 	* Steps apply against an isolated candidate. Rows, schema changes, and
@@ -3568,6 +3602,26 @@ var MemoryDriver = class {
 			case "index.remove": this.#require(tables, step.table);
 		}
 	}
+	async *#stream(table, input) {
+		const store = this.#store(table);
+		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 && !matchesQuery(row, conditions)) continue;
+			if (skipped < offset) {
+				skipped += 1;
+				continue;
+			}
+			yield structuredClone(row);
+			yielded += 1;
+		}
+	}
 	#store(table) {
 		this.#table(table);
 		const store = this.#tables.get(table);
@@ -3578,41 +3632,50 @@ var MemoryDriver = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a database over a driver and a declared `tables` schema.
+* Creates a database over a driver and a declared `tables` schema.
 *
 * @remarks
 * `tables` maps each name to its columns (a `column → shape` map); the database
 * wraps each in an `objectShape`, so you never write `objectShape` at the table
 * 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 `primary` and `indexes` maps.
+* columns — no annotations. Name a non-`id` primary-key column per table through
+* the optional `primary` and `indexes` maps.
 *
 * @param options - The driver, `tables`, and optional `primary`, `indexes`,
 *   `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) {
 	return new Database(options);
 }
 /**
-* Create the in-memory reference {@link DriverInterface}.
+* Creates the in-memory reference {@link DriverInterface}.
 *
 * @remarks
 * Backed by nested maps with no I/O — the same driver runs in a browser or on a
@@ -3624,6 +3687,122 @@ function createMemoryDriver() {
 	return new MemoryDriver();
 }
 //#endregion
-export { DEFAULT_PRIMARY, Database, DatabaseError, MAX_PATTERN_LENGTH, MemoryDriver, applyQuery, auditDriver, bindRowKey, checkAbort, cloneDriverMetadata, cloneDriverSchema, cloneMigrationInput, compareValues, computeAggregate, conformDriver, createDatabase, createMemoryDriver, driverFindings, equalsValue, extractKey, filterRows, isColumnSchema, isDatabaseError, isDriverMetadata, isDriverSchema, isKey, isMigration, isMigrationInput, isMigrationStep, isTableSchema, matchesCondition, matchesFuzzy, matchesGlobPattern, matchesLikePattern, matchesQuery, matchesWildcardPattern, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, shapeToColumnSchema, shapeToColumnStorage, sortRows, validatePage };
+//#region src/core/DriverIterator.ts
+/**
+* Forms the internal continuation boundary for a root driver async iterator.
+*
+* @remarks
+* A driver transaction can begin while a caller holds an idle root iterator.
+* Every `next` therefore checks the driver's root-state guard immediately
+* before and after advancing the source. A failed continuation terminalizes the
+* iterator, discards any row produced before the post-advance guard failed, and
+* attempts source cleanup exactly once.
+*
+* A driver implementing the published `DriverInterface` extension seam wraps its
+* own source iterator in one so a root `scan` / `stream` cannot outlive the
+* driver state it was opened against.
+*
+* @typeParam T - The value the wrapped source yields
+*
+* @example
+* ```ts
+* import type { Row } from '@orkestrel/database'
+* import { DatabaseError, DriverIterator } from '@orkestrel/database'
+*
+* // Inside a driver's `scan`, over its own row source and root-state guard.
+* declare const rows: AsyncIterator<Row>
+* declare const transacting: () => boolean
+* const scan = new DriverIterator(rows, () => {
+* 	if (transacting()) {
+* 		throw new DatabaseError('CONFLICT', 'scan: a transaction is active')
+* 	}
+* })
+* for await (const row of scan) row // one row at a time, guarded around each advance
+* ```
+*/
+var DriverIterator = class {
+	#source;
+	#guard;
+	#terminal = false;
+	#cleaned = false;
+	/**
+	* Wraps one source iterator in the continuation boundary.
+	*
+	* @param source - The driver's own row iterator, advanced once per `next`
+	* @param guard - The root-state check, run immediately before and after each advance; it throws to terminalize the iteration
+	*/
+	constructor(source, guard) {
+		this.#source = source;
+		this.#guard = guard;
+	}
+	[Symbol.asyncIterator]() {
+		return this;
+	}
+	async next() {
+		if (this.#terminal) return {
+			done: true,
+			value: void 0
+		};
+		try {
+			this.#guard();
+			const result = await this.#source.next();
+			this.#guard();
+			if (result.done === true) {
+				this.#terminal = true;
+				this.#cleaned = true;
+			}
+			return result;
+		} catch (error) {
+			this.#terminal = true;
+			await this.#discard();
+			throw error;
+		}
+	}
+	async return() {
+		if (this.#terminal) return {
+			done: true,
+			value: void 0
+		};
+		this.#terminal = true;
+		if (this.#cleaned || this.#source.return === void 0) {
+			this.#cleaned = true;
+			return {
+				done: true,
+				value: void 0
+			};
+		}
+		this.#cleaned = true;
+		return this.#source.return();
+	}
+	async throw(error) {
+		if (this.#terminal) throw error;
+		if (this.#source.throw === void 0) {
+			this.#terminal = true;
+			await this.#discard();
+			throw error;
+		}
+		try {
+			const result = await this.#source.throw(error);
+			if (result.done === true) {
+				this.#terminal = true;
+				this.#cleaned = true;
+			}
+			return result;
+		} catch (cause) {
+			this.#terminal = true;
+			await this.#discard();
+			throw cause;
+		}
+	}
+	async #discard() {
+		if (this.#cleaned) return;
+		this.#cleaned = true;
+		try {
+			await this.#source.return?.();
+		} catch {}
+	}
+};
+//#endregion
+export { CONFORMANCE_POSTS_SCHEMA, CONFORMANCE_SCHEMA, CONFORMANCE_USERS_SCHEMA, DEFAULT_PRIMARY, Database, DatabaseError, DriverIterator, MAX_PATTERN_LENGTH, MemoryDriver, applyQuery, auditDriver, bindRowKey, checkAbort, cloneDriverMetadata, cloneDriverSchema, cloneMigrationInput, compareValues, computeAggregate, conformDriver, createDatabase, createMemoryDriver, equalsValue, extractKey, filterRows, findColumn, isColumnSchema, isDatabaseError, isDriverMetadata, isDriverSchema, isKey, isMigration, isMigrationInput, isMigrationStep, isTableSchema, matchesCondition, matchesGlobPattern, matchesLikePattern, matchesQuery, matchesWildcardPattern, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, requireColumns, resolvePrimary, scanDriver, shapeToColumnSchema, shapeToColumnStorage, sortRows, validatePage };
 
 //# sourceMappingURL=index.js.map