@warlock.js/seal 5.29.0 → 5.31.0

package/llms-full.txt

@@ -8,35 +8,36 @@
 
 ---
 name: bridge-standard-schema
-description: 'Diagnose `StandardSchemaV1` interop — phantom-intersection at the `v` factory return, why typed slots reject a schema, cascade `Model<TSchema>` variance. Triggers: `StandardSchemaV1`, `~standard`, `Infer`, `ObjectValidator`, `StringValidator`, `LiteralValidator`, `BaseValidator`, `Model<TSchema>`, `StandardJSONSchemaV1`, `Result<unknown>`; "StandardSchemaV1 slot rejecting my schema", "Result<unknown> error", "drop as unknown as cast", "cascade Model schema variance"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: foundations — the `seal-basics` topic; JSON Schema gen — the `generate-json-schema` topic; competing spec `@standard-schema/spec`.'
+description: 'Diagnose `StandardSchemaV1` interop — input/output class parameters and primitive factory intersections, why typed slots reject a schema, cascade `Model<TSchema>` variance. Triggers: `StandardSchemaV1`, `~standard`, `Infer`, `ObjectValidator`, `StringValidator`, `LiteralValidator`, `BaseValidator`, `Model<TSchema>`, `StandardJSONSchemaV1`, `Result<unknown>`; "StandardSchemaV1 slot rejecting my schema", "Result<unknown> error", "drop as unknown as cast", "cascade Model schema variance"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: foundations — the `seal-basics` topic; JSON Schema gen — the `generate-json-schema` topic; competing spec `@standard-schema/spec`.'
 ---
 
 # The Standard Schema bridge
 
 Seal validators implement [Standard Schema V1](https://standardschema.dev) — every validator exposes a `~standard` member with `validate()`, JSON Schema metadata, and inferred types. Any consumer that accepts `StandardSchemaV1<T>` (`@warlock.js/ai` supervisor `output`, ai tool `input`, LangGraph state, OpenAI structured outputs, TanStack Form, Conform) accepts a seal schema directly.
 
-This skill is about the **typing** of that interop — the phantom intersection that makes `v.object({...})` satisfy `StandardSchemaV1<T>` without `as unknown as` casts.
+This skill covers the input and output types exposed through `~standard`, and
+compatibility with consumers such as Cascade model schemas and AI tool schemas.
 
 ## The shape of the bridge
 
-The `v` factory returns aren't bare validator classes. Each factory widens its return with a phantom intersection:
+`ObjectValidator<TSchema>` already threads `Infer.Input` and `Infer.Output` shapes
+into `BaseValidator<TInput, TOutput>`. Both `v.object(fields)` and the standalone
+`object(fields)` factory return that class directly. No extra Standard Schema
+intersection is needed for objects: avoiding one keeps large composed schemas
+cheaper for TypeScript to instantiate.
 
-```ts
-// Inside seal's factory:
-object: <T extends Schema>(schema: T) =>
-  new ObjectValidator<T>(schema) as ObjectValidator<T>
-    & StandardSchemaV1<Infer<ObjectValidator<T>>>;
-
-string: () =>
-  new StringValidator() as StringValidator & StandardSchemaV1<string>;
-
-literal: <T extends readonly [...] >(...values: T) =>
-  new LiteralValidator<T>(values) as LiteralValidator<T> & StandardSchemaV1<T[number]>;
+Other factories add a Standard Schema intersection when their class has no precise
+generic output declaration, for example:
 
-// ...one intersection per factory.
+```ts
+// Inside Seal's factory:
+string: () => new StringValidator() as StringValidator & StandardSchemaV1<string>;
 ```
 
-The intersection is **only on the factory return type** — the `BaseValidator` and `ObjectValidator` *class* shapes are unchanged. That distinction is load-bearing: putting `Infer<this>` directly on `BaseValidator['~standard']` breaks `@warlock.js/cascade`'s `Model<TSchema>` because `ObjectValidator` becomes invariant when its members vary with `TSchema`. The factory-side intersection avoids that — bare classes in `Model.schema: ObjectValidator<TSchema>` slots are still structurally compatible with the typed factory return.
+Keep input and output distinct when writing consumer types. Defaults and catches
+can make input fields optional while output fields are required. Avoid computing
+`Infer<this>` in the base class: object shapes are already supplied as generic
+parameters, and recursively walking the full class increases compiler work.
 
 ## What this means for app code
 
@@ -58,7 +59,7 @@ ai.tool({
   name: "create_user",
   description: "Create a new user",
   input: userSchema,
-  execute: async input => createUser(input),
+  execute: async (input) => createUser(input),
 });
 
 // ✅ supervisor output — no cast
@@ -82,7 +83,7 @@ const schema = v.object({
   blocks: v.array(v.literal("text", "image")).optional(),
 });
 
-type Output = Infer<typeof schema>;
+type Output = Infer.Output<typeof schema>;
 // { email: string; blocks?: ("text" | "image")[] }
 ```
 
@@ -92,17 +93,12 @@ Hand-rolled parallel types drift the moment a field changes — and seal's tight
 
 Three failure modes you'll see in real projects:
 
-### 1. You annotated the schema with the bare class type
+### 1. An annotation discarded schema details
 
-```ts
-// ❌ Discards the phantom intersection
-const schema: ObjectValidator<{ email: StringValidator }> = v.object({...});
-
-// ✅ Let inference run
-const schema = v.object({...});
-```
-
-The annotation strips `& StandardSchemaV1<...>` from the type. The schema stops fitting `StandardSchemaV1<T>` slots. Fix: remove the annotation. If you need the value type, use `Infer<typeof schema>`.
+Let the factory infer its concrete schema. An annotation such as bare
+`ObjectValidator` loses the field types; primitive factories also lose their
+Standard Schema intersection when annotated with a bare primitive class.
+`ObjectValidator<typeof fields>` preserves an object's input and output types.
 
 ### 2. The schema's inferred shape doesn't match the target type
 
@@ -117,23 +113,51 @@ The supervisor's explicit `<MyOutput>` generic is a constraint the schema must s
 - **Drop the explicit generic** — let the supervisor infer output type from the schema. The hand-rolled type was probably documentation-only anyway.
 - **Align them** — if the hand-rolled type is the source of truth (e.g. a domain type from elsewhere), make the schema match.
 
-### 3. The error says `Result<unknown>` even though `Infer<>` resolves correctly
+### 3. The error says `Result<unknown>`
+
+Check whether an annotation erased a factory's output type, and compare
+`Infer.Input<typeof schema>` and `Infer.Output<typeof schema>` with the consumer's
+expected types. Output slots should use the post-default output shape. Objects
+carry that shape directly through their class generics; primitive factories add
+it through their Standard Schema intersection.
 
-This is a TypeScript reporting quirk, not a bridge bug. When a `StandardSchemaV1<T>` slot rejects a schema, TS picks the simplest mismatch chain to report — often it falls through `BaseValidator['~standard'].validate`'s wider `Result<unknown>` declaration before reaching the factory-side narrower one. The intersection *is* there structurally, but the error message mentions `unknown`.
+## Union and record outputs
 
-If you see this, ignore the `unknown` and ask: does `Infer<typeof schema>` match the slot's expected `T`? Probe with:
+Use `Infer.Output<T>` or `StandardSchemaV1.InferOutput<T>` for downstream data.
+Unions and records preserve their children's output types independently of input
+shapes. Defaults and catches make object fields required in output. Their factory
+intersections put the precise Standard Schema signature first, so direct
+`~standard.validate()` calls return the declared output. `Infer.Output` reads the
+output metadata rather than inferring from overloaded validation signatures. A union
+returns the selected branch's validated data before its own transformers and
+refinements; it does not discard branch defaults, computed values or transformations.
 
 ```ts
-type _Probe = Infer<typeof schema>;
-const _force: { __nope: 1 } = null as unknown as _Probe;
-// Hover the error to see the resolved shape, then compare to the slot's T.
+const entry = v.object({ count: v.int().optional().default(1) });
+const entries = v.record(entry);
+type Entries = Infer.Output<typeof entries>;
+// Record<string, { count: number }>
+const maybeEntry = v.union([entry, v.string()]);
+type MaybeEntry = Infer.Output<typeof maybeEntry>;
+// { count: number } | string
 ```
 
-That's the real mismatch.
+When upgrading, union output can change through member trimming, Date parsing,
+defaults, computed fields and unknown-key stripping. An explicit `undefined`
+member output drops its containing object field. Keep the raw input before
+validation if storage, comparisons or serialization also need that value.
+
+## Compiler budget
+
+From `packages/seal`, run `pnpm bench:types --check` after changes to inference or
+factory types. CI runs the same deterministic composed-schema fixture when Seal
+is selected. Instantiations and type counts may grow at most 5% above the checked-in
+baseline. Refresh with `node scripts/bench-types.mjs --update` only after reviewing
+the measurements; time and memory are diagnostic rather than gated.
 
 ## Why not `Omit<class, "~standard"> & StandardSchemaV1<T>`?
 
-Tempting — it would force the factory's `~standard` to fully replace the class's wider one, fixing the misleading `Result<unknown>` error message. **Don't do it.** `Omit` on a class instance type triggers the same variance trap as putting `Infer<this>` on the class itself: cascade explodes with hundreds of `ObjectValidator<{specific}>` vs `ObjectValidator<TSchema>` errors. The phantom intersection is the only shape that satisfies both ends — narrower for typed slots, structurally identical to the class for cascade's invariant generic positions.
+Tempting — it would force the factory's `~standard` to fully replace the class's wider one, fixing the misleading `Result<unknown>` error message. **Don't do it.** `Omit` on a class instance type triggers the same variance trap as putting `Infer<this>` on the class itself: cascade explodes with hundreds of `ObjectValidator<{specific}>` vs `ObjectValidator<TSchema>` errors. Keep object factories as their existing generic class, and retain factory-side intersections for primitive classes that need them. Both preserve the validator's class members for generic consumers.
 
 ## Why not import `@standard-schema/spec` instead of forking the types?
 
@@ -167,31 +191,61 @@ When `validate()` runs against a value, the order is:
 3. optional/required check — decide whether to run rules
 4. requiredRule  — required-condition rule (.requiredIf, .requiredWith, etc.)
 5. rules         — every other rule, in declaration order
-6. transformers  — reshape value into data (.toISOString, .toLowerCase)
+6. children      — validate container members, fill defaults and computed fields
+7. transformers  — reshape value into data (.toISOString, .toLowerCase)
+8. refinements   — typed custom checks against successful output
 ```
 
 If a rule fails, transformers don't run for that field.
 
 **Mutator vs transformer mental model:**
+
 - **Mutator** = pre-validation reshape. `v.date()` ships one that parses strings. Use when you want rules to see the reshaped value.
 - **Transformer** = post-validation reshape. Lands in `data`. Use when you only care about the output form.
 
 ```ts
 // trim BEFORE length check — use a mutator
-v.string().addMutator(s => s.trim()).min(3)
+v.string()
+  .addMutator((s) => s.trim())
+  .min(3);
 // "  Hi  " → mutator trims → "Hi" → fails min(3)
 
 // trim only the OUTPUT — use a transformer (.trim() on string is a transformer)
-v.string().min(3).trim()
+v.string().min(3).trim();
 // "  Hi  " → rules see "  Hi  " (length 6, passes min(3)) → trim → data = "Hi"
 ```
 
+## `.refine()`
+
+Refinements receive the validator's output type, after children, defaults, computed
+fields and output transformers. They skip failed validation and absent/null values,
+including when `firstErrorOnly: false`. Return an error string to reject the value;
+return `undefined` to accept it. Async callbacks are supported. Use `.addRule()`
+when a check must run against input before children validate.
+
+```ts
+v.object({ count: v.int().optional().default(1) }).refine((value) => {
+  // count is a number, and defaults have already been applied.
+  return value.count > 10 ? "Too many items" : undefined;
+});
+```
+
+Successful empty defaults such as `.default("")` are refined too. `.merge()`
+appends the other object's refinements; `.extend()` imports only fields. Cloning
+and field-selection methods preserve the receiver's refinements, so callbacks
+must tolerate fields removed by `.pick()` or `.without()`.
+
+Output transformers do not yet change declared output types: a
+`v.date().toISOString()` refinement receives a string at runtime despite the
+`Date` declaration. Use a Date input rule, or convert after validation; moving
+`.refine()` earlier in the chain does not move it before transformers.
+
 ## `.required()` / `.optional()` / `.present()`
 
 ```ts
-v.string()             // already required inside v.object
-v.string().optional()  // type: string | undefined — { isOptional: true } brand
-v.string().present()   // must exist, may be "" / null
+v.string(); // already required inside v.object
+v.string().optional(); // type: string | undefined — { isOptional: true } brand
+v.string().present(); // must exist, may be "" / null
 ```
 
 **Required is the default inside `v.object`.** Most schemas read cleaner without `.required()` — `Infer<>` already shows what's required (no `?`) vs optional (`?`). Calling `.required()` explicitly is harmless and accepted, but the canonical seal style is to skip it. Keep `.optional()` explicit (it changes behavior); skip `.required()` (it doesn't).
@@ -199,9 +253,11 @@ v.string().present()   // must exist, may be "" / null
 The `{ isOptional: true }` brand survives chaining (`.optional().min(3)` is still optional) and `Infer<>` reads it to make the key optional.
 
 **When `.required()` is still useful:**
-- It's not needed for conditional rules — `.requiredIf(field, value)` and friends *replace* the default required-condition slot, so they work standalone.
+
+- It's not needed for conditional rules — `.requiredIf(field, value)` and friends _replace_ the default required-condition slot, so they work standalone.
 
 Conditional variants (run inside `v.object` only):
+
 - `.requiredIf(field, value)` / `.requiredIfSibling(field, value)`
 - `.requiredWith(field)` / `.requiredWithSibling(field)`
 - `.requiredWithout(field)` / `.requiredWithoutSibling(field)`
@@ -213,22 +269,22 @@ Conditional variants (run inside `v.object` only):
 ## `.nullable()` / `.notNullable()` / `.nullish()`
 
 ```ts
-v.string().nullable()  // type: string | null
-v.string().nullish()   // sugar for .optional().nullable()
+v.string().nullable(); // type: string | null
+v.string().nullish(); // sugar for .optional().nullable()
 ```
 
-Independent of optional — a field can be required *and* nullable. Defaults to non-nullable. The `{ isNullable: true }` brand widens both `Infer.Input` and `Infer.Output` with `| null`.
+Independent of optional — a field can be required _and_ nullable. Defaults to non-nullable. The `{ isNullable: true }` brand widens both `Infer.Input` and `Infer.Output` with `| null`.
 
 ## `.default(value | callback)`
 
 ```ts
-v.string().default("guest")
-v.int().default(0)
-v.date().default(() => new Date())   // lazy — fresh each validation
-v.array(v.string()).default([])
+v.string().default("guest");
+v.int().default(0);
+v.date().default(() => new Date()); // lazy — fresh each validation
+v.array(v.string()).default([]);
 ```
 
-If input is `undefined` (or missing), the default is used and rules run against it. Pass a callback for fresh-per-run values. The default fires *before* rules — so `v.string().min(3).default("a")` fails because `"a"` is shorter than 3.
+If input is `undefined` (or missing), the default is used and rules run against it. Pass a callback for fresh-per-run values. The default fires _before_ rules — so `v.string().min(3).default("a")` fails because `"a"` is shorter than 3.
 
 Date sugar: `v.date().defaultNow()` ≡ `.default(() => new Date())`.
 
@@ -236,7 +292,7 @@ The `{ hasDefault: true }` brand makes the key optional in `Infer.Input` (caller
 
 ## `.catch(fallback)`
 
-Rescues *failed* validation by substituting a fallback. Complement to `.default()`:
+Rescues _failed_ validation by substituting a fallback. Complement to `.default()`:
 
 - `.default(x)` fires when input is **absent**
 - `.catch(y)` fires when input is **present but invalid**
@@ -271,7 +327,7 @@ const schema = v.object({
   retries: v.int().catch(3),
 });
 
-type In  = Infer.Input<typeof schema>;
+type In = Infer.Input<typeof schema>;
 // {
 //   bio?:     string;
 //   status?:  Status;      ← default makes caller optional
@@ -285,10 +341,11 @@ type Out = Infer.Output<typeof schema>;
 //   retries: number;       ← catch guarantees a value
 // }
 
-type Default = Infer<typeof schema>;   // alias for Infer.Input
+type Default = Infer<typeof schema>; // alias for Infer.Input
 ```
 
 **When to reach for which:**
+
 - `Infer.Input<T>` (or bare `Infer<T>`) — for HTTP request bodies, form payloads, DTOs, anything pre-validation. **The common case in HTTP-shaped code.**
 - `Infer.Output<T>` — for Cascade `Model<>` params, validated state, anywhere downstream of `validate()`.
 
@@ -298,26 +355,26 @@ Both widen with `| null` when `.nullable()` is set.
 
 Three failure modes, three different rescue mechanisms:
 
-| Input state | Rescued by | What appears in `data` |
-| --- | --- | --- |
-| Field absent | `.default(x)` | `x` |
-| Field absent (no default) | `.optional()` | Key omitted entirely |
-| Field present and invalid | `.catch(y)` | `y` |
-| Field is `null` | `.nullable()` | `null` |
-| Field present, empty (`""`, `[]`, `{}`) | (none needed — empty is a valid value) | Preserved as-is |
+| Input state                             | Rescued by                             | What appears in `data` |
+| --------------------------------------- | -------------------------------------- | ---------------------- |
+| Field absent                            | `.default(x)`                          | `x`                    |
+| Field absent (no default)               | `.optional()`                          | Key omitted entirely   |
+| Field present and invalid               | `.catch(y)`                            | `y`                    |
+| Field is `null`                         | `.nullable()`                          | `null`                 |
+| Field present, empty (`""`, `[]`, `{}`) | (none needed — empty is a valid value) | Preserved as-is        |
 
 Full truth table for an `.optional()` field inside `v.object(…)`:
 
-| Input | What appears in `data` |
-| --- | --- |
-| Field absent | Key **omitted entirely** (not `undefined`-valued) |
-| Field is explicit `undefined` | Key omitted (treated identically to absent) |
-| Field is `null` (no `.nullable()`) | Key omitted — for an **optional** field, `null` coalesces to empty and the (cleared) required rule doesn't fire. On a **required** field the same `null` triggers a validation error. |
-| Field is `null` with `.nullable()` | Key is `null` |
-| Field present and empty (`""`, `[]`, `{}`) | Preserved as-is — empty ≠ absent |
-| Field is `.default(x)` and absent | Key is `x` (default fires, then rules run on `x`) |
-| Field is `.default(x)` and present | Caller value wins; default is unused |
-| Field is `.catch(y)` and validation fails | Key is `y` (catch rescues) |
+| Input                                      | What appears in `data`                                                                                                                                                                |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Field absent                               | Key **omitted entirely** (not `undefined`-valued)                                                                                                                                     |
+| Field is explicit `undefined`              | Key omitted (treated identically to absent)                                                                                                                                           |
+| Field is `null` (no `.nullable()`)         | Key omitted — for an **optional** field, `null` coalesces to empty and the (cleared) required rule doesn't fire. On a **required** field the same `null` triggers a validation error. |
+| Field is `null` with `.nullable()`         | Key is `null`                                                                                                                                                                         |
+| Field present and empty (`""`, `[]`, `{}`) | Preserved as-is — empty ≠ absent                                                                                                                                                      |
+| Field is `.default(x)` and absent          | Key is `x` (default fires, then rules run on `x`)                                                                                                                                     |
+| Field is `.default(x)` and present         | Caller value wins; default is unused                                                                                                                                                  |
+| Field is `.catch(y)` and validation fails  | Key is `y` (catch rescues)                                                                                                                                                            |
 
 ```ts
 const schema = v.object({
@@ -325,11 +382,12 @@ const schema = v.object({
   embedding: v.array(v.number()).optional(),
 });
 
-(await validate(schema, {})).data
-// → {} — neither key appears
-// (NOT { metadata: {}, embedding: [] })
+(await validate(schema, {}))
+  .data
+  // → {} — neither key appears
+  // (NOT { metadata: {}, embedding: [] })
 
-(await validate(schema, { metadata: {}, embedding: [] })).data
+  (await validate(schema, { metadata: {}, embedding: [] })).data;
 // → { metadata: {}, embedding: [] } — present-empty is preserved
 ```
 
@@ -342,12 +400,12 @@ Collection validators (`v.record`, `v.array`, `v.tuple`) explicitly honor this
 Available on `v.string()`, `v.number()`, `v.int()`, `v.float()`, `v.boolean()`, `v.scalar()`:
 
 ```ts
-v.string().in(["admin", "user", "guest"])   // value must match one
-v.string().oneOf(["a", "b"])                // alias for .in
-v.string().notIn(["banned", "blocked"])     // value must NOT match
-v.string().forbids(["banned"])              // alias for .notIn
-v.number().allowsOnly([1, 2, 3])            // stricter — explicit allowlist
-v.string().enum(MyTSEnum)                   // accepts a TS enum object via Object.values
+v.string().in(["admin", "user", "guest"]); // value must match one
+v.string().oneOf(["a", "b"]); // alias for .in
+v.string().notIn(["banned", "blocked"]); // value must NOT match
+v.string().forbids(["banned"]); // alias for .notIn
+v.number().allowsOnly([1, 2, 3]); // stricter — explicit allowlist
+v.string().enum(MyTSEnum); // accepts a TS enum object via Object.values
 ```
 
 For literal-typed narrowing (`"admin" | "user" | "guest"` instead of `string`), use `v.literal(...)` instead — `oneOf` keeps the broader primitive type.
@@ -359,10 +417,10 @@ v.object({
   email: v.string(),
   password: v.string(),
   passwordConfirm: v.string().sameAs("password").omit(),
-})
+});
 ```
 
-`.omit()` keeps the field in *validation* but drops it from `data` and from `Infer<>`. Use for confirmation/checksum fields that exist only for cross-field rules. `.exclude()` is the same idea, used internally for managed/computed plumbing.
+`.omit()` keeps the field in _validation_ but drops it from `data` and from `Infer<>`. Use for confirmation/checksum fields that exist only for cross-field rules. `.exclude()` is the same idea, used internally for managed/computed plumbing.
 
 ## `.label("Display Name")` — field display name
 
@@ -371,7 +429,7 @@ To control the `:input` placeholder in a field's own messages, call `.label()` o
 ```ts
 v.object({
   email_address: v.string().label("Email Address"),
-})
+});
 // Error message: "The Email Address is required" (instead of "The email_address is required")
 ```
 
@@ -379,12 +437,14 @@ v.object({
 
 ### `.attributes({ ... })` is a different tool
 
-`.attributes()` does NOT relabel a field's own `:input`. It supplies named substitution values consumed by the translation layer and by rules that reference *other* fields (e.g. `matches`):
+`.attributes()` does NOT relabel a field's own `:input`. It supplies named substitution values consumed by the translation layer and by rules that reference _other_ fields (e.g. `matches`):
 
 ```ts
