@oh-my-pi/omptype 17.2.6 → 17.2.7

package/src/infer.ts

@@ -1,4 +1,4 @@
-/** Type-level output inference for the definition forms accepted by omptype. */
+/** Type-level input and output inference for definitions accepted by omptype. */
 
 type Whitespace = " " | "\n" | "\r" | "\t";
 
@@ -6,48 +6,94 @@ type TrimLeft<s extends string> = s extends `${Whitespace}${infer rest}` ? TrimL
 type TrimRight<s extends string> = s extends `${infer rest}${Whitespace}` ? TrimRight<rest> : s;
 type Trim<s extends string> = TrimLeft<TrimRight<s>>;
 
-type InferPrimitive<s extends string> = s extends "string" | "string.url"
+/**
+ * Flat keyword lookup. An indexed access is one instantiation level, unlike a
+ * nested conditional chain — this sits under every string-DSL property, so its
+ * depth is multiplied by every layer of object nesting above it.
+ * `never` is intentionally absent: the parser rejects it and the fallback in
+ * `InferMember` treats a missing entry as "not a primitive".
+ */
+interface PrimitiveMap {
+	string: string;
+	"string.url": string;
+	number: number;
+	"number.integer": number;
+	boolean: boolean;
+	null: null;
+	undefined: undefined;
+	unknown: unknown;
+	any: unknown;
+	object: object;
+	bigint: bigint;
+	symbol: symbol;
+	Date: Date;
+	true: true;
+	false: false;
+}
+
+type Merge<left, right> = left extends object
+	? right extends object
+		? Omit<left, keyof right> & right
+		: never
+	: never;
+
+type InferUtility<s extends string> = s extends `Record<${string},${infer value}>`
+	? Record<string, InferString<value>>
+	: s extends `Array<${infer element}>`
+		? InferString<element>[]
+		: s extends `Partial<${infer value}>`
+			? Partial<InferString<value>>
+			: s extends `Required<${infer value}>`
+				? Required<InferString<value>>
+				: s extends `Pick<${infer value},${infer keys}>`
+					? Pick<InferString<value>, Extract<InferString<keys>, keyof InferString<value>>>
+					: s extends `Omit<${infer value},${infer keys}>`
+						? Omit<InferString<value>, Extract<InferString<keys>, keyof InferString<value>>>
+						: s extends `Merge<${infer left},${infer right}>`
+							? Merge<InferString<left>, InferString<right>>
+							: never;
+
+/**
+ * Member inference as a flat false-branch chain: TypeScript tail-evaluates
+ * chained conditionals in the false position, so this stays at constant
+ * instantiation depth where the previous `extends infer` ladder nested every
+ * fallback inside a true branch and accumulated depth per step.
+ */
+type InferMember<member extends string> = Trim<member> extends infer s extends string ? InferMemberTrimmed<s> : unknown;
+
+type InferMemberTrimmed<s extends string> = s extends `(${infer inner})`
+	? InferString<inner>
+	: s extends `${infer element}[]`
+		? InferMember<element>[]
+		: s extends `'${infer literal}'` | `"${infer literal}"`
+			? literal
+			: s extends `d'${string}'` | `d"${string}"`
+				? Date
+				: s extends `\`${string}\``
+					? string
+					: s extends `/${string}/${string}` | `/${string}/`
+						? string
+						: s extends `${infer literal extends number}`
+							? literal
+							: s extends keyof PrimitiveMap
+								? PrimitiveMap[s]
+								: InferUtility<s> extends infer utility
+									? [utility] extends [never]
+										? InferMemberFallback<s>
+										: utility
+									: unknown;
+
+type InferMemberFallback<s extends string> = s extends `string.${string}`
 	? string
