@orkestrel/database 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,3364 @@
+//#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;
+//#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;
+}
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/** Determine whether a value is `null`. */
+function isNull(value) {
+	return value === null;
+}
+/** Determine whether a value is `undefined`. */
+function isUndefined(value) {
+	return value === void 0;
+}
+/** Determine whether a value is a string. */
+function isString(value) {
+	return typeof value === "string";
+}
+/** Determine whether a value is a finite number (excludes `NaN` and `±Infinity`). */
+function isFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+/** Determine whether a value is a finite integer (excludes `NaN`, `±Infinity`, and fractional numbers). */
+function isInteger(value) {
+	return Number.isInteger(value);
+}
+/** Determine whether a value is a boolean. */
+function isBoolean(value) {
+	return typeof value === "boolean";
+}
+/**
+* Determine whether a value is a non-null object.
+*
+* @remarks
+* `true` for arrays, class instances, plain objects, `Map`, `Set`, etc. — use
+* {@link isRecord} when you need a plain-record check.
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Determine whether a value is a plain record (object literal or null-prototype),
+* not an array or class instance.
+*
+* @remarks
+* Use instead of {@link isObject} to distinguish a plain `{}` /
+* `Object.create(null)` from arrays, `Date`, `Map`, etc. The prototype-chain
+* test is realm-agnostic: rather than comparing against the current realm's
+* `Object.prototype` (which a plain object from another `vm.Context`, iframe,
+* or worker would fail), it accepts any value whose prototype is `null`, OR
+* whose prototype's own prototype is `null` — the shape every plain object
+* has in every realm, since `Object.prototype` itself always sits one step
+* above `null`. Arrays and class instances are still rejected: an array's
+* prototype chain runs through `Array.prototype` before `null`, and a class
+* instance's runs through the class's own prototype. The whole body runs
+* inside `attempt` (AGENTS §14) so a revoked `Proxy` or a hostile
+* `getPrototypeOf` trap cannot escape as a thrown error.
+*/
+function isRecord(value) {
+	const outcome = attempt(() => {
+		if (!isObject(value) || isArray(value)) return false;
+		const prototype = Object.getPrototypeOf(value);
+		return prototype === null || Object.getPrototypeOf(prototype) === null;
+	});
+	return outcome.success && outcome.value;
+}
+/** Determine whether a value is an array. */
+function isArray(value) {
+	return Array.isArray(value);
+}
+/**
+* Determine whether a value is a cycle-safe JSON value.
+*
+* @remarks
+* Total guard: never throws, returns `false` for cycles, functions, `Date`
+* instances, class instances, `NaN`, and `±Infinity`. Arrays and plain records
+* are walked with an ancestor set so recursive input fails instead of hanging.
+* The whole walk runs inside `attempt` (AGENTS §14): a hostile getter on a
+* record property, or a revoked `Proxy` anywhere in the structure, is caught
+* and yields `false` instead of escaping as a thrown error.
+*
+* @param value - The value to test
+* @returns `true` when the value has a JSON representation
+*
+* @example
+* ```ts
+* isJSONValue({ nested: [1, 'x', null] }) // true
+* isJSONValue(Number.NaN)                 // false
+* ```
+*/
+function isJSONValue(value) {
+	const ancestors = /* @__PURE__ */ new WeakSet();
+	const check = (entry) => {
+		if (entry === null || isString(entry) || isBoolean(entry) || isFiniteNumber(entry)) return true;
+		if (Array.isArray(entry)) {
+			if (ancestors.has(entry)) return false;
+			ancestors.add(entry);
+			const valid = entry.every(check);
+			ancestors.delete(entry);
+			return valid;
+		}
+		if (!isRecord(entry)) return false;
+		if (ancestors.has(entry)) return false;
+		ancestors.add(entry);
+		const valid = Object.values(entry).every(check);
+		ancestors.delete(entry);
+		return valid;
+	};
+	const outcome = attempt(() => check(value));
+	return outcome.success && outcome.value;
+}
+/**
+* Invoke a callback and capture its outcome as a {@link Result}, never letting
+* a throw escape.
+*
+* @remarks
+* The single sanctioned never-throw boundary for the guards (AGENTS §14). The
+* `whereOf`, `lazyOf`, and `transformOf` combinators invoke caller-supplied
+* callbacks *inside* a guard body, yet a guard must NEVER throw — it returns a
+* `boolean`. This converts a throwing callback into a `Failure` so the
+* surrounding guard can treat it as a non-match instead of propagating the
+* exception, written once and shared rather than copy-pasted as ad-hoc
+* `try`/`catch`.
+*
+* @param callback - The callback to invoke with no arguments
+* @returns A `Success` carrying the return value, or a `Failure` carrying the
+*          thrown reason normalised to an `Error`
+*
+* @example
+* ```ts
+* const outcome = attempt(() => predicate(value))
+* return outcome.success && outcome.value
+* ```
+*/
+function attempt(callback) {
+	try {
+		return {
+			success: true,
+			value: callback()
+		};
+	} catch (reason) {
+		if (reason instanceof Error) return {
+			success: false,
+			error: reason
+		};
+		let message = "Unknown thrown value";
+		try {
+			message = String(reason);
+		} catch {}
+		return {
+			success: false,
+			error: new Error(message)
+		};
+	}
+}
+/**
+* Resolve a (possibly nested) field value from a record by a key or key path.
+*
+* @remarks
+* A single `string` is ONE key (never split on `.`, so dotted keys are safe); a
+* string array descends left-to-right through nested objects. Intermediates may
+* be any object — records, class instances, or arrays indexed by string. Returns
+* `undefined` the moment a segment is missing or lands on a non-object, so the
+* lookup is total — even against a hostile getter or Proxy trap that throws on
+* read, contained via {@link attempt} so the throw never escapes.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @returns The resolved value, or `undefined`
+*
+* @example
+* ```ts
+* resolveField({ user: { name: 'Ada' } }, ['user', 'name']) // 'Ada'
+* resolveField({ 'a.b': 1 }, 'a.b')                          // 1 (one key)
+* resolveField({ a: 1 }, ['a', 'b'])                         // undefined
+* ```
+*/
+function resolveField(record, path) {
+	const keys = isString(path) ? [path] : path;
+	let current = record;
+	for (const key of keys) {
+		if (!isObject(current)) return void 0;
+		const container = current;
+		const outcome = attempt(() => Reflect.get(container, key));
+		if (!outcome.success) return void 0;
+		current = outcome.value;
+	}
+	return current;
+}
+/**
+* Build a deterministic pseudo-random source seeded from a single number.
+*
+* @remarks
+* A mulberry32 generator — the same seed always yields the same sequence, so
+* generated seed data is reproducible across runs. Used as the default random
+* source for {@link compileGenerator}, seeded from the wall clock so casual
+* callers still get varied output without passing a source themselves.
+*
+* @param seed - The seed for the sequence
+* @returns A {@link RandomFunction} returning values in `[0, 1)`
+*
+* @example
+* ```ts
+* const random = seededRandom(42)
+* random() // always the same first value for seed 42
+* ```
+*/
+function seededRandom(seed) {
+	let state = seed >>> 0;
+	return () => {
+		state = state + 1831565813 >>> 0;
+		let t = state;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+function arrayOf(elementGuard) {
+	return (value) => {
+		if (!isArray(value)) return false;
+		const outcome = attempt(() => value.every(elementGuard));
+		return outcome.success && outcome.value;
+	};
+}
+/**
+* Build a guard that accepts values identical (via `Object.is`) to one of the
+* provided literal primitives.
+*
+* @example
+* ```ts
+* const isRole = literalOf('admin', 'member', 'guest')
+* isRole('admin') // true
+* isRole('owner') // false
+* ```
+*/
+function literalOf(...literals) {
+	return (value) => literals.some((literal) => Object.is(literal, value));
+}
+/**
+* Build a guard that accepts plain records matching a guard shape.
+*
+* @remarks
+* Three calling modes depending on the `optional` argument:
+* - **No `optional`** — all shape keys required; extra keys rejected.
+* - **`optional: K[]`** — the listed keys are optional; all others required.
+* - **`optional: true`** — every shape key is optional.
+*
+* Key presence is tested with `Object.hasOwn`, so a shape key satisfied only by
+* an inherited prototype member (`toString`, `constructor`, …) counts as absent.
+* A non-object / `null` / array input returns `false` rather than throwing. The
+* extra-key check only inspects `Object.keys` (string keys), so an extra
+* enumerable SYMBOL key is never rejected — intentional, for JSON fidelity, and
+* matches the compiled guard.
+*
+* @example
+* ```ts
+* const isUser = recordOf({ name: isString, age: isNumber })
+* isUser({ name: 'Ada', age: 36 }) // true
+* isUser({ name: 'Ada' })          // false — age missing
+*
+* const isPartial = recordOf({ name: isString, age: isNumber }, ['age'])
+* isPartial({ name: 'Ada' }) // true
+* ```
+*/
+function recordOf(shape, optional) {
+	const allowed = /* @__PURE__ */ new Set();
+	for (const key in shape) if (Object.prototype.hasOwnProperty.call(shape, key)) allowed.add(key);
+	const optionalSet = new Set(optional === true ? [...allowed] : isArray(optional) ? optional.map((key) => String(key)) : []);
+	return (value) => {
+		if (!isRecord(value)) return false;
+		const outcome = attempt(() => {
+			for (const key of Object.keys(value)) if (!allowed.has(key)) return false;
+			for (const key in shape) {
+				if (!Object.prototype.hasOwnProperty.call(shape, key)) continue;
+				const present = Object.hasOwn(value, key);
+				if (!optionalSet.has(key) && !present) return false;
+				if (present) {
+					const guard = shape[key];
+					if (!guard(value[key])) return false;
+				}
+			}
+			return true;
+		});
+		return outcome.success && outcome.value;
+	};
+}
+function orOf(left, right) {
+	return (value) => left(value) || right(value);
+}
+function unionOf(...guards) {
+	return (value) => guards.some((guard) => guard(value));
+}
+function intersectionOf(...guards) {
+	return (value) => guards.every((guard) => guard(value));
+}
+function whereOf(base, predicate) {
+	return (value) => {
+		if (!base(value)) return false;
+		const outcome = attempt(() => predicate(value));
+		return outcome.success && outcome.value;
+	};
+}
+/**
+* Build a guard that accepts finite numbers within an inclusive `[min, max]`
+* range.
+*
+* @remarks
+* Refines {@link isFiniteNumber} with the bound comparison, so `NaN` /
+* `±Infinity` are rejected before any comparison runs. An absent bound never
+* constrains that side. Reused for a number's own value AND, applied to a
+* `.length`, for string and array length refinements — the single source of the
+* bound logic shared by the compiled guard and parser (compilers.ts).
+*
+* @example
+* ```ts
+* const inRange = boundsOf(1, 5)
+* inRange(3)  // true
+* inRange(0)  // false — below min
+* inRange(6)  // false — above max
+*
+* const atLeastTwo = boundsOf(2)
+* atLeastTwo(2) // true — unbounded above
+* ```
+*/
+function boundsOf(min, max) {
+	return whereOf(isFiniteNumber, (value) => (min === void 0 || value >= min) && (max === void 0 || value <= max));
+}
+/**
+* Build a guard that accepts strings satisfying optional length and pattern
+* refinements — `min` / `max` length and a `pattern`.
+*
+* @remarks
+* Composes {@link isString} with {@link boundsOf} on the string's `.length` and
+* an inline `pattern.test` (the same refinement {@link matchOf} performs). When all three options are absent it returns
+* the bare {@link isString} guard (the unconstrained fast path), so an
+* unrefined string leaf pays no wrapping cost. The single source of the string
+* refinement shared by the compiled guard and parser (compilers.ts).
+*
+* @example
+* ```ts
+* const isSlug = stringOf({ min: 1, max: 32, pattern: /^[a-z-]+$/ })
+* isSlug('hello-world') // true
+* isSlug('')            // false — below min
+* isSlug('Hello')       // false — pattern miss
+*
+* stringOf() // identical to isString
+* ```
+*/
+function stringOf(options) {
+	const min = options?.min;
+	const max = options?.max;
+	const pattern = options?.pattern;
+	if (min === void 0 && max === void 0 && pattern === void 0) return isString;
+	const withinLength = boundsOf(min, max);
+	return whereOf(isString, (value) => withinLength(value.length) && (pattern === void 0 || pattern.test(value)));
+}
+/**
+* Extend a guard to also allow `null`.
+*
+* @example
+* ```ts
+* const isNullableString = nullableOf(isString)
+* isNullableString('hi') // true
+* isNullableString(null) // true
+* isNullableString(42)   // false
+* ```
+*/
+function nullableOf(guard) {
+	return (value) => value === null || guard(value);
+}
+/**
+* Parse an unknown value to a string.
+*
+* @remarks
+* A string is returned unchanged; a finite number is coerced to its decimal
+* string (`42` → `'42'`). `NaN`, `±Infinity`, and every other type → `undefined`.
+*
+* @param value - The value to parse
+* @returns A string, or `undefined`
+*/
+function parseString(value) {
+	if (isString(value)) return value;
+	if (isFiniteNumber(value)) return String(value);
+}
+/**
+* Parse an unknown value to a finite number.
+*
+* @remarks
+* A finite number is returned unchanged; a non-blank numeric string is parsed
+* via `Number(...)`. `NaN`, `±Infinity`, blank/non-numeric strings, and every
+* other type → `undefined`.
+*
+* @param value - The value to parse
+* @returns A finite number, or `undefined`
+*/
+function parseNumber(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (isString(value)) {
+		if (value.trim() === "") return void 0;
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+/**
+* Parse an unknown value to a finite integer.
+*
+* @remarks
+* Accepts whatever {@link parseNumber} accepts, then requires the result to have
+* no fractional part. `3.14` / `'3.14'` → `undefined`.
+*
+* @param value - The value to parse
+* @returns A finite integer, or `undefined`
+*/
+function parseInteger(value) {
+	const parsed = parseNumber(value);
+	if (parsed === void 0) return void 0;
+	return Number.isInteger(parsed) ? parsed : void 0;
+}
+/**
+* Parse an unknown value to a boolean.
+*
+* @remarks
+* A boolean is returned unchanged. The strings `'true'` / `'false'` / `'1'` /
+* `'0'` and the numbers `1` / `0` coerce to the matching boolean. Everything
+* else → `undefined`.
+*
+* @param value - The value to parse
+* @returns A boolean, or `undefined`
+*/
+function parseBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (value === "true" || value === "1" || value === 1) return true;
+	if (value === "false" || value === "0" || value === 0) return false;
+}
+/**
+* Parse an unknown value to a plain record — the input reference, never cloned.
+*
+* @param value - The value to parse
+* @returns The record, or `undefined`
+*/
+function parseRecord(value) {
+	return isRecord(value) ? value : void 0;
+}
+/**
+* Validate that a {@link ContractShape} tree is well-formed — a pure recursive
+* prepass run before compilation.
+*
+* @remarks
+* Fail-fast, per AGENTS §12: a malformed shape is a programmer error, so this
+* throws a plain `Error` immediately rather than surfacing as a silently-wrong
+* guard, parser, schema, or generator later. Checks, recursively:
+*
+* - An {@link OptionalShape} is only legal as a direct object-property value —
+*   `optionalShape` wrapping an array item, a union variant, another
+*   optional/nullable's inner shape, `additionalProperties`, or the top-level
+*   shape all throw. An object property IS the one legal placement: its value
+*   is unwrapped to `.inner` before recursing, so `.inner` itself is validated
+*   as a normal (non-optional-wrapping) shape.
+* - A {@link UnionShape} needs at least one variant; a {@link LiteralShape}
+*   needs at least one value and rejects non-finite (`NaN` / `Infinity` /
+*   `-Infinity`) number values.
+* - A bounded {@link StringShape} / {@link NumberShape} / {@link ArrayShape}
+*   needs `min <= max` when both are set.
+* - An integer {@link NumberShape} (`integer: true`) needs a non-empty integer
+*   range: `Math.ceil(min ?? -Infinity) <= Math.floor(max ?? Infinity)`.
+* - `null` / `json` / `raw` / `boolean` are always-valid leaves. Recursion
+*   continues into array items, object properties (and `additionalProperties`
+*   when it is a shape), union variants, and optional/nullable inner shapes.
+*
+* @param shape - The shape to validate
+* @throws {Error} When the shape is malformed
+*/
+function validateShape(shape) {
+	switch (shape.type) {
+		case "string":
+			if (shape.min !== void 0 && shape.max !== void 0 && shape.min > shape.max) throw new Error("validateShape: a string shape has min greater than max");
+			return;
+		case "number":
+			if (shape.min !== void 0 && shape.max !== void 0 && shape.min > shape.max) throw new Error("validateShape: a number shape has min greater than max");
+			if (shape.integer === true) {
+				if (Math.ceil(shape.min ?? Number.NEGATIVE_INFINITY) > Math.floor(shape.max ?? Number.POSITIVE_INFINITY)) throw new Error("validateShape: an integer number shape has an empty integer range");
+			}
+			return;
+		case "boolean":
+		case "null":
+		case "json":
+		case "raw": return;
+		case "literal":
+			if (shape.values.length === 0) throw new Error("validateShape: a literal shape needs at least one value");
+			for (const value of shape.values) if (typeof value === "number" && !Number.isFinite(value)) throw new Error("validateShape: a literal shape may not contain non-finite number values");
+			return;
+		case "array":
+			if (shape.min !== void 0 && shape.max !== void 0 && shape.min > shape.max) throw new Error("validateShape: an array shape has min greater than max");
+			validateShape(shape.items);
+			return;
+		case "object": {
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				validateShape(child.type === "optional" ? child.inner : child);
+			}
+			const extra = shape.additionalProperties;
+			if (extra !== void 0 && extra !== true && extra !== false) validateShape(extra);
+			return;
+		}
+		case "union":
+			if (shape.variants.length === 0) throw new Error("validateShape: a union shape needs at least one variant");
+			for (const variant of shape.variants) validateShape(variant);
+			return;
+		case "optional": throw new Error("validateShape: an optional shape may only appear as a direct object-property value");
+		case "nullable":
+			validateShape(shape.inner);
+			return;
+	}
+}
+/**
+* Compile a {@link ContractShape} into a JSON Schema document.
+*
+* @remarks
+* Object shapes emit `additionalProperties: false` (unless opened) and list only
+* required keys in `required`; nullable shapes emit an `anyOf` with `{ type:
+* 'null' }`. Emission only — it never inspects a runtime value.
+*
+* @param shape - The shape to compile
+* @returns The emitted JSON Schema
+*/
+function compileSchema(shape) {
+	switch (shape.type) {
+		case "string": return {
+			type: "string",
+			...shape.min !== void 0 ? { minLength: shape.min } : {},
+			...shape.max !== void 0 ? { maxLength: shape.max } : {},
+			...shape.pattern !== void 0 ? { pattern: shape.pattern.source } : {},
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "number": return {
+			type: shape.integer === true ? "integer" : "number",
+			...shape.min !== void 0 ? { minimum: shape.min } : {},
+			...shape.max !== void 0 ? { maximum: shape.max } : {},
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "boolean": return {
+			type: "boolean",
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "null": return {
+			type: "null",
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "json": return { ...shape.description !== void 0 ? { description: shape.description } : {} };
+		case "literal": return {
+			enum: [...shape.values],
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "array": return {
+			type: "array",
+			items: compileSchema(shape.items),
+			...shape.min !== void 0 ? { minItems: shape.min } : {},
+			...shape.max !== void 0 ? { maxItems: shape.max } : {},
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "object": {
+			const properties = {};
+			const required = [];
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				properties[key] = compileSchema(child);
+				if (child.type !== "optional") required.push(key);
+			}
+			const extra = shape.additionalProperties;
+			const additionalProperties = extra === true ? true : extra !== void 0 && extra !== false ? compileSchema(extra) : false;
+			return {
+				type: "object",
+				...Object.keys(properties).length > 0 ? { properties } : {},
+				...required.length > 0 ? { required } : {},
+				additionalProperties,
+				...shape.description !== void 0 ? { description: shape.description } : {}
+			};
+		}
+		case "union": return {
+			...shape.mode === "oneOf" ? { oneOf: shape.variants.map((variant) => compileSchema(variant)) } : { anyOf: shape.variants.map((variant) => compileSchema(variant)) },
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "optional": return compileSchema(shape.inner);
+		case "nullable": return { anyOf: [compileSchema(shape.inner), { type: "null" }] };
+		case "raw": return shape.schema;
+	}
+}
+/**
+* Compile a {@link ContractShape} into a runtime type guard.
+*
+* @remarks
+* Reuses the combinators: `literalOf` for literals, `arrayOf` for arrays,
+* `recordOf` for closed objects, `unionOf` for unions, `nullableOf` for nullable,
+* and `whereOf` for constraint refinement. Like every guard it is total — it
+* never throws (AGENTS §14).
+*
+* @param shape - The shape to compile
+* @returns A guard narrowing to the shape's inferred type
+*/
+function compileGuard(shape) {
+	switch (shape.type) {
+		case "string": return stringOf({
+			min: shape.min,
+			max: shape.max,
+			pattern: shape.pattern
+		});
+		case "number": {
+			const base = shape.integer === true ? isInteger : isFiniteNumber;
+			if (shape.min === void 0 && shape.max === void 0) return base;
+			return shape.integer === true ? intersectionOf(isInteger, boundsOf(shape.min, shape.max)) : boundsOf(shape.min, shape.max);
+		}
+		case "boolean": return isBoolean;
+		case "null": return isNull;
+		case "json": return isJSONValue;
+		case "literal": return literalOf(...shape.values);
+		case "array": {
+			const base = arrayOf(compileGuard(shape.items));
+			if (shape.min === void 0 && shape.max === void 0) return base;
+			const withinLength = boundsOf(shape.min, shape.max);
+			return whereOf(base, (value) => withinLength(value.length));
+		}
+		case "object": {
+			const map = Object.create(null);
+			const optionalKeys = [];
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				if (child.type === "optional") {
+					map[key] = compileGuard(child.inner);
+					optionalKeys.push(key);
+				} else map[key] = compileGuard(child);
+			}
+			const extra = shape.additionalProperties;
+			if (extra === void 0 || extra === false) return optionalKeys.length > 0 ? recordOf(map, optionalKeys) : recordOf(map);
+			const additional = extra === true ? void 0 : compileGuard(extra);
+			const required = Object.keys(map).filter((key) => !optionalKeys.includes(key));
+			return (value) => {
+				if (!isRecord(value)) return false;
+				for (const key of required) if (!Object.hasOwn(value, key)) return false;
+				const outcome = attempt(() => {
+					for (const key of Object.keys(value)) {
+						const guard = Object.hasOwn(map, key) ? map[key] : void 0;
+						if (guard !== void 0) {
+							if (!guard(value[key])) return false;
+						} else if (additional !== void 0 && !additional(value[key])) return false;
+					}
+					return true;
+				});
+				return outcome.success && outcome.value;
+			};
+		}
+		case "union": return unionOf(...shape.variants.map((variant) => compileGuard(variant)));
+		case "optional": return orOf(isUndefined, compileGuard(shape.inner));
+		case "nullable": return nullableOf(compileGuard(shape.inner));
+		case "raw": return (_value) => true;
+	}
+}
+/**
+* Compile a {@link ContractShape} into an input parser.
+*
+* @remarks
+* Reuses the leaf parsers (`parseString` / `parseInteger` / `parseNumber` /
+* `parseBoolean` / `parseRecord`) and coerces structurally. An object fails as a
+* whole on any required-field failure; a union returns a guard-valid value
+* unchanged, otherwise the first variant that both parses and guards wins.
+*
+* After coercing a leaf, it re-applies that leaf's REFINEMENTS through the same
+* combinators `compileGuard` uses — `stringOf` for a string's length/pattern and
+* `boundsOf` for a number's value and an array's length — so a value that coerces
+* but violates a bound parses to `undefined`. The result is full parse↔guard
+* soundness (AGENTS §14): a non-`undefined` parse always satisfies the contract's
+* `is`, refinements included.
+*
+* @param shape - The shape to compile
+* @returns A parser yielding the shape's inferred type or `undefined`
+*/
+function compileParser(shape) {
+	switch (shape.type) {
+		case "string": {
+			if (shape.min === void 0 && shape.max === void 0 && shape.pattern === void 0) return parseString;
+			const guard = stringOf({
+				min: shape.min,
+				max: shape.max,
+				pattern: shape.pattern
+			});
+			return (value) => {
+				const parsed = parseString(value);
+				return parsed !== void 0 && guard(parsed) ? parsed : void 0;
+			};
+		}
+		case "number": {
+			const base = shape.integer === true ? parseInteger : parseNumber;
+			if (shape.min === void 0 && shape.max === void 0) return base;
+			const within = boundsOf(shape.min, shape.max);
+			return (value) => {
+				const parsed = base(value);
+				return parsed !== void 0 && within(parsed) ? parsed : void 0;
+			};
+		}
+		case "boolean": return parseBoolean;
+		case "null": return (value) => value === null ? null : void 0;
+		case "json": return (value) => isJSONValue(value) ? value : void 0;
+		case "literal": {
+			const allowed = new Set(shape.values);
+			return (value) => {
+				if (allowed.has(value)) return value;
+				if (isString(value)) {
+					const trimmed = value.trim();
+					if (allowed.has(trimmed)) return trimmed;
+				}
+			};
+		}
+		case "array": {
+			const item = compileParser(shape.items);
+			const unbounded = shape.min === void 0 && shape.max === void 0;
+			const withinLength = boundsOf(shape.min, shape.max);
+			return (value) => {
+				if (!isArray(value)) return void 0;
+				const result = [];
+				for (const entry of value) {
+					const parsed = item(entry);
+					if (parsed === void 0) return void 0;
+					result.push(parsed);
+				}
+				return unbounded || withinLength(result.length) ? result : void 0;
+			};
+		}
+		case "object": {
+			const entries = [];
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				const optional = child.type === "optional";
+				entries.push({
+					key,
+					parse: compileParser(optional ? child.inner : child),
+					optional
+				});
+			}
+			const known = new Set(entries.map((entry) => entry.key));
+			const extra = shape.additionalProperties;
+			const additional = extra === void 0 || extra === false || extra === true ? void 0 : compileParser(extra);
+			const open = extra === true || additional !== void 0;
+			return (value) => {
+				const record = parseRecord(value);
+				if (record === void 0) return void 0;
+				const outcome = attempt(() => {
+					const result = Object.create(null);
+					for (const entry of entries) {
+						const raw = record[entry.key];
+						if (raw === void 0) {
+							if (entry.optional) continue;
+							return;
+						}
+						const parsed = entry.parse(raw);
+						if (parsed === void 0) return void 0;
+						result[entry.key] = parsed;
+					}
+					if (open) for (const key of Object.keys(record)) {
+						if (known.has(key)) continue;
+						if (additional === void 0) result[key] = record[key];
+						else {
+							const parsed = additional(record[key]);
+							if (parsed === void 0) return void 0;
+							result[key] = parsed;
+						}
+					}
+					return result;
+				});
+				return outcome.success ? outcome.value : void 0;
+			};
+		}
+		case "union": {
+			const variants = shape.variants.map((variant) => ({
+				parse: compileParser(variant),
+				guard: compileGuard(variant)
+			}));
+			return (value) => {
+				for (const variant of variants) if (variant.guard(value)) return value;
+				for (const variant of variants) {
+					const parsed = variant.parse(value);
+					if (parsed !== void 0 && variant.guard(parsed)) return parsed;
+				}
+			};
+		}
+		case "optional": {
+			const inner = compileParser(shape.inner);
+			return (value) => value === void 0 ? void 0 : inner(value);
+		}
+		case "nullable": {
+			const inner = compileParser(shape.inner);
+			return (value) => value === null ? null : inner(value);
+		}
+		case "raw": return (value) => value;
+	}
+}
+/**
+* Compile a {@link ContractShape} into a deterministic seed value.
+*
+* @remarks
+* The same shape and the same `random` source always produce the same value, so
+* seed data is reproducible. Defaults to a {@link seededRandom} source seeded
+* from the wall clock when none is supplied. Throws on a degenerate empty
+* `literalShape` / `unionShape`, on a pattern-constrained `stringShape` whose
+* generated sample cannot satisfy the pattern, or on a `rawShape` (its embedded
+* schema is arbitrary and cannot be auto-generated) — a programmer error that
+* cannot generate a value (AGENTS §12). `createContract` runs
+* {@link validateShape} first, so a degenerate `literalShape` / `unionShape` /
+* bounded shape is normally caught there; these throws remain here as defense
+* for standalone `compileGenerator` use.
+*
+* @param shape - The shape to generate from
+* @param random - A seeded random source (defaults to `seededRandom(Date.now())`)
+* @returns A value matching the shape
+*/
+function compileGenerator(shape, random = seededRandom(Date.now())) {
+	switch (shape.type) {
+		case "string": {
+			const min = shape.min ?? 0;
+			const max = shape.max ?? Math.max(min, 12);
+			const length = Math.max(min, Math.min(max, 8));
+			const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+			let value = "";
+			for (let index = 0; index < length; index += 1) value += alphabet[Math.floor(random() * 36)];
+			if (shape.pattern !== void 0 && !shape.pattern.test(value)) throw new Error("compileGenerator: a pattern-constrained string shape cannot be auto-generated — supply or verify values another way");
+			return value;
+		}
+		case "number": {
+			const min = shape.min ?? 0;
+			const max = shape.max ?? 100;
+			if (shape.integer === true) {
+				const lo = Math.ceil(min);
+				const hi = Math.floor(max);
+				return Math.floor(random() * (hi - lo + 1)) + lo;
+			}
+			return random() * (max - min) + min;
+		}
+		case "boolean": return random() >= .5;
+		case "null": return null;
+		case "json": {
+			const pick = Math.floor(random() * 5);
+			if (pick === 0) return null;
+			if (pick === 1) return random() >= .5;
+			if (pick === 2) return Math.floor(random() * 1e3);
+			if (pick === 3) {
+				const alphabet = "abcdefghijklmnopqrstuvwxyz";
+				let value = "";
+				for (let index = 0; index < 6; index += 1) value += alphabet[Math.floor(random() * 26)];
+				return value;
+			}
+			return { value: Math.floor(random() * 1e3) };
+		}
+		case "literal":
+			if (shape.values.length === 0) throw new Error("compileGenerator: a literal shape needs at least one value");
+			return shape.values[Math.floor(random() * shape.values.length)];
+		case "array": {
+			const lo = shape.min ?? Math.min(1, shape.max ?? 1);
+			const hi = shape.max ?? Math.max(lo, 3);
+			const length = Math.floor(random() * (hi - lo + 1)) + lo;
+			const result = [];
+			for (let index = 0; index < length; index += 1) result.push(compileGenerator(shape.items, random));
+			return result;
+		}
+		case "object": {
+			const result = {};
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				if (child.type === "optional" && random() < .3) continue;
+				result[key] = compileGenerator(child, random);
+			}
+			const extra = shape.additionalProperties;
+			if (extra !== void 0 && extra !== true && extra !== false) {
+				const count = 1 + Math.floor(random() * 2);
+				for (let index = 0; index < count; index += 1) {
+					const key = `key${index}`;
+					if (Object.hasOwn(result, key)) continue;
+					result[key] = compileGenerator(extra, random);
+				}
+			}
+			return result;
+		}
+		case "union":
+			if (shape.variants.length === 0) throw new Error("compileGenerator: a union shape needs at least one variant");
+			return compileGenerator(shape.variants[Math.floor(random() * shape.variants.length)], random);
+		case "optional": return compileGenerator(shape.inner, random);
+		case "nullable": return random() < .2 ? null : compileGenerator(shape.inner, random);
+		case "raw": throw new Error("compileGenerator: a raw shape embeds an arbitrary JSON Schema and cannot be auto-generated — supply values another way");
+	}
+}
+function createContract(shape) {
+	validateShape(shape);
+	const schema = compileSchema(shape);
+	const guard = compileGuard(shape);
+	const parser = compileParser(shape);
+	return {
+		schema,
+		is: guard,
+		parse(value) {
+			return parser(value);
+		},
+		generate(random) {
+			return compileGenerator(shape, random);
+		}
+	};
+}
+/**
+* Build an {@link ObjectShape} from a property map.
+*
+* @remarks
+* Wrap any property in {@link optionalShape} to allow its absence. By default
+* the compiled guard rejects unknown keys; pass `additionalProperties` to open
+* the object.
+*
+* @param properties - Map of property names to child shapes
+* @param options - Optional `additionalProperties` and `description`
+* @returns An object shape
+*
+* @example
+* ```ts
+* const user = objectShape({
+* 	name: stringShape({ min: 1 }),
+* 	age: integerShape({ min: 0, max: 120 }),
+* 	bio: optionalShape(stringShape()),
+* })
+* ```
+*/
+function objectShape(properties, options) {
+	return {
+		type: "object",
+		properties,
+		additionalProperties: options?.additionalProperties,
+		description: options?.description
+	};
+}
+//#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 (isRecord(left) && 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 use {@link compareValues}; `like` / `glob` / `starts`
+* / `ends` match only strings; `any` / `none` test membership by value equality.
+* 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 = resolveField(row, condition.column);
+	const first = condition.values[0];
+	const second = condition.values[1];
+	switch (condition.operator) {
+		case "equals": return compareValues(value, first) === 0;
+		case "not": return compareValues(value, first) !== 0;
+		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 isString(value) && isString(first) && likeMatch(value, first);
+		case "glob": return isString(value) && isString(first) && globMatch(value, first);
+		case "starts": return isString(value) && isString(first) && value.startsWith(first);
+		case "ends": return isString(value) && isString(first) && value.endsWith(first);
+		case "any": return condition.values.some((candidate) => compareValues(value, candidate) === 0);
+		case "none": return !condition.values.some((candidate) => compareValues(value, candidate) === 0);
+		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(resolveField(left, term.column), 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 (!isRecord(row)) continue;
+		const value = parseNumber(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 (isString(value)) return value;
+	if (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";
+	}
+}
+/**
+* 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.
+*
+* @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`
+*
+* @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) if (!beforeColumns.has(column.name)) steps.push({
+			operation: "column.add",
+			table: table.name,
+			column
+		});
+		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
+* copy-in/copy-out isolation (mutating the caller's row after `write`, or the
+* 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; 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
+			}
+		],
+		indexes: []
+	};
+	const CONFORMANCE_SCHEMA = [CONFORMANCE_USERS_SCHEMA, {
+		name: "posts",
+		primary: "slug",
+		columns: [{
+			name: "slug",
+			type: "text",
+			nullable: false
+		}, {
+			name: "title",
+			type: "text",
+			nullable: false
+		}],
+		indexes: []
+	}];
+	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
+				};
+				await driver.write("users", "u1", input);
+				input.name = "Mutated after write";
+				const stored = await driver.read("users", "u1");
+				const original = {
+					id: "u1",
+					name: "Ada",
+					age: 30
+				};
+				if (stored === void 0 || !deepEqual(stored, original)) {
+					await driver.close();
+					return findingOf("copy-in", "write must copy the input row rather than store it by reference", {
+						table: "users",
+						expected: original,
+						actual: stored
+					});
+				}
+				stored.name = "Mutated after read";
+				const reread = await driver.read("users", "u1");
+				if (reread === void 0 || !deepEqual(reread, original)) {
+					await driver.close();
+					return findingOf("copy-out", "read must copy the stored row 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: "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;
+				await driver.open(CONFORMANCE_SCHEMA);
+				await driver.write("users", "u1", {
+					id: "u1",
+					name: "Ada",
+					age: 30,
+					legacy: true
+				});
+				const removePlan = planMigration([{
+					...CONFORMANCE_USERS_SCHEMA,
+					columns: [...CONFORMANCE_USERS_SCHEMA.columns, {
+						name: "legacy",
+						type: "boolean",
+						nullable: false
+					}]
+				}], [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;
+}
+//#endregion
+//#region node_modules/@orkestrel/emitter/dist/src/core/index.js
+/**
+* Extract the own enumerable keys of a mapped object, typed as its key union.
+*
+* @remarks
+* `Object.keys` widens its result to `string[]`, which breaks the key↔value
+* correlation a mapped type (like `EmitterHooks<TMap>`) otherwise guarantees.
+* A `for…in` push into a `keyof`-typed array narrows the result back,
+* type-safely and with no assertion.
+*
+* @typeParam T - The object shape whose keys are extracted.
+* @param object - The object to read keys from.
+* @returns The object's own enumerable keys, typed as `(keyof T)[]`.
+*
+* @example
+* ```ts
+* import { extractKeys } from '@src/core'
+*
+* const hooks = { tick: () => {}, done: () => {} }
+* extractKeys(hooks) // ['tick', 'done']
+* extractKeys({}) // []
+* ```
+*/
+function extractKeys(object) {
+	const collected = [];
+	for (const key in object) collected.push(key);
+	return collected;
+}
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/** Determine whether a value is callable. */
+function isFunction(value) {
+	return typeof value === "function";
+}
+/**
+* A typed synchronous event emitter — the foundational observable primitive of
+* the codebase (AGENTS §13). Stateful entities OWN one as a `#emitter` field and
+* expose it through `readonly emitter`; they never inherit from it.
+*
+* @typeParam TMap - The event map: each event name to the argument tuple its
+*   listeners receive.
+*
+* @remarks
+* - **Synchronous.** `emit` invokes listeners in registration order, in the
+*   current tick.
+* - **Listener isolation.** A throwing listener never stops its siblings: every
+*   listener runs, and a throw is routed to the `error` handler
+*   ({@link EmitterOptions.error}) — never rethrown. Every throwing listener
+*   surfaces (not just the first), and with no `error` handler a throw is swallowed
+*   silently. The `error` handler runs inside its own try/catch, so a throwing
+*   error-handler is swallowed too (anti-recursion — it cannot escape or re-enter).
+* - **Per-event storage.** Listeners live in a per-event `Set`, so every public
+*   method is precisely typed with no assertions.
+* - **Destroyed → no-op.** After `destroy()`, `on` / `once` / `emit` do nothing
+*   and `destroyed` is `true`.
+*
+* @example
+* ```ts
+* type CounterEventMap = {
+* 	tick: readonly [count: number]
+* 	done: readonly []
+* }
+*
+* const emitter = new Emitter<CounterEventMap>({
+* 	on: { done: () => stop() },
+* 	error: (error, event) => log(`listener for ${event} threw`, error),
+* })
+* emitter.on('tick', (count) => render(count))
+* emitter.emit('tick', 1)
+* ```
+*/
+var Emitter = class {
+	#destroyed = false;
+	#listeners = {};
+	#wrappers = {};
+	#error;
+	constructor(options) {
+		const error = options?.error;
+		this.#error = isFunction(error) ? error : void 0;
+		const hooks = options?.on;
+		if (hooks !== void 0) this.#wire(hooks);
+	}
+	get destroyed() {
+		return this.#destroyed;
+	}
+	on(event, handler) {
+		if (this.#destroyed) return;
+		(this.#listeners[event] ??= /* @__PURE__ */ new Set()).add(handler);
+	}
+	once(event, handler) {
+		if (this.#destroyed) return;
+		const pending = this.#wrappers[event] ??= /* @__PURE__ */ new Map();
+		const wrapper = (...args) => {
+			this.#listeners[event]?.delete(wrapper);
+			const wrappers = pending.get(handler);
+			wrappers?.delete(wrapper);
+			if (wrappers !== void 0 && wrappers.size === 0) pending.delete(handler);
+			handler(...args);
+		};
+		const wrappers = pending.get(handler) ?? /* @__PURE__ */ new Set();
+		wrappers.add(wrapper);
+		pending.set(handler, wrappers);
+		this.on(event, wrapper);
+	}
+	off(event, handler) {
+		const listeners = this.#listeners[event];
+		const wrappers = this.#wrappers[event];
+		const pending = wrappers?.get(handler);
+		if (pending !== void 0) {
+			for (const wrapper of pending) listeners?.delete(wrapper);
+			wrappers?.delete(handler);
+		}
+		listeners?.delete(handler);
+	}
+	emit(event, ...args) {
+		if (this.#destroyed) return;
+		const listeners = this.#listeners[event];
+		if (listeners === void 0) return;
+		for (const handler of [...listeners]) try {
+			handler(...args);
+		} catch (error) {
+			this.#surface(error, event);
+		}
+	}
+	count(event) {
+		if (event !== void 0) return this.#listeners[event]?.size ?? 0;
+		let total = 0;
+		for (const set of Object.values(this.#listeners)) total += set?.size ?? 0;
+		return total;
+	}
+	clear(event) {
+		if (event !== void 0) {
+			delete this.#listeners[event];
+			delete this.#wrappers[event];
+			return;
+		}
+		this.#listeners = {};
+		this.#wrappers = {};
+	}
+	destroy() {
+		this.#listeners = {};
+		this.#wrappers = {};
+		this.#error = void 0;
+		this.#destroyed = true;
+	}
+	#surface(error, event) {
+		const handler = this.#error;
+		if (handler === void 0) return;
+		try {
+			handler(error, String(event));
+		} catch {}
+	}
+	#wire(hooks) {
+		for (const event of extractKeys(hooks)) {
+			const handler = hooks[event];
+			if (isFunction(handler)) this.on(event, handler);
+		}
+	}
+};
+//#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 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 (isArray(keys)) return this.#each(keys, (key) => this.#read(key));
+		return this.#read(keys);
+	}
+	async resolve(keys) {
+		await this.#ready();
+		if (isArray(keys)) return this.#each(keys, (key) => this.#resolveOne(key));
+		return this.#resolveOne(keys);
+	}
+	async has(keys) {
+		await this.#ready();
+		if (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;
+	}
+	async count(criteria, options) {
+		checkAbort(options?.signal);
+		await this.#ready();
+		const conditions = criteria?.conditions;
+		const native = await this.#driver.count?.(this.#name, conditions ? { conditions } : {});
+		if (native !== void 0) return native;
+		return filterRows(await this.#collect(), criteria?.conditions ?? []).length;
+	}
+	async 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 generator 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 (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 (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 (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 (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 (!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 || !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 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), createContract(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: compileSchema(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 copied in and out so a
+* caller can never mutate stored state by reference (AGENTS §11), and `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 : { ...row };
+	}
+	async write(table, key, row) {
+		this.#store(table).set(key, { ...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 { ...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 { ...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, { ...row });
+				copy.set(name, cloned);
+			}
+			return async () => {
+				this.#tables.clear();
+				for (const [name, store] of copy) this.#tables.set(name, store);
+			};
+		}
+		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, { ...row });
+			copy.set(name, cloned);
+		}
+		return async () => {
+			for (const [name, store] of copy) this.#tables.set(name, store);
+		};
+	}
+	/**
+	* 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
+export { Clause, Cursor, DEFAULT_PRIMARY, Database, DatabaseError, MAX_PATTERN_LENGTH, MemoryDriver, Query, Table, applyCriteria, auditDriver, checkAbort, compareValues, computeAggregate, conformDriver, createDatabase, createMemoryDriver, deepEqual, driverFindings, extractKey, filterRows, globMatch, isDatabaseError, likeMatch, matchesCondition, matchesCriteria, migrateRows, planMigration, shapeToColumnType, sortRows, wildcardMatch };
+
+//# sourceMappingURL=index.js.map