-v.string().sameAs("confirmPassword").attributes({
-  matches: { confirmPassword: "Confirm Password" },
-})
+v.string()
+  .sameAs("confirmPassword")
+  .attributes({
+    matches: { confirmPassword: "Confirm Password" },
+  });
 ```
 
 For per-field display names use `.label()`; for translated messages wire the `translateRule` / `translateAttribute` hooks via `configureSeal()`.
@@ -412,7 +472,7 @@ Switch back with `.immutable`. Default is fine 99% of the time. Reach for `.muta
 
 ## Things NOT to do
 
-- Don't put a transformer where a mutator belongs — `.trim()` is a transformer; if you need trimming *before* `.min()`, use `.addMutator(s => s.trim())`.
+- Don't put a transformer where a mutator belongs — `.trim()` is a transformer; if you need trimming _before_ `.min()`, use `.addMutator(s => s.trim())`.
 - Don't combine `.required()` and `.optional()` on the same chain — last wins, but the intent is unclear; pick one.
 - Don't chain `.default("a")` with `.min(3)` and expect `"a"` to pass — the default goes through rules.
 - Don't expect `.requiredIf()` to work on a standalone validator outside `v.object` — sibling resolution silently passes.
@@ -437,20 +497,20 @@ v.object({
   email: v.string().email(),
   age: v.int().min(13).optional(),
   role: v.literal("admin", "user", "guest"),
-})
+});
 ```
 
 - **Required by default.** `.optional()` to opt out — the `{ isOptional: true }` brand makes the key optional in `Infer<>`.
 - **Unknown keys policy.** By default extra keys are silently dropped from `data`. Toggle with `.allowUnknown()` (forward as-is), `.stripUnknown()` (explicit drop), or `.allow(...keys)` (whitelist specific extras). See [`object-methods.md`](./object-methods.md).
 - **Schema composition.** `.extend(schema)`, `.merge(other)`, `.pick(...keys)`, `.without(...keys)`, `.partial(...keys)`, `.requiredFields(...keys)` — all in [`object-methods.md`](./object-methods.md).
-- **Cross-field rules** (`sameAs`, `requiredIf`, `requiredWith`) attach to fields *inside* a `v.object`. Without a parent, sibling resolution silently passes.
+- **Cross-field rules** (`sameAs`, `requiredIf`, `requiredWith`) attach to fields _inside_ a `v.object`. Without a parent, sibling resolution silently passes.
 
 ## `v.array` — homogeneous lists
 
 ```ts
-v.array(v.string())          // type: string[]
-v.array(userSchema)          // type: User[]
-v.array(v.array(v.int()))    // type: number[][] — recursive inference
+v.array(v.string()); // type: string[]
+v.array(userSchema); // type: User[]
+v.array(v.array(v.int())); // type: number[][] — recursive inference
 ```
 
 The inner validator runs against each element; failure on any element fails the array. Method surface (`.min`, `.max`, `.unique`, `.sorted`, `.flip`, …) in [`array-methods.md`](./array-methods.md).
@@ -458,9 +518,9 @@ The inner validator runs against each element; failure on any element fails the
 ## `v.record` — homogeneous values, dynamic keys
 
 ```ts
-v.record(v.int())                          // type: Record<string, number>
-v.record(v.object({ count: v.int() }))     // type: Record<string, { count: number }>
-v.record()                                 // type: Record<string, any>
+v.record(v.int()); // type: Record<string, number>
+v.record(v.object({ count: v.int() })); // type: Record<string, { count: number }>
+v.record(); // type: Record<string, any>
 ```
 
 Reach for `v.record` when keys are dynamic (user-provided, dictionary-style) but values share a schema. If keys are also constrained (e.g. only `"draft" | "published"`), use `v.object` with literal keys instead — the constraint lives in the type.
@@ -468,26 +528,40 @@ Reach for `v.record` when keys are dynamic (user-provided, dictionary-style) but
 ## `v.tuple` — positional types
 
 ```ts
-v.tuple([v.string(), v.int(), v.boolean()])  // type: [string, number, boolean]
-v.tuple([v.literal("ok"), v.string()])       // type: ["ok", string]
+v.tuple([v.string(), v.int(), v.boolean()]); // type: [string, number, boolean]
+v.tuple([v.literal("ok"), v.string()]); // type: ["ok", string]
 ```
 
 Each position has its own validator; the array length must match the tuple length. Pair with `v.literal` at position 0 for result-tuple patterns (`["ok", data]` vs `["error", message]`).
 
+Pass the validators as a literal list so each position keeps its own type, for input and validated output alike. A list typed `BaseValidator[]` (built at runtime) has no fixed positions, so its output is an array rather than a tuple.
+
 ## `v.union` — one of N validators (untagged)
 
 ```ts
-v.union([v.string(), v.int()])  // type: string | number
+v.union([v.string(), v.int()]); // type: string | number
+```
+
+Every branch whose type matches the value (`matchesType()`) is tried, in order, and the first that passes wins; the union returns that branch's validated output. `firstErrorOnly` limits the errors reported, never the branches tried, so a union of several object shapes accepts a value matching any of them:
+
+```ts
+const owner = v.object({ kind: v.literal("owner"), id: v.literal("__owner__") });
+const member = v.object({ kind: v.literal("member"), id: v.string() });
+
+await validate(v.union([owner, member]), { kind: "member", id: "x" });
+// → valid, data: { kind: "member", id: "x" }
 ```
 
-The first type-matching validator wins, picked via each branch's `matchesType()`. Use for unions of **scalar** types (string vs number, etc.) where `matchesType` is enough to disambiguate. For object-vs-object unions, reach for `v.discriminatedUnion` instead — `matchesType` can't distinguish two object branches and you'll get errors from the wrong branch.
+When no branch passes, the union reports the **closest** failed branch, picked by: fewest mismatched `v.literal(...)` fields, then fewest errors, then the deepest error path, then declaration order. Its errors keep their own paths (`actor.id`, not `actor`) and have the type `"union"` — the first one by default, all of them with `firstErrorOnly: false`. A custom `errorMessage` (`v.union([...], "Unknown actor")`), or a value no branch can hold by type, gives a single error at the union's path.
+
+For object shapes that share a tag field, `v.discriminatedUnion` is still the better fit: it routes straight to one branch instead of trying each, and narrows exactly in TypeScript.
 
 ## `v.discriminatedUnion` — tagged unions (recommended for objects)
 
 ```ts
 const email = v.object({ type: v.literal("email"), email: v.string().email() });
-const sms   = v.object({ type: v.literal("sms"),   phone: v.string() });
-const push  = v.object({ type: v.literal("push"),  deviceId: v.string() });
+const sms = v.object({ type: v.literal("sms"), phone: v.string() });
+const push = v.object({ type: v.literal("push"), deviceId: v.string() });
 
 const notif = v.discriminatedUnion("type", [email, sms, push]);
 
@@ -499,8 +573,8 @@ type Notif = Infer<typeof notif>;
 
 Routes payloads by reading the discriminator field (here `type`), looking it up in a key→branch map built at construction time, and delegating to the matching branch only. Benefits over plain `v.union`:
 