-	: s extends "number" | "number.integer"
-		? number
-		: s extends "boolean"
-			? boolean
-			: s extends "null"
-				? null
-				: s extends "undefined"
-					? undefined
-					: s extends "unknown"
-						? unknown
-						: s extends "object"
-							? object
-							: s extends "bigint"
-								? bigint
-								: s extends "true"
-									? true
-									: s extends "false"
-										? false
-										: never;
-
-type InferMember<member extends string> =
-	Trim<member> extends infer s extends string
-		? s extends `${infer element}[]`
-			? InferMember<element>[]
-			: s extends `'${infer literal}'` | `"${infer literal}"`
-				? literal
-				: s extends `${infer literal extends number}`
-					? literal
-					: InferPrimitive<s> extends infer primitive
-						? [primitive] extends [never]
-							? s extends `${string}string${string}`
-								? string
-								: s extends `${string}number${string}`
-									? number
-									: unknown
-							: primitive
-						: unknown
-		: unknown;
+	: s extends `${string}Date${string}`
+		? Date
+		: s extends `${string}string${string}`
+			? string
+			: s extends `${string}number${string}`
+				? number
+				: unknown;
 
-/** Split top-level unions without distributing over the accumulated members. */
+/** Split unions without distributing over the accumulated members. */
 type InferUnion<s extends string, result = never> = s extends `${infer head}|${infer tail}`
 	? InferUnion<tail, result | InferMember<head>>
 	: result | InferMember<s>;
@@ -61,61 +107,136 @@ type HasInlineDefault<s extends string> = s extends `${string}=${string}`
 type WithoutInlineDefault<s extends string> =
 	HasInlineDefault<s> extends true ? (s extends `${infer base}=${string}` ? Trim<base> : s) : s;
 
-/** String-DSL-only inference; safe inside recursive interfaces (never probes `Type`). */
+type InferStringOutput<s extends string> = s extends
+	| "string.numeric.parse"
+	| "string.integer.parse"
+	| "parse.number"
+	| "parse.integer"
+	? number
+	: s extends "string.date.parse" | "string.date.iso.parse" | "string.date.epoch.parse" | "parse.date"
+		? Date
+		: s extends "string.url.parse" | "parse.url"
+			? URL
+			: s extends "string.json.parse" | "parse.json"
+				? unknown
+				: s extends "parse.boolean"
+					? boolean
+					: s extends "parse.bigint"
+						? bigint
+						: InferUnion<s>;
+
+/** String-DSL output inference. */
 export type InferString<s extends string> =
 	WithoutInlineDefault<Trim<s>> extends infer trimmed extends string
 		? trimmed extends `${infer base}?`
 			? InferString<base>
 			: trimmed extends `(${infer inner})[]`
 				? InferUnion<inner>[]
-				: InferUnion<trimmed>
+				: InferStringOutput<trimmed>
+		: unknown;
+
+/** String-DSL input inference, preserving the source side of morph keywords. */
+export type InferStringIn<s extends string> =
+	WithoutInlineDefault<Trim<s>> extends infer trimmed extends string
+		? trimmed extends `${string}.parse` | `parse.${string}`
+			? string
+			: InferString<trimmed>
 		: unknown;
 
 type HasDefault<def> = def extends string
 	? HasInlineDefault<def>
-	: def extends { readonly hasDefault: true }
+	: def extends readonly [unknown, "=", unknown]
 		? true
-		: false;
+		: def extends { readonly hasDefault: true }
+			? true
+			: false;
 
-type DefinitionKeys<def extends object> = Exclude<keyof def, "+" | "[string]">;
+type DefinitionKeys<def extends object> = Exclude<keyof def, "+" | "[string]" | "...">;
 
-/** Optional when the key carries a `?` suffix or the string value does (`limit: "number?"`). */
 type IsOptionalProp<key, def> = key extends `${string}?`
 	? true
 	: def extends string
 		? Trim<def> extends `${string}?`
 			? true
 			: false
-		: false;
+		: def extends readonly [unknown, "?"]
+			? true
+			: false;
 
 type PropName<key extends PropertyKey> = key extends `${infer name}?` ? name : key;
+type UnwrapProperty<def> = def extends readonly [infer value, "?" | "=", ...unknown[]] ? value : def;
+type Simplify<t> = { [key in keyof t]: t[key] };
 
-type RequiredProperties<def extends object> = {
+type OutputRequired<def extends object> = {
 	-readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true
 		? HasDefault<def[key]> extends true
 			? PropName<key>
 			: never
-		: PropName<key>]-?: InferDef<def[key]>;
+		: PropName<key>]-?: InferDef<UnwrapProperty<def[key]>>;
 };
 
