@orkestrel/database 0.0.1 → 0.0.3

package/dist/src/core/index.cjs

@@ -0,0 +1,2494 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_contract = require("@orkestrel/contract");
+let _orkestrel_emitter = require("@orkestrel/emitter");
+//#region src/core/constants.ts
+/**
+* The primary-key column assumed when {@link TableKeys} does not name one.
+*
+* @remarks
+* `id` is the convention IndexedDB (`keyPath: 'id'`) and SQL (`id` / rowid) both
+* lean on, so a table that omits `key` keys its rows by `id`.
+*/
+var DEFAULT_PRIMARY = "id";
+/**
+* The longest `LIKE` / `GLOB` pattern the wildcard matcher accepts before rejecting it.
+*
+* @remarks
+* A ReDoS bound (AGENTS §6.5): the SA1–SA4 migration lets a model supply `list`
+* criteria over the wire, so `likeMatch` / `globMatch` run attacker-controlled
+* patterns. The matcher is the LINEAR greedy two-pointer wildcard match — never a
+* backtracking regex (`.*`-segments-separated-by-literals against a long input is the
+* catastrophic shape JS cannot bound without atomic groups), so it is O(value ×
+* pattern). Capping the pattern length bounds that pattern factor, leaving a match
+* linear in the value length whatever the pattern. A longer pattern throws a
+* `VALIDATION` {@link DatabaseError}; the cap is generous for any legitimate search.
+*/
+var MAX_PATTERN_LENGTH = 1024;
+/** The number of bytes encoded by an RFC 4122 UUID. */
+var UUID_BYTE_COUNT = 16;
+/** The number of distinct values one UUID byte may hold. */
+var UUID_BYTE_RANGE = 256;
+//#endregion
+//#region src/core/errors.ts
+/**
+* An error thrown by the database layer.
+*
+* @remarks
+* Carries a {@link DatabaseErrorCode} and an optional `context` bag naming the
+* offending table / key. Thrown for: operating on a closed database (`CLOSED`), a
+* `resolve` miss (`NOT_FOUND`), an `add` onto an existing key (`CONFLICT`), a
+* row that fails its table's contract (`VALIDATION`), a cancelled operation whose
+* {@link ReadOptions.signal} aborted (`ABORTED`, carrying `signal.reason` in
+* `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
+* persisting (`DRIVER`) — as opposed to expected domain conditions, which
+* keep their specific codes.
+*/
+var DatabaseError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "DatabaseError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Narrow 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}
+*
+* @example
+* ```ts
+* try {
+* 	await users.add(row)
+* } catch (error) {
+* 	if (isDatabaseError(error) && error.code === 'CONFLICT') await users.set(row)
+* }
+* ```
+*/
+function isDatabaseError(value) {
+	return value instanceof DatabaseError;
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* A total ordering over arbitrary values — the comparator behind sorting and the
+* range operators.
+*
+* @remarks
+* Values of different types order by a fixed type rank (`undefined` < `null` <
+* boolean < number < string < other); same-typed values compare naturally.
+* `NaN` sorts after every other number and equal to itself, so the comparator
+* is total and never returns `NaN`.
+*
+* @param left - The left value
+* @param right - The right value
+* @returns `-1`, `0`, or `1`
+*/
+function compareValues(left, right) {
+	const rankOf = (value) => {
+		if (value === void 0) return 0;
+		if (value === null) return 1;
+		if (typeof value === "boolean") return 2;
+		if (typeof value === "number") return 3;
+		if (typeof value === "string") return 4;
+		return 5;
+	};
+	const leftRank = rankOf(left);
+	const rightRank = rankOf(right);
+	if (leftRank !== rightRank) return leftRank < rightRank ? -1 : 1;
+	if (typeof left === "number" && typeof right === "number") {
+		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;
+	return 0;
+}
+/**
+* Structural equality 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 `deepEqual`). Plain
+* records (via `isRecord`) compare by their OWN enumerable keys: same key
+* COUNT and, for every key in `left`, `right` has that key (`Object.hasOwn`)
+* with a `deepEqual` value — so a key present with value `undefined` is NOT
+* equal to that key being absent (both differ in `Object.keys` membership).
+* Anything else (functions, class instances, mismatched shapes) falls through
+* to `false`. There is no cycle detection — a cyclic input recurses forever;
+* callers pass acyclic data (rows, plans, config).
+*
+* @param left - The left value
+* @param right - The right value
+* @returns Whether `left` and `right` are structurally equal
+*
+* @example
+* ```ts
+* deepEqual(Number.NaN, Number.NaN) // true
+* deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
+* deepEqual({ a: undefined }, {}) // false — present-undefined ≠ absent
+* ```
+*/
+function deepEqual(left, right) {
+	if (typeof left === "number" && typeof right === "number") return Number.isNaN(left) && Number.isNaN(right) || left === right;
+	if (left === right) return true;
+	if (Array.isArray(left) && Array.isArray(right)) return left.length === right.length && left.every((item, index) => deepEqual(item, right[index]));
+	if ((0, _orkestrel_contract.isRecord)(left) && (0, _orkestrel_contract.isRecord)(right)) {
+		const leftKeys = Object.keys(left);
+		const rightKeys = Object.keys(right);
+		if (leftKeys.length !== rightKeys.length) return false;
+		return leftKeys.every((key) => Object.hasOwn(right, key) && deepEqual(left[key], right[key]));
+	}
+	return false;
+}
+/**
+* Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
+* engine behind {@link likeMatch} and {@link globMatch}.
+*
+* @remarks
+* A backtracking RegExp (`a%b%c` → `^a.*b.*c$`) is CATASTROPHIC on a hostile pattern:
+* `.*` segments separated by literals, matched against a long non-matching input, blow
+* up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it
+* (AGENTS §6.5, now that the authed server runs model-supplied `list` criteria over the
+* wire). So this builds NO regex. It runs the classic GREEDY TWO-POINTER wildcard match:
+* the `any` wildcard records its position and, on a later mismatch, backtracks ONLY to
+* that last `any` (letting it absorb one more char) — so the work is O(value × pattern),
+* 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),
+* bounding the pattern factor so a match stays linear in the value length whatever the
+* pattern.
+*
+* The `any` wildcard matches any run (including empty); `single` matches exactly one
+* 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.
+*
+* @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`
+* @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
+*/
+function wildcardMatch(value, pattern, any, single, fold) {
+	if (pattern.length > 1024) throw new DatabaseError("VALIDATION", `Pattern exceeds the maximum length of ${MAX_PATTERN_LENGTH}`, {
+		length: pattern.length,
+		limit: MAX_PATTERN_LENGTH
+	});
+	const haystack = fold ? value.toLowerCase() : value;
+	const needle = fold ? pattern.toLowerCase() : pattern;
+	let vi = 0;
+	let pi = 0;
+	let star = -1;
+	let mark = 0;
+	while (vi < haystack.length) {
+		const pc = pi < needle.length ? needle[pi] : void 0;
+		if (pc === any) {
+			star = pi;
+			mark = vi;
+			pi += 1;
+		} else if (pc !== void 0 && (pc === single || pc === haystack[vi])) {
+			vi += 1;
+			pi += 1;
+		} else if (star !== -1) {
+			pi = star + 1;
+			mark += 1;
+			vi = mark;
+		} else return false;
+	}
+	while (pi < needle.length && needle[pi] === any) pi += 1;
+	return pi === needle.length;
+}
+function likeMatch(value, pattern) {
+	return wildcardMatch(value, pattern, "%", "_", true);
+}
+function globMatch(value, pattern) {
+	return wildcardMatch(value, pattern, "*", "?", false);
+}
+/**
+* Evaluate 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 deepEqual} — STRUCTURAL equality, not the total
+* order's rank-5-collapses-all-objects behavior, so `equals` on an object/array
+* operand only matches a structurally-equal value, never every row holding any
+* object. This is a semantics change from ranking: `deepEqual` is SameValueZero
+* 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.
+*
+* @param row - The row to test
+* @param condition - The condition to apply
+* @returns Whether the row satisfies the condition
+*/
+function matchesCondition(row, condition) {
+	const value = (0, _orkestrel_contract.resolveField)(row, condition.column);
+	const first = condition.values[0];
+	const second = condition.values[1];
+	switch (condition.operator) {
+		case "equals": return deepEqual(value, first);
+		case "not": return !deepEqual(value, first);
+		case "above": return compareValues(value, first) > 0;
+		case "below": return compareValues(value, first) < 0;
+		case "from": return compareValues(value, first) >= 0;
+		case "to": return compareValues(value, first) <= 0;
+		case "between": return compareValues(value, first) >= 0 && compareValues(value, second) <= 0;
+		case "like": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && likeMatch(value, first);
+		case "glob": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && globMatch(value, first);
+		case "starts": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && value.startsWith(first);
+		case "ends": return (0, _orkestrel_contract.isString)(value) && (0, _orkestrel_contract.isString)(first) && value.endsWith(first);
+		case "any": return condition.values.some((candidate) => deepEqual(value, candidate));
+		case "none": return !condition.values.some((candidate) => deepEqual(value, candidate));
+		case "absent": return value === void 0 || value === null;
+		case "present": return value !== void 0 && value !== null;
+	}
+}
+/**
+* Fold 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
+* condition combines with `&&` (`and`) or `||` (`or`). An empty list matches
+* every row. There is no operator precedence — conditions combine in the order
+* the query builder recorded them.
+*
+* @param row - The row to test
+* @param conditions - The conditions to fold
+* @returns Whether the row satisfies the combined conditions
+*/
+function matchesCriteria(row, conditions) {
+	let result = true;
+	let seeded = false;
+	for (const condition of conditions) {
+		const match = matchesCondition(row, condition);
+		if (!seeded) {
+			result = match;
+			seeded = true;
+		} else result = condition.connector === "or" ? result || match : result && match;
+	}
+	return result;
+}
+/**
+* Filter rows by a list of conditions — the shared basis for a table's count
+* and aggregate paths (no sort/page, unlike {@link applyCriteria}).
+*
+* @remarks
+* An empty condition list matches every row (returned as-is, no copy). Folds
+* each row through {@link matchesCriteria}.
+*
+* @param rows - The rows to filter
+* @param conditions - The conditions to apply (empty matches everything)
+* @returns The matching rows
+*
+* @example
+* ```ts
+* filterRows(
+* 	[{ age: 30 }, { age: 12 }],
+* 	[{ column: 'age', operator: 'above', values: [18], connector: 'and' }],
+* ) // => [{ age: 30 }]
+* ```
+*/
+function filterRows(rows, conditions) {
+	if (conditions.length === 0) return rows;
+	return rows.filter((row) => matchesCriteria(row, conditions));
+}
+/**
+* Sort rows by an ordering specification, leaving the input untouched.
+*
+* @remarks
+* Applies the terms in priority order — the first term that distinguishes two
+* rows decides — using {@link compareValues}, reversing for `descending`.
+*
+* @param rows - The rows to sort
+* @param order - The ordering terms in priority order
+* @returns A new, sorted array
+*/
+function sortRows(rows, order) {
+	const sorted = [...rows];
+	sorted.sort((left, right) => {
+		for (const term of order) {
+			const comparison = compareValues((0, _orkestrel_contract.resolveField)(left, term.column), (0, _orkestrel_contract.resolveField)(right, term.column));
+			if (comparison !== 0) return term.direction === "descending" ? -comparison : comparison;
+		}
+		return 0;
+	});
+	return sorted;
+}
+/**
+* Apply a {@link Criteria} to rows — filter, then sort, then page.
+*
+* @remarks
+* The whole portable read pipeline in one place: conditions filter, `order`
+* sorts, and `offset` / `limit` window the result. Each step is skipped when its
+* part of the criteria is absent. The reference {@link DriverInterface} backends
+* lean on this rather than each re-deriving it.
+*
+* @param rows - The rows to process (typically a table's full `scan`)
+* @param criteria - The read specification, or `undefined` for all rows as-is
+* @returns The filtered, sorted, paged rows
+*/
+function applyCriteria(rows, criteria) {
+	let result = rows;
+	const conditions = criteria?.conditions;
+	if (conditions !== void 0 && conditions.length > 0) result = result.filter((row) => matchesCriteria(row, conditions));
+	const order = criteria?.order;
+	if (order !== void 0 && order.length > 0) result = sortRows(result, order);
+	const offset = criteria?.offset ?? 0;
+	const limit = criteria?.limit;
+	if (offset > 0 || limit !== void 0) result = result.slice(offset, limit !== void 0 ? offset + limit : void 0);
+	return result;
+}
+/**
+* Compute an aggregate over a column across rows.
+*
+* @remarks
+* `count` returns the row count. The numeric aggregates coerce each cell with
+* the contracts `parseNumber` (so `'42'` counts) and ignore non-numeric cells;
+* over zero numeric values they return `undefined` — the SQL `NULL` of an empty
+* aggregate.
+*
+* @param rows - The rows to aggregate (non-record entries are ignored)
+* @param operation - The aggregate to compute
+* @param column - The column to aggregate
+* @returns The aggregate value, or `undefined` when undefined for the inputs
+*/
+function computeAggregate(rows, operation, column) {
+	if (operation === "count") return rows.length;
+	const numbers = [];
+	for (const row of rows) {
+		if (!(0, _orkestrel_contract.isRecord)(row)) continue;
+		const value = (0, _orkestrel_contract.parseNumber)((0, _orkestrel_contract.resolveField)(row, column));
+		if (value !== void 0) numbers.push(value);
+	}
+	if (numbers.length === 0) return void 0;
+	if (operation === "sum" || operation === "average") {
+		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);
+}
+/**
+* Read 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
+* @returns The key (a string or finite number), or `undefined`
+*/
+function extractKey(row, column) {
+	const value = row[column];
+	if ((0, _orkestrel_contract.isString)(value)) return value;
+	if ((0, _orkestrel_contract.isFiniteNumber)(value)) return value;
+}
+/**
+* Map a column's {@link ContractShape} to its portable {@link ColumnType} — the
+* value a `TableSchema` carries so a native backend can declare a real column.
+*
+* @remarks
+* `string` → `text`; `number` → `integer` when the shape is integer-only, else
+* `real`; `boolean` → `boolean`. A `literal` takes the type of its values
+* (all-boolean → `boolean`, all-integer → `integer`, mixed/fractional numbers →
+* `real`, anything else → `text`). `optional` / `nullable` unwrap to their inner
+* type (nullability is tracked separately). `null` / `object` / `array` / `union` /
+* `json` / `raw` → `json`: a backend stores them as JSON text and can `json_extract`
+* for nested `FieldPath` queries. A scan-only backend ignores the result.
+*
+* @param shape - The column's contract shape
+* @returns The portable column type
+*
+* @example
+* ```ts
+* shapeToColumnType(stringShape()) // 'text'
+* shapeToColumnType(integerShape()) // 'integer'
+* shapeToColumnType(optionalShape(integerShape())) // 'integer'
+* shapeToColumnType(objectShape({ a: stringShape() })) // 'json'
+* ```
+*/
+function shapeToColumnType(shape) {
+	switch (shape.type) {
+		case "string": return "text";
+		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";
+			return "text";
+		case "optional":
+		case "nullable": return shapeToColumnType(shape.inner);
+		case "null":
+		case "object":
+		case "array":
+		case "union":
+		case "json":
+		case "raw": return "json";
+	}
+}
+/**
+* Whether a value is a well-formed {@link DriverMeta} — the boundary guard a
+* versioning driver's `meta()` narrows a stored (structured-clone or
+* `JSON.parse`d) value through before trusting it, replacing the per-driver
+* duplicated narrowing every backend used to hand-roll (AGENTS §14: never `as`).
+*
+* @remarks
+* Total and total-recursive over the whole shape: a finite `version`, and a
+* `schema` array of well-formed {@link TableSchema} entries — each a `name` /
+* `primary` string pair, a `columns` array of well-formed {@link ColumnSchema}
+* entries (a `name` string, a {@link ColumnType} literal, a `nullable`
+* boolean), and an `indexes` array of string arrays. Anything off-shape
+* (including a non-record) returns `false` rather than throwing.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed `DriverMeta`
+*
+* @example
+* ```ts
+* isDriverMeta({ version: 1, schema: [] }) // true
+* isDriverMeta({ version: 1, schema: [{ name: 'users' }] }) // false
+* ```
+*/
+function isDriverMeta(value) {
+	const COLUMN_TYPES = [
+		"text",
+		"integer",
+		"real",
+		"boolean",
+		"json",
+		"blob"
+	];
+	const isColumnType = (candidate) => (0, _orkestrel_contract.isString)(candidate) && COLUMN_TYPES.some((type) => type === candidate);
+	const isColumnSchema = (candidate) => (0, _orkestrel_contract.isRecord)(candidate) && (0, _orkestrel_contract.isString)(candidate.name) && isColumnType(candidate.type) && (0, _orkestrel_contract.isBoolean)(candidate.nullable);
+	const isIndexGroup = (candidate) => (0, _orkestrel_contract.isArray)(candidate) && candidate.every((entry) => (0, _orkestrel_contract.isString)(entry));
+	const isTableSchema = (candidate) => (0, _orkestrel_contract.isRecord)(candidate) && (0, _orkestrel_contract.isString)(candidate.name) && (0, _orkestrel_contract.isString)(candidate.primary) && (0, _orkestrel_contract.isArray)(candidate.columns) && candidate.columns.every(isColumnSchema) && (0, _orkestrel_contract.isArray)(candidate.indexes) && candidate.indexes.every(isIndexGroup);
+	return (0, _orkestrel_contract.isRecord)(value) && (0, _orkestrel_contract.isFiniteNumber)(value.version) && (0, _orkestrel_contract.isArray)(value.schema) && value.schema.every(isTableSchema);
+}
+/**
+* Throw when an {@link ReadOptions.signal | AbortSignal} has fired — the shared
+* cancellation gate checked at operation boundaries and between streamed rows.
+*
+* @remarks
+* A no-op for `undefined` or a live signal, so callers thread `options?.signal`
+* straight through. When the signal has aborted, throws an `ABORTED`
+* {@link DatabaseError} carrying the signal's `reason` in its context — callers
+* mint signals with whatever tool they like (`AbortSignal.timeout(ms)`,
+* `new AbortController()`, `@orkestrel/abort`).
+*
+* @param signal - The signal to check, if any
+* @returns Nothing — returns normally while the signal is live
+* @throws An `ABORTED` {@link DatabaseError} when the signal has aborted
+*
+* @example
+* ```ts
+* import { checkAbort } from '@orkestrel/database'
+*
+* const controller = new AbortController()
+* checkAbort(controller.signal) // returns
+* controller.abort('too slow')
+* checkAbort(controller.signal) // throws DatabaseError('ABORTED', …)
+* ```
+*/
+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}
+* plan.
+*
+* @remarks
+* Tables present in `declared` but not `deployed` become `table.add` steps
+* (carrying the full declared {@link TableSchema}); tables present in
+* `deployed` but not `declared` become `table.remove` steps. Tables present in
+* both are diffed column-by-column (by name) and index-group-by-index-group
+* (by deep equality of the column-name array), each producing `column.add` /
+* `column.remove` / `index.add` / `index.remove` steps. Step order is
+* deterministic: every `table.remove`, then every `table.add`, then each
+* shared table's column/index changes in `declared` order. `from` / `to` are
+* plan labels only — version tracking itself is deferred to persistent
+* backends.
+*
+* A column present in BOTH schemas under the same name but with a different
+* `type` or `nullable` 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
+* @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`)
+* @returns The migration plan moving `deployed` toward `declared`
+* @throws A `MIGRATION` {@link DatabaseError} when a shared column's `type` or
+* `nullable` differs between `deployed` and `declared`
+*
+* @example
+* ```ts
+* const plan = planMigration(
+* 	[{ name: 'users', primary: 'id', columns: [], indexes: [] }],
+* 	[{ name: 'users', primary: 'id', columns: [{ name: 'age', type: 'integer', nullable: false }], indexes: [] }],
+* )
+* // plan.steps === [{ operation: 'column.add', table: 'users', column: { name: 'age', ... } }]
+* ```
+*/
+function planMigration(deployed, declared, from = 0, to = 1) {
+	const deployedByName = new Map(deployed.map((table) => [table.name, table]));
+	const declaredByName = new Map(declared.map((table) => [table.name, table]));
+	const steps = [];
+	for (const table of deployed) if (!declaredByName.has(table.name)) steps.push({
+		operation: "table.remove",
+		table: table.name
+	});
+	for (const table of declared) if (!deployedByName.has(table.name)) steps.push({
+		operation: "table.add",
+		table
+	});
+	for (const table of declared) {
+		const before = deployedByName.get(table.name);
+		if (before === void 0) continue;
+		const beforeColumns = new Map(before.columns.map((column) => [column.name, column]));
+		const afterColumns = new Map(table.columns.map((column) => [column.name, column]));
+		for (const column of before.columns) if (!afterColumns.has(column.name)) steps.push({
+			operation: "column.remove",
+			table: table.name,
+			column: column.name
+		});
+		for (const column of table.columns) {
+			const previous = beforeColumns.get(column.name);
+			if (previous === void 0) {
+				steps.push({
+					operation: "column.add",
+					table: table.name,
+					column
+				});
+				continue;
+			}
+			if (previous.type !== column.type || previous.nullable !== column.nullable) throw new DatabaseError("MIGRATION", `planMigration: column '${column.name}' on table '${table.name}' changed shape (type ${previous.type}→${column.type}, nullable ${previous.nullable}→${column.nullable}) — in-place type/nullability changes are not auto-migrated; add a new column, copy/convert the data, then remove the old column`, {
+				table: table.name,
+				column: column.name,
+				from: {
+					type: previous.type,
+					nullable: previous.nullable
+				},
+				to: {
+					type: column.type,
+					nullable: column.nullable
+				}
+			});
+		}
+		const sameIndex = (left, right) => left.length === right.length && left.every((column, position) => column === right[position]);
+		for (const index of before.indexes) if (!table.indexes.some((candidate) => sameIndex(candidate, index))) steps.push({
+			operation: "index.remove",
+			table: table.name,
+			index
+		});
+		for (const index of table.indexes) if (!before.indexes.some((candidate) => sameIndex(candidate, index))) steps.push({
+			operation: "index.add",
+			table: table.name,
+			index
+		});
+	}
+	return {
+		from,
+		to,
+		steps
+	};
+}
+/**
+* Apply 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
+* 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
+* `rows` belongs to are ignored — pass only the steps relevant to this table.
+*
+* @param rows - The table's current rows
+* @param steps - The migration steps to apply (typically one table's slice of a {@link Migration})
+* @returns A new array of transformed rows; `rows` is never mutated
+*
+* @example
+* ```ts
+* const rows = [{ id: 'a', name: 'Ada', legacy: true }]
+* migrateRows(rows, [{ operation: 'column.remove', table: 'users', column: 'legacy' }])
+* // => [{ id: 'a', name: 'Ada' }]
+* ```
+*/
+function migrateRows(rows, steps) {
+	const removed = steps.filter((step) => step.operation === "column.remove").map((step) => step.column);
+	if (removed.length === 0) return rows.map((row) => ({ ...row }));
+	return rows.map((row) => {
+		const next = {};
+		for (const key of Object.keys(row)) if (!removed.includes(key)) next[key] = row[key];
+		return next;
+	});
+}
+/**
+* Run 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}.
+*
+* @remarks
+* Framework-agnostic: no test-runner or Node imports, only sibling core
+* modules — so it runs equally from a unit test, a smoke script, or a new
+* 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; `delete` returns `true` then `false`;
+* `keys`/`scan` yield in ascending key order; `clear` empties only its target
+* table; `snapshot`'s rollback thunk restores pre-snapshot state, including a
+* NESTED field mutated in place on a read-back row between capture and
+* restore; a scoped `snapshot(['users'])` rolls back only the named table,
+* leaving a concurrent mutation to another table intact; a
+* non-`id` primary key (`posts.slug`) round-trips; a nested-object row
+* round-trips structurally (via {@link deepEqual}). The optional surface is
+* presence-gated: when `migrate` exists, a `column.remove` plan strips the
+* column from stored rows and a plan referencing an unknown table throws
+* `DatabaseError` `MIGRATION`; when `stream` exists, it yields only
+* condition-matching rows and honors `offset`/`limit`; when `transaction`
+* exists, `commit` persists and `rollback` restores; when both `meta` and
+* `stamp` exist, a fresh store's `meta()` is `undefined`, and after
+* `stamp({ version, schema })`, `meta()` returns the exact stamped value.
+*
+* 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
+* 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
+* phases never run) — that is exactly what {@link conformDriver} does.
+*
+* @param factory - Mints a fresh, unopened driver instance (called once per phase)
+* @yields One {@link ConformanceFinding} per violated invariant, in phase order
+*
+* @example
+* ```ts
+* import { createMemoryDriver, driverFindings } from '@orkestrel/database'
+*
+* for await (const finding of driverFindings(() => createMemoryDriver())) {
+* 	console.log(finding.check, finding.message)
+* }
+* ```
+*/
+async function* driverFindings(factory) {
+	const CONFORMANCE_USERS_SCHEMA = {
+		name: "users",
+		primary: "id",
+		columns: [
+			{
+				name: "id",
+				type: "text",
+				nullable: false
+			},
+			{
+				name: "name",
+				type: "text",
+				nullable: false
+			},
+			{
+				name: "age",
+				type: "integer",
+				nullable: true
+			},
+			{
+				name: "meta",
+				type: "json",
+				nullable: true
+			}
+		],
+		indexes: []
+	};
+	const CONFORMANCE_POSTS_SCHEMA = {
+		name: "posts",
+		primary: "slug",
+		columns: [{
+			name: "slug",
+			type: "text",
+			nullable: false
+		}, {
+			name: "title",
+			type: "text",
+			nullable: false
+		}],
+		indexes: []
+	};
+	const CONFORMANCE_SCHEMA = [CONFORMANCE_USERS_SCHEMA, CONFORMANCE_POSTS_SCHEMA];
+	const findingOf = (check, message, context) => ({
+		check,
+		message,
+		context
+	});
+	const phases = [
+		{
+			check: "open-close",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				await driver.close();
+			}
+		},
+		{
+			check: "read-missing",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				const missing = await driver.read("users", "nope");
+				await driver.close();
+				if (missing !== void 0) return findingOf("read-missing", "read of a missing key must return undefined", {
+					table: "users",
+					expected: void 0,
+					actual: missing
+				});
+			}
+		},
+		{
+			check: "write-read",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				const input = {
+					id: "u1",
+					name: "Ada",
+					age: 30,
+					meta: { tags: ["a"] }
+				};
+				await driver.write("users", "u1", input);
+				input.name = "Mutated after write";
+				if ((0, _orkestrel_contract.isRecord)(input.meta) && Array.isArray(input.meta.tags)) input.meta.tags.push("mutated");
+				const stored = await driver.read("users", "u1");
+				const original = {
+					id: "u1",
+					name: "Ada",
+					age: 30,
+					meta: { tags: ["a"] }
+				};
+				if (stored === void 0 || !deepEqual(stored, original)) {
+					await driver.close();
+					return findingOf("copy-in", "write must deep-copy the input row (including nested fields) rather than store it by reference", {
+						table: "users",
+						expected: original,
+						actual: stored
+					});
+				}
+				stored.name = "Mutated after read";
+				if ((0, _orkestrel_contract.isRecord)(stored.meta) && Array.isArray(stored.meta.tags)) stored.meta.tags.push("mutated");
+				const reread = await driver.read("users", "u1");
+				if (reread === void 0 || !deepEqual(reread, original)) {
+					await driver.close();
+					return findingOf("copy-out", "read must deep-copy the stored row (including nested fields) rather than return it by reference", {
+						table: "users",
+						expected: original,
+						actual: reread
+					});
+				}
+				const overwrite = {
+					id: "u1",
+					name: "Ada Overwritten",
+					age: 31
+				};
+				await driver.write("users", "u1", overwrite);
+				const overwritten = await driver.read("users", "u1");
+				await driver.close();
+				if (overwritten === void 0 || !deepEqual(overwritten, overwrite)) return findingOf("upsert", "write must upsert-overwrite an existing key", {
+					table: "users",
+					expected: overwrite,
+					actual: overwritten
+				});
+			}
+		},
+		{
+			check: "delete",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				await driver.write("users", "u1", {
+					id: "u1",
+					name: "Ada",
+					age: 30
+				});
+				const first = await driver.delete("users", "u1");
+				if (first !== true) {
+					await driver.close();
+					return findingOf("delete-true", "delete of an existing key must return true", {
+						table: "users",
+						expected: true,
+						actual: first
+					});
+				}
+				const second = await driver.delete("users", "u1");
+				await driver.close();
+				if (second !== false) return findingOf("delete-false", "delete of an already-removed key must return false", {
+					table: "users",
+					expected: false,
+					actual: second
+				});
+			}
+		},
+		{
+			check: "order",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				for (const row of [
+					{
+						id: "c",
+						name: "C",
+						age: 3
+					},
+					{
+						id: "a",
+						name: "A",
+						age: 1
+					},
+					{
+						id: "b",
+						name: "B",
+						age: 2
+					}
+				]) await driver.write("users", row.id, row);
+				const expected = [
+					"a",
+					"b",
+					"c"
+				];
+				const keys = [...await driver.keys("users")];
+				if (!deepEqual(keys, expected)) {
+					await driver.close();
+					return findingOf("keys-order", "keys must be returned in ascending key order", {
+						table: "users",
+						expected,
+						actual: keys
+					});
+				}
+				const scanned = [];
+				for await (const row of driver.scan("users")) scanned.push(row);
+				const scannedIds = scanned.map((row) => row.id);
+				await driver.close();
+				if (!deepEqual(scannedIds, expected)) return findingOf("scan-order", "scan must yield rows in ascending key order", {
+					table: "users",
+					expected,
+					actual: scannedIds
+				});
+			}
+		},
+		{
+			check: "clear",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				await driver.write("users", "u1", {
+					id: "u1",
+					name: "Ada",
+					age: 30
+				});
+				await driver.write("posts", "p1", {
+					slug: "p1",
+					title: "Post"
+				});
+				await driver.clear("users");
+				const usersKeys = await driver.keys("users");
+				const postsKeys = await driver.keys("posts");
+				await driver.close();
+				if (usersKeys.length !== 0) return findingOf("clear-target", "clear must empty the targeted table", {
+					table: "users",
+					expected: [],
+					actual: usersKeys
+				});
+				if (postsKeys.length !== 1) return findingOf("clear-other", "clear must not affect other tables", {
+					table: "posts",
+					expected: 1,
+					actual: postsKeys.length
+				});
+			}
+		},
+		{
+			check: "snapshot",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				const original = {
+					id: "u1",
+					name: "Ada",
+					age: 30
+				};
+				await driver.write("users", "u1", original);
+				const rollback = await driver.snapshot();
+				await driver.write("users", "u2", {
+					id: "u2",
+					name: "Grace",
+					age: 40
+				});
+				await driver.delete("users", "u1");
+				await rollback();
+				const keys = [...await driver.keys("users")];
+				if (!deepEqual(keys, ["u1"])) {
+					await driver.close();
+					return findingOf("snapshot-rollback", "snapshot rollback must restore the pre-snapshot key set", {
+						table: "users",
+						expected: ["u1"],
+						actual: keys
+					});
+				}
+				const restored = await driver.read("users", "u1");
+				await driver.close();
+				if (restored === void 0 || !deepEqual(restored, original)) return findingOf("snapshot-rollback-value", "snapshot rollback must restore pre-snapshot row values", {
+					table: "users",
+					expected: original,
+					actual: restored
+				});
+			}
+		},
+		{
+			check: "snapshot-nested",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				const original = {
+					id: "u3",
+					name: "Nested",
+					age: 20,
+					meta: { tags: ["a"] }
+				};
+				await driver.write("users", "u3", original);
+				const rollback = await driver.snapshot();
+				const before = await driver.read("users", "u3");
+				if ((0, _orkestrel_contract.isRecord)(before) && (0, _orkestrel_contract.isRecord)(before.meta) && Array.isArray(before.meta.tags)) before.meta.tags.push("mutated-before-restore");
+				await driver.write("users", "u3", {
+					id: "u3",
+					name: "Nested",
+					age: 20,
+					meta: { tags: ["a", "mutated-after-write"] }
+				});
+				await rollback();
+				const restored = await driver.read("users", "u3");
+				await driver.close();
+				if (restored === void 0 || !deepEqual(restored, original)) return findingOf("snapshot-nested", "snapshot rollback must restore pre-snapshot nested field values, unaffected by a later in-place mutation of a read-back row", {
+					table: "users",
+					expected: original,
+					actual: restored
+				});
+			}
+		},
+		{
+			check: "non-id-primary",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				await driver.write("posts", "hello-world", {
+					slug: "hello-world",
+					title: "Hello"
+				});
+				const post = await driver.read("posts", "hello-world");
+				const key = post === void 0 ? void 0 : extractKey(post, "slug");
+				await driver.close();
+				if (key !== "hello-world") return findingOf("non-id-primary", "a non-id primary key column must round-trip through the store", {
+					table: "posts",
+					expected: "hello-world",
+					actual: key
+				});
+			}
+		},
+		{
+			check: "nested-roundtrip",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				const nested = {
+					id: "u3",
+					name: "Nested",
+					age: 20,
+					meta: {
+						tags: ["a", "b"],
+						deep: { flag: true }
+					}
+				};
+				await driver.write("users", "u3", nested);
+				const readBack = await driver.read("users", "u3");
+				await driver.close();
+				if (readBack === void 0 || !deepEqual(readBack, nested)) return findingOf("nested-roundtrip", "a nested-object row must round-trip structurally", {
+					table: "users",
+					expected: nested,
+					actual: readBack
+				});
+			}
+		},
+		{
+			check: "migrate",
+			run: async () => {
+				const driver = factory();
+				if (driver.migrate === void 0) return void 0;
+				const deployedUsers = {
+					...CONFORMANCE_USERS_SCHEMA,
+					columns: [...CONFORMANCE_USERS_SCHEMA.columns, {
+						name: "legacy",
+						type: "boolean",
+						nullable: true
+					}]
+				};
+				await driver.open([deployedUsers, CONFORMANCE_POSTS_SCHEMA]);
+				await driver.write("users", "u1", {
+					id: "u1",
+					name: "Ada",
+					age: 30,
+					legacy: true
+				});
+				const removePlan = planMigration([deployedUsers], [CONFORMANCE_USERS_SCHEMA]);
+				await driver.migrate(removePlan);
+				const migrated = await driver.read("users", "u1");
+				if (migrated === void 0 || "legacy" in migrated) {
+					await driver.close();
+					return findingOf("migrate-column-remove", "a column.remove migration must strip the column from stored rows", {
+						table: "users",
+						expected: void 0,
+						actual: migrated === void 0 ? void 0 : migrated.legacy
+					});
+				}
+				let caught;
+				try {
+					await driver.migrate({
+						from: 0,
+						to: 1,
+						steps: [{
+							operation: "table.remove",
+							table: "ghost"
+						}]
+					});
+				} catch (error) {
+					caught = error;
+				}
+				await driver.close();
+				if (!isDatabaseError(caught) || caught.code !== "MIGRATION") return findingOf("migrate-unknown-table", "a migration step referencing an unknown table must throw a MIGRATION DatabaseError", {
+					table: "ghost",
+					expected: "MIGRATION",
+					actual: isDatabaseError(caught) ? caught.code : caught
+				});
+			}
+		},
+		{
+			check: "stream",
+			run: async () => {
+				const driver = factory();
+				if (driver.stream === void 0) return void 0;
+				await driver.open(CONFORMANCE_SCHEMA);
+				for (const row of [
+					{
+						id: "a",
+						name: "A",
+						age: 10
+					},
+					{
+						id: "b",
+						name: "B",
+						age: 20
+					},
+					{
+						id: "c",
+						name: "C",
+						age: 30
+					}
+				]) await driver.write("users", row.id, row);
+				const criteria = { conditions: [{
+					column: "age",
+					operator: "above",
+					values: [10],
+					connector: "and"
+				}] };
+				const matched = [];
+				for await (const row of driver.stream("users", criteria)) matched.push(row);
+				const matchedIds = matched.map((row) => row.id).sort();
+				if (!deepEqual(matchedIds, ["b", "c"])) {
+					await driver.close();
+					return findingOf("stream-match", "stream must yield only condition-matching rows", {
+						table: "users",
+						expected: ["b", "c"],
+						actual: matchedIds
+					});
+				}
+				const paged = [];
+				for await (const row of driver.stream("users", {
+					offset: 1,
+					limit: 1
+				})) paged.push(row);
+				await driver.close();
+				if (paged.length !== 1) return findingOf("stream-page", "stream must honor offset and limit", {
+					table: "users",
+					expected: 1,
+					actual: paged.length
+				});
+			}
+		},
+		{
+			check: "transaction",
+			run: async () => {
+				const driver = factory();
+				if (driver.transaction === void 0) return void 0;
+				await driver.open(CONFORMANCE_SCHEMA);
+				await driver.write("users", "u1", {
+					id: "u1",
+					name: "Ada",
+					age: 30
+				});
+				const committing = await driver.transaction();
+				await driver.write("users", "u2", {
+					id: "u2",
+					name: "Grace",
+					age: 40
+				});
+				await committing.commit();
+				const afterCommit = [...await driver.keys("users")].sort();
+				if (!deepEqual(afterCommit, ["u1", "u2"])) {
+					await driver.close();
+					return findingOf("transaction-commit", "transaction commit must persist writes made during the scope", {
+						table: "users",
+						expected: ["u1", "u2"],
+						actual: afterCommit
+					});
+				}
+				const rollingBack = await driver.transaction();
+				await driver.write("users", "u3", {
+					id: "u3",
+					name: "Marie",
+					age: 50
+				});
+				await rollingBack.rollback();
+				const afterRollback = [...await driver.keys("users")].sort();
+				await driver.close();
+				if (!deepEqual(afterRollback, ["u1", "u2"])) return findingOf("transaction-rollback", "transaction rollback must restore pre-transaction state", {
+					table: "users",
+					expected: ["u1", "u2"],
+					actual: afterRollback
+				});
+			}
+		},
+		{
+			check: "meta-stamp",
+			run: async () => {
+				const driver = factory();
+				if (driver.meta === void 0 || driver.stamp === void 0) return void 0;
+				await driver.open(CONFORMANCE_SCHEMA);
+				const fresh = await driver.meta();
+				if (fresh !== void 0) {
+					await driver.close();
+					return findingOf("meta-fresh", "a fresh store must report undefined meta", {
+						expected: void 0,
+						actual: fresh
+					});
+				}
+				const stamped = {
+					version: 1,
+					schema: CONFORMANCE_SCHEMA
+				};
+				await driver.stamp(stamped);
+				const read = await driver.meta();
+				await driver.close();
+				if (read === void 0 || !deepEqual(read, stamped)) return findingOf("meta-stamp", "meta() must return exactly the last-stamped value", {
+					expected: stamped,
+					actual: read
+				});
+			}
+		},
+		{
+			check: "snapshot-scoped",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				await driver.write("users", "u1", {
+					id: "u1",
+					name: "Ada",
+					age: 30
+				});
+				await driver.write("posts", "p1", {
+					slug: "p1",
+					title: "Post"
+				});
+				const rollback = await driver.snapshot(["users"]);
+				await driver.write("users", "u2", {
+					id: "u2",
+					name: "Grace",
+					age: 40
+				});
+				await driver.write("posts", "p2", {
+					slug: "p2",
+					title: "Another post"
+				});
+				await rollback();
+				const usersKeys = [...await driver.keys("users")];
+				if (!deepEqual(usersKeys, ["u1"])) {
+					await driver.close();
+					return findingOf("snapshot-scoped-users", "a scoped snapshot must roll back only the named table", {
+						table: "users",
+						expected: ["u1"],
+						actual: usersKeys
+					});
+				}
+				const postsKeys = [...await driver.keys("posts")].sort();
+				await driver.close();
+				if (!deepEqual(postsKeys, ["p1", "p2"])) return findingOf("snapshot-scoped-posts", "a scoped snapshot must leave an unnamed table's mutations intact", {
+					table: "posts",
+					expected: ["p1", "p2"],
+					actual: postsKeys
+				});
+			}
+		}
+	];
+	for (const phase of phases) try {
+		const finding = await phase.run();
+		if (finding !== void 0) yield finding;
+	} catch (error) {
+		yield findingOf(phase.check, error instanceof Error ? error.message : String(error), { error });
+	}
+}
+/**
+* Run 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
+* 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 }`.
+*
+* @param factory - Mints a fresh, unopened driver instance (called once per phase)
+* @returns Nothing — resolves once every phase has passed
+* @throws A `CONFORMANCE` {@link DatabaseError} on the first violated invariant
+*
+* @example
+* ```ts
+* import { conformDriver, createMemoryDriver } from '@orkestrel/database'
+*
+* await conformDriver(() => createMemoryDriver()) // resolves when every invariant holds
+* ```
+*/
+async function conformDriver(factory) {
+	for await (const finding of driverFindings(factory)) throw new DatabaseError("CONFORMANCE", finding.message, {
+		check: finding.check,
+		...finding.context
+	});
+}
+/**
+* Run the FULL driver-conformance battery and collect 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
+* of earlier violations, so a driver breaking two independent invariants
+* reports both. An empty array means the driver is fully conformant.
+*
+* @param factory - Mints a fresh, unopened driver instance (called once per phase)
+* @returns Every violated invariant found, in phase order (empty when fully conformant)
+*
+* @example
+* ```ts
+* import { auditDriver, createMemoryDriver } from '@orkestrel/database'
+*
+* const findings = await auditDriver(() => createMemoryDriver())
+* for (const finding of findings) console.log(`${finding.check}: ${finding.message}`)
+* ```
+*/
+async function auditDriver(factory) {
+	const findings = [];
+	for await (const finding of driverFindings(factory)) findings.push(finding);
+	return findings;
+}
+/**
+* Generate an RFC 4122 version 4 UUID from a number source — no host crypto global.
+*
+* @remarks
+* Draws exactly {@link UUID_BYTE_COUNT} values from `random`, one per byte, then
+* forces the version (`4`) and variant (`10xx`) bits. The default source is
+* `Math.random` — a pure-ECMAScript intrinsic, so generation works on every host;
+* pass a seeded source (`seededRandom` from `@orkestrel/contract`) and reuse it
+* across calls for reproducible sequences in tests and fixtures — production
+* identifiers should keep the default source, whose engine entropy is far larger
+* than a 32-bit seed. Each byte is floored and masked, so a source straying
+* outside `[0, 1)` (negative, `>= 1`, `NaN`, `Infinity`) can never yield a
+* malformed UUID. Suitable as a collision-resistant record identifier — not a
+* cryptographic token; never use one as a secret.
+*
+* @param random - A number source returning values in the half-open range `[0, 1)` (defaults to `Math.random`)
+* @returns A lowercase RFC 4122 version 4 UUID
+*
+* @example
+* ```ts
+* import { generateUUID } from '@orkestrel/database'
+* import { seededRandom } from '@orkestrel/contract'
+*
+* generateUUID() // e.g. '9b2f7c1e-3d4a-4f6b-8e2d-5a1c0b9f8e7d'
+* generateUUID(seededRandom(42)) // the same UUID on every run
+* ```
+*/
+function generateUUID(random = Math.random) {
+	const bytes = Array.from({ length: 16 }, () => Math.floor(random() * 256) & 255);
+	bytes[6] = bytes[6] & 15 | 64;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = bytes.map((byte) => byte.toString(16).padStart(2, "0"));
+	return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+}
+//#endregion
+//#region src/core/Cursor.ts
+/**
+* A forward row cursor for bulk in-place mutation.
+*
+* @remarks
+* Iterates a snapshot of the table's keys captured when the cursor was opened,
+* reading each row lazily through the owning table — so a mutation made during
+* iteration cannot corrupt the walk, and a key removed mid-iteration is simply
+* skipped. `update` and `remove` act on the row at the current position.
+*/
+var Cursor = class {
+	#table;
+	#keys;
+	#index = -1;
+	#value;
+	#closed = false;
+	constructor(table, keys) {
+		this.#table = table;
+		this.#keys = keys;
+	}
+	get value() {
+		return this.#value;
+	}
+	get index() {
+		return this.#index;
+	}
+	get done() {
+		return this.#closed || this.#index >= this.#keys.length;
+	}
+	async next() {
+		if (this.#closed) return;
+		this.#index += 1;
+		while (this.#index < this.#keys.length) {
+			const row = await this.#table.get(this.#keys[this.#index]);
+			if (row !== void 0) {
+				this.#value = row;
+				return;
+			}
+			this.#index += 1;
+		}
+		this.#value = void 0;
+	}
+	async update(changes) {
+		if (this.#closed || this.#value === void 0) return;
+		const key = this.#keys[this.#index];
+		await this.#table.update(key, changes);
+		this.#value = await this.#table.get(key);
+	}
+	async remove() {
+		if (this.#closed || this.#value === void 0) return;
+		await this.#table.remove(this.#keys[this.#index]);
+		this.#value = void 0;
+	}
+	close() {
+		this.#closed = true;
+		this.#value = void 0;
+	}
+};
+//#endregion
+//#region src/core/Clause.ts
+/**
+* A pending condition opened by a query's `where` / `and` / `or`.
+*
+* @remarks
+* Holds the column, the connector that will join this condition to the ones
+* before it, and a recorder the owning query supplies. Each operator builds the
+* {@link Condition}, hands it to the recorder, and returns the query — so the
+* fluent chain flows straight back into the builder without exposing a mutator.
+*/
+var Clause = class {
+	#record;
+	#column;
+	#connector;
+	constructor(record, column, connector) {
+		this.#record = record;
+		this.#column = column;
+		this.#connector = connector;
+	}
+	equals(value) {
+		return this.#apply("equals", [value]);
+	}
+	not(value) {
+		return this.#apply("not", [value]);
+	}
+	above(value) {
+		return this.#apply("above", [value]);
+	}
+	below(value) {
+		return this.#apply("below", [value]);
+	}
+	from(value) {
+		return this.#apply("from", [value]);
+	}
+	to(value) {
+		return this.#apply("to", [value]);
+	}
+	between(lower, upper) {
+		return this.#apply("between", [lower, upper]);
+	}
+	like(pattern) {
+		return this.#apply("like", [pattern]);
+	}
+	glob(pattern) {
+		return this.#apply("glob", [pattern]);
+	}
+	starts(prefix) {
+		return this.#apply("starts", [prefix]);
+	}
+	ends(suffix) {
+		return this.#apply("ends", [suffix]);
+	}
+	any(values) {
+		return this.#apply("any", values);
+	}
+	none(values) {
+		return this.#apply("none", values);
+	}
+	absent() {
+		return this.#apply("absent", []);
+	}
+	present() {
+		return this.#apply("present", []);
+	}
+	#apply(operator, values) {
+		return this.#record({
+			column: this.#column,
+			operator,
+			values,
+			connector: this.#connector
+		});
+	}
+};
+//#endregion
+//#region src/core/Query.ts
+/**
+* A fluent query builder bound to one table.
+*
+* @remarks
+* Accumulates conditions, ordering, JS filters, and a page; each builder method
+* mutates and returns the same instance, so a chain reads as one statement. The
+* portable parts (conditions, order, page) compile into a {@link Criteria} the
+* table resolves; a `filter` predicate is applied in memory after the read and
+* before paging, so it composes with the rest without a backend ever seeing a
+* JS callback.
+*/
+var Query = class {
+	#table;
+	#conditions = [];
+	#orders = [];
+	#filters = [];
+	#limit;
+	#offset;
+	constructor(table) {
+		this.#table = table;
+	}
+	where(column) {
+		return this.#clause(column, "and");
+	}
+	and(column) {
+		return this.#clause(column, "and");
+	}
+	or(column) {
+		return this.#clause(column, "or");
+	}
+	filter(predicate) {
+		this.#filters.push(predicate);
+		return this;
+	}
+	ascending(column) {
+		this.#orders.push({
+			column,
+			direction: "ascending"
+		});
+		return this;
+	}
+	descending(column) {
+		this.#orders.push({
+			column,
+			direction: "descending"
+		});
+		return this;
+	}
+	limit(count) {
+		this.#limit = count;
+		return this;
+	}
+	offset(count) {
+		this.#offset = count;
+		return this;
+	}
+	async all() {
+		if (this.#filters.length === 0) return this.#table.records({
+			conditions: this.#conditions,
+			order: this.#orders,
+			limit: this.#limit,
+			offset: this.#offset
+		});
+		const fetched = await this.#table.records({
+			conditions: this.#conditions,
+			order: this.#orders
+		});
+		return this.#page(this.#filtered(fetched));
+	}
+	async first() {
+		return (await this.all())[0];
+	}
+	async count() {
+		if (this.#filters.length === 0) return this.#table.count({ conditions: this.#conditions });
+		const fetched = await this.#table.records({ conditions: this.#conditions });
+		return this.#filtered(fetched).length;
+	}
+	/**
+	* Lazy per-row evaluation of this query's conditions / filters / offset /
+	* limit.
+	*
+	* @remarks
+	* `order` and its comparators are IGNORED (streaming yields unsorted, as rows
+	* are evaluated one at a time). Same abort semantics as
+	* `TableInterface.scan`: the signal (if any) is checked before each yield,
+	* and breaking out early closes the underlying source.
+	*
+	* @param options - `signal` to cancel the iteration; checked before each yield
+	* @returns An async iterable of matching rows
+	*/
+	async *stream(options) {
+		if (this.#filters.length === 0) {
+			yield* this.#table.scan({
+				conditions: this.#conditions,
+				limit: this.#limit,
+				offset: this.#offset
+			}, options);
+			return;
+		}
+		const offset = this.#offset ?? 0;
+		let matched = 0;
+		let yielded = 0;
+		for await (const row of this.#table.scan({ conditions: this.#conditions }, options)) {
+			if (this.#limit !== void 0 && yielded >= this.#limit) break;
+			let matches = true;
+			for (const predicate of this.#filters) if (!predicate(row)) {
+				matches = false;
+				break;
+			}
+			if (!matches) continue;
+			if (matched < offset) {
+				matched += 1;
+				continue;
+			}
+			matched += 1;
+			yielded += 1;
+			yield row;
+		}
+	}
+	aggregate(operation, column) {
+		if (this.#filters.length === 0) return this.#table.aggregate(operation, column, { conditions: this.#conditions });
+		return this.#table.records({ conditions: this.#conditions }).then((fetched) => computeAggregate(this.#filtered(fetched), operation, column));
+	}
+	sum(column) {
+		return this.aggregate("sum", column);
+	}
+	average(column) {
+		return this.aggregate("average", column);
+	}
+	minimum(column) {
+		return this.aggregate("minimum", column);
+	}
+	maximum(column) {
+		return this.aggregate("maximum", column);
+	}
+	#clause(column, connector) {
+		return new Clause((condition) => {
+			this.#conditions.push(condition);
+			return this;
+		}, column, connector);
+	}
+	#filtered(rows) {
+		let result = rows;
+		for (const predicate of this.#filters) result = result.filter(predicate);
+		return result;
+	}
+	#page(rows) {
+		const offset = this.#offset ?? 0;
+		if (offset === 0 && this.#limit === void 0) return rows;
+		return rows.slice(offset, this.#limit === void 0 ? void 0 : offset + this.#limit);
+	}
+};
+//#endregion
+//#region src/core/Table.ts
+/**
+* A table — 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
+* 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
+*   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
+*   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
+*   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.
+*/
+var Table = class {
+	#ready;
+	#driver;
+	#name;
+	#key;
+	#contract;
+	#guard;
+	#generate;
+	#emitter;
+	constructor(ready, driver, name, key, contract, generate, on, error) {
+		this.#ready = ready;
+		this.#driver = driver;
+		this.#name = name;
+		this.#key = key;
+		this.#contract = contract;
+		this.#guard = contract.is;
+		this.#generate = generate;
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			on,
+			error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get name() {
+		return this.#name;
+	}
+	get primary() {
+		return this.#key;
+	}
+	get contract() {
+		return this.#contract;
+	}
+	async get(keys) {
+		await this.#ready();
+		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#read(key));
+		return this.#read(keys);
+	}
+	async resolve(keys) {
+		await this.#ready();
+		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#resolveOne(key));
+		return this.#resolveOne(keys);
+	}
+	async has(keys) {
+		await this.#ready();
+		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, async (key) => await this.#read(key) !== void 0);
+		return await this.#read(keys) !== void 0;
+	}
+	async keys() {
+		await this.#ready();
+		return this.#driver.keys(this.#name);
+	}
+	async records(criteria, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		const source = await this.#driver.records?.(this.#name, criteria ?? {}) ?? applyCriteria(await this.#collect(), criteria);
+		const rows = [];
+		for (const row of source) if (this.#guard(row)) rows.push(row);
+		return rows;
+	}
+	/**
+	* Count rows matching `criteria`'s conditions.
+	*
+	* @remarks
+	* Unlike {@link records}, which narrows every row through the table's
+	* contract guard before returning it, `count` operates on STORED rows
+	* WITHOUT that guard (both the native `driver.count` hook and the
+	* `filterRows`-over-`#collect()` fallback count raw storage) — so it can
+	* exceed `(await records(criteria)).length` when storage holds rows that
+	* no longer conform to the table's contract (legacy or migrated data).
+	*
+	* @param criteria - Optional conditions to filter by (paging is ignored)
+	* @param options - `{ signal }` to abort
+	* @returns The count of matching stored rows
+	*/
+	async count(criteria, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		const conditions = criteria?.conditions;
+		const native = await this.#driver.count?.(this.#name, conditions ? { conditions } : {});
+		if (native !== void 0) return native;
+		return filterRows(await this.#collect(), criteria?.conditions ?? []).length;
+	}
+	/**
+	* Compute an aggregate over `column` across rows matching `criteria`'s
+	* conditions.
+	*
+	* @remarks
+	* Like {@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
+	* output.
+	*
+	* @param operation - The aggregate to compute
+	* @param column - The column to aggregate
+	* @param criteria - Optional conditions to filter by (paging is ignored)
+	* @param options - `{ signal }` to abort
+	* @returns The aggregate value, or `undefined` when undefined for the inputs
+	*/
+	async aggregate(operation, column, criteria, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		const conditions = criteria?.conditions;
+		const filter = conditions ? { conditions } : {};
+		const native = this.#driver.aggregate?.(this.#name, operation, column, filter);
+		if (native !== void 0) return native;
+		return computeAggregate(await this.#driver.records?.(this.#name, filter) ?? filterRows(await this.#collect(), criteria?.conditions ?? []), operation, column);
+	}
+	/**
+	* Stream the table's rows matching `criteria`, applying offset/limit paging.
+	*
+	* @remarks
+	* `criteria.limit` counts rows that pass BOTH the criteria conditions AND the
+	* table's contract guard (a stored row that fails the guard is skipped and
+	* does not count toward `limit`) — this can differ from {@link records}'s
+	* `limit`, which a driver's optional native `records` hook applies BEFORE
+	* the contract guard runs, when storage holds rows that no longer conform
+	* to the table's contract.
+	*
+	* @param criteria - Optional conditions plus offset/limit paging
+	* @param options - `{ signal }` to abort mid-stream
+	* @returns An async iterable of matching, guard-conforming rows
+	*/
+	async *scan(criteria, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		if (this.#driver.stream !== void 0) {
+			for await (const row of this.#driver.stream(this.#name, criteria ?? {})) {
+				checkAbort(options?.signal);
+				const narrowed = this.#cast(row);
+				if (narrowed !== void 0) yield narrowed;
+			}
+			return;
+		}
+		const conditions = criteria?.conditions;
+		const offset = criteria?.offset ?? 0;
+		const limit = criteria?.limit;
+		let matched = 0;
+		let yielded = 0;
+		for await (const row of this.#driver.scan(this.#name)) {
+			checkAbort(options?.signal);
+			if (limit !== void 0 && yielded >= limit) break;
+			if (conditions !== void 0 && conditions.length > 0 && !matchesCriteria(row, conditions)) continue;
+			if (matched < offset) {
+				matched += 1;
+				continue;
+			}
+			matched += 1;
+			const narrowed = this.#cast(row);
+			if (narrowed !== void 0) {
+				yielded += 1;
+				yield narrowed;
+			}
+		}
+	}
+	async set(rows, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		if ((0, _orkestrel_contract.isArray)(rows)) return this.#each(rows, (row) => this.#put(row, false), options?.signal);
+		return this.#put(rows, false);
+	}
+	async add(rows, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		if ((0, _orkestrel_contract.isArray)(rows)) return this.#each(rows, (row) => this.#put(row, true), options?.signal);
+		return this.#put(rows, true);
+	}
+	async update(keys, changes, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#updateOne(key, changes), options?.signal);
+		return this.#updateOne(keys, changes);
+	}
+	async remove(keys, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		if ((0, _orkestrel_contract.isArray)(keys)) return this.#each(keys, (key) => this.#delete(key), options?.signal);
+		return this.#delete(keys);
+	}
+	async clear() {
+		await this.#ready();
+		await this.#driver.clear(this.#name);
+		this.#emitter.emit("clear");
+	}
+	query() {
+		return new Query(this);
+	}
+	async cursor() {
+		await this.#ready();
+		const cursor = new Cursor(this, await this.#driver.keys(this.#name));
+		await cursor.next();
+		return cursor;
+	}
+	async #each(items, operation, signal) {
+		const results = [];
+		for (const item of items) {
+			checkAbort(signal);
+			results.push(await operation(item));
+		}
+		return results;
+	}
+	async #read(key) {
+		return this.#cast(await this.#driver.read(this.#name, key));
+	}
+	async #resolveOne(key) {
+		const row = await this.#read(key);
+		if (row === void 0) throw new DatabaseError("NOT_FOUND", `No row '${key}' in table '${this.#name}'`, {
+			table: this.#name,
+			key
+		});
+		return row;
+	}
+	async #put(row, exclusive) {
+		const validated = this.#validate(this.#prepare(row));
+		const key = this.#resolveKey(validated);
+		if (exclusive && await this.#driver.read(this.#name, key) !== void 0) throw new DatabaseError("CONFLICT", `Row '${key}' already exists in table '${this.#name}'`, {
+			table: this.#name,
+			key
+		});
+		await this.#driver.write(this.#name, key, validated);
+		this.#emitter.emit("write", key);
+		return key;
+	}
+	async #updateOne(key, changes) {
+		const existing = await this.#driver.read(this.#name, key);
+		if (existing === void 0) return false;
+		await this.#driver.write(this.#name, key, this.#validate(Object.assign({}, existing, changes)));
+		this.#emitter.emit("write", key);
+		return true;
+	}
+	async #delete(key) {
+		const removed = await this.#driver.delete(this.#name, key);
+		if (removed) this.#emitter.emit("remove", key);
+		return removed;
+	}
+	async #collect() {
+		const rows = [];
+		for await (const row of this.#driver.scan(this.#name)) rows.push(row);
+		return rows;
+	}
+	#prepare(row) {
+		if (!(0, _orkestrel_contract.isRecord)(row)) throw new DatabaseError("VALIDATION", `Row for table '${this.#name}' is not a record`, { table: this.#name });
+		const prepared = { ...row };
+		if (prepared[this.#key] === void 0) {
+			if (this.#generate === void 0) throw new DatabaseError("VALIDATION", `Row for table '${this.#name}' is missing its key column '${this.#key}' and no key factory was provided`, {
+				table: this.#name,
+				column: this.#key
+			});
+			prepared[this.#key] = this.#generate();
+		}
+		return prepared;
+	}
+	#validate(row) {
+		const parsed = this.#contract.parse(row);
+		if (parsed === void 0 || !(0, _orkestrel_contract.isRecord)(parsed)) throw new DatabaseError("VALIDATION", `Row failed the '${this.#name}' contract`, {
+			table: this.#name,
+			row
+		});
+		return parsed;
+	}
+	#resolveKey(row) {
+		const key = extractKey(row, this.#key);
+		if (key === void 0) throw new DatabaseError("VALIDATION", `Row has no usable key in column '${this.#key}'`, {
+			table: this.#name,
+			column: this.#key
+		});
+		return key;
+	}
+	#cast(row) {
+		return row !== void 0 && this.#guard(row) ? row : void 0;
+	}
+};
+//#endregion
+//#region src/core/Database.ts
+/**
+* A database — the ergonomic entry point over a {@link DriverInterface}.
+*
+* @remarks
+* Owns the driver and a `tables` shape map, connecting the driver lazily on first
+* use so a freshly created database is immediately usable. `table(name)` returns
+* a table typed by that table's shape `Infer`. `import` registers more tables and
+* returns a database re-typed with them over the **same** driver and storage;
+* `export` emits a portable {@link TableExport} per table. `transaction` snapshots
+* the driver, runs the scope, and rolls every table back if it throws — an
+* optimistic model that works uniformly across backends rather than reconciling
+* SQL's and IndexedDB's incompatible native transactions.
+*
+* @remarks
+* - **Versioned (optional).** When {@link DatabaseOptions.version} is set and the driver
+*   implements both {@link DriverInterface.meta} and {@link DriverInterface.stamp},
+*   `open()` reconciles the driver's persisted {@link DriverMeta} against the declared
+*   version INSIDE the same lazy-connect chain, AFTER the `open` event fires — see
+*   {@link DatabaseOptions.version} for the full reconciliation contract.
+* - **Observable (§13).** The owned {@link emitter} ({@link DatabaseEventMap}) carries the
+*   connection + transaction lifecycle — `open` / `close` / `transaction` / `commit` /
+*   `rollback` — for fire-and-forget observers, ALONGSIDE each table's per-row events. Every
+*   event is emitted directly, strictly AFTER the relevant transition: `commit` only after
+*   the scope succeeds, `rollback` only after every table is restored. The `rollback` emit
+*   OBSERVES the propagated error — it never swallows it (the original throw propagates
+*   exactly as before). The emitter isolates a listener throw and routes it to its `error`
+*   handler (the `error` option), so observation can never reorder, throw into, or corrupt
+*   the snapshot / commit / rollback flow.
+*/
+var Database = class Database {
+	#driver;
+	#tables;
+	#keys;
+	#indexes;
+	#name;
+	#generate;
+	#version;
+	#emitter;
+	#status = "idle";
+	#ready;
+	constructor(options) {
+		this.#driver = options.driver;
+		this.#tables = options.tables;
+		this.#keys = options.keys ?? {};
+		this.#indexes = options.indexes ?? {};
+		this.#name = options.name ?? "database";
+		this.#generate = options.key;
+		this.#version = options.version;
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			on: options.on,
+			error: options.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get name() {
+		return this.#name;
+	}
+	get status() {
+		return this.#status;
+	}
+	table(name) {
+		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
+		return this.#build(name, this.#key(name), (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.objectShape)(this.#tables[name])));
+	}
+	import(tables, keys) {
+		return this.#spawn(tables, {
+			...this.#keys,
+			...keys
+		});
+	}
+	export() {
+		const result = {};
+		for (const name of Object.keys(this.#tables)) {
+			const columns = this.#tables[name];
+			result[name] = {
+				key: this.#key(name),
+				columns,
+				schema: (0, _orkestrel_contract.compileSchema)((0, _orkestrel_contract.objectShape)(columns))
+			};
+		}
+		return result;
+	}
+	async open() {
+		await this.#connect();
+	}
+	async close() {
+		this.#status = "closed";
+		this.#ready = void 0;
+		await this.#driver.close();
+		this.#emitter.emit("close");
+	}
+	/**
+	* Run `scope` transactionally: commit its writes on success, roll every table
+	* back if it throws.
+	*
+	* @remarks
+	* When the driver implements the optional native {@link DriverInterface.transaction}
+	* hook, that native `commit` / `rollback` handle drives the transaction; otherwise
+	* the universal snapshot floor (`driver.snapshot()`) runs unchanged. Either path
+	* emits the same `transaction` / `commit` / `rollback` lifecycle (AGENTS §13).
+	* `options.signal` is checked ONCE at entry, before connecting or starting any
+	* transactional work — an already-aborted signal throws `ABORTED` and neither the
+	* native hook nor the snapshot floor is invoked. Nesting is unguarded and
+	* unsupported exactly as before: this is a single-writer model, not reentrant.
+	* On the native path, a `scope` throw rolls back via the native handle; a
+	* native `commit` failure propagates as-is with no rollback attempt — the
+	* engine owns transaction state after a failed COMMIT.
+	*
+	* @param scope - The transactional work to run
+	* @param options - `{ signal }` to abort before the transaction starts
+	* @returns The scope's resolved value
+	* @throws An `ABORTED` {@link DatabaseError} when `options.signal` has already fired
+	*/
+	async transaction(scope, options) {
+		checkAbort(options?.signal);
+		await this.#connect();
+		const native = await this.#driver.transaction?.();
+		if (native !== void 0) {
+			this.#emitter.emit("transaction");
+			let value;
+			try {
+				value = await scope();
+			} catch (error) {
+				await native.rollback();
+				this.#emitter.emit("rollback", error);
+				throw error;
+			}
+			await native.commit();
+			this.#emitter.emit("commit");
+			return value;
+		}
+		const rollback = await this.#driver.snapshot();
+		this.#emitter.emit("transaction");
+		try {
+			const value = await scope();
+			this.#emitter.emit("commit");
+			return value;
+		} catch (error) {
+			await rollback();
+			this.#emitter.emit("rollback", error);
+			throw error;
+		}
+	}
+	/**
+	* Diff `deployed` against this database's declared schema and apply the
+	* resulting plan through the driver's optional `migrate` hook.
+	*
+	* @param deployed - The schema currently deployed, as {@link TableSchema}s
+	* @param options - `{ signal }` to abort before the migration starts
+	* @returns The applied {@link Migration} plan
+	* @throws A `MIGRATION` {@link DatabaseError} when the driver does not
+	* implement `migrate`, or when a step references an unknown table
+	* (propagated from the driver)
+	* @throws An `ABORTED` {@link DatabaseError} when `options.signal` has
+	* already fired at entry
+	*/
+	async migrate(deployed, options) {
+		checkAbort(options?.signal);
+		await this.#connect();
+		const plan = planMigration(deployed, this.#schema());
+		if (this.#driver.migrate === void 0) throw new DatabaseError("MIGRATION", `Database '${this.#name}' driver does not support migration`, { name: this.#name });
+		await this.#apply(plan);
+		return plan;
+	}
+	#build(name, key, contract) {
+		return new Table(() => this.#connect(), this.#driver, name, key, contract, this.#generate);
+	}
+	#spawn(tables, keys) {
+		return new Database({
+			driver: this.#driver,
+			tables,
+			keys,
+			name: this.#name,
+			...this.#generate === void 0 ? {} : { key: this.#generate }
+		});
+	}
+	#key(name) {
+		return this.#keys[name] ?? "id";
+	}
+	#schema() {
+		return Object.keys(this.#tables).map((name) => {
+			const columns = this.#tables[name];
+			return {
+				name,
+				primary: this.#key(name),
+				columns: Object.keys(columns).map((column) => {
+					const shape = columns[column];
+					return {
+						name: column,
+						type: shapeToColumnType(shape),
+						nullable: shape.type === "optional" || shape.type === "nullable"
+					};
+				}),
+				indexes: this.#indexes[name] ?? []
+			};
+		});
+	}
+	#connect() {
+		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
+		if (this.#ready === void 0) this.#ready = this.#driver.open(this.#schema()).then(async () => {
+			if (this.#status === "idle") this.#status = "open";
+			this.#emitter.emit("open");
+			await this.#reconcile();
+		});
+		return this.#ready;
+	}
+	async #reconcile() {
+		if (this.#version === void 0 || this.#driver.meta === void 0) return;
+		const declared = this.#schema();
+		const meta = await this.#driver.meta();
+		if (meta === void 0) {
+			await this.#stamp();
+			return;
+		}
+		if (meta.version > this.#version) throw new DatabaseError("MIGRATION", `Database '${this.#name}' store version ${meta.version} is newer than declared version ${this.#version}`, {
+			name: this.#name,
+			stored: meta.version,
+			declared: this.#version
+		});
+		if (meta.version < this.#version) {
+			const plan = planMigration(meta.schema, declared, meta.version, this.#version);
+			if (plan.steps.length > 0 && this.#driver.migrate === void 0) throw new DatabaseError("MIGRATION", `Database '${this.#name}' driver does not support migration`, {
+				name: this.#name,
+				stored: meta.version,
+				declared: this.#version
+			});
+			await this.#apply(plan);
+		}
+	}
+	async #apply(plan) {
+		const native = await this.#driver.transaction?.();
+		if (native !== void 0) {
+			try {
+				await this.#driver.migrate?.(plan);
+				await this.#stamp();
+			} catch (error) {
+				await native.rollback();
+				throw error;
+			}
+			await native.commit();
+			this.#emitter.emit("migrate", plan);
+			return;
+		}
+		await this.#driver.migrate?.(plan);
+		await this.#stamp();
+		this.#emitter.emit("migrate", plan);
+	}
+	async #stamp() {
+		if (this.#version === void 0 || this.#driver.stamp === void 0) return;
+		const meta = {
+			version: this.#version,
+			schema: this.#schema()
+		};
+		await this.#driver.stamp(meta);
+	}
+};
+//#endregion
+//#region src/core/drivers/MemoryDriver.ts
+/**
+* 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
+* `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
+* would still share nested object/array references. `snapshot`
+* clones every table to give transactions an exact rollback point. `scan` and
+* `keys` yield in key order — sorted by the core {@link compareValues} total
+* order, the same contract the SQLite (`ORDER BY`) and IndexedDB (key-ordered
+* reads) backends honor, so an unordered read agrees across every backend rather
+* than leaking Map insertion order. A persistent backend (IndexedDB, SQLite)
+* implements the same nine methods over real storage.
+*/
+var MemoryDriver = class {
+	#tables = /* @__PURE__ */ new Map();
+	#meta;
+	async open(schema) {
+		for (const table of schema) if (!this.#tables.has(table.name)) this.#tables.set(table.name, /* @__PURE__ */ new Map());
+	}
+	async close() {}
+	async read(table, key) {
+		const row = this.#store(table).get(key);
+		return row === void 0 ? void 0 : structuredClone(row);
+	}
+	async write(table, key, row) {
+		this.#store(table).set(key, structuredClone(row));
+	}
+	async delete(table, key) {
+		return this.#store(table).delete(key);
+	}
+	async keys(table) {
+		return this.#ordered(table);
+	}
+	async *scan(table) {
+		const store = this.#store(table);
+		for (const key of this.#ordered(table)) {
+			const row = store.get(key);
+			if (row !== void 0) yield structuredClone(row);
+		}
+	}
+	/**
+	* Natively filtered lazy iteration — 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
+	* `criteria.conditions` (via {@link matchesCriteria}) before counting it
+	* toward `offset` / `limit`. Both are applied lazily as matches are found —
+	* `offset` matches are skipped without being yielded, and iteration stops the
+	* instant `limit` yields have been produced, so a large table is never fully
+	* walked for a small page. `criteria.order` is IGNORED (the same contract as
+	* `TableInterface.scan` and `QueryInterface.stream`): streaming yields key
+	* order, sorted output is `records()`'s job. Rows yield copy-out (AGENTS
+	* §11), and an unknown table mirrors `scan`'s empty-yield behavior.
+	*
+	* @param table - The table to stream
+	* @param criteria - The filter / offset / limit to apply lazily
+	*
+	* @example
+	* ```ts
+	* for await (const row of driver.stream('users', { conditions, limit: 10 })) {
+	*   // one matched row at a time, in key order
+	* }
+	* ```
+	*/
+	async *stream(table, criteria) {
+		const store = this.#store(table);
+		const conditions = criteria.conditions;
+		const offset = criteria.offset ?? 0;
+		const limit = criteria.limit;
+		let skipped = 0;
+		let yielded = 0;
+		for (const key of this.#ordered(table)) {
+			if (limit !== void 0 && yielded >= limit) return;
+			const row = store.get(key);
+			if (row === void 0) continue;
+			if (conditions !== void 0 && conditions.length > 0 && !matchesCriteria(row, conditions)) continue;
+			if (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.
+	*
+	* @remarks
+	* `tables` omitted clones and restores the WHOLE store, byte-identical to the
+	* prior whole-store behavior. `tables` provided clones ONLY the named tables,
+	* and the returned thunk restores ONLY those — every other table keeps
+	* whatever it was mutated to after the snapshot was taken.
+	*
+	* @param tables - The table names to scope the snapshot to; omitted captures every table
+	* @returns A thunk that restores the captured tables
+	*/
+	async snapshot(tables) {
+		if (tables === void 0) {
+			const copy = /* @__PURE__ */ new Map();
+			for (const [name, store] of this.#tables) {
+				const cloned = /* @__PURE__ */ new Map();
+				for (const [key, row] of store) cloned.set(key, structuredClone(row));
+				copy.set(name, cloned);
+			}
+			return async () => {
+				this.#tables.clear();
+				for (const [name, store] of copy) {
+					const restored = /* @__PURE__ */ new Map();
+					for (const [key, row] of store) restored.set(key, structuredClone(row));
+					this.#tables.set(name, restored);
+				}
+			};
+		}
+		const copy = /* @__PURE__ */ new Map();
+		for (const name of tables) {
+			const store = this.#tables.get(name);
+			if (store === void 0) continue;
+			const cloned = /* @__PURE__ */ new Map();
+			for (const [key, row] of store) cloned.set(key, structuredClone(row));
+			copy.set(name, cloned);
+		}
+		return async () => {
+			for (const [name, store] of copy) {
+				const restored = /* @__PURE__ */ new Map();
+				for (const [key, row] of store) restored.set(key, structuredClone(row));
+				this.#tables.set(name, restored);
+			}
+		};
+	}
+	/**
+	* Return the persisted {@link DriverMeta}, or `undefined` when the store has
+	* never been stamped.
+	*
+	* @remarks
+	* In-process only — the metadata lives in this instance's memory, exactly
+	* like the rest of this driver's storage. A driver-conformance-valid
+	* implementation of the optional `meta` / `stamp` pair.
+	*
+	* @returns The last-stamped {@link DriverMeta}, or `undefined`
+	*/
+	async meta() {
+		return this.#meta;
+	}
+	/**
+	* Persist `meta` verbatim for a later `meta()` to return.
+	*
+	* @param meta - The {@link DriverMeta} to persist
+	*/
+	async stamp(meta) {
+		this.#meta = meta;
+	}
+	/**
+	* Apply a {@link Migration} plan's steps against the in-memory store.
+	*
+	* @remarks
+	* A multi-step plan applies its steps sequentially and is NOT atomic — a
+	* failure partway through a plan leaves the earlier steps already applied.
+	*
+	* @param plan - The migration plan to apply
+	*/
+	async migrate(plan) {
+		for (const step of plan.steps) switch (step.operation) {
+			case "table.add":
+				if (!this.#tables.has(step.table.name)) this.#tables.set(step.table.name, /* @__PURE__ */ new Map());
+				break;
+			case "table.remove":
+				this.#require(step.table);
+				this.#tables.delete(step.table);
+				break;
+			case "column.add":
+			case "column.remove": {
+				const store = this.#require(step.table);
+				const rows = [...store.entries()];
+				const migrated = migrateRows(rows.map(([, row]) => row), [step]);
+				rows.forEach(([key], index) => store.set(key, migrated[index]));
+				break;
+			}
+			case "index.add":
+			case "index.remove":
+				this.#require(step.table);
+				break;
+		}
+	}
+	#ordered(table) {
+		return [...this.#store(table).keys()].sort(compareValues);
+	}
+	#require(table) {
+		const store = this.#tables.get(table);
+		if (store === void 0) throw new DatabaseError("MIGRATION", `migrate: unknown table '${table}'`, { table });
+		return store;
+	}
+	#store(table) {
+		let store = this.#tables.get(table);
+		if (store === void 0) {
+			store = /* @__PURE__ */ new Map();
+			this.#tables.set(table, store);
+		}
+		return store;
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create 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 `keys` map.
+*
+* @param options - The driver, the `tables` column map, optional `keys`, and an
+*                   optional `name`
+* @returns A typed {@link DatabaseInterface}
+*
+* @example
+* ```ts
+* import { createDatabase, createMemoryDriver } from '@orkestrel/database'
+* import { integerShape, stringShape } from '@orkestrel/contract'
+*
+* const db = createDatabase({
+* 	driver: createMemoryDriver(),
+* 	tables: {
+* 		users: { id: stringShape(), age: integerShape() },
+* 		posts: { slug: stringShape(), title: stringShape() },
+* 	},
+* 	keys: { posts: 'slug' },
+* })
+* await db.table('users').set({ id: 'u1', age: 36 }) // typed; coerced + validated
+* ```
+*/
+function createDatabase(options) {
+	return new Database(options);
+}
+/**
+* Create 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
+* server, making it the natural choice for tests and ephemeral storage.
+*
+* @returns A fresh in-memory driver
+*/
+function createMemoryDriver() {
+	return new MemoryDriver();
+}
+//#endregion
+exports.Clause = Clause;
+exports.Cursor = Cursor;
+exports.DEFAULT_PRIMARY = DEFAULT_PRIMARY;
+exports.Database = Database;
+exports.DatabaseError = DatabaseError;
+exports.MAX_PATTERN_LENGTH = MAX_PATTERN_LENGTH;
+exports.MemoryDriver = MemoryDriver;
+exports.Query = Query;
+exports.Table = Table;
+exports.UUID_BYTE_COUNT = UUID_BYTE_COUNT;
+exports.UUID_BYTE_RANGE = UUID_BYTE_RANGE;
+exports.applyCriteria = applyCriteria;
+exports.auditDriver = auditDriver;
+exports.checkAbort = checkAbort;
+exports.compareValues = compareValues;
+exports.computeAggregate = computeAggregate;
+exports.conformDriver = conformDriver;
+exports.createDatabase = createDatabase;
+exports.createMemoryDriver = createMemoryDriver;
+exports.deepEqual = deepEqual;
+exports.driverFindings = driverFindings;
+exports.extractKey = extractKey;
+exports.filterRows = filterRows;
+exports.generateUUID = generateUUID;
+exports.globMatch = globMatch;
+exports.isDatabaseError = isDatabaseError;
+exports.isDriverMeta = isDriverMeta;
+exports.likeMatch = likeMatch;
+exports.matchesCondition = matchesCondition;
+exports.matchesCriteria = matchesCriteria;
+exports.migrateRows = migrateRows;
+exports.planMigration = planMigration;
+exports.shapeToColumnType = shapeToColumnType;
+exports.sortRows = sortRows;
+exports.wildcardMatch = wildcardMatch;
+
+//# sourceMappingURL=index.cjs.map