-- **Precise errors.** Failures come from the matched branch, not from every branch.
-- **O(1) routing** instead of trial-and-error.
+- **Precise errors.** Failures come from the branch the tag names, not from the closest guess.
+- **O(1) routing** instead of trying each branch.
 - **Exact TS inference** — discriminated union with narrowing inside `if (x.type === "email")` blocks.
 - **Cleaner JSON Schema** — `oneOf` with literal discriminators; OpenAI-strict accepts it.
 
@@ -538,20 +612,20 @@ Use for: trees (categories, file systems), threaded data (comment chains), mutua
 
 ## Quick map
 
-| Want | Reach for |
-| --- | --- |
-| Fixed-shape record | `v.object({...})` |
-| Dynamic keys, same value shape | `v.record(valueSchema)` |
-| List of items | `v.array(itemSchema)` |
-| Position-typed array | `v.tuple([a, b, c])` |
-| One of N scalar types | `v.union([...])` |
-| One of N object shapes with a tag field | `v.discriminatedUnion(key, [...])` |
-| Self-referencing or forward reference | `v.lazy(() => schema)` |
-| One of N constants | `v.literal(...values)` (not structural — see the `pick-seal-primitive` topic) |
+| Want                                    | Reach for                                                                     |
+| --------------------------------------- | ----------------------------------------------------------------------------- |
+| Fixed-shape record                      | `v.object({...})`                                                             |
+| Dynamic keys, same value shape          | `v.record(valueSchema)`                                                       |
+| List of items                           | `v.array(itemSchema)`                                                         |
+| Position-typed array                    | `v.tuple([a, b, c])`                                                          |
+| One of N scalar types                   | `v.union([...])`                                                              |
+| One of N object shapes with a tag field | `v.discriminatedUnion(key, [...])`                                            |
+| Self-referencing or forward reference   | `v.lazy(() => schema)`                                                        |
+| One of N constants                      | `v.literal(...values)` (not structural — see the `pick-seal-primitive` topic) |
 
 ## A note on cascade Models
 
-`@warlock.js/cascade` Models declare `static schema: ObjectValidator<TSchema>`. Passing a `v.object({...})` works directly — the factory return widens to fit the Model's invariant generic without breaking type checking. If TS complains *"`ObjectValidator<{specific}>` is not assignable to `ObjectValidator<TSchema>`"*, that's the variance trap and the answer isn't to widen the schema — it's almost always that `Model<TSchema>` was parameterized with a hand-rolled type that drifted from the schema's inferred shape. Fix the type, not the schema. See the `bridge-standard-schema` topic.
+`@warlock.js/cascade` Models declare `static schema: ObjectValidator<TSchema>`. Passing a `v.object({...})` works directly — the factory return widens to fit the Model's invariant generic without breaking type checking. If TS complains _"`ObjectValidator<{specific}>` is not assignable to `ObjectValidator<TSchema>`"_, that's the variance trap and the answer isn't to widen the schema — it's almost always that `Model<TSchema>` was parameterized with a hand-rolled type that drifted from the schema's inferred shape. Fix the type, not the schema. See the `bridge-standard-schema` topic.
 
 ## Method-surface reference
 
@@ -569,41 +643,41 @@ The inner validator runs against each element. Failure on any element fails the
 
 ## Length
 
-| Method | Args | JSON Schema | Example |
-|---|---|---|---|
-| `.min(n, msg?)` | n/a — see note below | — | use `.minLength(n)` |
-| `.minLength(n, msg?)` | inclusive lower bound | `minItems: n` | `v.array(v.string()).minLength(1)` |
-| `.maxLength(n, msg?)` | inclusive upper bound | `maxItems: n` | `v.array(v.string()).maxLength(10)` |
-| `.length(n, msg?)` | exact length | `minItems=maxItems=n` | `v.array(v.string()).length(3)` |
-| `.between(a, b, msg?)` | inclusive range | `minItems: a, maxItems: b` | `v.array(v.string()).between(1, 10)` |
-| `.lengthBetween(a, b, msg?)` | alias for `.between()` | `minItems: a, maxItems: b` | — |
+| Method                       | Args                   | JSON Schema                | Example                              |
+| ---------------------------- | ---------------------- | -------------------------- | ------------------------------------ |
+| `.min(n, msg?)`              | n/a — see note below   | —                          | use `.minLength(n)`                  |
+| `.minLength(n, msg?)`        | inclusive lower bound  | `minItems: n`              | `v.array(v.string()).minLength(1)`   |
+| `.maxLength(n, msg?)`        | inclusive upper bound  | `maxItems: n`              | `v.array(v.string()).maxLength(10)`  |
+| `.length(n, msg?)`           | exact length           | `minItems=maxItems=n`      | `v.array(v.string()).length(3)`      |
+| `.between(a, b, msg?)`       | inclusive range        | `minItems: a, maxItems: b` | `v.array(v.string()).between(1, 10)` |
+| `.lengthBetween(a, b, msg?)` | alias for `.between()` | `minItems: a, maxItems: b` | —                                    |
 
 **Note on `.min`/`.max`:** the array validator does not expose `.min`/`.max` directly — use `.minLength`/`.maxLength` (or `.between`/`.length`). This is intentional: `.min`/`.max` would conflict with primitive value-comparison semantics if they ever bled into here.
 
 ## Uniqueness & sort
 
-| Method | Args | Effect |
-|---|---|---|
-| `.unique(msg?)` | — | every element is distinct |
+| Method                      | Args                          | Effect                        |
+| --------------------------- | ----------------------------- | ----------------------------- |
+| `.unique(msg?)`             | —                             | every element is distinct     |
 | `.sorted(direction?, msg?)` | `"asc"` (default) or `"desc"` | array is monotonically sorted |
 
 ## Mutators (pre-validation reshape)
 
-| Method | Args | Effect |
-|---|---|---|
-| `.flip()` | — | reverse the array |
-| `.reverse()` | — | alias for `.flip()` |
-| `.onlyUnique()` | — | dedupe before validation |
-| `.sort(direction?, key?)` | `"asc"` (default) or `"desc"`; optional sort key for object items | sort before validation |
+| Method                    | Args                                                              | Effect                   |
+| ------------------------- | ----------------------------------------------------------------- | ------------------------ |
+| `.flip()`                 | —                                                                 | reverse the array        |
+| `.reverse()`              | —                                                                 | alias for `.flip()`      |
+| `.onlyUnique()`           | —                                                                 | dedupe before validation |
+| `.sort(direction?, key?)` | `"asc"` (default) or `"desc"`; optional sort key for object items | sort before validation   |
 
 `onlyUnique()` and `unique()` differ: the mutator silently dedupes; the rule fails when duplicates are present. Pick by intent — coerce vs reject.
 
 ## Inner validator notes
 
 ```ts
-v.array(v.string().email())              // every element must be a valid email
-v.array(userSchema)                      // every element must satisfy userSchema
-v.array(v.array(v.int()))                // matrix-ish — Infer is recursive
+v.array(v.string().email()); // every element must be a valid email
+v.array(userSchema); // every element must satisfy userSchema
+v.array(v.array(v.int())); // matrix-ish — Infer is recursive
 ```
 
 Element validators run with element-level context. `path` becomes `${parent}.${index}` for error messages. Cross-field rules inside element schemas resolve to that element's fields, not the array.
@@ -621,25 +695,25 @@ Element validators run with element-level context. `path` becomes `${parent}.${i
 
 ```ts
 // Tags
-v.array(v.string().min(1)).unique().between(1, 10)
+v.array(v.string().min(1)).unique().between(1, 10);
 
 // User list
-v.array(userSchema).minLength(1)
+v.array(userSchema).minLength(1);
 
 // Pre-sorted, deduped
-v.array(v.string()).onlyUnique().sort("asc")
+v.array(v.string()).onlyUnique().sort("asc");
 
 // Reverse-emit
-v.array(v.string()).flip()
+v.array(v.string()).flip();
 
 // Matrix
-v.array(v.array(v.number())).minLength(1)
+v.array(v.array(v.number())).minLength(1);
 
 // Sorted ids
-v.array(v.string().uuid()).sorted("asc").unique()
+v.array(v.string().uuid()).sorted("asc").unique();
 
 // Optional list with default
-v.array(v.string()).default([]).optional()
+v.array(v.string()).default([]).optional();
 ```
 
 
@@ -656,10 +730,12 @@ These return a new `ObjectValidator` with a transformed schema. The TypeScript i
 ### `.extend(schemaOrValidator)` — add fields, keep config
 
 ```ts