-type OptionalProperties<def extends object> = {
+type OutputOptional<def extends object> = {
 	-readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true
 		? HasDefault<def[key]> extends true
 			? never
 			: PropName<key>
-		: never]?: InferDef<def[key]>;
+		: never]?: InferDef<UnwrapProperty<def[key]>>;
 };
 
-type Simplify<t> = { [key in keyof t]: t[key] };
-type PropertiesOf<def extends object> = Simplify<RequiredProperties<def> & OptionalProperties<def>>;
+type InputRequired<def extends object> = {
+	-readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true
+		? never
+		: HasDefault<def[key]> extends true
+			? never
+			: PropName<key>]-?: InferDefIn<UnwrapProperty<def[key]>>;
+};
+
+type InputOptional<def extends object> = {
+	-readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true
+		? PropName<key>
+		: HasDefault<def[key]> extends true
+			? PropName<key>
+			: never]?: InferDefIn<UnwrapProperty<def[key]>>;
+};
+
+/**
+ * CYCLE SAFETY: when a fluent generic method is called on a schema whose def
+ * embeds other schemas, TypeScript instantiates `InferDef<def>` while `def`
+ * is still generic. `"..." extends keyof def` resolves TRUE under permissive
+ * instantiation (`keyof any` contains every literal), so spread/index members
+ * cannot be deferred by wrapper conditionals — a bare `InferDef<def["..."]>`
+ * member re-enters this expansion and instantiates without bound (TS2589).
+ * Interface members only instantiate when resolved, so routing the recursive
+ * reference through `DefBox` keeps generic instantiation shallow: it stops at
+ * a type reference plus an indexed access instead of expanding `InferDef`.
+ */
+interface DefBox<def> {
+	readonly out: InferDef<def>;
+	readonly in: InferDefIn<def>;
+}
+
+type OutputSpread<def extends object> = "..." extends keyof def ? DefBox<def["..."]>["out"] : unknown;
+type InputSpread<def extends object> = "..." extends keyof def ? DefBox<def["..."]>["in"] : unknown;
+type OutputIndex<def extends object> = "[string]" extends keyof def
+	? Record<string, DefBox<def["[string]"]>["out"]>
+	: unknown;
+type InputIndex<def extends object> = "[string]" extends keyof def
+	? Record<string, DefBox<def["[string]"]>["in"]>
+	: unknown;
 
 type InferObject<def extends object> = "[string]" extends keyof def
 	? [DefinitionKeys<def>] extends [never]
-		? Record<string, InferDef<def["[string]"]>>
-		: PropertiesOf<def> & Record<string, InferDef<def["[string]"]>>
-	: PropertiesOf<def>;
+		? Record<string, DefBox<def["[string]"]>["out"]>
+		: Simplify<OutputRequired<def> & OutputOptional<def> & OutputSpread<def>> & OutputIndex<def>
+	: Simplify<OutputRequired<def> & OutputOptional<def> & OutputSpread<def>>;
 
-/** Object-literal inference for fluent composition without re-inspecting the containing `Type`. */
+type InferObjectIn<def extends object> = "[string]" extends keyof def
+	? [DefinitionKeys<def>] extends [never]
+		? Record<string, DefBox<def["[string]"]>["in"]>
+		: Simplify<InputRequired<def> & InputOptional<def> & InputSpread<def>> & InputIndex<def>
+	: Simplify<InputRequired<def> & InputOptional<def> & InputSpread<def>>;
+
+/** Object-literal inference used by fluent composition overloads. */
 export type InferObjectDef<def extends object> = InferObject<def>;
 
 type InferLiteralDef<def> = def extends string
@@ -124,37 +245,123 @@ type InferLiteralDef<def> = def extends string
 		? InferObjectLiteral<def>
 		: unknown;
 
-type LiteralRequiredProperties<def extends object> = {
+type LiteralRequired<def extends object> = {
 	-readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true
 		? HasDefault<def[key]> extends true
 			? PropName<key>
 			: never
-		: PropName<key>]-?: InferLiteralDef<def[key]>;
+		: PropName<key>]-?: InferLiteralDef<UnwrapProperty<def[key]>>;
 };
 
