@warlock.js/seal 5.30.0 → 5.32.0

package/llms.txt

@@ -6,7 +6,7 @@
 
 ## Skills
 
-- [bridge-standard-schema](@warlock.js/seal/bridge-standard-schema/SKILL.md): 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`.
+- [bridge-standard-schema](@warlock.js/seal/bridge-standard-schema/SKILL.md): 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`.
 - [compose-seal-modifiers](@warlock.js/seal/compose-seal-modifiers/SKILL.md): Apply cross-cutting modifiers — `.optional` / `.nullable` / `.default` / `.catch` / `.omit` / membership rules — plus the mutator-vs-transformer pipeline and `Infer.Input` vs `Infer.Output`. Triggers: `.optional`, `.required`, `.nullable`, `.default`, `.catch`, `.present`, `.requiredIf`, `.requiredWith`, `.in`, `.oneOf`, `.notIn`, `.omit`, `.attribute`, `.mutable`, `.addMutator`, `Infer.Input`, `Infer.Output`; "mark field optional in seal", "default value in schema", "mutator vs transformer", "when does .catch fire"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: primitives — the `pick-seal-primitive` topic; containers — the `define-structural-shape` topic; errors — the `handle-seal-errors` topic; competing `zod` `.optional`/`.default`.
 - [define-structural-shape](@warlock.js/seal/define-structural-shape/SKILL.md): Compose `v.object` / `v.array` / `v.record` / `v.tuple` / `v.union` / `v.discriminatedUnion` / `v.lazy`. Triggers: `v.object`, `v.array`, `v.record`, `v.tuple`, `v.union`, `v.discriminatedUnion`, `v.lazy`, `ObjectValidator`; "how do I build an object schema", "dynamic-keyed record", "tagged union with discriminator", "recursive schema", "self-referencing schema"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: leaf primitives — the `pick-seal-primitive` topic; modifiers — the `compose-seal-modifiers` topic; standard-schema bridge — the `bridge-standard-schema` topic; competing libs `zod`, `valibot`.
 - [extend-seal-with-plugins](@warlock.js/seal/extend-seal-with-plugins/SKILL.md): Author a custom seal plugin to add validator methods (`.slug`, `.postalCode`, etc) — `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation. Triggers: `SealPlugin`, `registerPlugin`, `unregisterPlugin`, `hasPlugin`, `getInstalledPlugins`, `StringValidator`, `NumberValidator`, `DateValidator`, `BaseValidator`, `install`, `uninstall`; "how do I add a custom validator method", "write a seal plugin", "extend v.string with .slug", "module augmentation for seal"; typical import `import { StringValidator, registerPlugin, type SealPlugin } from "@warlock.js/seal"`. Skip: built-in primitives — the `pick-seal-primitive` topic; bridge typing — the `bridge-standard-schema` topic; competing `zod` `.refine`/`.transform`.

package/package.json

@@ -23,7 +23,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.30.0",
+  "version": "5.32.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/bridge-standard-schema/SKILL.md

@@ -1,34 +1,35 @@
 ---
 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
 
@@ -50,7 +51,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
@@ -74,7 +75,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")[] }
 ```
 
@@ -84,17 +85,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
 
@@ -109,23 +105,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?
 

package/skills/compose-seal-modifiers/SKILL.md

@@ -17,31 +17,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).
@@ -49,9 +79,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)`
@@ -63,22 +95,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())`.
 
@@ -86,7 +118,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**
@@ -121,7 +153,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
@@ -135,10 +167,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()`.
 
@@ -148,26 +181,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({
@@ -175,11 +208,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
 ```
 
@@ -192,12 +226,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.
@@ -209,10 +243,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
 
@@ -221,7 +255,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")
 ```
 
@@ -229,12 +263,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()`.
@@ -262,7 +298,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.

package/skills/define-structural-shape/SKILL.md

@@ -14,20 +14,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).
@@ -35,9 +35,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.
@@ -45,26 +45,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]);
 
@@ -76,8 +90,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.
 
@@ -115,20 +129,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