@orkestrel/contract 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,2026 @@
+//#region src/core/constants.ts
+/**
+* The seven standard JSON Schema `type` names, frozen.
+*
+* @remarks
+* The runtime source of truth for the {@link JSONSchemaType} vocabulary. Compose
+* it with the shipped primitives instead of reaching for a bespoke guard:
+* `literalOf(...JSON_SCHEMA_TYPES)` is the guard, and
+* `parseEnum(value, JSON_SCHEMA_TYPES)` / `parseEnumField(record, path, JSON_SCHEMA_TYPES)`
+* is the parser.
+*
+* @example
+* ```ts
+* import { JSON_SCHEMA_TYPES, literalOf, parseEnumField } from '@src/core'
+*
+* const isSchemaType = literalOf(...JSON_SCHEMA_TYPES) // Guard<JSONSchemaType>
+* parseEnumField(schema, 'type', JSON_SCHEMA_TYPES)    // JSONSchemaType | undefined
+* ```
+*/
+var JSON_SCHEMA_TYPES = Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+//#endregion
+//#region src/core/validators.ts
+/** 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 defined (neither `null` nor `undefined`). */
+function isDefined(value) {
+	return value !== null && value !== void 0;
+}
+/** Determine whether a value is a string. */
+function isString(value) {
+	return typeof value === "string";
+}
+/**
+* Determine whether a value is a number.
+*
+* @remarks
+* Includes `NaN` and `±Infinity` — use {@link isFiniteNumber} to exclude them.
+*/
+function isNumber(value) {
+	return typeof value === "number";
+}
+/** 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 exactly `true`. */
+function isTrue(value) {
+	return value === true;
+}
+/** Determine whether a value is exactly `false`. */
+function isFalse(value) {
+	return value === false;
+}
+/** Determine whether a value is a bigint. */
+function isBigInt(value) {
+	return typeof value === "bigint";
+}
+/** Determine whether a value is a symbol. */
+function isSymbol(value) {
+	return typeof value === "symbol";
+}
+/** Determine whether a value is callable. */
+function isFunction(value) {
+	return typeof value === "function";
+}
+/** Determine whether a value is a string or `null`. */
+function isNullableString(value) {
+	return value === null || isString(value);
+}
+/** Determine whether a value is a number or `null` (the number may be `NaN` / `±Infinity`). */
+function isNullableNumber(value) {
+	return value === null || isNumber(value);
+}
+/** Determine whether a value is a boolean or `null`. */
+function isNullableBoolean(value) {
+	return value === null || isBoolean(value);
+}
+/** Determine whether a value is a `Date`. */
+function isDate(value) {
+	return value instanceof Date;
+}
+/** Determine whether a value is a `RegExp`. */
+function isRegExp(value) {
+	return value instanceof RegExp;
+}
+/** Determine whether a value is an `Error`. */
+function isError(value) {
+	return value instanceof Error;
+}
+/** Determine whether a value is a native `Promise` (use {@link isPromiseLike} for any thenable). */
+function isPromise(value) {
+	return value instanceof Promise;
+}
+/**
+* Determine whether a value is promise-like — an object exposing callable
+* `then`, `catch`, and `finally` methods.
+*
+* @remarks
+* Accepts any object with all three methods, not only native `Promise`
+* instances. Use {@link isPromise} when you specifically need `instanceof Promise`.
+*/
+function isPromiseLike(value) {
+	if (!isObject(value)) return false;
+	const outcome = attempt(() => {
+		const thenValue = Reflect.get(value, "then");
+		const catchValue = Reflect.get(value, "catch");
+		const finallyValue = Reflect.get(value, "finally");
+		return isFunction(thenValue) && isFunction(catchValue) && isFunction(finallyValue);
+	});
+	return outcome.success && outcome.value;
+}
+/** Determine whether a value is an `ArrayBuffer`. */
+function isArrayBuffer(value) {
+	return value instanceof ArrayBuffer;
+}
+/**
+* Determine whether a value is a `SharedArrayBuffer`.
+*
+* @remarks
+* Guards the global existence of `SharedArrayBuffer` first — safe where it is
+* absent or disabled (e.g. a context that is not cross-origin isolated).
+*/
+function isSharedArrayBuffer(value) {
+	return typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
+}
+/**
+* Determine whether a value implements the iterable protocol (`Symbol.iterator`).
+*
+* @remarks
+* Strings are explicitly included: a string has a callable `Symbol.iterator`
+* but is not an object, so the generic object path alone would miss it.
+*/
+function isIterable(value) {
+	if (isString(value)) return true;
+	if (!isObject(value)) return false;
+	const outcome = attempt(() => isFunction(Reflect.get(value, Symbol.iterator)));
+	return outcome.success && outcome.value;
+}
+/** Determine whether a value implements the async iterable protocol (`Symbol.asyncIterator`). */
+function isAsyncIterable(value) {
+	if (!isObject(value)) return false;
+	const outcome = attempt(() => isFunction(Reflect.get(value, Symbol.asyncIterator)));
+	return outcome.success && outcome.value;
+}
+/**
+* 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 a `Map`. */
+function isMap(value) {
+	return value instanceof Map;
+}
+/** Determine whether a value is a `Set`. */
+function isSet(value) {
+	return value instanceof Set;
+}
+/** Determine whether a value is a `WeakMap`. */
+function isWeakMap(value) {
+	return value instanceof WeakMap;
+}
+/** Determine whether a value is a `WeakSet`. */
+function isWeakSet(value) {
+	return value instanceof WeakSet;
+}
+/** Determine whether a value is an array. */
+function isArray(value) {
+	return Array.isArray(value);
+}
+/** Determine whether a value is a `DataView`. */
+function isDataView(value) {
+	return value instanceof DataView;
+}
+/** Determine whether a value is an `ArrayBufferView` (any typed array or `DataView`). */
+function isArrayBufferView(value) {
+	return ArrayBuffer.isView(value);
+}
+/** Determine whether a value is an `Int8Array`. */
+function isInt8Array(value) {
+	return value instanceof Int8Array;
+}
+/** Determine whether a value is a `Uint8Array`. */
+function isUint8Array(value) {
+	return value instanceof Uint8Array;
+}
+/** Determine whether a value is a `Uint8ClampedArray`. */
+function isUint8ClampedArray(value) {
+	return value instanceof Uint8ClampedArray;
+}
+/** Determine whether a value is an `Int16Array`. */
+function isInt16Array(value) {
+	return value instanceof Int16Array;
+}
+/** Determine whether a value is a `Uint16Array`. */
+function isUint16Array(value) {
+	return value instanceof Uint16Array;
+}
+/** Determine whether a value is an `Int32Array`. */
+function isInt32Array(value) {
+	return value instanceof Int32Array;
+}
+/** Determine whether a value is a `Uint32Array`. */
+function isUint32Array(value) {
+	return value instanceof Uint32Array;
+}
+/** Determine whether a value is a `Float32Array`. */
+function isFloat32Array(value) {
+	return value instanceof Float32Array;
+}
+/** Determine whether a value is a `Float64Array`. */
+function isFloat64Array(value) {
+	return value instanceof Float64Array;
+}
+/**
+* Determine whether a value is a `BigInt64Array`.
+*
+* @remarks
+* Guards the global existence of `BigInt64Array` first — safe in environments
+* that pre-date the BigInt typed-array additions.
+*/
+function isBigInt64Array(value) {
+	return typeof BigInt64Array !== "undefined" && value instanceof BigInt64Array;
+}
+/**
+* Determine whether a value is a `BigUint64Array`.
+*
+* @remarks
+* Guards the global existence of `BigUint64Array` first — safe in environments
+* that pre-date the BigInt typed-array additions.
+*/
+function isBigUint64Array(value) {
+	return typeof BigUint64Array !== "undefined" && value instanceof BigUint64Array;
+}
+/** Determine whether a value is the empty string `''`. */
+function isEmptyString(value) {
+	return isString(value) && value.length === 0;
+}
+/** Determine whether a value is an empty array. */
+function isEmptyArray(value) {
+	return isArray(value) && value.length === 0;
+}
+/** Determine whether a value is an empty plain object (no own string or enumerable symbol keys). */
+function isEmptyObject(value) {
+	if (!isRecord(value)) return false;
+	return Object.keys(value).length === 0 && enumerableSymbolCount(value) === 0;
+}
+/** Determine whether a value is an empty `Map`. */
+function isEmptyMap(value) {
+	return value instanceof Map && value.size === 0;
+}
+/** Determine whether a value is an empty `Set`. */
+function isEmptySet(value) {
+	return value instanceof Set && value.size === 0;
+}
+/** Determine whether a value is a non-empty string (at least one character). */
+function isNonEmptyString(value) {
+	return isString(value) && value.length > 0;
+}
+/** Determine whether a value is a non-empty array (at least one element). */
+function isNonEmptyArray(value) {
+	return isArray(value) && value.length > 0;
+}
+/** Determine whether a value is a non-empty plain object (at least one own string or enumerable symbol key). */
+function isNonEmptyObject(value) {
+	if (!isRecord(value)) return false;
+	return Object.keys(value).length > 0 || enumerableSymbolCount(value) > 0;
+}
+/** Determine whether a value is a non-empty `Map` (at least one entry). */
+function isNonEmptyMap(value) {
+	return value instanceof Map && value.size > 0;
+}
+/** Determine whether a value is a non-empty `Set` (at least one element). */
+function isNonEmptySet(value) {
+	return value instanceof Set && value.size > 0;
+}
+/** Determine whether a value is a function that declares zero parameters (`Function.length === 0`). */
+function isZeroArg(value) {
+	return isFunction(value) && value.length === 0;
+}
+/**
+* Determine whether a value is a native `async function`.
+*
+* @remarks
+* Uses `constructor.name === 'AsyncFunction'` — not `instanceof`, which is
+* unreliable across realms. The `?.` keeps the guard total (§14): a function
+* whose `constructor` was nulled yields `undefined`, never a thrown `null.name`.
+*/
+function isAsyncFunction(value) {
+	return isFunction(value) && value.constructor?.name === "AsyncFunction";
+}
+/** Determine whether a value is a generator function (`function*`). */
+function isGeneratorFunction(value) {
+	return isFunction(value) && value.constructor?.name === "GeneratorFunction";
+}
+/** Determine whether a value is an async generator function (`async function*`). */
+function isAsyncGeneratorFunction(value) {
+	return isFunction(value) && value.constructor?.name === "AsyncGeneratorFunction";
+}
+/** Determine whether a value is a zero-argument async function. */
+function isZeroArgAsync(value) {
+	return isZeroArg(value) && isAsyncFunction(value);
+}
+/** Determine whether a value is a zero-argument generator function. */
+function isZeroArgGenerator(value) {
+	return isZeroArg(value) && isGeneratorFunction(value);
+}
+/** Determine whether a value is a zero-argument async generator function. */
+function isZeroArgAsyncGenerator(value) {
+	return isZeroArg(value) && isAsyncGeneratorFunction(value);
+}
+/**
+* Determine whether a value can be used as a `new`-target constructor.
+*
+* @remarks
+* Probes with `Reflect.construct(String, [], value)`: a real constructor
+* succeeds, while arrow functions, plain functions, and non-functions throw
+* and yield `false`. Never throws. Backs the `instanceOf` combinator.
+*/
+function isConstructor(value) {
+	if (!isFunction(value)) return false;
+	try {
+		Reflect.construct(String, [], value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* 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;
+}
+/**
+* Determine whether a value is a primitive JSON value.
+*
+* @remarks
+* The flat leaf of any JSON document: `null`, a string, a **finite** number, or
+* a boolean. Uses {@link isFiniteNumber} (not {@link isNumber}) because real JSON
+* carries no `NaN` / `±Infinity` — `JSON.stringify(NaN)` is `'null'`.
+*
+* The recursive {@link isJSONValue} guard is shipped and stays total with
+* cycle-safe walking. Dedicated `isJSONObject` / `isJSONSchema` validators and
+* the broad `JSONSchemaDefinition` remain omitted; compose narrower shapes with
+* the combinators and gate untrusted strings with `parseJSON` / `parseJSONAs`.
+*
+* @param value - The value to test
+* @returns `true` when `value` is `null`, a string, a finite number, or a boolean
+*
+* @example
+* ```ts
+* isJSONPrimitive(null)        // true
+* isJSONPrimitive('hi')        // true
+* isJSONPrimitive(42)          // true
+* isJSONPrimitive(Number.NaN)  // false — not representable in JSON
+* isJSONPrimitive({})          // false
+* ```
+*/
+function isJSONPrimitive(value) {
+	return isNull(value) || isString(value) || isFiniteNumber(value) || isBoolean(value);
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* 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;
+	};
+}
+/**
+* Count the enumerable own-symbol keys on a value.
+*
+* @remarks
+* String keys are ignored — only `Object.getOwnPropertySymbols` entries whose
+* descriptor is `enumerable` are counted. Backs the object-emptiness guards
+* (`isEmptyObject` / `isNonEmptyObject`) so a record keyed only by an
+* enumerable symbol is not mistaken for empty.
+*
+* @param value - The object to inspect
+* @returns The number of enumerable own-symbol keys
+*
+* @example
+* ```ts
+* const flag = Symbol('flag')
+* enumerableSymbolCount(Object.defineProperty({}, flag, { value: 1, enumerable: true })) // 1
+* enumerableSymbolCount({}) // 0
+* ```
+*/
+function enumerableSymbolCount(value) {
+	let count = 0;
+	for (const symbol of Object.getOwnPropertySymbols(value)) if (Object.getOwnPropertyDescriptor(value, symbol)?.enumerable) count += 1;
+	return count;
+}
+/**
+* Narrow a compiled {@link JSONSchema} down to the open `Readonly<Record<string, unknown>>` shape
+* tool definitions advertise as `parameters` — through the {@link isRecord} boundary guard, never
+* an assertion (AGENTS §14).
+*
+* @remarks
+* A `JSONSchema` is the closed contract-compiler fragment (it has no index signature), whereas a
+* tool advertises its `parameters` as an open record. The two are structurally compatible but not
+* assignable, so the schema crosses that boundary through `isRecord` — a compiled contract schema
+* is always a record, so the guard passes; the `undefined` fallback only satisfies the type's
+* optionality. This is the single sanctioned narrowing from a compiled contract schema to the open
+* tool-parameters record, so the crossing lives once rather than being copy-pasted per call site.
+*
+* @param schema - The compiled JSON Schema (a contract's `schema`)
+* @returns The schema as the open tool-parameters record, or `undefined` when it is not a record
+*
+* @example
+* ```ts
+* import { createContract, schemaToParameters } from '@src/core'
+*
+* const contract = createContract(shape)
+* const parameters = schemaToParameters(contract.schema) // the open record a tool advertises
+* ```
+*/
+function schemaToParameters(schema) {
+	return isRecord(schema) ? schema : void 0;
+}
+//#endregion
+//#region src/core/combinators.ts
+function arrayOf(elementGuard) {
+	return (value) => {
+		if (!isArray(value)) return false;
+		const outcome = attempt(() => value.every(elementGuard));
+		return outcome.success && outcome.value;
+	};
+}
+function tupleOf(...guards) {
+	return (value) => {
+		if (!isArray(value)) return false;
+		const outcome = attempt(() => {
+			if (value.length !== guards.length) return false;
+			for (let index = 0; index < guards.length; index += 1) {
+				const guard = guards[index];
+				if (!guard?.(value[index])) return false;
+			}
+			return true;
+		});
+		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 instances of the provided constructor.
+*
+* @remarks
+* Verifies that `ctor` is a real constructor (via {@link isConstructor}) first,
+* so passing an arrow function does not silently produce a broken guard.
+*
+* @example
+* ```ts
+* const isDateValue = instanceOf(Date)
+* isDateValue(new Date()) // true
+* isDateValue({})         // false
+* ```
+*/
+function instanceOf(ctor) {
+	return (value) => isConstructor(ctor) && isObject(value) && value instanceof ctor;
+}
+/**
+* Build a guard from a native `enum` or any object whose values are strings or
+* numbers.
+*
+* @example
+* ```ts
+* enum Direction { Up = 'up', Down = 'down' }
+* const isDirection = enumOf(Direction)
+* isDirection('up')   // true
+* isDirection('left') // false
+* ```
+*/
+function enumOf(enumeration) {
+	const values = new Set(Object.values(enumeration));
+	return (value) => (isString(value) || isNumber(value)) && values.has(value);
+}
+function setOf(elementGuard) {
+	return (value) => {
+		if (!isSet(value)) return false;
+		const outcome = attempt(() => {
+			for (const entry of value) if (!elementGuard(entry)) return false;
+			return true;
+		});
+		return outcome.success && outcome.value;
+	};
+}
+function mapOf(keyGuard, valueGuard) {
+	return (value) => {
+		if (!isMap(value)) return false;
+		const outcome = attempt(() => {
+			for (const [key, entryValue] of value) if (!keyGuard(key) || !valueGuard(entryValue)) return false;
+			return true;
+		});
+		return outcome.success && outcome.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 iterableOf(elementGuard) {
+	return (value) => {
+		if (!isIterable(value)) return false;
+		const outcome = attempt(() => {
+			for (const entry of value) if (!elementGuard(entry)) return false;
+			return true;
+		});
+		return outcome.success && outcome.value;
+	};
+}
+/**
+* Build a guard that accepts values that are own keys of the provided object.
+*
+* @remarks
+* Membership is tested with `Object.hasOwn`, so inherited prototype-chain keys
+* (`toString`, `constructor`, …) are rejected. An own property that shadows a
+* prototype name is accepted.
+*
+* @example
+* ```ts
+* const COLORS = { red: '#f00', green: '#0f0', blue: '#00f' } as const
+* const isColorKey = keyOf(COLORS)
+* isColorKey('red')      // true
+* isColorKey('purple')   // false
+* isColorKey('toString') // false — inherited, not an own key
+* ```
+*/
+function keyOf(value) {
+	return (entry) => (isString(entry) || isSymbol(entry) || isNumber(entry)) && Object.hasOwn(value, entry);
+}
+/**
+* Build a new guard shape by keeping only the listed keys — the structural
+* equivalent of `Pick<T, K>`. Produces a shape for {@link recordOf}, not a guard.
+*
+* @example
+* ```ts
+* const full = { name: isString, age: isNumber, role: isString }
+* const isName = recordOf(pickOf(full, ['name']))
+* isName({ name: 'Ada' }) // true
+* ```
+*/
+function pickOf(shape, keys) {
+	const result = Object.create(null);
+	for (const key of keys) if (Object.prototype.hasOwnProperty.call(shape, key)) result[key] = shape[key];
+	return result;
+}
+/**
+* Build a new guard shape by removing the listed keys — the structural
+* equivalent of `Omit<T, K>`. Produces a shape for {@link recordOf}, not a guard.
+*
+* @example
+* ```ts
+* const full = { name: isString, age: isNumber, role: isString }
+* const isPublic = recordOf(omitOf(full, ['role']))
+* isPublic({ name: 'Ada', age: 36 }) // true
+* ```
+*/
+function omitOf(shape, keys) {
+	const skipped = /* @__PURE__ */ new Set();
+	for (const key of keys) skipped.add(key);
+	const result = Object.create(null);
+	for (const key in shape) {
+		if (!Object.prototype.hasOwnProperty.call(shape, key)) continue;
+		if (!skipped.has(key)) result[key] = shape[key];
+	}
+	return result;
+}
+function andOf(left, right) {
+	return (value) => left(value) && right(value);
+}
+function orOf(left, right) {
+	return (value) => left(value) || right(value);
+}
+/**
+* Negate a guard or predicate — passes when `guard` returns `false`.
+*
+* @remarks
+* Typed as `Guard<unknown>` because `Exclude<unknown, T>` is not useful; use
+* {@link complementOf} when you need the narrowed `Exclude<TBase, TExcluded>`.
+*
+* @example
+* ```ts
+* const isNotNull = notOf(isNull)
+* ```
+*/
+function notOf(guard) {
+	return (value) => !guard(value);
+}
+/**
+* Build a guard for `Exclude<TBase, TExcluded>` — accepts values that pass
+* `base` but not `excluded`.
+*
+* @example
+* ```ts
+* const isNonEmpty = complementOf(isString, isEmptyString)
+* isNonEmpty('hi') // true
+* isNonEmpty('')   // false
+* ```
+*/
+function complementOf(base, excluded) {
+	return (value) => {
+		if (!base(value)) return false;
+		return !excluded(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;
+	};
+}
+/**
+* Defer guard creation until first use by calling `thunk()` on every
+* invocation.
+*
+* @remarks
+* `thunk` is called on every guard call, not cached — this lets it close over a
+* binding assigned *after* `lazyOf` is called, the primary use case for
+* self-referential recursive guards. Per §14 a throw from `thunk` (or the guard
+* it resolves to) is contained and reported as a non-match.
+*
+* A recursive guard built this way has no cycle/depth detection: a cyclic or
+* pathologically deep input is stack-bounded — the overflow is contained and the
+* guard returns `false` rather than throwing, but it is not validated correctly
+* past that bound.
+*
+* @example
+* ```ts
+* type Tree = { value: number; children: Tree[] }
+* let isTree: Guard<Tree>
+* isTree = recordOf({ value: isNumber, children: arrayOf(lazyOf(() => isTree)) })
+* ```
+*/
+function lazyOf(thunk) {
+	return (value) => {
+		const outcome = attempt(() => thunk()(value));
+		return outcome.success && outcome.value;
+	};
+}
+function transformOf(base, project, target) {
+	return (value) => {
+		if (!base(value)) return false;
+		const outcome = attempt(() => project(value));
+		return outcome.success && target(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 matching a regular expression.
+*
+* @example
+* ```ts
+* const isHex = matchOf(/^[0-9a-f]+$/)
+* isHex('1a2f') // true
+* isHex('xyz')  // false
+* ```
+*/
+function matchOf(pattern) {
+	return whereOf(isString, (value) => pattern.test(value));
+}
+/**
+* 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);
+}
+/**
+* Extend a guard to also allow `undefined` — the optional counterpart of
+* {@link nullableOf}.
+*
+* @example
+* ```ts
+* const isOptionalString = optionalOf(isString)
+* isOptionalString('hi')        // true
+* isOptionalString(undefined)   // true
+* isOptionalString(null)        // false
+* ```
+*/
+function optionalOf(guard) {
+	return (value) => value === void 0 || guard(value);
+}
+//#endregion
+//#region src/core/parsers.ts
+/**
+* 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 `null`.
+*
+* @remarks
+* A successful parse returns `null` itself — distinct from the `undefined`
+* failure sentinel every other parser in this file uses. Only `null` passes;
+* every other value (including `undefined`) → `undefined`.
+*
+* @param value - The value to parse
+* @returns `null` on a successful parse, or `undefined`
+*/
+function parseNull(value) {
+	return isNull(value) ? value : void 0;
+}
+/**
+* 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;
+}
+/**
+* Parse an unknown value to an array — the input reference, never cloned —
+* optionally guarding every element.
+*
+* @remarks
+* Without a `guard`, element types are NOT verified; let `T` default to
+* `unknown` rather than asserting a specific element type.
+*
+* @param value - The value to parse
+* @param guard - Optional element guard
+* @returns The array, or `undefined`
+*/
+function parseArray(value, guard) {
+	if (!isArray(value)) return void 0;
+	if (guard !== void 0 && !value.every(guard)) return void 0;
+	return value;
+}
+/**
+* Parse an unknown value to a cycle-safe JSON value — the input reference,
+* never cloned.
+*
+* @remarks
+* Unlike {@link parseRecord} / {@link parseArray}, this is a DEEP gate: it
+* walks the entire tree via {@link isJSONValue} rather than checking only the
+* top-level shape. That walk is cycle-safe and total (never throws) because
+* `isJSONValue` runs its own probe inside a guard, so an adversarial
+* structure (a cycle, a hostile getter) yields `undefined` instead of hanging
+* or throwing.
+*
+* @param value - The value to parse
+* @returns The value, or `undefined` when it is not a valid JSON value
+*/
+function parseJSONValue(value) {
+	return isJSONValue(value) ? value : void 0;
+}
+/**
+* Parse an unknown value as one of the allowed literal primitives.
+*
+* @remarks
+* Pairs with {@link literalOf} — both match by `Object.is`, so the
+* `parseEnum ↔ literalOf(...allowed)` pairing covers every literal primitive
+* (string, number, or boolean), not only strings. Matching is identity, never
+* cross-type coercion: `parseEnum('1', [1])` stays `undefined`.
+*
+* @param value - The value to parse
+* @param allowed - The permitted literal values
+* @returns The matched literal (by identity), or `undefined`
+*/
+function parseEnum(value, allowed) {
+	for (const option of allowed) if (Object.is(value, option)) return option;
+}
+/**
+* Read and parse a string field from a record by key or nested key path.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @returns A string, or `undefined`
+*/
+function parseStringField(record, path) {
+	return parseString(resolveField(record, path));
+}
+/**
+* Read and parse a finite-number field from a record by key or nested key path.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @returns A finite number, or `undefined`
+*/
+function parseNumberField(record, path) {
+	return parseNumber(resolveField(record, path));
+}
+/**
+* Read and parse a finite-integer field from a record by key or nested key path.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @returns A finite integer, or `undefined`
+*/
+function parseIntegerField(record, path) {
+	return parseInteger(resolveField(record, path));
+}
+/**
+* Read and parse a boolean field from a record by key or nested key path.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @returns A boolean, or `undefined`
+*/
+function parseBooleanField(record, path) {
+	return parseBoolean(resolveField(record, path));
+}
+/**
+* Read and parse a `null` field from a record by key or nested key path.
+*
+* @remarks
+* A successful parse returns `null` itself — distinct from the `undefined`
+* failure sentinel, which also covers a missing field.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @returns `null` on a successful parse, or `undefined`
+*/
+function parseNullField(record, path) {
+	return parseNull(resolveField(record, path));
+}
+/**
+* Read and parse a nested record field from a record by key or nested key path.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @returns A plain record, or `undefined`
+*/
+function parseRecordField(record, path) {
+	return parseRecord(resolveField(record, path));
+}
+/**
+* Read and parse an array field from a record by key or nested key path,
+* optionally guarding elements.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @param guard - Optional element guard
+* @returns An array, or `undefined`
+*/
+function parseArrayField(record, path, guard) {
+	return parseArray(resolveField(record, path), guard);
+}
+/**
+* Read and parse an enum field from a record by key or nested key path.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @param allowed - The permitted literal values
+* @returns The matched literal, or `undefined`
+*/
+function parseEnumField(record, path, allowed) {
+	return parseEnum(resolveField(record, path), allowed);
+}
+/**
+* Read and parse a JSON-value field from a record by key or nested key path.
+*
+* @remarks
+* Deep-gates the field's whole subtree via {@link parseJSONValue} — see that
+* function's remarks for why this differs from the shallow
+* {@link parseRecordField} / {@link parseArrayField}.
+*
+* @param record - The source record
+* @param path - A property key, or a key path descending into nested objects
+* @returns The value, or `undefined`
+*/
+function parseJSONValueField(record, path) {
+	return parseJSONValue(resolveField(record, path));
+}
+/**
+* Parse a JSON string, returning `undefined` instead of throwing.
+*
+* @remarks
+* The safe boundary for untrusted JSON text: a malformed string yields
+* `undefined`, never an exception. Returns `unknown` — a successful parse proves
+* nothing about shape, so narrow the result with a guard (or use
+* {@link parseJSONAs}). A large document is not walked here; parsing is shallow
+* and lazy validation is the caller's to compose.
+*
+* @param value - The JSON string to parse
+* @returns The parsed value, or `undefined` when `value` is not valid JSON
+*/
+function parseJSON(value) {
+	try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+}
+/**
+* Parse a JSON string and validate the result against a guard.
+*
+* @remarks
+* The lazy, safe path from an untrusted string to a typed `T`: parse, then check
+* the parsed value with the guard you bring — typically one composed from the
+* combinators (`recordOf`, `arrayOf`, …). Only the shape the guard inspects is
+* validated, so a large document is never walked in full unless the guard does.
+*
+* @param value - The JSON string to parse
+* @param guard - The guard for the expected shape
+* @returns The parsed value when it satisfies `guard`, otherwise `undefined`
+*
+* @example
+* ```ts
+* const isConfig = recordOf({ host: isString, tags: arrayOf(isString) })
+* parseJSONAs('{"host":"localhost","tags":["a"]}', isConfig) // { host: 'localhost', tags: ['a'] }
+* parseJSONAs('{"host":"localhost"}', isConfig)              // undefined — guard fails
+* parseJSONAs('not json', isConfig)                          // undefined — never throws
+* ```
+*/
+function parseJSONAs(value, guard) {
+	const parsed = parseJSON(value);
+	if (parsed === void 0) return void 0;
+	return guard(parsed) ? parsed : void 0;
+}
+//#endregion
+//#region src/core/compilers.ts
+/**
+* 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);
+		}
+	};
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* Build a string {@link StringShape}.
+*
+* @param options - Optional length (`min` / `max`), `pattern`, and `description`
+* @returns A string shape
+*
+* @example
+* ```ts
+* const name = stringShape({ min: 1, max: 80, description: 'Display name' })
+* ```
+*/
+function stringShape(options) {
+	return {
+		type: "string",
+		min: options?.min,
+		max: options?.max,
+		pattern: options?.pattern,
+		description: options?.description
+	};
+}
+/**
+* Build a numeric {@link NumberShape}.
+*
+* @param options - Optional bounds (`min` / `max`), `integer`, and `description`
+* @returns A number shape
+*/
+function numberShape(options) {
+	return {
+		type: "number",
+		min: options?.min,
+		max: options?.max,
+		integer: options?.integer,
+		description: options?.description
+	};
+}
+/**
+* Build an integer {@link NumberShape} — forces `integer: true`.
+*
+* @remarks
+* The emitted JSON Schema uses `"type": "integer"` and the guard rejects
+* fractional numbers.
+*
+* @param options - Optional bounds and `description` (no `integer` key)
+* @returns An integer number shape
+*/
+function integerShape(options) {
+	return {
+		type: "number",
+		integer: true,
+		min: options?.min,
+		max: options?.max,
+		description: options?.description
+	};
+}
+/**
+* Build a {@link BooleanShape}.
+*
+* @param options - Optional `description`
+* @returns A boolean shape
+*/
+function booleanShape(options) {
+	return {
+		type: "boolean",
+		description: options?.description
+	};
+}
+/**
+* Build a {@link NullShape}.
+*
+* @param options - Optional `description`
+* @returns A null shape
+*/
+function nullShape(options) {
+	return {
+		type: "null",
+		description: options?.description
+	};
+}
+/**
+* Build a literal shape from a fixed set of primitive values.
+*
+* @param values - The permitted literals
+* @param options - Optional `description`
+* @returns A literal shape whose `Infer` is the union of `values`
+*
+* @example
+* ```ts
+* const role = literalShape(['admin', 'member', 'guest'])
+* // Infer<typeof role> = 'admin' | 'member' | 'guest'
+*
+* const via = literalShape(['function', 'tool', 'agent'], { description: 'How to run the step.' })
+* ```
+*/
+function literalShape(values, options) {
+	return {
+		type: "literal",
+		values,
+		description: options?.description
+	};
+}
+/**
+* Build an {@link ArrayShape} from an element shape.
+*
+* @param items - The element shape
+* @param options - Optional length bounds and `description`
+* @returns An array shape
+*
+* @example
+* ```ts
+* const tags = arrayShape(stringShape(), { max: 10 })
+* ```
+*/
+function arrayShape(items, options) {
+	return {
+		type: "array",
+		items,
+		min: options?.min,
+		max: options?.max,
+		description: options?.description
+	};
+}
+/**
+* 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
+	};
+}
+/**
+* Build an open {@link ObjectShape} with no fixed properties — a dictionary.
+*
+* @remarks
+* Every value is validated against `values`; keys are unconstrained. Equivalent
+* to `objectShape({}, { additionalProperties: values })`.
+*
+* @param values - The shape every value must match
+* @param options - Optional `description`
+* @returns An open object shape
+*
+* @example
+* ```ts
+* const bindings = recordShape(numberShape()) // ~ Record<string, number>
+* ```
+*/
+function recordShape(values, options) {
+	return {
+		type: "object",
+		properties: {},
+		additionalProperties: values,
+		description: options?.description
+	};
+}
+/**
+* Build a {@link UnionShape} from a list of variant shapes (`anyOf` in JSON Schema).
+*
+* @param variants - The candidate shapes; the first match wins at runtime
+* @returns A union shape whose `Infer` is the union of the variants
+*
+* @example
+* ```ts
+* const id = unionShape(stringShape(), integerShape())
+* // Infer<typeof id> = string | number
+* ```
+*/
+function unionShape(...variants) {
+	return {
+		type: "union",
+		variants
+	};
+}
+/**
+* Build a {@link UnionShape} that emits `oneOf` (exactly one match) in JSON Schema.
+*
+* @remarks
+* Runtime behavior is identical to {@link unionShape} — only the emitted schema
+* keyword differs (`oneOf` vs `anyOf`).
+*
+* @param variants - The candidate shapes
+* @returns A union shape with `mode: 'oneOf'`
+*/
+function oneOfShape(...variants) {
+	return {
+		type: "union",
+		variants,
+		mode: "oneOf"
+	};
+}
+/**
+* Wrap a shape so it may be absent (`undefined`).
+*
+* @remarks
+* As an {@link objectShape} property, the field becomes a true optional property
+* in the inferred type.
+*
+* @param inner - The wrapped shape
+* @returns An optional shape
+*/
+function optionalShape(inner) {
+	return {
+		type: "optional",
+		inner
+	};
+}
+/**
+* Wrap a shape so it may be `null`.
+*
+* @param inner - The wrapped shape
+* @returns A nullable shape
+*/
+function nullableShape(inner) {
+	return {
+		type: "nullable",
+		inner
+	};
+}
+/**
+* Build a {@link JSONShape}.
+*
+* @remarks
+* The sound counterpart of {@link rawShape}: `rawShape` embeds an arbitrary
+* schema fragment and accepts anything at runtime, while `jsonShape` validates
+* that a value is real JSON (via {@link isJSONValue}).
+*
+* @param options - Optional `description`
+* @returns A JSON passthrough shape
+*/
+function jsonShape(options) {
+	return {
+		type: "json",
+		description: options?.description
+	};
+}
+/**
+* Build a {@link RawShape} from a JSON Schema fragment.
+*
+* @remarks
+* For values the shape DSL can't express. The compiled guard accepts any value;
+* the parser passes it through; the schema is emitted verbatim.
+*
+* @param schema - The JSON Schema fragment to embed
+* @returns A raw shape
+*/
+function rawShape(schema) {
+	return {
+		type: "raw",
+		schema
+	};
+}
+//#endregion
+export { JSON_SCHEMA_TYPES, andOf, arrayOf, arrayShape, attempt, booleanShape, boundsOf, compileGenerator, compileGuard, compileParser, compileSchema, complementOf, createContract, enumOf, enumerableSymbolCount, instanceOf, integerShape, intersectionOf, isArray, isArrayBuffer, isArrayBufferView, isAsyncFunction, isAsyncGeneratorFunction, isAsyncIterable, isBigInt, isBigInt64Array, isBigUint64Array, isBoolean, isConstructor, isDataView, isDate, isDefined, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isError, isFalse, isFiniteNumber, isFloat32Array, isFloat64Array, isFunction, isGeneratorFunction, isInt16Array, isInt32Array, isInt8Array, isInteger, isIterable, isJSONPrimitive, isJSONValue, isMap, isNonEmptyArray, isNonEmptyMap, isNonEmptyObject, isNonEmptySet, isNonEmptyString, isNull, isNullableBoolean, isNullableNumber, isNullableString, isNumber, isObject, isPromise, isPromiseLike, isRecord, isRegExp, isSet, isSharedArrayBuffer, isString, isSymbol, isTrue, isUint16Array, isUint32Array, isUint8Array, isUint8ClampedArray, isUndefined, isWeakMap, isWeakSet, isZeroArg, isZeroArgAsync, isZeroArgAsyncGenerator, isZeroArgGenerator, iterableOf, jsonShape, keyOf, lazyOf, literalOf, literalShape, mapOf, matchOf, notOf, nullShape, nullableOf, nullableShape, numberShape, objectShape, omitOf, oneOfShape, optionalOf, optionalShape, orOf, parseArray, parseArrayField, parseBoolean, parseBooleanField, parseEnum, parseEnumField, parseInteger, parseIntegerField, parseJSON, parseJSONAs, parseJSONValue, parseJSONValueField, parseNull, parseNullField, parseNumber, parseNumberField, parseRecord, parseRecordField, parseString, parseStringField, pickOf, rawShape, recordOf, recordShape, resolveField, schemaToParameters, seededRandom, setOf, stringOf, stringShape, transformOf, tupleOf, unionOf, unionShape, validateShape, whereOf };
+
+//# sourceMappingURL=index.js.map