-const baseUser = v.object({
-  name: v.string(),
-  email: v.string().email(),
-}).allowUnknown();
+const baseUser = v
+  .object({
+    name: v.string(),
+    email: v.string().email(),
+  })
+  .allowUnknown();
 
 const adminUser = baseUser.extend({
   role: v.string().oneOf(["admin", "superadmin"]),
@@ -673,10 +749,12 @@ Accepts a plain schema object **or** another `ObjectValidator` (only its schema
 
 ```ts
 const base = v.object({ name: v.string() }).allowUnknown();
-const audit = v.object({
-  createdAt: v.date(),
-  updatedAt: v.date(),
-}).stripUnknown();
+const audit = v
+  .object({
+    createdAt: v.date(),
+    updatedAt: v.date(),
+  })
+  .stripUnknown();
 
 const merged = base.merge(audit);
 // type: { name; createdAt; updatedAt }
@@ -713,8 +791,8 @@ Returns `ObjectValidator<Omit<TSchema, K>>`. Inverse of `.pick`. Keeps original
 ### `.partial(...keys?)` — mark fields optional
 
 ```ts
-fullUser.partial()                // every field becomes optional
-fullUser.partial("password")      // only `password` becomes optional
+fullUser.partial(); // every field becomes optional
+fullUser.partial("password"); // only `password` becomes optional
 ```
 
 Walks the schema and applies `.optional()` to each named field (or all if no keys given). `Infer<>` makes those keys optional.
@@ -722,7 +800,7 @@ Walks the schema and applies `.optional()` to each named field (or all if no key
 ### `.requiredFields(...keys?)` — mark fields required
 
 ```ts
-const partialUser = fullUser.partial();    // all optional
+const partialUser = fullUser.partial(); // all optional
 const updateUser = partialUser.requiredFields("id", "email");
 // id and email are required again, others stay optional
 ```
@@ -733,29 +811,31 @@ Inverse of `.partial`.
 
 By default, extra keys in input are silently dropped from `data` (no error, no forward).
 
-| Method | Effect |
-|---|---|
-| `.allowUnknown(allow = true)` | extra **direct-child** keys forward as-is |
-| `.stripUnknown()` | explicit drop (mutator-based — affects `data` shape) |
-| `.allow(...keys)` | whitelist specific extras to forward without validation |
+| Method                        | Effect                                                  |
+| ----------------------------- | ------------------------------------------------------- |
+| `.allowUnknown(allow = true)` | extra **direct-child** keys forward as-is               |
+| `.stripUnknown()`             | explicit drop (mutator-based — affects `data` shape)    |
+| `.allow(...keys)`             | whitelist specific extras to forward without validation |
 
 `.allowUnknown()` only affects direct children — nested objects keep their own policies. For a fully permissive object including nested children, set `.allowUnknown()` on each level.
 
 ### Output DTOs — stripping extras instead of rejecting them
 
-The default is to **reject** unknown keys, which is what you want for inbound payloads. For an *outbound* DTO — where the record legitimately carries internal fields you simply don't want to expose — use `.stripUnknown()`, which drops them and returns the clean object:
+The default is to **reject** unknown keys, which is what you want for inbound payloads. For an _outbound_ DTO — where the record legitimately carries internal fields you simply don't want to expose — use `.stripUnknown()`, which drops them and returns the clean object:
 
 ```ts
-const publicArticle = v.object({
-  id: v.string(),
-  title: v.string(),
-}).stripUnknown();
+const publicArticle = v
+  .object({
+    id: v.string(),
+    title: v.string(),
+  })
+  .stripUnknown();
 
 const { isValid, data } = await v.validate(publicArticle, record);
 // record had version / authorId / status; data has only id + title
 ```
 
-Without `.stripUnknown()` the same record fails with *"The schema contains unknown keys: …"* rather than being cleaned.
+Without `.stripUnknown()` the same record fails with _"The schema contains unknown keys: …"_ rather than being cleaned.
 
 :::note[`data` is `undefined` on failure — since 4.9.2]
 A failed validation returns `data: undefined`, never the input it rejected. Before 4.9.2 an `object` returned the raw input on failure (while `discriminatedUnion` returned `undefined`), so a caller who read `data` without branching on `isValid` forwarded the exact fields the schema existed to exclude. Always branch on `isValid`.
@@ -763,8 +843,8 @@ A failed validation returns `data: undefined`, never the input it rejected. Befo
 
 ## Object-level mutators
 
-| Method | Args | Effect |
-|---|---|---|
+| Method              | Args           | Effect                                           |
+| ------------------- | -------------- | ------------------------------------------------ |
 | `.trim(recursive?)` | default `true` | recursively trim string values across the object |
 
 For per-field mutators, attach on the field validator instead.
@@ -777,7 +857,7 @@ The cross-field methods (`.sameAs`, `.requiredIf`, `.requiredWith`, etc.) are **
 v.object({
   password: v.string(),
   passwordConfirm: v.string().sameAs("password"),
-})
+});
 ```
 
 If you call cross-field rules outside a `v.object`, sibling resolution silently passes — there's nobody to compare against.
@@ -785,7 +865,7 @@ If you call cross-field rules outside a `v.object`, sibling resolution silently
 ## `Infer<>` semantics
 
 ```ts
-Infer<typeof userSchema>
+Infer<typeof userSchema>;
 // { reqField: T; optField?: T }
 ```
 
@@ -818,10 +898,12 @@ const timestamps = v.object({
 const userWithAudit = baseUser.extend(timestamps);
 
 // Permissive container that forwards extras
-const eventEnvelope = v.object({
-  type: v.literal("user.created", "user.updated"),
-  payload: v.object({}).allowUnknown(),
-}).allowUnknown();
+const eventEnvelope = v
+  .object({
+    type: v.literal("user.created", "user.updated"),
+    payload: v.object({}).allowUnknown(),
+  })
+  .allowUnknown();
 
 // Confirmation pattern with omit
 const signupSchema = v.object({
@@ -858,7 +940,7 @@ Seal exposes a plugin system so you can add validator methods without forking th
 import type { SealPlugin } from "@warlock.js/seal";
 
 type SealPlugin = {
-  name: string;          // unique identifier — duplicates warn and skip install
+  name: string; // unique identifier — duplicates warn and skip install
   version?: string;
   description?: string;
   install: (context: { name: string; version?: string }) => void | Promise<void>;
@@ -896,8 +978,8 @@ import { registerPlugin, unregisterPlugin, hasPlugin, getInstalledPlugins } from
 await registerPlugin(slugPlugin);
 // console.warn if "slug" is already installed; otherwise install() runs and the plugin is tracked.
 
-hasPlugin("slug");           // → true
-getInstalledPlugins();       // → [slugPlugin]
+hasPlugin("slug"); // → true
+getInstalledPlugins(); // → [slugPlugin]
 
 await unregisterPlugin("slug");
 // runs slugPlugin.uninstall?.(); removes from registry.
@@ -1000,8 +1082,8 @@ For a method that creates a **new validator** (not chained from an existing one)
 ## Introspection — checking what's loaded
 
 ```ts
-hasPlugin("slug");                 // boolean
-getInstalledPlugins();             // SealPlugin[]
+hasPlugin("slug"); // boolean
+getInstalledPlugins(); // SealPlugin[]
 ```
 
 Use these in startup diagnostics or in tests that need to assert a plugin is registered before exercising a method that depends on it.
@@ -1014,6 +1096,40 @@ Use these in startup diagnostics or in tests that need to assert a plugin is reg
 - Don't ship a plugin that overrides a built-in method without a clear reason. If you must, `uninstall` should restore the original — but the better path is a different method name.
 - Don't author one plugin per method. Group related methods (e.g. "country-specific validators") into one plugin so the install/uninstall lifecycle is coherent.
 
+## Returning validated rule output
+
+A custom rule's success result can contain `data` to replace the current value:
+`{ isValid: true, data: replacement }`. Later rules, transformers and refinements
+receive that replacement. Omitting `data` preserves the current value; a present
+`data: undefined` explicitly clears it. This is also how a union preserves the
+selected branch's validated defaults, catches and child transformations.
+
+## Reporting several errors from one rule
+
+A failed rule result can carry `errors: [{ error, path }, ...]` to report more than
+one error, each at its own path; every entry gets the rule's `name` as its `type`.
+`v.union` uses this to relay the closest branch's errors. Return as many as fit the
+caller's `context.configurations?.firstErrorOnly` (default `true`: one).
+
+```ts
+import { invalidRule, type SchemaRule } from "@warlock.js/seal";
+
+const bothDates: SchemaRule = {
+  name: "bothDates",
+  async validate(value: { from?: unknown; to?: unknown }, context) {
+    const missing = (["from", "to"] as const).filter((key) => !value?.[key]);
+    if (missing.length === 0) return { isValid: true };
+
+    const failed = invalidRule(this, context);
+    const errors = missing.map((key) => ({
+      error: `The ${key} date is required`,
+      path: context.path ? `${context.path}.${key}` : key,
+    }));
+    return { ...failed, errors };
+  },
+};
+```
+
 
 ## generate-json-schema  `@warlock.js/seal/generate-json-schema/SKILL.md`
 
@@ -1048,19 +1164,19 @@ userSchema.toJsonSchema("draft-2020-12");
 
 ```ts
 type JsonSchemaTarget =
-  | "draft-2020-12"  // default — modern JSON Schema
-  | "draft-07"       // older tooling, Swagger 2.0
-  | "openapi-3.0"    // uses { nullable: true } instead of type unions
-  | "openai-strict"  // OpenAI Structured Outputs strict mode
+  | "draft-2020-12" // default — modern JSON Schema
+  | "draft-07" // older tooling, Swagger 2.0
+  | "openapi-3.0" // uses { nullable: true } instead of type unions
+  | "openai-strict"; // OpenAI Structured Outputs strict mode
 ```
 
 Pick by consumer:
 
-| Consumer | Target |
-| --- | --- |
-| Modern tooling, no specific reason otherwise | `"draft-2020-12"` |
-| Swagger 2.0 / older OpenAPI / older form builders | `"draft-07"` |
-| OpenAPI 3.0 spec (uses `nullable: true`) | `"openapi-3.0"` |
+| Consumer                                                        | Target            |
+| --------------------------------------------------------------- | ----------------- |
+| Modern tooling, no specific reason otherwise                    | `"draft-2020-12"` |
+| Swagger 2.0 / older OpenAPI / older form builders               | `"draft-07"`      |
+| OpenAPI 3.0 spec (uses `nullable: true`)                        | `"openapi-3.0"`   |
 | OpenAI `response_format: { type: "json_schema", strict: true }` | `"openai-strict"` |
 
 ## OpenAI structured outputs (`openai-strict`)
@@ -1141,8 +1257,8 @@ Cleanly mapped:
 
 Some seal constructs have no JSON Schema representation:
 
-- **Cross-field rules** (`sameAs`, `requiredIf`, `requiredWith`, etc.) — runtime-only. The generated schema describes the *shape*, not the inter-field invariants.
-- **Transformers and mutators** — output reshaping doesn't appear in the schema; the schema reflects *post-mutator, pre-transformer* shape (since that's what rules see and what the LLM is asked to produce for `openai-strict`).
+- **Cross-field rules** (`sameAs`, `requiredIf`, `requiredWith`, etc.) — runtime-only. The generated schema describes the _shape_, not the inter-field invariants.
+- **Transformers and mutators** — output reshaping doesn't appear in the schema; the schema reflects _post-mutator, pre-transformer_ shape (since that's what rules see and what the LLM is asked to produce for `openai-strict`).
 - **`v.computed` / `v.managed`** — **skipped** entirely by the parent `v.object`; they never appear in `properties`. They aren't part of the data contract. (Calling `.toJsonSchema()` directly on one throws — the parent object is responsible for skipping them.)
 - **`v.instanceof(Ctor)`** — produces `{}`. Class identity isn't expressible. For `File`, attach `{ type: "string", format: "binary" }` manually after generation if needed for OpenAPI.
 - **`v.any()`** — produces `{}` deliberately (any value is valid).
@@ -1151,10 +1267,10 @@ Boolean rules `accepted` / `declined` and similar coercion-style rules are also
 
 ## When the generated schema rejects valid data
 
-If the schema validator itself accepts data but the *generated* JSON Schema rejects the same data downstream, the cause is usually one of:
+If the schema validator itself accepts data but the _generated_ JSON Schema rejects the same data downstream, the cause is usually one of:
 
 - **Cross-field rule.** The generated schema doesn't enforce it, but a separate consumer might. (Or the runtime check fired at a different stage.)
-- **Transformer running on the wrong side.** The schema describes the input shape (or strict-mode normalized form). If your transformer reshapes `Date` to ISO string for `data`, the *input* still needs to be a Date-parseable thing.
+- **Transformer running on the wrong side.** The schema describes the input shape (or strict-mode normalized form). If your transformer reshapes `Date` to ISO string for `data`, the _input_ still needs to be a Date-parseable thing.
 - **`openai-strict` quirk.** Optional fields show as `["T", "null"]` rather than omitted — if the model omits them entirely (without sending `null`), strict mode fails. The fix is on the prompt side: tell the model to send `null` for unused fields.
 
 ## Cost note
@@ -1171,19 +1287,17 @@ description: 'Read `ValidationResult` — `isValid`, `errors[]`, `data`. Branch
 
 # `ValidationResult` — reading errors
 
-`validate(schema, data)` never throws. It returns a `ValidationResult`:
+`validate(schema, data)` never throws. It returns a result narrowed on `isValid`:
 
 ```ts
-type ValidationResult = {
-  isValid: boolean;
-  data: any;             // shape after mutators + transformers (the validated value)
-  errors: ValidationError[];
-};
+type TypedValidationResult<TData> =
+  | { isValid: true; data: TData; errors: ValidationError[] } // TData = Infer.Output<typeof schema>
+  | { isValid: false; data: undefined; errors: ValidationError[] };
 
 type ValidationError = {
-  type: string;          // rule type that failed — "required", "email", "min", "string", ...
-  error: string;         // resolved message (translated, with attribute substitution)
-  input: string;         // input field name — "email" or "address.city"
+  type: string; // rule type that failed — "required", "email", "min", "string", ...
+  error: string; // resolved message (translated, with attribute substitution)
+  input: string; // input field name — "email" or "address.city"
 };
 ```
 
@@ -1202,7 +1316,7 @@ const schema = v.object({
 const result = await validate(schema, input);
 
 if (result.isValid) {
-  return result.data;  // typed as the inferred shape (post-transformer)
+  return result.data; // typed as the inferred shape (post-transformer)
 }
 
 return {
@@ -1217,15 +1331,13 @@ return {
 const result = await validate(schema, input);
 
 if (!result.isValid) {
-  const emailMissing = result.errors.find(
-    e => e.input === "email" && e.type === "required",
-  );
+  const emailMissing = result.errors.find((e) => e.input === "email" && e.type === "required");
   if (emailMissing) {
     return { redirect: "/signup", reason: "no email" };
   }
 
   const ageInvalid = result.errors.find(
-    e => e.input === "age" && (e.type === "int" || e.type === "min"),
+    (e) => e.input === "age" && (e.type === "int" || e.type === "min"),
   );
   if (ageInvalid) {
     return { error: "Age must be 13 or older" };
@@ -1241,18 +1353,20 @@ These are the strings you'll see in `error.type`:
 
 The `type` is the rule's own `name` field — not the method you called. Several methods map to one shared rule name (e.g. `.min()` / `.minLength()` on a string both surface as `minLength`; `.sameAs()` surfaces as `equalsField`). The table below lists the actual `type` strings:
 
-| Type | Produced by |
-| --- | --- |
-| `required`, `present` | `.required()`, `.present()` (note: `.optional()` has no error type — it clears the required rule) |
-| `requiredIf`, `requiredWith`, `requiredWithout`, `requiredUnless` | conditional required methods |
-| `string`, `number`, `int`, `float`, `boolean`, `scalar`, `object`, `array`, `date` | type guards from `matchesType` |
-| `minLength`, `maxLength`, `betweenLength`, `length` | string / array length rules (`.min`/`.max` on a string alias to `minLength`/`maxLength`) |
-| `min`, `max`, `betweenNumbers` | number range rules (`.min`/`.max`/`.between` on a number) |
-| `email`, `url`, `uuid`, `pattern`, `matches` | string format rules (`.pattern()` → `pattern`) |
-| `literal`, `enum`, `in`, `allowedValues`, `notAllowedValues` | value-membership rules (`.oneOf` aliases `in`; `.notIn`/`.forbids` → `notAllowedValues`; `.allowsOnly` → `allowedValues`) |
-| `instanceof` | `v.instanceof(Ctor)` |
-| `equalsField`, `notEqualsField` | cross-field equality (`.sameAs` → `equalsField`; `.differentFrom` → `notEqualsField`) |
-| `minDate`, `maxDate`, `beforeField`, `afterField`, `today`, `past`, `future`, `weekDay`, `weekend`, `businessDay`, `birthday` | date rules (`.min`/`.max` → `minDate`/`maxDate`; `.before`/`.after` → `beforeField`/`afterField`) |
+| Type                                                                                                                          | Produced by                                                                                                               |
+| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `required`, `present`                                                                                                         | `.required()`, `.present()` (note: `.optional()` has no error type — it clears the required rule)                         |
+| `requiredIf`, `requiredWith`, `requiredWithout`, `requiredUnless`                                                             | conditional required methods                                                                                              |
+| `string`, `number`, `int`, `float`, `boolean`, `scalar`, `object`, `array`, `date`                                            | type guards from `matchesType`                                                                                            |
+| `minLength`, `maxLength`, `betweenLength`, `length`                                                                           | string / array length rules (`.min`/`.max` on a string alias to `minLength`/`maxLength`)                                  |
+| `min`, `max`, `betweenNumbers`                                                                                                | number range rules (`.min`/`.max`/`.between` on a number)                                                                 |
+| `email`, `url`, `uuid`, `pattern`, `matches`                                                                                  | string format rules (`.pattern()` → `pattern`)                                                                            |
+| `literal`, `enum`, `in`, `allowedValues`, `notAllowedValues`                                                                  | value-membership rules (`.oneOf` aliases `in`; `.notIn`/`.forbids` → `notAllowedValues`; `.allowsOnly` → `allowedValues`) |
+| `instanceof`                                                                                                                  | `v.instanceof(Ctor)`                                                                                                      |
+| `equalsField`, `notEqualsField`                                                                                               | cross-field equality (`.sameAs` → `equalsField`; `.differentFrom` → `notEqualsField`)                                     |
+| `minDate`, `maxDate`, `beforeField`, `afterField`, `today`, `past`, `future`, `weekDay`, `weekend`, `businessDay`, `birthday` | date rules (`.min`/`.max` → `minDate`/`maxDate`; `.before`/`.after` → `beforeField`/`afterField`)                         |
+
+`v.union(...)` reports `union`: when no branch passes, it relays the closest branch's errors (fewest mismatched literals, then fewest errors, then deepest path) at their own paths, all typed `union`. A custom rule can do the same by returning `errors: [{ error, path }, ...]` with its failed result.
 
 If you write custom rules, the `type` name you set on the rule object is what shows up here. Pick stable, kebab-or-camel-case names — they become a public API.
 
@@ -1284,7 +1398,7 @@ For attribute display names ("email" → "Email Address"), use `.attributes({ em
 
 ## When to throw
 
-Don't wrap `validate()` in try/catch for *validation* failures — those land in `result.errors`. The only thing that *throws* is a programming bug:
+Don't wrap `validate()` in try/catch for _validation_ failures — those land in `result.errors`. The only thing that _throws_ is a programming bug:
 
 - A rule's callback threw (e.g. you wrote `async validate() { throw new Error(...) }`).
 - A transformer threw on output.
@@ -1300,7 +1414,7 @@ If you're surfacing seal errors through HTTP / RPC, the typical shape is:
 if (!result.isValid) {
   return reply.code(422).send({
     error: "validation_failed",
-    fields: result.errors.map(e => ({
+    fields: result.errors.map((e) => ({
       field: e.input,
       type: e.type,
       message: e.error,
@@ -1323,7 +1437,7 @@ description: "@warlock.js/seal overview for orientation and choosing the focused
 
 # `@warlock.js/seal` — overview
 
-A type-safe, framework-agnostic validation library. You build a schema with the `v` factory, run it with `validate(schema, data)`, and pull the static type out with `Infer<typeof schema>`. One schema is the runtime check *and* the TypeScript type *and* (optionally) a JSON Schema.
+A type-safe, framework-agnostic validation library. You build a schema with the `v` factory, run it with `validate(schema, data)`, and pull the static type out with `Infer<typeof schema>`. One schema is the runtime check _and_ the TypeScript type _and_ (optionally) a JSON Schema.
 
 Standalone — no framework required. Ships built-in with `@warlock.js/core`, which adds framework-specific validators (file uploads, database existence/uniqueness rules) on top.
 
@@ -1346,31 +1460,39 @@ Eight task skills. Most schemas only need `seal-basics` + `pick-seal-primitive`
 ### Foundations
 
 #### `seal-basics`
+
 Start here. The `v` factory, `validate(schema, data)`, and `Infer<typeof schema>`.
 
 ### Building schemas
 
 #### `pick-seal-primitive`
+
 Choose the right primitive — `string` / `int` / `literal` / `date` / `enum` / `computed` / `managed` / `instanceof` / `any`. Covers the close calls (`string` vs `scalar`, `int` vs `number`, `literal` vs `enum`).
 
 #### `define-structural-shape`
+
 Compose `v.object` / `v.array` / `v.record` / `v.tuple` / `v.union` / `v.discriminatedUnion` / `v.lazy` — object schemas, dynamic-keyed records, tagged unions, recursive shapes.
 
 #### `compose-seal-modifiers`
+
 Cross-cutting modifiers — `.optional` / `.nullable` / `.default` / `.catch` / `.omit` / membership rules — plus the mutator-vs-transformer pipeline and `Infer.Input` vs `Infer.Output`.
 
 ### Output + interop
 
 #### `handle-seal-errors`
+
 Read a `ValidationResult` — `isValid`, `errors[]`, `data`. Branch on `error.type`, customize messages, hook translation.
 
 #### `generate-json-schema`
+
 `schema.toJsonSchema(target)` — draft-2020-12 / draft-07 / openapi-3.0 / openai-strict. For OpenAI structured outputs, OpenAPI specs, any JSON-Schema consumer.
 
 #### `bridge-standard-schema`
-Standard Schema interop — why a `StandardSchemaV1<T>` slot might reject a schema, the phantom-intersection at the `v` factory return, Cascade `Model<TSchema>` variance. For migrating off `as unknown as` casts.
+
+Standard Schema interop — why a `StandardSchemaV1<T>` slot might reject a schema, object input/output class parameters and primitive factory intersections, Cascade `Model<TSchema>` variance. For migrating off `as unknown as` casts.
 
 #### `extend-seal-with-plugins`
+
 Author a plugin to add validator methods (`.slug`, `.postalCode`, …) — the `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation.
 
 ## Configuration
@@ -1399,25 +1521,25 @@ description: 'Pick the right `v` factory primitive — string / int / literal /
 
 # Picking the right primitive
 
-This is the orientation skill — *which* primitive for *which* job. For the chainable methods on each (`.email()`, `.min()`, `.between()`, etc.), load the matching `*-methods.md` reference file in this skill folder.
+This is the orientation skill — _which_ primitive for _which_ job. For the chainable methods on each (`.email()`, `.min()`, `.between()`, etc.), load the matching `*-methods.md` reference file in this skill folder.
 
 ## Strings
 
 ```ts
-v.string()              // type: string — full surface in string-methods.md
-v.email()               // shorthand for v.string().email()
-v.enum(["a", "b"])      // type: "a" | "b" — runs as v.string().oneOf, but the factory overload preserves the literal union
+v.string(); // type: string — full surface in string-methods.md
+v.email(); // shorthand for v.string().email()
+v.enum(["a", "b"]); // type: "a" | "b" — runs as v.string().oneOf, but the factory overload preserves the literal union
 ```
 
 Reach for `v.string()` for any text input. `v.email()` is just sugar — switch back to `v.string().email().min(...)` when you need extra rules.
 
 ## Numbers — pick by what you accept
 
-| Validator | Accepts | When |
-|---|---|---|
-| `v.number()` | any finite number | accepts both integers and floats |
-| `v.int()` | integers only | rejects `1.5` |
-| `v.float()` | finite, non-integer | rejects `1` |
+| Validator     | Accepts                   | When                                                        |
+| ------------- | ------------------------- | ----------------------------------------------------------- |
+| `v.number()`  | any finite number         | accepts both integers and floats                            |
+| `v.int()`     | integers only             | rejects `1.5`                                               |
+| `v.float()`   | finite, non-integer       | rejects `1`                                                 |
 | `v.numeric()` | numeric strings + numbers | form/query inputs that arrive as `"42"` — coerces to number |
 
 All four share the same chain surface (see [`number-methods.md`](./number-methods.md)). Picking is about input acceptance, not chain power.
@@ -1425,8 +1547,8 @@ All four share the same chain surface (see [`number-methods.md`](./number-method
 ## Booleans & scalars
 
 ```ts
-v.boolean()  // type: boolean — adds .accepted() / .declined() for form-style inputs
-v.scalar()   // type: string | number | boolean — usually a smell pointing at a missing discriminator
+v.boolean(); // type: boolean — adds .accepted() / .declined() for form-style inputs
+v.scalar(); // type: string | number | boolean — usually a smell pointing at a missing discriminator
 ```
 
 Use `v.scalar()` only when the field truly accepts any of the three primitives. If it's "one of N specific values across types", `v.literal(...)` is cleaner.
@@ -1434,8 +1556,8 @@ Use `v.scalar()` only when the field truly accepts any of the three primitives.
 ## Dates
 
 ```ts
-v.date()                  // type: Date — normalizes strings/timestamps to Date, rich rule surface
-v.instanceof(Date)        // type: Date — raw instanceof, no normalization, no rules
+v.date(); // type: Date — normalizes strings/timestamps to Date, rich rule surface
+v.instanceof(Date); // type: Date — raw instanceof, no normalization, no rules
 ```
 
 `v.date()` is the right tool 99% of the time — it ships `.min/.max/.before/.after/.weekDay/.minAge/...` and a built-in mutator that parses strings. `v.instanceof(Date)` is the escape hatch when you specifically need strict instance identity with zero coercion.
@@ -1443,14 +1565,14 @@ v.instanceof(Date)        // type: Date — raw instanceof, no normalization, no
 ## Literals & instances
 
 ```ts
-v.literal("items")                          // type: "items"
-v.literal("draft", "published", "archived") // type: "draft" | "published" | "archived"
-v.literal(1, 2, 3)                          // type: 1 | 2 | 3
-v.literal(true)                             // type: true
+v.literal("items"); // type: "items"
+v.literal("draft", "published", "archived"); // type: "draft" | "published" | "archived"
+v.literal(1, 2, 3); // type: 1 | 2 | 3
+v.literal(true); // type: true
 
-v.instanceof(File)                          // type: File
-v.instanceof(Buffer)                        // type: Buffer
-v.instanceof(MyClass)                       // type: MyClass
+v.instanceof(File); // type: File
+v.instanceof(Buffer); // type: Buffer
+v.instanceof(MyClass); // type: MyClass
 ```
 
 **`v.literal` vs `v.string().oneOf([...])` vs `v.enum([...])`:**
@@ -1459,20 +1581,24 @@ v.instanceof(MyClass)                       // type: MyClass
 - `v.string().oneOf(["a", "b"])` infers as `string` (loses literal types). Use when broad type is fine.
 - `v.enum(["a", "b"])` runs the same `oneOf` rule at runtime (it builds a `StringValidator().oneOf(...)`), but the `v.enum` factory overload **preserves the literal union** — it infers `"a" | "b"`, not `string`. Pass a TS enum object (`v.enum(Direction)`) and it uses `Object.values`, inferring `Direction[keyof Direction]`.
 
-`**`v.literal("")` — the empty string is a value, not an absence.** `""` is accepted when it is one of the configured literals, and the field is still required to be *present*:
+`**`v.literal("")`— the empty string is a value, not an absence.**`""` is accepted when it is one of the configured literals, and the field is still required to be _present_:
 
 ```ts
 const decorative = v.object({ decorative: v.literal(true), alt: v.literal("") });
 
-await v.validate(decorative, { decorative: true, alt: "" });      // valid
-await v.validate(decorative, { decorative: true, alt: "text" });  // invalid — not the literal
-await v.validate(decorative, { decorative: true });               // invalid — key missing
+await v.validate(decorative, { decorative: true, alt: "" }); // valid
+await v.validate(decorative, { decorative: true, alt: "text" }); // invalid — not the literal
+await v.validate(decorative, { decorative: true }); // invalid — key missing
 ```
 
 That distinction matters wherever "empty" and "absent" mean different things — `alt=""` marks an image as decorative to a screen reader, while a missing `alt` is an authoring mistake. Add `.optional()` only when a missing key really is acceptable; a present value must still match the literal.
 
 :::note[Fixed in 4.9.2]
-Before 4.9.2 `v.literal("")` always failed with *"is required"*, and `.optional()` looked like a workaround while actually disabling the literal check — accepting `""`, `null`, and a missing key alike. `v.literal(0)` and `v.literal(false)` were never affected.
+Before 4.9.2 `v.literal("")` always failed with _"is required"_, and `.optional()` looked like a workaround while actually disabling the literal check — accepting `""`, `null`, and a missing key alike. `v.literal(0)` and `v.literal(false)` were never affected.
+:::
+
+:::note[Fixed again in 5.30]
+5.25 made a blank form value count as missing for literal and enum sets, so an unselected `<select>` reads as absent. That rule also caught `v.literal("")` from 5.25 to 5.29: the required literal rejected `""` and `.optional()` dropped it from the data. Since 5.30 a literal set that lists a blank string keeps `""` as a value in its default (implicit) required state and under `.present()`, `.optional()` and `.nullable()`; a set without one still reads a blank value as missing. An explicit `.required()` (or `requiredIf` and the other conditional rules) puts back the strict non-empty rule and rejects `""` — leave the default state in place when `""` is a valid value.
 :::
 
 `v.instanceof(Ctor)` for File/Buffer/Uint8Array/custom classes. Returns `{}` from `toJsonSchema()` (not representable). For OpenAPI `File`, attach `{ type: "string", format: "binary" }` manually after generation.
@@ -1480,7 +1606,7 @@ Before 4.9.2 `v.literal("")` always failed with *"is required"*, and `.optional(
 ## `v.any` — escape hatch
 
 ```ts
-v.any()  // type: any — skips validation entirely
+v.any(); // type: any — skips validation entirely
 ```
 
 Reach for it when you genuinely don't care about the shape. Usually a smell — search PRs for it and ask whether a real schema would catch a class of bugs.
@@ -1502,26 +1628,26 @@ v.object({
 - **`v.computed`** runs after sibling validation; callback signature is `(data, context)` — `data` is the validated sibling object. Use for derived values (full name, hash of fields, computed totals). An optional second arg validates the result: `v.computed<string>(cb, v.string().min(3))`.
 - **`v.managed`** runs from `SchemaContext` only — callback signature is `(context)`. Caller-supplied extras passed to `validate(schema, data, { context })` land on `context.context`. Use for framework-injected values — timestamps, current user, request id. The callback is optional (`v.managed()`) for values the framework injects without a generator.
 
-Both are **skipped** when their parent `v.object` generates JSON Schema — they never appear in `properties`, since they're runtime-only and not part of the JSON contract an LLM or external API consumer reads. Calling `.toJsonSchema()` *directly* on a `v.computed` / `v.managed` validator **throws** (it's a programming error — let the parent object skip them).
+Both are **skipped** when their parent `v.object` generates JSON Schema — they never appear in `properties`, since they're runtime-only and not part of the JSON contract an LLM or external API consumer reads. Calling `.toJsonSchema()` _directly_ on a `v.computed` / `v.managed` validator **throws** (it's a programming error — let the parent object skip them).
 
 ## Quick map — "I need to validate…"
 
-| Need | Reach for |
-|---|---|
-| Email | `v.string().email()` or `v.email()` |
-| URL | `v.string().url()` |
-| UUID | `v.string().uuid()` (see [`string-methods.md`](./string-methods.md)) |
-| Number 0–100 | `v.number().between(0, 100)` |
-| Positive integer | `v.int().positive()` |
-| One of N constants | `v.literal(...values)` |
-| One of TS enum values | `v.enum(MyEnum)` |
-| Date in the past | `v.date().past()` |
-| File upload | `v.instanceof(File)` |
-| Class instance (not Date) | `v.instanceof(Ctor)` |
-| Discriminated union | see the `define-structural-shape` topic |
-| Derived value (computed from siblings) | `v.computed<T>(callback)` |
-| Framework-injected value | `v.managed<T>(callback)` |
-| Free-form / pass-through | `v.any()` (only when you've thought about it) |
+| Need                                   | Reach for                                                            |
+| -------------------------------------- | -------------------------------------------------------------------- |
+| Email                                  | `v.string().email()` or `v.email()`                                  |
+| URL                                    | `v.string().url()`                                                   |
+| UUID                                   | `v.string().uuid()` (see [`string-methods.md`](./string-methods.md)) |
+| Number 0–100                           | `v.number().between(0, 100)`                                         |
+| Positive integer                       | `v.int().positive()`                                                 |
+| One of N constants                     | `v.literal(...values)`                                               |
+| One of TS enum values                  | `v.enum(MyEnum)`                                                     |
+| Date in the past                       | `v.date().past()`                                                    |
+| File upload                            | `v.instanceof(File)`                                                 |
+| Class instance (not Date)              | `v.instanceof(Ctor)`                                                 |
+| Discriminated union                    | see the `define-structural-shape` topic                              |
+| Derived value (computed from siblings) | `v.computed<T>(callback)`                                            |
+| Framework-injected value               | `v.managed<T>(callback)`                                             |
+| Free-form / pass-through               | `v.any()` (only when you've thought about it)                        |
 
 ## Method-surface reference
 
@@ -1540,7 +1666,7 @@ For cross-cutting modifiers (`.optional`/`.nullable`/`.default`/`.catch`/`.in`/`
 - Don't pick `v.scalar` because "it's flexible". Flexibility at this layer usually means a missing discriminator — try `v.literal` or `v.union` first.
 - Don't reach for `v.instanceof(Date)` when `v.date()` works. The latter is purpose-built.
 - Don't use `v.string().oneOf(["a", "b"])` for discriminator fields where you need the literal type — use `v.literal("a", "b")`.
-- Don't expect `v.computed` / `v.managed` to validate input — they ignore input shape entirely. Reach for them only when *producing* a value.
+- Don't expect `v.computed` / `v.managed` to validate input — they ignore input shape entirely. Reach for them only when _producing_ a value.
 
 
 ### pick-seal-primitive/boolean-methods.md  `@warlock.js/seal/pick-seal-primitive/boolean-methods.md`
@@ -1659,139 +1785,139 @@ v.object({
 
 ## Range — global value comparison
 
-| Method | Args | Example |
-|---|---|---|
-| `.min(dateOrField, msg?)` | inclusive `>=` | `v.date().min("2024-01-01")` or `v.date().min(new Date())` |
-| `.max(dateOrField, msg?)` | inclusive `<=` | `v.date().max(new Date())` |
-| `.before(dateOrField, msg?)` | strict `<` | `v.date().before(new Date())` |
-| `.after(dateOrField, msg?)` | strict `>` | `v.date().after(new Date())` |
-| `.between(start, end, msg?)` | inclusive range | `v.date().between(start, end)` |
+| Method                       | Args            | Example                                                    |
+| ---------------------------- | --------------- | ---------------------------------------------------------- |
+| `.min(dateOrField, msg?)`    | inclusive `>=`  | `v.date().min("2024-01-01")` or `v.date().min(new Date())` |
+| `.max(dateOrField, msg?)`    | inclusive `<=`  | `v.date().max(new Date())`                                 |
+| `.before(dateOrField, msg?)` | strict `<`      | `v.date().before(new Date())`                              |
+| `.after(dateOrField, msg?)`  | strict `>`      | `v.date().after(new Date())`                               |
+| `.between(start, end, msg?)` | inclusive range | `v.date().between(start, end)`                             |
 
 Smart detection: a string with `-` or `/` is a date string; a plain string is a sibling field name.
 
 ## Range — explicit sibling scope
 
-| Method | Effect |
-|---|---|
-| `.minSibling(field, msg?)` | `>=` sibling field |
-| `.maxSibling(field, msg?)` | `<=` sibling field |
-| `.beforeSibling(field, msg?)` | `<` sibling field |
-| `.afterSibling(field, msg?)` | `>` sibling field |
-| `.sameAsField(field, msg?)` | `===` sibling field |
+| Method                             | Effect                               |
+| ---------------------------------- | ------------------------------------ |
+| `.minSibling(field, msg?)`         | `>=` sibling field                   |
+| `.maxSibling(field, msg?)`         | `<=` sibling field                   |
+| `.beforeSibling(field, msg?)`      | `<` sibling field                    |
+| `.afterSibling(field, msg?)`       | `>` sibling field                    |
+| `.sameAsField(field, msg?)`        | `===` sibling field                  |
 | `.sameAsFieldSibling(field, msg?)` | `===` sibling field (explicit scope) |
 
 Only run inside `v.object`. Not representable in JSON Schema.
 
 ## Today / past / future
 
-| Method | Effect |
-|---|---|
-| `.today(msg?)` | exactly today |
-| `.fromToday(msg?)` | today or future |
+| Method               | Effect                |
+| -------------------- | --------------------- |
+| `.today(msg?)`       | exactly today         |
+| `.fromToday(msg?)`   | today or future       |
 | `.beforeToday(msg?)` | strictly before today |
-| `.afterToday(msg?)` | strictly after today |
-| `.past(msg?)` | any past date |
-| `.future(msg?)` | any future date |
+| `.afterToday(msg?)`  | strictly after today  |
+| `.past(msg?)`        | any past date         |
+| `.future(msg?)`      | any future date       |
 
 ## Relative window
 
-| Method | Args | Effect |
-|---|---|---|
-| `.withinDays(n, msg?)` | within N days past or future | — |
-| `.withinPastDays(n, msg?)` | within N days in the past | — |
-| `.withinFutureDays(n, msg?)` | within N days in the future | — |
+| Method                       | Args                         | Effect |
+| ---------------------------- | ---------------------------- | ------ |
+| `.withinDays(n, msg?)`       | within N days past or future | —      |
+| `.withinPastDays(n, msg?)`   | within N days in the past    | —      |
+| `.withinFutureDays(n, msg?)` | within N days in the future  | —      |
 
 ## Age
 
-| Method | Args | Effect |
-|---|---|---|
-| `.age(years, msg?)` | exactly N years old |
-| `.minAge(years, msg?)` | at least N years old |
-| `.maxAge(years, msg?)` | at most N years old |
-| `.betweenAge(min, max, msg?)` | between min/max years |
+| Method                              | Args                              | Effect |
+| ----------------------------------- | --------------------------------- | ------ |
+| `.age(years, msg?)`                 | exactly N years old               |
+| `.minAge(years, msg?)`              | at least N years old              |
+| `.maxAge(years, msg?)`              | at most N years old               |
+| `.betweenAge(min, max, msg?)`       | between min/max years             |
 | `.birthday(minAge?, maxAge?, msg?)` | not in future, optional age range |
 
 ## Weekday / weekend / business day
 
-| Method | Args | Effect |
-|---|---|---|
-| `.weekDay(day, msg?)` | day = `"monday"` … `"sunday"` |
-| `.weekdays(days, msg?)` | array of weekdays |
-| `.weekend(msg?)` | Saturday or Sunday |
-| `.businessDay(msg?)` | Monday – Friday |
+| Method                  | Args                          | Effect |
+| ----------------------- | ----------------------------- | ------ |
+| `.weekDay(day, msg?)`   | day = `"monday"` … `"sunday"` |
+| `.weekdays(days, msg?)` | array of weekdays             |
+| `.weekend(msg?)`        | Saturday or Sunday            |
+| `.businessDay(msg?)`    | Monday – Friday               |
 
 ## Period — month / year / quarter
 
-| Method | Args | Effect |
-|---|---|---|
-| `.month(m, msg?)` | `m` = 1–12 (or `Month` enum) |
-| `.year(y, msg?)` | exact year |
-| `.quarter(q, msg?)` | `q` = 1–4 |
-| `.leapYear(msg?)` | year is a leap year |
-| `.minYear(yearOrField, msg?)` | year `>=` |
-| `.maxYear(yearOrField, msg?)` | year `<=` |
-| `.minMonth(mOrField, msg?)` | month `>=` |
-| `.maxMonth(mOrField, msg?)` | month `<=` |
-| `.minDay(dOrField, msg?)` | day-of-month `>=` |
-| `.maxDay(dOrField, msg?)` | day-of-month `<=` |
-| `.betweenYears(start, end, msg?)` | inclusive year range |
-| `.betweenMonths(start, end, msg?)` | inclusive month range |
-| `.betweenDays(start, end, msg?)` | inclusive day-of-month range |
+| Method                             | Args                         | Effect |
+| ---------------------------------- | ---------------------------- | ------ |
+| `.month(m, msg?)`                  | `m` = 1–12 (or `Month` enum) |
+| `.year(y, msg?)`                   | exact year                   |
+| `.quarter(q, msg?)`                | `q` = 1–4                    |
+| `.leapYear(msg?)`                  | year is a leap year          |
+| `.minYear(yearOrField, msg?)`      | year `>=`                    |
+| `.maxYear(yearOrField, msg?)`      | year `<=`                    |
+| `.minMonth(mOrField, msg?)`        | month `>=`                   |
+| `.maxMonth(mOrField, msg?)`        | month `<=`                   |
+| `.minDay(dOrField, msg?)`          | day-of-month `>=`            |
+| `.maxDay(dOrField, msg?)`          | day-of-month `<=`            |
+| `.betweenYears(start, end, msg?)`  | inclusive year range         |
+| `.betweenMonths(start, end, msg?)` | inclusive month range        |
+| `.betweenDays(start, end, msg?)`   | inclusive day-of-month range |
 
 Each `min*` / `max*` / `between*` accepts a sibling field name. Sibling-explicit variants exist: `.minYearSibling`, `.maxYearSibling`, `.minMonthSibling`, `.maxMonthSibling`, `.minDaySibling`, `.maxDaySibling`, `.betweenYearsSibling`, `.betweenMonthsSibling`, `.betweenDaysSibling`.
 
 ## Time — hour / minute
 
-| Method | Args | Effect |
-|---|---|---|
-| `.fromHour(h, msg?)` | h = 0–23, time `>= h:00` |
-| `.beforeHour(h, msg?)` | time `< h:00` |
-| `.betweenHours(start, end, msg?)` | inclusive hour range |
-| `.fromMinute(m, msg?)` | m = 0–59 |
-| `.beforeMinute(m, msg?)` | — |
-| `.betweenMinutes(start, end, msg?)` | inclusive minute range |
-| `.betweenTimes(start, end, msg?)` | "HH:MM" strings |
+| Method                              | Args                     | Effect |
+| ----------------------------------- | ------------------------ | ------ |
+| `.fromHour(h, msg?)`                | h = 0–23, time `>= h:00` |
+| `.beforeHour(h, msg?)`              | time `< h:00`            |
+| `.betweenHours(start, end, msg?)`   | inclusive hour range     |
+| `.fromMinute(m, msg?)`              | m = 0–59                 |
+| `.beforeMinute(m, msg?)`            | —                        |
+| `.betweenMinutes(start, end, msg?)` | inclusive minute range   |
+| `.betweenTimes(start, end, msg?)`   | "HH:MM" strings          |
 
 ## Format
 
-| Method | Args | Effect |
-|---|---|---|
+| Method               | Args                | Effect                      |
+| -------------------- | ------------------- | --------------------------- |
 | `.format(fmt, msg?)` | dayjs format string | input must match the format |
 
 ## Mutators (pre-validation reshape)
 
-| Method | Effect |
-|---|---|
-| `.toStartOfDay()` | 00:00:00.000 |
-| `.toEndOfDay()` | 23:59:59.999 |
-| `.toStartOfMonth()` | first day of month |
-| `.toEndOfMonth()` | last day of month |
-| `.toStartOfYear()` | January 1st |
-| `.toEndOfYear()` | December 31st |
-| `.addDays(n)` | shift by N days (negative = back) |
-| `.addMonths(n)` | shift by N months |
-| `.addYears(n)` | shift by N years |
-| `.addHours(n)` | shift by N hours |
-| `.toUTC()` | normalize to UTC |
-
-Mutators run *before* rules. `v.date().addDays(7).future()` checks whether the shifted date is in the future.
+| Method              | Effect                            |
+| ------------------- | --------------------------------- |
+| `.toStartOfDay()`   | 00:00:00.000                      |
+| `.toEndOfDay()`     | 23:59:59.999                      |
+| `.toStartOfMonth()` | first day of month                |
+| `.toEndOfMonth()`   | last day of month                 |
+| `.toStartOfYear()`  | January 1st                       |
+| `.toEndOfYear()`    | December 31st                     |
+| `.addDays(n)`       | shift by N days (negative = back) |
+| `.addMonths(n)`     | shift by N months                 |
+| `.addYears(n)`      | shift by N years                  |
+| `.addHours(n)`      | shift by N hours                  |
+| `.toUTC()`          | normalize to UTC                  |
+
+Mutators run _before_ rules. `v.date().addDays(7).future()` checks whether the shifted date is in the future.
 
 ## Transformers (post-validation, reshape `data`)
 
-| Method | Args | Effect |
-|---|---|---|
-| `.toISOString()` | — | `Date` → `"2026-01-15T00:00:00.000Z"` |
-| `.toTimestamp()` | — | `Date` → number (ms since epoch) |
-| `.toFormat(fmt)` | dayjs format string | `Date` → formatted string |
-| `.toDateOnly()` | — | `"YYYY-MM-DD"` |
-| `.toTimeOnly()` | — | `"HH:mm:ss"` |
+| Method           | Args                | Effect                                |
+| ---------------- | ------------------- | ------------------------------------- |
+| `.toISOString()` | —                   | `Date` → `"2026-01-15T00:00:00.000Z"` |
+| `.toTimestamp()` | —                   | `Date` → number (ms since epoch)      |
+| `.toFormat(fmt)` | dayjs format string | `Date` → formatted string             |
+| `.toDateOnly()`  | —                   | `"YYYY-MM-DD"`                        |
+| `.toTimeOnly()`  | —                   | `"HH:mm:ss"`                          |
 
-Transformers shape the *output*. `Infer<>` still resolves to `Date` even if a transformer changes the runtime shape — `Infer` reads the validator type, not the transformer pipeline.
+Transformers shape the _output_. `Infer<>` still resolves to `Date` even if a transformer changes the runtime shape — `Infer` reads the validator type, not the transformer pipeline.
 
 ## Defaults
 
-| Method | Effect |
-|---|---|
+| Method          | Effect                                     |
+| --------------- | ------------------------------------------ |
 | `.defaultNow()` | shorthand for `.default(() => new Date())` |
 
 ## JSON Schema mapping
@@ -1805,28 +1931,28 @@ Transformers shape the *output*. `Infer<>` still resolves to `Date` even if a tr
 
 ```ts
 // Birthday — must be 13+ and in the past
-v.date().past().minAge(13)
+v.date().past().minAge(13);
 
 // Reservation — future, business day, between hours
-v.date().future().businessDay().betweenHours(9, 17)
+v.date().future().businessDay().betweenHours(9, 17);
 
 // Effective date range (cross-field)
 v.object({
   startsAt: v.date(),
   endsAt: v.date().afterSibling("startsAt"),
-})
+});
 
 // API response — emit ISO string
-v.date().toISOString()
+v.date().toISOString();
 
 // Event window — within 30 future days, normalized to UTC
-v.date().toUTC().withinFutureDays(30)
+v.date().toUTC().withinFutureDays(30);
 
 // Quarterly report
-v.date().quarter(1).year(2026)
+v.date().quarter(1).year(2026);
 
 // Date-only, end-of-day for inclusive comparisons
-v.date().toEndOfDay().toDateOnly()
+v.date().toEndOfDay().toDateOnly();
 ```
 
 
@@ -1838,23 +1964,23 @@ All four share this surface. The picking guide (which factory to call) is in the
 
 ## Range — global value comparison
 
-| Method | Args | JSON Schema | Example |
-|---|---|---|---|
-| `.min(n, msg?)` | inclusive lower bound | `minimum: n` | `v.int().min(0)` |
-| `.max(n, msg?)` | inclusive upper bound | `maximum: n` | `v.int().max(100)` |
-| `.between(a, b, msg?)` | inclusive range | `minimum: a, maximum: b` | `v.number().between(0, 1)` |
-| `.greaterThan(n, msg?)` | strict `>` | `exclusiveMinimum: n` | `v.int().greaterThan(0)` |
-| `.gt(n, msg?)` | alias for `.greaterThan` | `exclusiveMinimum: n` | — |
-| `.lessThan(n, msg?)` | strict `<` | `exclusiveMaximum: n` | `v.int().lessThan(100)` |
-| `.lt(n, msg?)` | alias for `.lessThan` | `exclusiveMaximum: n` | — |
+| Method                  | Args                     | JSON Schema              | Example                    |
+| ----------------------- | ------------------------ | ------------------------ | -------------------------- |
+| `.min(n, msg?)`         | inclusive lower bound    | `minimum: n`             | `v.int().min(0)`           |
+| `.max(n, msg?)`         | inclusive upper bound    | `maximum: n`             | `v.int().max(100)`         |
+| `.between(a, b, msg?)`  | inclusive range          | `minimum: a, maximum: b` | `v.number().between(0, 1)` |
+| `.greaterThan(n, msg?)` | strict `>`               | `exclusiveMinimum: n`    | `v.int().greaterThan(0)`   |
+| `.gt(n, msg?)`          | alias for `.greaterThan` | `exclusiveMinimum: n`    | —                          |
+| `.lessThan(n, msg?)`    | strict `<`               | `exclusiveMaximum: n`    | `v.int().lessThan(100)`    |
+| `.lt(n, msg?)`          | alias for `.lessThan`    | `exclusiveMaximum: n`    | —                          |
 
 `.min` / `.max` / `.between` / `.greaterThan` / `.lessThan` accept a **string** as the value — interpreted as a sibling field name (smart detection):
 
 ```ts
 v.object({
   minPrice: v.int(),
-  maxPrice: v.int().min("minPrice"),  // maxPrice >= minPrice
-})
+  maxPrice: v.int().min("minPrice"), // maxPrice >= minPrice
+});
 ```
 
 Sibling references are **not representable in JSON Schema** — silently omitted from generated output.
@@ -1863,68 +1989,68 @@ Sibling references are **not representable in JSON Schema** — silently omitted
 
 For when smart detection is ambiguous (e.g. a numeric string that happens to match a field name):
 
-| Method | Effect |
-|---|---|
-| `.minSibling(field, msg?)` | value `>=` sibling field |
-| `.maxSibling(field, msg?)` | value `<=` sibling field |
-| `.greaterThanSibling(field, msg?)` | value `>` sibling field |
-| `.gtSibling(field, msg?)` | alias |
-| `.lessThanSibling(field, msg?)` | value `<` sibling field |
-| `.ltSibling(field, msg?)` | alias |
+| Method                                      | Effect                     |
+| ------------------------------------------- | -------------------------- |
+| `.minSibling(field, msg?)`                  | value `>=` sibling field   |
+| `.maxSibling(field, msg?)`                  | value `<=` sibling field   |
+| `.greaterThanSibling(field, msg?)`          | value `>` sibling field    |
+| `.gtSibling(field, msg?)`                   | alias                      |
+| `.lessThanSibling(field, msg?)`             | value `<` sibling field    |
+| `.ltSibling(field, msg?)`                   | alias                      |
 | `.betweenSibling(minField, maxField, msg?)` | between two sibling fields |
 
 These **only run inside `v.object`** — sibling resolution silently passes otherwise.
 
 ## Sign & parity
 
-| Method | Effect | Example |
-|---|---|---|
-| `.positive(msg?)` | value `> 0` | `v.int().positive()` |
-| `.negative(msg?)` | value `< 0` | `v.int().negative()` |
-| `.odd(msg?)` | value is odd | `v.int().odd()` |
-| `.even(msg?)` | value is even | `v.int().even()` |
+| Method            | Effect        | Example              |
+| ----------------- | ------------- | -------------------- |
+| `.positive(msg?)` | value `> 0`   | `v.int().positive()` |
+| `.negative(msg?)` | value `< 0`   | `v.int().negative()` |
+| `.odd(msg?)`      | value is odd  | `v.int().odd()`      |
+| `.even(msg?)`     | value is even | `v.int().even()`     |
 
 ## Divisibility / modulo
 
-| Method | Effect | JSON Schema |
-|---|---|---|
-| `.modulo(n, msg?)` | value `% n === 0` | `multipleOf: n` |
-| `.divisibleBy(n, msg?)` | alias | `multipleOf: n` |
-| `.multipleOf(n, msg?)` | alias | `multipleOf: n` |
-| `.modulusOf(n, msg?)` | alias | `multipleOf: n` |
+| Method                  | Effect            | JSON Schema     |
+| ----------------------- | ----------------- | --------------- |
+| `.modulo(n, msg?)`      | value `% n === 0` | `multipleOf: n` |
+| `.divisibleBy(n, msg?)` | alias             | `multipleOf: n` |
+| `.multipleOf(n, msg?)`  | alias             | `multipleOf: n` |
+| `.modulusOf(n, msg?)`   | alias             | `multipleOf: n` |
 
 ## String-form length (rare)
 
 When the numeric value is a fixed-format code (PINs, IDs):
 
-| Method | Effect |
-|---|---|
-| `.length(n, msg?)` | string-rep length must be exactly `n` |
-| `.minLength(n, msg?)` | string-rep length `>= n` |
-| `.maxLength(n, msg?)` | string-rep length `<= n` |
+| Method                | Effect                                |
+| --------------------- | ------------------------------------- |
+| `.length(n, msg?)`    | string-rep length must be exactly `n` |
+| `.minLength(n, msg?)` | string-rep length `>= n`              |
+| `.maxLength(n, msg?)` | string-rep length `<= n`              |
 
 For most numeric-shaped IDs you'd use `v.string().length(n).numeric()` instead — let the value be a string.
 
 ## Mutators (pre-validation reshape)
 
-| Method | Args | Effect |
-|---|---|---|
-| `.abs()` | — | `Math.abs(value)` |
-| `.ceil()` | — | round up to integer |
-| `.floor()` | — | round down to integer |
-| `.round(decimals?)` | default 0 | round to N decimals |
-| `.toFixed(decimals?)` | default 2 | round to N decimals — returns a **number** |
-| `.coerce()` | — | a **numeric-shaped string** → `Number`; any other value passes through unchanged |
+| Method                | Args      | Effect                                                                           |
+| --------------------- | --------- | -------------------------------------------------------------------------------- |
+| `.abs()`              | —         | `Math.abs(value)`                                                                |
+| `.ceil()`             | —         | round up to integer                                                              |
+| `.floor()`            | —         | round down to integer                                                            |
+| `.round(decimals?)`   | default 0 | round to N decimals                                                              |
+| `.toFixed(decimals?)` | default 2 | round to N decimals — returns a **number**                                       |
+| `.coerce()`           | —         | a **numeric-shaped string** → `Number`; any other value passes through unchanged |
 
-These run *before* validation rules. If you mutate `1.6` with `.ceil()`, `v.int()` sees `2` and passes. Use mutators when the input arrives in a slightly wrong form and you want to coerce, not reject.
+These run _before_ validation rules. If you mutate `1.6` with `.ceil()`, `v.int()` sees `2` and passes. Use mutators when the input arrives in a slightly wrong form and you want to coerce, not reject.
 
 `.coerce()` (5.9+) is the opt-in for the most common case: **query-string params arrive as strings.** `v.int()` is strict by default — `?limit=2` is the string `"2"` and is rejected — so add `.coerce()` when a schema validates `request.query`:
 
 ```ts
-v.object({ limit: v.int().coerce().min(1).max(100) })   // "2" → 2, passes
+v.object({ limit: v.int().coerce().min(1).max(100) }); // "2" → 2, passes
 ```
 
-It only fixes the string *representation* — the type rule still runs, so `v.int().coerce()` on `"5.5"` coerces to `5.5` and correctly **fails** (still not an integer), and `"abc"` passes through and fails. Strictness is unchanged unless you chain `.coerce()`; the output type is unaffected (`v.int().coerce()` still infers `number`). Prefer this over hand-rolling `.addMutator(...)` in app schemas.
+It only fixes the string _representation_ — the type rule still runs, so `v.int().coerce()` on `"5.5"` coerces to `5.5` and correctly **fails** (still not an integer), and `"abc"` passes through and fails. Strictness is unchanged unless you chain `.coerce()`; the output type is unaffected (`v.int().coerce()` still infers `number`). Prefer this over hand-rolling `.addMutator(...)` in app schemas.
 
 That ordering is exactly why `.toFixed()` yields a number rather than a fixed-point string: the mutated value is what the validator's own type rule sees, and a `number` schema that emitted `"3.14"` would reject its own output. Format to a string at the presentation edge instead.
 
@@ -1944,31 +2070,31 @@ Before 4.9.2 `.toFixed()` returned a string, so `v.number().toFixed(2)` **always
 
 ```ts
 // Age
-v.int().min(0).max(150)
+v.int().min(0).max(150);
 
 // Price (cents)
-v.int().min(0)
+v.int().min(0);
 
 // Probability
-v.number().between(0, 1)
+v.number().between(0, 1);
 
 // Even page index
-v.int().min(0).even()
+v.int().min(0).even();
 
 // Quantity divisible by box size
-v.int().min(1).multipleOf(12)
+v.int().min(1).multipleOf(12);
 
 // Coerced from form input
-v.numeric().min(0).max(100)
+v.numeric().min(0).max(100);
 
 // Cross-field range
 v.object({
   startYear: v.int(),
   endYear: v.int().minSibling("startYear"),
-})
+});
 
 // Optional with default
-v.int().min(0).default(0).optional()
+v.int().min(0).default(0).optional();
 ```
 
 
@@ -1982,168 +2108,173 @@ For the picking guide (`v.string` vs `v.scalar` vs `v.literal`), see the `pick-s
 
 ## Length
 
-| Method | Args | JSON Schema | Example |
-|---|---|---|---|
-| `.min(n, msg?)` | min length, inclusive | `minLength: n` | `v.string().min(3)` |
-| `.minLength(n, msg?)` | alias for `.min()` | `minLength: n` | `v.string().minLength(3)` |
-| `.max(n, msg?)` | max length, inclusive | `maxLength: n` | `v.string().max(120)` |
-| `.maxLength(n, msg?)` | alias for `.max()` | `maxLength: n` | `v.string().maxLength(120)` |
-| `.length(n, msg?)` | exact length | `minLength=maxLength=n` | `v.string().length(10)` |
-| `.lengthBetween(a, b, msg?)` | min and max length | `minLength: a, maxLength: b` | `v.string().lengthBetween(5, 30)` |
+| Method                       | Args                  | JSON Schema                  | Example                           |
+| ---------------------------- | --------------------- | ---------------------------- | --------------------------------- |
+| `.min(n, msg?)`              | min length, inclusive | `minLength: n`               | `v.string().min(3)`               |
+| `.minLength(n, msg?)`        | alias for `.min()`    | `minLength: n`               | `v.string().minLength(3)`         |
+| `.max(n, msg?)`              | max length, inclusive | `maxLength: n`               | `v.string().max(120)`             |
+| `.maxLength(n, msg?)`        | alias for `.max()`    | `maxLength: n`               | `v.string().maxLength(120)`       |
+| `.length(n, msg?)`           | exact length          | `minLength=maxLength=n`      | `v.string().length(10)`           |
+| `.lengthBetween(a, b, msg?)` | min and max length    | `minLength: a, maxLength: b` | `v.string().lengthBetween(5, 30)` |
 
 ## Format
 
-| Method | Pattern | JSON Schema | Example |
-|---|---|---|---|
-| `.email(msg?)` | RFC-flavored regex | `format: "email"` | `v.string().email()` |
-| `.url(msg?)` | http/https URL | `format: "uri"` | `v.string().url()` |
-| `.pattern(re, msg?)` | custom regex | `pattern: re.source` | `v.string().pattern(/^[A-Z]/)` |
-| `.alpha(msg?)` | letters only | — | `v.string().alpha()` |
-| `.alphanumeric(msg?)` | letters + digits | — | `v.string().alphanumeric()` |
-| `.numeric(msg?)` | digits only (string) | — | `v.string().numeric()` |
-| `.withoutWhitespace(msg?)` | no spaces/tabs/newlines | — | `v.string().withoutWhitespace()` |
-| `.creditCard(msg?)` | credit-card-shaped | — | `v.string().creditCard()` |
-| `.ip(msg?)` | IPv4 or IPv6 | `format: "ipv4"` | `v.string().ip()` |
-| `.ip4(msg?)` | IPv4 only | `format: "ipv4"` | `v.string().ip4()` |
-| `.ip6(msg?)` | IPv6 only | `format: "ipv6"` | `v.string().ip6()` |
-| `.strongPassword(minLen?, msg?)` | 8+ chars, upper+lower+digit+symbol | — | `v.string().strongPassword(12)` |
+| Method                           | Pattern                            | JSON Schema          | Example                          |
+| -------------------------------- | ---------------------------------- | -------------------- | -------------------------------- |
+| `.email(msg?)`                   | RFC-flavored regex                 | `format: "email"`    | `v.string().email()`             |
+| `.url(msg?)`                     | http/https URL                     | `format: "uri"`      | `v.string().url()`               |
+| `.pattern(re, msg?)`             | custom regex                       | `pattern: re.source` | `v.string().pattern(/^[A-Z]/)`   |
+| `.alpha(msg?)`                   | letters only                       | —                    | `v.string().alpha()`             |
+| `.alphanumeric(msg?)`            | letters + digits                   | —                    | `v.string().alphanumeric()`      |
+| `.numeric(msg?)`                 | digits only (string)               | —                    | `v.string().numeric()`           |
+| `.withoutWhitespace(msg?)`       | no spaces/tabs/newlines            | —                    | `v.string().withoutWhitespace()` |
+| `.creditCard(msg?)`              | credit-card-shaped                 | —                    | `v.string().creditCard()`        |
+| `.ip(msg?)`                      | IPv4 or IPv6                       | `format: "ipv4"`     | `v.string().ip()`                |
+| `.ip4(msg?)`                     | IPv4 only                          | `format: "ipv4"`     | `v.string().ip4()`               |
+| `.ip6(msg?)`                     | IPv6 only                          | `format: "ipv6"`     | `v.string().ip6()`               |
+| `.strongPassword(minLen?, msg?)` | 8+ chars, upper+lower+digit+symbol | —                    | `v.string().strongPassword(12)`  |
 
 ## ID formats
 
-| Method | Args | JSON Schema | Example |
-|---|---|---|---|
-| `.uuid(version?, msg?)` | UUID, any version or restrict to 1/3/4/5/6/7 | `format: "uuid"` | `v.string().uuid(4)` |
-| `.cuid({ version?: 1\|2 }?)` | CUID2 default (24 chars, lowercase); v1 legacy | `pattern: …` | `v.string().cuid()` |
-| `.ulid(msg?)` | 26 chars, Crockford base32 (no I/L/O/U) | `pattern: …` | `v.string().ulid()` |
-| `.nanoid(length?, msg?)` | URL-safe alphabet, default length 21 | `pattern: …` | `v.string().nanoid(21)` |
+| Method                       | Args                                           | JSON Schema      | Example                 |
+| ---------------------------- | ---------------------------------------------- | ---------------- | ----------------------- |
+| `.uuid(version?, msg?)`      | UUID, any version or restrict to 1/3/4/5/6/7   | `format: "uuid"` | `v.string().uuid(4)`    |
+| `.cuid({ version?: 1\|2 }?)` | CUID2 default (24 chars, lowercase); v1 legacy | `pattern: …`     | `v.string().cuid()`     |
+| `.ulid(msg?)`                | 26 chars, Crockford base32 (no I/L/O/U)        | `pattern: …`     | `v.string().ulid()`     |
+| `.nanoid(length?, msg?)`     | URL-safe alphabet, default length 21           | `pattern: …`     | `v.string().nanoid(21)` |
 
 UUID validation is RFC 4122 strict — the variant nibble (8/9/a/b at position 17) is checked, so "looks-like-UUID-but-not-valid" inputs are rejected. CUID defaults to **CUID2** since CUID1 is deprecated by its original author; pass `{ version: 1 }` only for legacy data. nanoid's alphabet is fixed (`A-Za-z0-9_-`) — for custom alphabets use `.pattern()` directly.
 
 ## Word count
 
-| Method | Args | Example |
-|---|---|---|
-| `.words(n, msg?)` | exact word count | `v.string().words(5)` |
-| `.minWords(n, msg?)` | min words | `v.string().minWords(3)` |
-| `.maxWords(n, msg?)` | max words | `v.string().maxWords(50)` |
+| Method               | Args             | Example                   |
+| -------------------- | ---------------- | ------------------------- |
+| `.words(n, msg?)`    | exact word count | `v.string().words(5)`     |
+| `.minWords(n, msg?)` | min words        | `v.string().minWords(3)`  |
+| `.maxWords(n, msg?)` | max words        | `v.string().maxWords(50)` |
 
 ## Content
 
-| Method | Args | Example |
-|---|---|---|
-| `.startsWith(s, msg?)` | prefix check | `v.string().startsWith("https://")` |
-| `.endsWith(s, msg?)` | suffix check | `v.string().endsWith(".pdf")` |
-| `.contains(s, msg?)` | substring check | `v.string().contains("@")` |
+| Method                  | Args              | Example                                 |
+| ----------------------- | ----------------- | --------------------------------------- |
+| `.startsWith(s, msg?)`  | prefix check      | `v.string().startsWith("https://")`     |
+| `.endsWith(s, msg?)`    | suffix check      | `v.string().endsWith(".pdf")`           |
+| `.contains(s, msg?)`    | substring check   | `v.string().contains("@")`              |
 | `.notContains(s, msg?)` | inverse substring | `v.string().notContains("javascript:")` |
 
 ## Color
 
-| Method | Accepts | Example |
-|---|---|---|
-| `.color(msg?)` | any valid CSS color | `v.string().color()` |
-| `.hexColor(msg?)` | `#rgb`, `#rrggbb` | `v.string().hexColor()` |
-| `.rgbColor(msg?)` | `rgb(r,g,b)` | — |
-| `.rgbaColor(msg?)` | `rgba(r,g,b,a)` | — |
-| `.hslColor(msg?)` | `hsl(h,s,l)` | — |
-| `.lightColor(msg?)` | luminance-based | — |
-| `.darkColor(msg?)` | luminance-based | — |
+| Method              | Accepts             | Example                 |
+| ------------------- | ------------------- | ----------------------- |
+| `.color(msg?)`      | any valid CSS color | `v.string().color()`    |
+| `.hexColor(msg?)`   | `#rgb`, `#rrggbb`   | `v.string().hexColor()` |
+| `.rgbColor(msg?)`   | `rgb(r,g,b)`        | —                       |
+| `.rgbaColor(msg?)`  | `rgba(r,g,b,a)`     | —                       |
+| `.hslColor(msg?)`   | `hsl(h,s,l)`        | —                       |
+| `.lightColor(msg?)` | luminance-based     | —                       |
+| `.darkColor(msg?)`  | luminance-based     | —                       |
 
 JSON Schema: `format: "color"` for `.hexColor()`; the others map to `format: "color"` only via `.hexColor()` — for OpenAPI consumers expecting strict format, prefer `.hexColor()`.
 
 ## Case mutators (pre-validation)
 
-| Method | Effect | Example |
-|---|---|---|
-| `.uppercase()` | "Hello" → "HELLO" | `v.string().uppercase()` |
-| `.lowercase()` | "Hello" → "hello" | — |
-| `.capitalize()` | "hello world" → "Hello world" | — |
-| `.titleCase()` | "hello world" → "Hello World" | — |
-| `.camelCase()` | "hello world" → "helloWorld" | — |
-| `.pascalCase()` | "hello world" → "HelloWorld" | — |
-| `.snakeCase()` | "hello world" → "hello_world" | — |
-| `.kebabCase()` | "hello world" → "hello-world" | — |
+| Method          | Effect                        | Example                  |
+| --------------- | ----------------------------- | ------------------------ |
+| `.uppercase()`  | "Hello" → "HELLO"             | `v.string().uppercase()` |
+| `.lowercase()`  | "Hello" → "hello"             | —                        |
+| `.capitalize()` | "hello world" → "Hello world" | —                        |
+| `.titleCase()`  | "hello world" → "Hello World" | —                        |
+| `.camelCase()`  | "hello world" → "helloWorld"  | —                        |
+| `.pascalCase()` | "hello world" → "HelloWorld"  | —                        |
+| `.snakeCase()`  | "hello world" → "hello_world" | —                        |
+| `.kebabCase()`  | "hello world" → "hello-world" | —                        |
 
 ## Trim & whitespace mutators
 
-| Method | Args | Effect |
-|---|---|---|
-| `.trim(needle?)` | default = space | trim both ends |
-| `.ltrim(needle?)` | — | trim left only |
-| `.rtrim(needle?)` | — | trim right only |
-| `.trimMultipleWhitespace()` | — | "a   b" → "a b" |
-| `.padStart(len, char?)` | char default = " " | left-pad to length |
-| `.padEnd(len, char?)` | char default = " " | right-pad to length |
+| Method                      | Args               | Effect              |
+| --------------------------- | ------------------ | ------------------- |
+| `.trim(needle?)`            | default = space    | trim both ends      |
+| `.ltrim(needle?)`           | —                  | trim left only      |
+| `.rtrim(needle?)`           | —                  | trim right only     |
+| `.trimMultipleWhitespace()` | —                  | "a b" → "a b"       |
+| `.padStart(len, char?)`     | char default = " " | left-pad to length  |
+| `.padEnd(len, char?)`       | char default = " " | right-pad to length |
 
 ## Replace, append, modify mutators
 
-| Method | Args | Example |
-|---|---|---|
-| `.replace(search, replace)` | string or RegExp + string | — |
-| `.replaceAll(search, replace)` | string or RegExp + string | — |
-| `.append(suffix)` | string | "foo" → "foobar" via `.append("bar")` |
-| `.prepend(prefix)` | string | "foo" → "barfoo" via `.prepend("bar")` |
-| `.reverse()` | — | "abc" → "cba" |
-| `.repeat(count)` | number | "ab" → "ababab" via `.repeat(3)` |
-| `.truncate(maxLen, suffix?)` | suffix default = "…" | "long text" → "long…" |
-| `.mask(start, end?, char?)` | char default = "*" | "1234567890" → "12******90" |
+| Method                         | Args                      | Example                                |
+| ------------------------------ | ------------------------- | -------------------------------------- |
+| `.replace(search, replace)`    | string or RegExp + string | —                                      |
+| `.replaceAll(search, replace)` | string or RegExp + string | —                                      |
+| `.append(suffix)`              | string                    | "foo" → "foobar" via `.append("bar")`  |
+| `.prepend(prefix)`             | string                    | "foo" → "barfoo" via `.prepend("bar")` |
+| `.reverse()`                   | —                         | "abc" → "cba"                          |
+| `.repeat(count)`               | number                    | "ab" → "ababab" via `.repeat(3)`       |
+| `.truncate(maxLen, suffix?)`   | suffix default = "…"      | "long text" → "long…"                  |
+| `.mask(start, end?, char?)`    | char default = "*"        | "1234567890" → "12******90"            |
 
 ## Filter mutators
 
-| Method | Effect |
-|---|---|
-| `.toAlpha()` | strip non-letters |
-| `.toAlphanumeric()` | strip non-alphanumerics |
-| `.removeSpecialCharacters()` | keep alphanumerics + whitespace |
-| `.removeNumbers()` | strip digits |
-| `.stripTags()` | strip HTML tags via a naive `<...>` regex — **not** an XSS sanitizer; `.safeHtml()` is a deprecated alias |
-| `.htmlEscape()` | `<` → `&lt;` etc |
-| `.unescapeHtml()` | reverse `htmlEscape()` |
+| Method                       | Effect                                                                                                    |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `.toAlpha()`                 | strip non-letters                                                                                         |
+| `.toAlphanumeric()`          | strip non-alphanumerics                                                                                   |
+| `.removeSpecialCharacters()` | keep alphanumerics + whitespace                                                                           |
+| `.removeNumbers()`           | strip digits                                                                                              |
+| `.stripTags()`               | strip HTML tags via a naive `<...>` regex — **not** an XSS sanitizer; `.safeHtml()` is a deprecated alias |
+| `.htmlEscape()`              | `<` → `&lt;` etc                                                                                          |
+| `.unescapeHtml()`            | reverse `htmlEscape()`                                                                                    |
 
 ## Encoding mutators
 
-| Method | Effect |
-|---|---|
-| `.base64Encode()` | utf8 → base64 |
-| `.base64Decode()` | base64 → utf8 |
-| `.urlEncode()` | percent-encode |
-| `.urlDecode()` | percent-decode |
-| `.slug()` | "Hello World!" → "hello-world" |
-| `.toString()` | coerce non-string input to string |
+| Method            | Effect                            |
+| ----------------- | --------------------------------- |
+| `.base64Encode()` | utf8 → base64                     |
+| `.base64Decode()` | base64 → utf8                     |
+| `.urlEncode()`    | percent-encode                    |
+| `.urlDecode()`    | percent-decode                    |
+| `.slug()`         | "Hello World!" → "hello-world"    |
+| `.toString()`     | coerce non-string input to string |
 
 ## Mutator vs transformer
 
-The methods above are **all mutators** — they reshape the value *before* validation rules run. If you want post-validation reshaping, attach via `.addTransformer(fn)` (see the `compose-seal-modifiers` topic).
+The methods above are **all mutators** — they reshape the value _before_ validation rules run. If you want post-validation reshaping, attach via `.addTransformer(fn)` (see the `compose-seal-modifiers` topic).
 
-Practical implication: `v.string().min(3).trim()` runs `min(3)` against the *un-trimmed* input. To check trimmed length, mutate first: `v.string().trim().min(3)`.
+Practical implication: `v.string().min(3).trim()` runs `min(3)` against the _un-trimmed_ input. To check trimmed length, mutate first: `v.string().trim().min(3)`.
 
 ## Common chains
 
 ```ts
 // Email field
-v.string().email()
+v.string().email();
 
 // Username
-v.string().min(3).max(30).alphanumeric().lowercase()
+v.string().min(3).max(30).alphanumeric().lowercase();
 
 // Slug from title
-v.string().slug()
+v.string().slug();
 
 // Strong password
-v.string().strongPassword(12)
+v.string().strongPassword(12);
 
 // URL with strict format
-v.string().url().startsWith("https://")
+v.string().url().startsWith("https://");
 
 // Tag-stripped HTML body (not XSS-safe — sanitize with DOMPurify/sanitize-html before rendering untrusted rich text)
-v.string().stripTags().min(1)
+v.string().stripTags().min(1);
 
 // Masked phone for response
-v.string().pattern(/^\+\d{8,}$/).mask(3, -2)
+v.string()
+  .pattern(/^\+\d{8,}$/)
+  .mask(3, -2);
 
 // Optional with default
-v.string().email().default("guest@example.com").optional()
+v.string().email().default("guest@example.com").optional();
 ```
 
+The standalone `replaceMutator` and `replaceAllMutator` preserve the stringified
+value when called without a context or replacement options.
+
 
 ## seal-basics  `@warlock.js/seal/seal-basics/SKILL.md`
 
@@ -2154,7 +2285,7 @@ description: "Start here for @warlock.js/seal schemas, validation, parsing, and
 
 # Validate with seal
 
-Schema-first validation. Single entry point: the `v` factory. Every validator chains, composes, and infers. Schemas double as runtime validators *and* type-level shapes via `Infer<typeof schema>`, and ship `~standard` so any Standard-Schema-aware consumer accepts them directly.
+Schema-first validation. Single entry point: the `v` factory. Every validator chains, composes, and infers. Schemas double as runtime validators _and_ type-level shapes via `Infer<typeof schema>`, and ship `~standard` so any Standard-Schema-aware consumer accepts them directly.
 
 > This skill is the seal **map** — read it first, then load the specific skill for the task.
 
@@ -2182,9 +2313,9 @@ type User = Infer<typeof userSchema>;
 
 const result = await validate(userSchema, input);
 if (result.isValid) {
-  result.data;      // typed, post-transformer
+  result.data; // typed, post-transformer
 } else {
-  result.errors;    // [{ type, error, input }, ...]
+  result.errors; // [{ type, error, input }, ...]
 }
 ```
 
@@ -2218,7 +2349,7 @@ The 12 things that are true in every seal use:
 2. **Every factory return is a `StandardSchemaV1<Infer.Output<T>>`.** Pass seal schemas straight into `StandardSchemaV1<T>`-typed slots — no casts.
 3. **Two inference helpers — `Infer.Input<T>` and `Infer.Output<T>`.** Bare `Infer<T>` is an alias for `Infer.Input<T>` (the dominant usage: HTTP bodies, DTOs, form payloads). Use `Infer.Output<T>` for validated state (Cascade `Model<>` params, post-`validate()` data). See [the rules below](#inferinput-vs-inferoutput).
 4. **Fields are required by default.** Mark optional explicitly: `.optional()`. Skip `.required()` — canonical seal style omits the redundant call; inferred types already show what's required.
-5. **`validate(schema, data)` never throws.** Returns `Promise<ValidationResult>` with `{ isValid, data, errors }` — the validated value is `result.data`. See the `handle-seal-errors` topic.
+5. **`validate(schema, data)` never throws.** Returns `{ isValid, data, errors }`, narrowed on `isValid`: on success `data` is `Infer.Output<typeof schema>`, on failure it is `undefined` (a bare `BaseValidator`/`ObjectValidator` annotation keeps `data: any`). See the `handle-seal-errors` topic.
 6. **Validators are immutable by default.** Every chain method (`.min(3)`, `.email()`, `.optional()`, …) returns a clone. Toggle with the `.mutable` getter.
 7. **Two pipelines: mutators (pre-validation), transformers (post-validation).** Order: `default → mutators → required check → required-condition rule → other rules → transformers → data`. `.catch(fallback)` rescues any failure on leaf validators.
 8. **Cross-field rules need a `v.object` parent.** Standalone scalar validators have no siblings to resolve against.
@@ -2240,13 +2371,13 @@ const schema = v.object({
   status: v.enum(Status).optional().default(Status.ACTIVE),
 });
 
-type In  = Infer.Input<typeof schema>;
+type In = Infer.Input<typeof schema>;
 // { email?: string; status?: Status }     ← caller may omit both
 
 type Out = Infer.Output<typeof schema>;
 // { email?: string; status: Status }      ← default fired for status
 
-type Default = Infer<typeof schema>;       // alias for Infer.Input
+type Default = Infer<typeof schema>; // alias for Infer.Input
 ```
 
 Both flavours widen with `| null` when `.nullable()` is set.
@@ -2258,15 +2389,15 @@ Both flavours widen with `| null` when `.nullable()` is set.
 
 ## Pick a skill
 
-| If the task is about… | Load |
-| --- | --- |
-| Picking the right primitive (`v.string` vs `v.scalar`, `v.literal` vs `v.enum`, `v.date` vs `v.instanceof(Date)`) | The `pick-seal-primitive` topic |
-| Building object / array / record / tuple / union schemas, discriminated unions, recursive schemas | The `define-structural-shape` topic |
-| Modifiers — `.required` / `.optional` / `.nullable` / `.default` / `.catch` / `.omit`, transformer vs mutator pipelines, membership rules | The `compose-seal-modifiers` topic |
-| Reading `ValidationResult`, branching on `error.type`, error message customization, translation | The `handle-seal-errors` topic |
-| Generating JSON Schema for OpenAI strict / OpenAPI / draft-07 | The `generate-json-schema` topic |
-| Why a `StandardSchemaV1<T>` slot accepts/rejects a schema, the phantom-intersection design, `Result<unknown>` errors | The `bridge-standard-schema` topic |
-| Authoring custom seal plugins to add validator methods | The `extend-seal-with-plugins` topic |
+| If the task is about…                                                                                                                                         | Load                                 |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| Picking the right primitive (`v.string` vs `v.scalar`, `v.literal` vs `v.enum`, `v.date` vs `v.instanceof(Date)`)                                             | The `pick-seal-primitive` topic      |
+| Building object / array / record / tuple / union schemas, discriminated unions, recursive schemas                                                             | The `define-structural-shape` topic  |
+| Modifiers — `.required` / `.optional` / `.nullable` / `.default` / `.catch` / `.omit`, transformer vs mutator pipelines, membership rules                     | The `compose-seal-modifiers` topic   |
+| Reading `ValidationResult`, branching on `error.type`, error message customization, translation                                                               | The `handle-seal-errors` topic       |
+| Generating JSON Schema for OpenAI strict / OpenAPI / draft-07                                                                                                 | The `generate-json-schema` topic     |
+| Why a `StandardSchemaV1<T>` slot accepts/rejects a schema, object input/output class parameters and primitive factory intersections, `Result<unknown>` errors | The `bridge-standard-schema` topic   |
+| Authoring custom seal plugins to add validator methods                                                                                                        | The `extend-seal-with-plugins` topic |
 
 ## Things NOT to do