@orkestrel/database 0.0.1 → 0.0.3

package/dist/src/core/index.js

@@ -1,3 +1,5 @@
+import { compileSchema, createContract, isArray, isBoolean, isFiniteNumber, isRecord, isString, objectShape, parseNumber, resolveField } from "@orkestrel/contract";
+import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /**
 * The primary-key column assumed when {@link TableKeys} does not name one.
@@ -21,6 +23,10 @@ var DEFAULT_PRIMARY = "id";
 * `VALIDATION` {@link DatabaseError}; the cap is generous for any legitimate search.
 */
 var MAX_PATTERN_LENGTH = 1024;
+/** The number of bytes encoded by an RFC 4122 UUID. */
+var UUID_BYTE_COUNT = 16;
+/** The number of distinct values one UUID byte may hold. */
+var UUID_BYTE_RANGE = 256;
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -67,946 +73,6 @@ var DatabaseError = class extends Error {
 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
 /**
@@ -1153,9 +219,16 @@ function globMatch(value, pattern) {
 * @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.
+* operator. Range operators (`above` / `below` / `from` / `to` / `between`) use
+* {@link compareValues}, the total order; the equality family (`equals` / `not`
+* / `any` / `none`) uses {@link deepEqual} — STRUCTURAL equality, not the total
+* order's rank-5-collapses-all-objects behavior, so `equals` on an object/array
+* operand only matches a structurally-equal value, never every row holding any
+* object. This is a semantics change from ranking: `deepEqual` is SameValueZero
+* on leaves, so `NaN` now equals `NaN` under `equals` / `any` (it never matched
+* anything under the old rank-based comparison). `like` / `glob` / `starts` /
+* `ends` match only strings; `absent` / `present` test nullishness. Total — a
+* type mismatch is simply a non-match.
 *
 * @param row - The row to test
 * @param condition - The condition to apply
@@ -1166,8 +239,8 @@ function matchesCondition(row, condition) {
 	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 "equals": return deepEqual(value, first);
+		case "not": return !deepEqual(value, first);
 		case "above": return compareValues(value, first) > 0;
 		case "below": return compareValues(value, first) < 0;
 		case "from": return compareValues(value, first) >= 0;
@@ -1177,8 +250,8 @@ function matchesCondition(row, condition) {
 		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 "any": return condition.values.some((candidate) => deepEqual(value, candidate));
+		case "none": return !condition.values.some((candidate) => deepEqual(value, candidate));
 		case "absent": return value === void 0 || value === null;
 		case "present": return value !== void 0 && value !== null;
 	}
@@ -1363,6 +436,44 @@ function shapeToColumnType(shape) {
 	}
 }
 /**
+* Whether a value is a well-formed {@link DriverMeta} — the boundary guard a
+* versioning driver's `meta()` narrows a stored (structured-clone or
+* `JSON.parse`d) value through before trusting it, replacing the per-driver
+* duplicated narrowing every backend used to hand-roll (AGENTS §14: never `as`).
+*
+* @remarks
+* Total and total-recursive over the whole shape: a finite `version`, and a
+* `schema` array of well-formed {@link TableSchema} entries — each a `name` /
+* `primary` string pair, a `columns` array of well-formed {@link ColumnSchema}
+* entries (a `name` string, a {@link ColumnType} literal, a `nullable`
+* boolean), and an `indexes` array of string arrays. Anything off-shape
+* (including a non-record) returns `false` rather than throwing.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed `DriverMeta`
+*
+* @example
+* ```ts
+* isDriverMeta({ version: 1, schema: [] }) // true
+* isDriverMeta({ version: 1, schema: [{ name: 'users' }] }) // false
+* ```
+*/
+function isDriverMeta(value) {
+	const COLUMN_TYPES = [
+		"text",
+		"integer",
+		"real",
+		"boolean",
+		"json",
+		"blob"
+	];
+	const isColumnType = (candidate) => isString(candidate) && COLUMN_TYPES.some((type) => type === candidate);
+	const isColumnSchema = (candidate) => isRecord(candidate) && isString(candidate.name) && isColumnType(candidate.type) && isBoolean(candidate.nullable);
+	const isIndexGroup = (candidate) => isArray(candidate) && candidate.every((entry) => isString(entry));
+	const isTableSchema = (candidate) => isRecord(candidate) && isString(candidate.name) && isString(candidate.primary) && isArray(candidate.columns) && candidate.columns.every(isColumnSchema) && isArray(candidate.indexes) && candidate.indexes.every(isIndexGroup);
+	return isRecord(value) && isFiniteNumber(value.version) && isArray(value.schema) && value.schema.every(isTableSchema);
+}
+/**
 * Throw when an {@link ReadOptions.signal | AbortSignal} has fired — the shared
 * cancellation gate checked at operation boundaries and between streamed rows.
 *
@@ -1406,11 +517,22 @@ function checkAbort(signal) {
 * plan labels only — version tracking itself is deferred to persistent
 * backends.
 *
+* A column present in BOTH schemas under the same name but with a different
+* `type` or `nullable` throws a `MIGRATION` {@link DatabaseError} naming the
+* table, the column, and the from→to difference — a name-only diff would
+* otherwise silently produce NO step for the drift, and versioned
+* reconciliation would stamp over it. There is no automatic in-place
+* type-change step: the manual path is to add a new column, copy/convert the
+* data at the application layer, then remove the old column — two separate
+* plans, never a single implicit "alter" step.
+*
 * @param deployed - The table schemas currently applied
 * @param declared - The table schemas the caller wants applied
 * @param from - The plan's source version label (defaults to `0`)
 * @param to - The plan's target version label (defaults to `1`)
 * @returns The migration plan moving `deployed` toward `declared`
+* @throws A `MIGRATION` {@link DatabaseError} when a shared column's `type` or
+* `nullable` differs between `deployed` and `declared`
 *
 * @example
 * ```ts
@@ -1443,11 +565,29 @@ function planMigration(deployed, declared, from = 0, to = 1) {
 			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
-		});
+		for (const column of table.columns) {
+			const previous = beforeColumns.get(column.name);
+			if (previous === void 0) {
+				steps.push({
+					operation: "column.add",
+					table: table.name,
+					column
+				});
+				continue;
+			}
+			if (previous.type !== column.type || previous.nullable !== column.nullable) throw new DatabaseError("MIGRATION", `planMigration: column '${column.name}' on table '${table.name}' changed shape (type ${previous.type}→${column.type}, nullable ${previous.nullable}→${column.nullable}) — in-place type/nullability changes are not auto-migrated; add a new column, copy/convert the data, then remove the old column`, {
+				table: table.name,
+				column: column.name,
+				from: {
+					type: previous.type,
+					nullable: previous.nullable
+				},
+				to: {
+					type: column.type,
+					nullable: column.nullable
+				}
+			});
+		}
 		const sameIndex = (left, right) => left.length === right.length && left.every((column, position) => column === right[position]);
 		for (const index of before.indexes) if (!table.indexes.some((candidate) => sameIndex(candidate, index))) steps.push({
 			operation: "index.remove",
@@ -1510,12 +650,14 @@ function migrateRows(rows, steps) {
 * default `id`, `posts` keyed by a non-id `slug`) and, calling `factory()`
 * fresh for each phase so failures stay isolated, verifies: `open`/`close`;
 * `read` of a missing key returns `undefined`; `write`/`read` round-trip with
-* 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
+* DEEP copy-in/copy-out isolation (mutating the caller's row — including a
+* NESTED field — after `write`, or a row `read` returns, never perturbs
+* stored state) and upsert-overwrite; `delete` returns `true` then `false`;
+* `keys`/`scan` yield in ascending key order; `clear` empties only its target
+* table; `snapshot`'s rollback thunk restores pre-snapshot state, including a
+* NESTED field mutated in place on a read-back row between capture and
+* restore; a scoped `snapshot(['users'])` rolls back only the named table,
+* leaving a concurrent mutation to another table intact; a
 * non-`id` primary key (`posts.slug`) round-trips; a nested-object row
 * round-trips structurally (via {@link deepEqual}). The optional surface is
 * presence-gated: when `migrate` exists, a `column.remove` plan strips the
@@ -1568,11 +710,16 @@ async function* driverFindings(factory) {
 				name: "age",
 				type: "integer",
 				nullable: true
+			},
+			{
+				name: "meta",
+				type: "json",
+				nullable: true
 			}
 		],
 		indexes: []
 	};
-	const CONFORMANCE_SCHEMA = [CONFORMANCE_USERS_SCHEMA, {
+	const CONFORMANCE_POSTS_SCHEMA = {
 		name: "posts",
 		primary: "slug",
 		columns: [{
@@ -1585,7 +732,8 @@ async function* driverFindings(factory) {
 			nullable: false
 		}],
 		indexes: []
-	}];
+	};
+	const CONFORMANCE_SCHEMA = [CONFORMANCE_USERS_SCHEMA, CONFORMANCE_POSTS_SCHEMA];
 	const findingOf = (check, message, context) => ({
 		check,
 		message,
@@ -1622,29 +770,33 @@ async function* driverFindings(factory) {
 				const input = {
 					id: "u1",
 					name: "Ada",
-					age: 30
+					age: 30,
+					meta: { tags: ["a"] }
 				};
 				await driver.write("users", "u1", input);
 				input.name = "Mutated after write";
+				if (isRecord(input.meta) && Array.isArray(input.meta.tags)) input.meta.tags.push("mutated");
 				const stored = await driver.read("users", "u1");
 				const original = {
 					id: "u1",
 					name: "Ada",
-					age: 30
+					age: 30,
+					meta: { tags: ["a"] }
 				};
 				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", {
+					return findingOf("copy-in", "write must deep-copy the input row (including nested fields) rather than store it by reference", {
 						table: "users",
 						expected: original,
 						actual: stored
 					});
 				}
 				stored.name = "Mutated after read";
+				if (isRecord(stored.meta) && Array.isArray(stored.meta.tags)) stored.meta.tags.push("mutated");
 				const reread = await driver.read("users", "u1");
 				if (reread === void 0 || !deepEqual(reread, original)) {
 					await driver.close();
-					return findingOf("copy-out", "read must copy the stored row rather than return it by reference", {
+					return findingOf("copy-out", "read must deep-copy the stored row (including nested fields) rather than return it by reference", {
 						table: "users",
 						expected: original,
 						actual: reread
@@ -1807,6 +959,37 @@ async function* driverFindings(factory) {
 				});
 			}
 		},
+		{
+			check: "snapshot-nested",
+			run: async () => {
+				const driver = factory();
+				await driver.open(CONFORMANCE_SCHEMA);
+				const original = {
+					id: "u3",
+					name: "Nested",
+					age: 20,
+					meta: { tags: ["a"] }
+				};
+				await driver.write("users", "u3", original);
+				const rollback = await driver.snapshot();
+				const before = await driver.read("users", "u3");
+				if (isRecord(before) && isRecord(before.meta) && Array.isArray(before.meta.tags)) before.meta.tags.push("mutated-before-restore");
+				await driver.write("users", "u3", {
+					id: "u3",
+					name: "Nested",
+					age: 20,
+					meta: { tags: ["a", "mutated-after-write"] }
+				});
+				await rollback();
+				const restored = await driver.read("users", "u3");
+				await driver.close();
+				if (restored === void 0 || !deepEqual(restored, original)) return findingOf("snapshot-nested", "snapshot rollback must restore pre-snapshot nested field values, unaffected by a later in-place mutation of a read-back row", {
+					table: "users",
+					expected: original,
+					actual: restored
+				});
+			}
+		},
 		{
 			check: "non-id-primary",
 			run: async () => {
@@ -1855,21 +1038,22 @@ async function* driverFindings(factory) {
 			run: async () => {
 				const driver = factory();
 				if (driver.migrate === void 0) return void 0;
-				await driver.open(CONFORMANCE_SCHEMA);
+				const deployedUsers = {
+					...CONFORMANCE_USERS_SCHEMA,
+					columns: [...CONFORMANCE_USERS_SCHEMA.columns, {
+						name: "legacy",
+						type: "boolean",
+						nullable: true
+					}]
+				};
+				await driver.open([deployedUsers, CONFORMANCE_POSTS_SCHEMA]);
 				await driver.write("users", "u1", {
 					id: "u1",
 					name: "Ada",
 					age: 30,
 					legacy: true
 				});
-				const removePlan = planMigration([{
-					...CONFORMANCE_USERS_SCHEMA,
-					columns: [...CONFORMANCE_USERS_SCHEMA.columns, {
-						name: "legacy",
-						type: "boolean",
-						nullable: false
-					}]
-				}], [CONFORMANCE_USERS_SCHEMA]);
+				const removePlan = planMigration([deployedUsers], [CONFORMANCE_USERS_SCHEMA]);
 				await driver.migrate(removePlan);
 				const migrated = await driver.read("users", "u1");
 				if (migrated === void 0 || "legacy" in migrated) {
@@ -2131,173 +1315,40 @@ async function auditDriver(factory) {
 	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.
+* Generate an RFC 4122 version 4 UUID from a number source — no host crypto global.
 *
 * @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)[]`.
+* Draws exactly {@link UUID_BYTE_COUNT} values from `random`, one per byte, then
+* forces the version (`4`) and variant (`10xx`) bits. The default source is
+* `Math.random` — a pure-ECMAScript intrinsic, so generation works on every host;
+* pass a seeded source (`seededRandom` from `@orkestrel/contract`) and reuse it
+* across calls for reproducible sequences in tests and fixtures — production
+* identifiers should keep the default source, whose engine entropy is far larger
+* than a 32-bit seed. Each byte is floored and masked, so a source straying
+* outside `[0, 1)` (negative, `>= 1`, `NaN`, `Infinity`) can never yield a
+* malformed UUID. Suitable as a collision-resistant record identifier — not a
+* cryptographic token; never use one as a secret.
+*
+* @param random - A number source returning values in the half-open range `[0, 1)` (defaults to `Math.random`)
+* @returns A lowercase RFC 4122 version 4 UUID
 *
 * @example
 * ```ts
-* import { extractKeys } from '@src/core'
+* import { generateUUID } from '@orkestrel/database'
+* import { seededRandom } from '@orkestrel/contract'
 *
-* const hooks = { tick: () => {}, done: () => {} }
-* extractKeys(hooks) // ['tick', 'done']
-* extractKeys({}) // []
+* generateUUID() // e.g. '9b2f7c1e-3d4a-4f6b-8e2d-5a1c0b9f8e7d'
+* generateUUID(seededRandom(42)) // the same UUID on every run
 * ```
 */
-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";
+function generateUUID(random = Math.random) {
+	const bytes = Array.from({ length: 16 }, () => Math.floor(random() * 256) & 255);
+	bytes[6] = bytes[6] & 15 | 64;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = bytes.map((byte) => byte.toString(16).padStart(2, "0"));
+	return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
 }
-/**
-* 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
 /**
@@ -2669,6 +1720,21 @@ var Table = class {
 		for (const row of source) if (this.#guard(row)) rows.push(row);
 		return rows;
 	}
+	/**
+	* Count rows matching `criteria`'s conditions.
+	*
+	* @remarks
+	* Unlike {@link records}, which narrows every row through the table's
+	* contract guard before returning it, `count` operates on STORED rows
+	* WITHOUT that guard (both the native `driver.count` hook and the
+	* `filterRows`-over-`#collect()` fallback count raw storage) — so it can
+	* exceed `(await records(criteria)).length` when storage holds rows that
+	* no longer conform to the table's contract (legacy or migrated data).
+	*
+	* @param criteria - Optional conditions to filter by (paging is ignored)
+	* @param options - `{ signal }` to abort
+	* @returns The count of matching stored rows
+	*/
 	async count(criteria, options) {
 		checkAbort(options?.signal);
 		await this.#ready();
@@ -2677,6 +1743,23 @@ var Table = class {
 		if (native !== void 0) return native;
 		return filterRows(await this.#collect(), criteria?.conditions ?? []).length;
 	}
+	/**
+	* Compute an aggregate over `column` across rows matching `criteria`'s
+	* conditions.
+	*
+	* @remarks
+	* Like {@link count}, `aggregate` operates on STORED rows WITHOUT the
+	* contract guard {@link records} / {@link scan} apply — a non-conforming
+	* stored row still contributes to the computed aggregate when it matches
+	* the conditions, even though it would never appear in `records()`'s
+	* output.
+	*
+	* @param operation - The aggregate to compute
+	* @param column - The column to aggregate
+	* @param criteria - Optional conditions to filter by (paging is ignored)
+	* @param options - `{ signal }` to abort
+	* @returns The aggregate value, or `undefined` when undefined for the inputs
+	*/
 	async aggregate(operation, column, criteria, options) {
 		checkAbort(options?.signal);
 		await this.#ready();
@@ -2699,7 +1782,7 @@ var Table = class {
 	*
 	* @param criteria - Optional conditions plus offset/limit paging
 	* @param options - `{ signal }` to abort mid-stream
-	* @returns An async generator of matching, guard-conforming rows
+	* @returns An async iterable of matching, guard-conforming rows
 	*/
 	async *scan(criteria, options) {
 		checkAbort(options?.signal);
@@ -3118,8 +2201,12 @@ var Database = class Database {
 * @remarks
 * The in-between made concrete: it runs identically in a browser or on a server,
 * so it is the storage behind tests, ephemeral caches, and any code that wants
-* the database API without a persistent backend. Rows are copied in and out so a
-* caller can never mutate stored state by reference (AGENTS §11), and `snapshot`
+* the database API without a persistent backend. Rows are DEEP-copied (via
+* `structuredClone`) in and out — at `write`, `read`, `scan`, `stream`, and both
+* snapshot capture and restore — so a caller mutating a nested field of an input
+* row, a returned row, or a row mutated in place between snapshot and rollback
+* can never perturb stored state (AGENTS §11); a shallow `{ ...row }` spread
+* would still share nested object/array references. `snapshot`
 * clones every table to give transactions an exact rollback point. `scan` and
 * `keys` yield in key order — sorted by the core {@link compareValues} total
 * order, the same contract the SQLite (`ORDER BY`) and IndexedDB (key-ordered
@@ -3136,10 +2223,10 @@ var MemoryDriver = class {
 	async close() {}
 	async read(table, key) {
 		const row = this.#store(table).get(key);
-		return row === void 0 ? void 0 : { ...row };
+		return row === void 0 ? void 0 : structuredClone(row);
 	}
 	async write(table, key, row) {
-		this.#store(table).set(key, { ...row });
+		this.#store(table).set(key, structuredClone(row));
 	}
 	async delete(table, key) {
 		return this.#store(table).delete(key);
@@ -3151,7 +2238,7 @@ var MemoryDriver = class {
 		const store = this.#store(table);
 		for (const key of this.#ordered(table)) {
 			const row = store.get(key);
-			if (row !== void 0) yield { ...row };
+			if (row !== void 0) yield structuredClone(row);
 		}
 	}
 	/**
@@ -3195,7 +2282,7 @@ var MemoryDriver = class {
 				skipped += 1;
 				continue;
 			}
-			yield { ...row };
+			yield structuredClone(row);
 			yielded += 1;
 		}
 	}
@@ -3219,12 +2306,16 @@ var MemoryDriver = class {
 			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 });
+				for (const [key, row] of store) cloned.set(key, structuredClone(row));
 				copy.set(name, cloned);
 			}
 			return async () => {
 				this.#tables.clear();
-				for (const [name, store] of copy) this.#tables.set(name, store);
+				for (const [name, store] of copy) {
+					const restored = /* @__PURE__ */ new Map();
+					for (const [key, row] of store) restored.set(key, structuredClone(row));
+					this.#tables.set(name, restored);
+				}
 			};
 		}
 		const copy = /* @__PURE__ */ new Map();
@@ -3232,11 +2323,15 @@ var MemoryDriver = class {
 			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 });
+			for (const [key, row] of store) cloned.set(key, structuredClone(row));
 			copy.set(name, cloned);
 		}
 		return async () => {
-			for (const [name, store] of copy) this.#tables.set(name, store);
+			for (const [name, store] of copy) {
+				const restored = /* @__PURE__ */ new Map();
+				for (const [key, row] of store) restored.set(key, structuredClone(row));
+				this.#tables.set(name, restored);
+			}
 		};
 	}
 	/**
@@ -3359,6 +2454,6 @@ 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 };
+export { Clause, Cursor, DEFAULT_PRIMARY, Database, DatabaseError, MAX_PATTERN_LENGTH, MemoryDriver, Query, Table, UUID_BYTE_COUNT, UUID_BYTE_RANGE, applyCriteria, auditDriver, checkAbort, compareValues, computeAggregate, conformDriver, createDatabase, createMemoryDriver, deepEqual, driverFindings, extractKey, filterRows, generateUUID, globMatch, isDatabaseError, isDriverMeta, likeMatch, matchesCondition, matchesCriteria, migrateRows, planMigration, shapeToColumnType, sortRows, wildcardMatch };
 
 //# sourceMappingURL=index.js.map