-type LiteralOptionalProperties<def extends object> = {
+type LiteralOptional<def extends object> = {
 	-readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true
 		? HasDefault<def[key]> extends true
 			? never
 			: PropName<key>
-		: never]?: InferLiteralDef<def[key]>;
+		: never]?: InferLiteralDef<UnwrapProperty<def[key]>>;
 };
 
-/** Object-literal-only inference for fluent branches; never inspects embedded schema types. */
-export type InferObjectLiteral<def extends object> = Simplify<
-	LiteralRequiredProperties<def> & LiteralOptionalProperties<def>
->;
+/** Object-literal-only inference that does not inspect embedded schema internals. */
+export type InferObjectLiteral<def extends object> = Simplify<LiteralRequired<def> & LiteralOptional<def>>;
+
+type InstanceOf<ctor> = ctor extends abstract new (...args: never[]) => infer instance ? instance : never;
+type SpreadOutput<def> = InferDef<def> extends readonly (infer element)[] ? element[] : never[];
+type SpreadInput<def> = InferDefIn<def> extends readonly (infer element)[] ? element[] : never[];
+
+type InferTupleOutput<defs extends readonly unknown[], result extends unknown[] = []> = defs extends readonly []
+	? result
+	: defs extends readonly ["...", infer spread, ...infer rest]
+		? [...result, ...SpreadOutput<spread>, ...InferTupleOutput<rest>]
+		: defs extends readonly [infer head, ...infer rest]
+			? head extends readonly [infer value, "?"]
+				? InferTupleOutput<rest, [...result, InferDef<value>?]>
+				: head extends readonly [infer value, "=", unknown]
+					? InferTupleOutput<rest, [...result, InferDef<value>]>
+					: InferTupleOutput<rest, [...result, InferDef<head>]>
+			: result;
+
+type InferTupleInput<defs extends readonly unknown[], result extends unknown[] = []> = defs extends readonly []
+	? result
+	: defs extends readonly ["...", infer spread, ...infer rest]
+		? [...result, ...SpreadInput<spread>, ...InferTupleInput<rest>]
+		: defs extends readonly [infer head, ...infer rest]
+			? head extends readonly [infer value, "?" | "=", ...unknown[]]
+				? InferTupleInput<rest, [...result, InferDefIn<value>?]>
+				: InferTupleInput<rest, [...result, InferDefIn<head>]>
+			: result;
+
+/**
+ * True only for `any` (`1 & any` is `any`; `0 extends any` holds). During
+ * relation checking TypeScript instantiates these aliases permissively with
+ * every type parameter replaced by `any`, and under `any` the object branch
+ * recurses forever (`any["..."]` is `any` again). Cutting `any` off up front
+ * makes permissive instantiation terminate immediately, mirroring ArkType's
+ * `anyOrNever` guards.
+ */
+type IsAny<def> = 0 extends 1 & def ? true : false;
 
 /** Infer the validated output type produced by a definition. */
-export type InferDef<def = unknown> = def extends { infer: infer output }
-	? output
-	: def extends string
-		? InferString<def>
-		: def extends readonly [infer element, "[]"]
-			? InferDef<element>[]
-			: def extends object
-				? InferObject<def>
-				: unknown;
+export type InferDef<def = unknown> =
+	IsAny<def> extends true
+		? unknown
+		: def extends { readonly infer: infer output }
+			? output
+			: def extends string
+				? InferString<def>
+				: def extends RegExp
+					? string
+					: def extends readonly [infer element, "[]"]
+						? InferDef<element>[]
+						: def extends readonly [infer left, "|", infer right]
+							? InferDef<left> | InferDef<right>
+							: def extends readonly [infer left, "&", infer right]
+								? InferDef<left> & InferDef<right>
+								: def extends readonly [unknown, "=>", (...args: never[]) => infer output]
+									? output
+									: def extends readonly [unknown, "|>", infer output]
+										? InferDef<output>
+										: def extends readonly [infer base, ":", unknown] | readonly [infer base, "@", unknown]
+											? InferDef<base>
+											: def extends readonly ["keyof", infer base]
+												? keyof InferDef<base>
+												: def extends readonly ["instanceof", ...infer constructors]
+													? InstanceOf<constructors[number]>
+													: def extends readonly ["===", ...infer values]
+														? values[number]
+														: def extends readonly unknown[]
+															? InferTupleOutput<def>
+															: def extends object
+																? InferObject<def>
+																: unknown;
 
-/** Input-side defaults and morphs are not distinguished yet. */
-export type InferDefIn<def = unknown> = InferDef<def>;
+/** Infer values accepted before defaults and morphs are applied. */
+export type InferDefIn<def = unknown> =
+	IsAny<def> extends true
+		? unknown
+		: def extends { readonly inferIn: infer input }
+			? input
+			: def extends string
+				? InferStringIn<def>
+				: def extends RegExp
+					? string
+					: def extends readonly [infer element, "[]"]
+						? InferDefIn<element>[]
+						: def extends readonly [infer left, "|", infer right]
+							? InferDefIn<left> | InferDefIn<right>
+							: def extends readonly [infer left, "&", infer right]
+								? InferDefIn<left> & InferDefIn<right>
+								: def extends readonly [infer input, "=>", unknown] | readonly [infer input, "|>", unknown]
+									? InferDefIn<input>
+									: def extends readonly [infer base, ":", unknown] | readonly [infer base, "@", unknown]
+										? InferDefIn<base>
+										: def extends readonly ["keyof", infer base]
+											? keyof InferDefIn<base>
+											: def extends readonly ["instanceof", ...infer constructors]
+												? InstanceOf<constructors[number]>
+												: def extends readonly ["===", ...infer values]
+													? values[number]
+													: def extends readonly unknown[]
+														? InferTupleInput<def>
+														: def extends object
+															? InferObjectIn<def>
+															: unknown;

package/src/interp.ts

@@ -1,6 +1,6 @@
 /**
- * Tree-walking validator used for a schema's first few calls (before the JIT
- * compiler kicks in) and as the fallback for IR shapes the compiler declines.
+ * Tree-walking validator used for a schema's first few calls and as the
+ * targeted fallback for recursive or predicate-only JIT subtrees.
  *
  * Semantics must stay in lockstep with `compile.ts`:
  * - success returns the output value; the input is returned as-is unless the
@@ -21,7 +21,8 @@ export function walk(ir: IR, value: unknown): unknown {
 }
 
 function fail(path: PropertyKey[], expected: string, data: unknown): OmpErrors {
-	return OmpErrors.single([...path], expected, data);
+	const storedPath = path.length === 0 ? undefined : path.length === 1 ? path[0] : [...path];
+	return new OmpErrors(storedPath, expected, data);
 }
 
 /** Pure predicate used for union-member scanning (no morphs, no errors). */
@@ -37,6 +38,10 @@ function checks(ir: IR, v: unknown): boolean {
 			return typeof v === "boolean";
 		case "bigint":
 			return typeof v === "bigint";
+		case "symbol":
+			return typeof v === "symbol";
+		case "never":
+			return false;
 		case "anyobject":
 			return typeof v === "object" && v !== null;
 		case "string":
@@ -47,16 +52,19 @@ function checks(ir: IR, v: unknown): boolean {
 				(!ir.url || URL.canParse(v))
 			);
 		case "number":
+			if (typeof v !== "number") return false;
 			return (
-				typeof v === "number" &&
-				(!ir.int || Number.isInteger(v)) &&
+				(ir.int ? Number.isInteger(v) : Number.isFinite(v)) &&
+				(ir.divisor === undefined || v % ir.divisor === 0) &&
 				(ir.min === undefined || (ir.xmin ? v > ir.min : v >= ir.min)) &&
 				(ir.max === undefined || (ir.xmax ? v < ir.max : v <= ir.max))
 			);
 		case "lit":
-			return v === ir.v;
+			return ir.v instanceof Date ? v instanceof Date && v.valueOf() === ir.v.valueOf() : v === ir.v;
 		case "union":
 			return ir.members.some(m => checks(m, v));
+		case "intersection":
+			return ir.members.every(member => checks(member, v));
 		case "array": {
 			if (!Array.isArray(v)) return false;
 			if (ir.min !== undefined && v.length < ir.min) return false;
@@ -64,6 +72,31 @@ function checks(ir: IR, v: unknown): boolean {
 			for (const el of v) if (!checks(ir.el, el)) return false;
 			return true;
 		}
+		case "tuple": {
+			if (!Array.isArray(v)) return false;
+			let required = ir.postfix.length;
+			for (const item of ir.prefix) if (!item.opt && !item.hasDefault) required++;
+			if (v.length < required) return false;
+			if (ir.variadic === undefined && v.length > ir.prefix.length + ir.postfix.length) return false;
+			const postfixStart = v.length - ir.postfix.length;
+			const prefixCount = Math.min(ir.prefix.length, postfixStart);
+			for (let index = 0; index < prefixCount; index++) {
+				if (!checks(ir.prefix[index].val, v[index])) return false;
+			}
+			for (let index = prefixCount; index < ir.prefix.length; index++) {
+				const item = ir.prefix[index];
+				if (!item.opt && !item.hasDefault) return false;
+			}
+			if (ir.variadic !== undefined) {
+				for (let index = prefixCount; index < postfixStart; index++) {
+					if (!checks(ir.variadic, v[index])) return false;
+				}
+			}
+			for (let index = 0; index < ir.postfix.length; index++) {
+				if (!checks(ir.postfix[index], v[postfixStart + index])) return false;
+			}
+			return true;
+		}
 		case "object": {
 			if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
 			const rec = v as Record<string, unknown>;
@@ -94,6 +127,19 @@ function checks(ir: IR, v: unknown): boolean {
 			}
 			return true;
 		}
+		case "instance":
+			return v instanceof ir.ctor;
+		case "refine":
+			if (!checks(ir.base, v)) return false;
+			try {
+				return ir.pred(v);
+			} catch {
+				return false;
+			}
+		case "alias":
+			return checks(ir.resolve(), v);
+		case "morph":
+			return checks(ir.input, v);
 		case "sub":
 			return !(ir.schema.run(v) instanceof OmpErrors);
 	}
@@ -101,6 +147,36 @@ function checks(ir: IR, v: unknown): boolean {
 
 function visit(ir: IR, v: unknown, path: PropertyKey[]): unknown {
 	switch (ir.k) {
+		case "alias":
+			return visit(ir.resolve(), v, path);
+		case "refine": {
+			const base = visit(ir.base, v, path);
+			if (base instanceof OmpErrors) return base;
+			try {
+				return ir.pred(base) ? base : fail(path, ir.expected, base);
+			} catch {
+				return fail(path, ir.expected, base);
+			}
+		}
+		case "morph": {
+			const input = visit(ir.input, v, path);
+			if (input instanceof OmpErrors) return input;
+			const context = {
+				error: (expected: string, data: unknown = input) => fail(path, expected, data),
+				reject: (problem: string, data: unknown = input) => fail(path, problem, data),
+			};
+			const output = ir.fn(input, context);
+			if (output instanceof OmpErrors) return output;
+			return ir.out === undefined ? output : visit(ir.out, output, path);
+		}
+		case "intersection": {
+			let output = v;
+			for (const member of ir.members) {
+				output = visit(member, output, path);
+				if (output instanceof OmpErrors) return output;
+			}
+			return output;
+		}
 		case "sub": {
 			const out = ir.schema.run(v);
 			if (out instanceof OmpErrors) {
@@ -122,7 +198,7 @@ function visit(ir: IR, v: unknown, path: PropertyKey[]): unknown {
 					if (!(out instanceof OmpErrors)) return out;
 				}
 			}
-			return unionFail(ir, v, path);
+			return ir.members.some(canRefineUnionFailure) ? unionFail(ir, v, path) : fail(path, expectedOf(ir), v);
 		}
 		case "array": {
 			if (!Array.isArray(v)) return fail(path, "an array", v);
@@ -149,6 +225,57 @@ function visit(ir: IR, v: unknown, path: PropertyKey[]): unknown {
 			}
 			return out;
 		}
+		case "tuple": {
+			if (!Array.isArray(v)) return fail(path, "an array", v);
+			let required = ir.postfix.length;
+			for (const item of ir.prefix) if (!item.opt && !item.hasDefault) required++;
+			if (v.length < required) return fail(path, `an array of at least length ${required}`, v);
+			const maximum = ir.prefix.length + ir.postfix.length;
+			if (ir.variadic === undefined && v.length > maximum) {
+				return fail(path, `an array of at most length ${maximum}`, v);
+			}
+			const postfixStart = v.length - ir.postfix.length;
+			const prefixCount = Math.min(ir.prefix.length, postfixStart);
+			const morph = hasMorph(ir);
+			const output = morph ? [...v] : v;
+			for (let index = 0; index < prefixCount; index++) {
+				path.push(index);
+				const item = visit(ir.prefix[index].val, v[index], path);
+				path.pop();
+				if (item instanceof OmpErrors) return item;
+				if (morph) output[index] = item;
+			}
+			for (let index = prefixCount; index < ir.prefix.length; index++) {
+				const item = ir.prefix[index];
+				if (item.hasDefault && morph) {
+					const payload = item.def;
+					output[index] = item.defFactory && typeof payload === "function" ? payload() : payload;
+				} else if (!item.opt) {
+					path.push(index);
+					const error = fail(path, expectedOf(item.val), MISSING);
+					path.pop();
+					return error;
+				}
+			}
+			if (ir.variadic !== undefined) {
+				for (let index = prefixCount; index < postfixStart; index++) {
+					path.push(index);
+					const item = visit(ir.variadic, v[index], path);
+					path.pop();
+					if (item instanceof OmpErrors) return item;
+					if (morph) output[index] = item;
+				}
+			}
+			for (let index = 0; index < ir.postfix.length; index++) {
+				const inputIndex = postfixStart + index;
+				path.push(inputIndex);
+				const item = visit(ir.postfix[index], v[inputIndex], path);
+				path.pop();
+				if (item instanceof OmpErrors) return item;
+				if (morph) output[inputIndex] = item;
+			}
+			return output;
+		}
 		case "object": {
 			if (typeof v !== "object" || v === null || Array.isArray(v)) return fail(path, "an object", v);
 			const rec = v as Record<string, unknown>;
@@ -220,6 +347,23 @@ function prefixAll(errs: OmpErrors, path: PropertyKey[]): OmpErrors {
 	return errs;
 }
 
+/** True when a union failure can be replaced with a more specific nested error. */
+export function canRefineUnionFailure(member: IR): boolean {
+	const base = member.k === "sub" ? member.schema.ir : member;
+	if (member.k === "sub") {
+		return (
+			base.k === "array" ||
+			base.k === "object" ||
+			base.k === "anyobject" ||
+			base.k === "string" ||
+			base.k === "number"
+		);
+	}
+	if (base.k === "array" || base.k === "object") return true;
+	if (base.k === "string") return base.min !== undefined || base.max !== undefined || base.url === true;
+	return base.k === "number" && (base.int === true || base.min !== undefined || base.max !== undefined);
+}
+
 /**
  * Detailed failure for a union: descend into the member the value was clearly
  * aimed at — unique runtime-kind match, else an object member whose literal
@@ -227,7 +371,7 @@ function prefixAll(errs: OmpErrors, path: PropertyKey[]): OmpErrors {
  * for a precise nested error (paths, narrow messages) instead of the coarse
  * "A or B" expectation.
  */
-export function unionFail(ir: IR & { k: "union" }, v: unknown, path: PropertyKey[]): OmpErrors {
+export function unionFail(ir: IR & { k: "union" }, v: unknown, path: PropertyKey[], expected?: string): OmpErrors {
 	let best: IR | undefined;
 	for (const m of ir.members) {
 		const base = m.k === "sub" ? m.schema.ir : m;
@@ -243,7 +387,7 @@ export function unionFail(ir: IR & { k: "union" }, v: unknown, path: PropertyKey
 		const out = visit(best, v, path);
 		if (out instanceof OmpErrors) return out;
 	}
-	return fail(path, expectedOf(ir), v);
+	return fail(path, expected ?? expectedOf(ir), v);
 }
 
 /** Pick the sole object member whose literal-typed property matches the value's. */