# Warlock Seal — full skills

> Package: `@warlock.js/seal`

> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/seal/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.

## bridge-standard-schema  `@warlock.js/seal/bridge-standard-schema/SKILL.md`

---
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 — `@warlock.js/seal/seal-basics/SKILL.md`; JSON Schema gen — `@warlock.js/seal/generate-json-schema/SKILL.md`; 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.

## The shape of the bridge

The `v` factory returns aren't bare validator classes. Each factory widens its return with a phantom intersection:

```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]>;

// ...one intersection per factory.
```

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.

## What this means for app code

You write the schema once, you use it anywhere a `StandardSchemaV1<T>` is expected, you never cast:

```ts
import { v, validate, type Infer } from "@warlock.js/seal";
import { ai } from "@warlock.js/ai";

const userSchema = v.object({
  email: v.string().email(),
  age: v.int().optional(),
});

type User = Infer<typeof userSchema>;

// ✅ ai-side slot — no cast
ai.tool({
  name: "create_user",
  description: "Create a new user",
  input: userSchema,
  execute: async input => createUser(input),
});

// ✅ supervisor output — no cast
ai.supervisor({
  name: "user-flow",
  output: userSchema,
  // ...
});

// ✅ direct validation — call ~standard
const result = await userSchema["~standard"].validate(rawData);
```

## `Infer<typeof schema>` vs hand-rolled types

Use `Infer<>`. Always:

```ts
const schema = v.object({
  email: v.string(),
  blocks: v.array(v.literal("text", "image")).optional(),
});

type Output = Infer<typeof schema>;
// { email: string; blocks?: ("text" | "image")[] }
```

Hand-rolled parallel types drift the moment a field changes — and seal's tightened typing now catches that drift at compile time. The old loose typing hid the mismatch; the bridge surfaces it.

## When the bridge "fails"

Three failure modes you'll see in real projects:

### 1. You annotated the schema with the bare class type

```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>`.

### 2. The schema's inferred shape doesn't match the target type

```ts
ai.supervisor<MyOutput, ...>({
  output: schema,  // ❌ schema infers differently from MyOutput
});
```

The supervisor's explicit `<MyOutput>` generic is a constraint the schema must satisfy. If they diverge, TS rightly rejects. Two fixes:

- **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

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`.

If you see this, ignore the `unknown` and ask: does `Infer<typeof schema>` match the slot's expected `T`? Probe with:

```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.
```

That's the real mismatch.

## 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.

## Why not import `@standard-schema/spec` instead of forking the types?

Seal forks the types locally. Reasons:

- Seal extends the spec with `StandardJSONSchemaV1` (JSON Schema converter on `~standard.jsonSchema`). The package doesn't have this — half-importing is the worst of both worlds.
- V1 spec is locked. The fork is ~70 lines and updates rarely.
- Avoids version-coupling pain across `@warlock.js/*` packages.

If V2 lands, re-fork. Until then the local copy is the right call.


## compose-seal-modifiers  `@warlock.js/seal/compose-seal-modifiers/SKILL.md`

---
name: compose-seal-modifiers
description: '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 — `@warlock.js/seal/pick-seal-primitive/SKILL.md`; containers — `@warlock.js/seal/define-structural-shape/SKILL.md`; errors — `@warlock.js/seal/handle-seal-errors/SKILL.md`; competing `zod` `.optional`/`.default`.'
---

# Cross-cutting modifiers + the pipeline

This skill covers methods that work on **every** validator. Type-specific methods (`.email()`, `.min()` on strings, `.between()` on numbers, `.weekDay()` on dates, etc.) live in the per-type method references — see [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md) and [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md).

## The pipeline

When `validate()` runs against a value, the order is:

```
1. default       — fills if input is undefined
2. mutators      — reshape value (string → Date, .trim(), .toUTC())
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)
```

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)
// "  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()
// "  Hi  " → rules see "  Hi  " (length 6, passes min(3)) → trim → data = "Hi"
```

## `.required()` / `.optional()` / `.present()`

```ts
v.string()             // already required inside v.object — no need to call .required()
v.string().optional()  // type: string | undefined — { isOptional: true } brand
v.string().present()   // must exist, may be "" / null
v.string().required()  // explicit form — same behavior, redundant
```

**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).

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:**
- Visual contrast next to `.optional()` siblings when you want the asymmetry to be loud — style call.
- 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)`
- `.requiredUnless(field, value)`
- `.requiredWhen(callback)` — predicate
- `.present()` / `.presentIf(field, value)` / `.presentUnless(field, value)`
- `.forbidden()` / `.forbiddenIf(field, value)` — opposite of present

## `.nullable()` / `.notNullable()` / `.nullish()`

```ts
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`.

## `.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([])
```

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())`.

The `{ hasDefault: true }` brand makes the key optional in `Infer.Input` (caller doesn't have to send it) and required in `Infer.Output` (data always has it).

## `.catch(fallback)`

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**

```ts
const config = v.object({
  retries: v.int().min(0).catch(3),
  region: v.string().in(["us", "eu"]).catch("us"),
  features: v.array(v.string()).catch([]),
});

await validate(config, { retries: "five", region: null, features: "x" });
// { isValid: true, data: { retries: 3, region: "us", features: [] } }
```

The fallback can be a value or a callback `(errors, originalInput) => fallback` — the callback variant is the only side-channel for the swallowed errors. Use it to log/alert before substituting.

**Scope (v1).** Catch is honoured for **leaf validators** (string, number, boolean, date, …) and for fields inside containers. It is a **no-op on container validators themselves** (`v.object`, `v.array`, `v.record`, `v.tuple`, `v.discriminatedUnion`) — those use their own iteration logic that bypasses the catch hook. To rescue a whole-container failure, wrap the call site in your own try/catch instead.

**Best used for:** LLM output parsing, third-party API responses, config files, any data where the cost of failure is higher than the cost of a wrong value. Overuse masks real bugs — reach for it deliberately.

The `{ hasCatch: true }` brand has the same effect on `Infer.Input`/`Infer.Output` as `{ hasDefault: true }`.

## `Infer.Input` vs `Infer.Output`

The two inference helpers describe the two halves of the pipeline:

```ts
const schema = v.object({
  bio: v.string().optional(),
  status: v.enum(Status).optional().default(Status.ACTIVE),
  retries: v.int().catch(3),
});

type In  = Infer.Input<typeof schema>;
// {
//   bio?:     string;
//   status?:  Status;      ← default makes caller optional
//   retries?: number;      ← catch makes caller optional
// }

type Out = Infer.Output<typeof schema>;
// {
//   bio?:    string;
//   status:  Status;       ← default guarantees a value
//   retries: number;       ← catch guarantees a value
// }

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()`.

Both widen with `| null` when `.nullable()` is set.

## Absent vs empty vs invalid — what `data` actually contains

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 |

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) |

```ts
const schema = v.object({
  metadata: v.record(v.string()).optional(),
  embedding: v.array(v.number()).optional(),
});

(await validate(schema, {})).data
// → {} — neither key appears
// (NOT { metadata: {}, embedding: [] })

(await validate(schema, { metadata: {}, embedding: [] })).data
// → { metadata: {}, embedding: [] } — present-empty is preserved
```

**Why the distinction matters.** Persistence layers see `key in data` as "user touched this column". Synthesizing `{}` / `[]` for absent input would write empty values to the DB, defeat `$exists` filters, and confuse "I cleared this" vs "I never set this" downstream. Cascade models, Standard-Schema consumers, and JSON serializers all depend on this contract.

Collection validators (`v.record`, `v.array`, `v.tuple`) explicitly honor this — they used to coerce absent input to empty containers (a long-standing bug), but now propagate `undefined` so the parent `v.object` correctly omits the key.

## Membership rules (inherited by every primitive)

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
```

For literal-typed narrowing (`"admin" | "user" | "guest"` instead of `string`), use `v.literal(...)` instead — `oneOf` keeps the broader primitive type.

## `.omit()` / `.exclude()`

```ts
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.

## `.label("Display Name")` — field display name

To control the `:input` placeholder in a field's own messages, call `.label()` on the field validator:

```ts
v.object({
  email_address: v.string().label("Email Address"),
})
// Error message: "The Email Address is required" (instead of "The email_address is required")
```

`.label(x)` sets the field's `:input` attribute, so every rule message for that field renders the friendly name.

### `.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`):

```ts
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()`.

## Mutability — `.mutable` / `.immutable`

Validators are **immutable by default**. Every chain method returns a clone:

```ts
const baseString = v.string();
const required = baseString.required();
// baseString is unchanged
```

This matters because schemas are often shared (`Model.schema = v.object({...})`). If chaining mutated, every reuse would carry forward the previous chain's state.

Toggle in-place with the `.mutable` getter (rare):

```ts
const schema = v.string().mutable.required().min(3);
// Same instance throughout — useful when building dynamically
```

Switch back with `.immutable`. Default is fine 99% of the time. Reach for `.mutable` only when you've thought about who else holds a reference.

## 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 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.
- Don't mutate a schema you handed to a Model. Default immutability protects you; opting into `.mutable` on shared schemas is asking for confusion.


## define-structural-shape  `@warlock.js/seal/define-structural-shape/SKILL.md`

---
name: define-structural-shape
description: '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 — `@warlock.js/seal/pick-seal-primitive/SKILL.md`; modifiers — `@warlock.js/seal/compose-seal-modifiers/SKILL.md`; standard-schema bridge — `@warlock.js/seal/bridge-standard-schema/SKILL.md`; competing libs `zod`, `valibot`.'
---

# Structural validators — picking guide

The five structural factories. Each composes — pass leaf primitives or other structural validators inside, infer with `Infer<typeof schema>`. **Method surface for `v.object` and `v.array` lives in `object-methods.md` and `array-methods.md`** — this file is just orientation.

## `v.object` — fixed-key records

```ts
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.

## `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
```

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).

## `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>
```

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.

## `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]
```

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]`).

## `v.union` — one of N validators (untagged)

```ts
v.union([v.string(), v.int()])  // type: string | number
```

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.

## `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 notif = v.discriminatedUnion("type", [email, sms, push]);

type Notif = Infer<typeof notif>;
// { type: "email"; email: string }
// | { type: "sms"; phone: string }
// | { type: "push"; deviceId: string }
```

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.
- **Exact TS inference** — discriminated union with narrowing inside `if (x.type === "email")` blocks.
- **Cleaner JSON Schema** — `oneOf` with literal discriminators; OpenAI-strict accepts it.

Construction-time validation throws on:

- Missing discriminator field in any branch
- Non-literal discriminator (must be `v.literal(...)`)
- Duplicate discriminator values across branches

So misconfigurations surface at schema-build time, not runtime.

## `v.lazy` — recursive and forward-referenced schemas

```ts
type Category = { name: string; children: Category[] };

const categorySchema: ObjectValidator<...> = v.object({
  name: v.string(),
  children: v.array(v.lazy(() => categorySchema)),
});

type T = Infer<typeof categorySchema>;
// { name: string; children: T[] }   ← recursive type
```

Defers resolution of the inner validator until validate-time. JavaScript evaluates the object literal before the `const` binding completes, so the inner reference would normally fail with `ReferenceError`. The thunk is invoked only when `validate()` runs, by which time the binding exists.

**Memoised.** The thunk fires once on first use; subsequent calls reuse the cached validator.

**JSON Schema caveat.** Simple-resolve in v1 — recursive shapes will infinite-loop in `toJsonSchema()`. If you need JSON Schema for a recursive shape, generate it manually with `$defs` + `$ref` until v2 lands.

**TS inference requires a recursive type alias.** TS can't infer `Category = { name: string; children: Category[] }` from the schema alone — declare the type explicitly and annotate the schema variable with `ObjectValidator<...>` or similar (same pattern as Zod's `z.ZodType<Category>`).

Use for: trees (categories, file systems), threaded data (comment chains), mutually recursive schemas (`A` references `B` references `A`), and forward references (a schema needs to use one defined later in the file).

## 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 [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md)) |

## 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 [`@warlock.js/seal/bridge-standard-schema/SKILL.md`](@warlock.js/seal/bridge-standard-schema/SKILL.md).

## Method-surface reference

- [`object-methods.md`](./object-methods.md) — `.extend` / `.merge` / `.pick` / `.without` / `.partial` / `.requiredFields` / `.allowUnknown` / `.stripUnknown` / `.allow` / `.trim`.
- [`array-methods.md`](./array-methods.md) — `.minLength` / `.maxLength` / `.length` / `.between` / `.unique` / `.sorted` / `.flip` / `.sort` / `.onlyUnique`.

`v.record` and `v.tuple` share the array-style length surface. `v.union` and `v.discriminatedUnion` have no chainable methods beyond what's shown above. `v.lazy` is a single-call factory.


### define-structural-shape/array-methods.md  `@warlock.js/seal/define-structural-shape/array-methods.md`

# `v.array(itemValidator)` — method reference

The inner validator runs against each element. Failure on any element fails the array. Picking guide (array vs tuple vs record) is in [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md).

## 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` | — |

**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 |
| `.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 |

`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
```

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.

## JSON Schema mapping

- `v.array(item)` → `{ type: "array", items: <item.toJsonSchema()> }`
- `.minLength(n)` → `minItems: n`
- `.maxLength(n)` → `maxItems: n`
- `.length(n)` → `minItems: n, maxItems: n`
- `.between(a, b)` → `minItems: a, maxItems: b`
- `.unique()` and `.sorted()` are NOT representable — silently omitted

## Common chains

```ts
// Tags
v.array(v.string().min(1)).unique().between(1, 10)

// User list
v.array(userSchema).minLength(1)

// Pre-sorted, deduped
v.array(v.string()).onlyUnique().sort("asc")

// Reverse-emit
v.array(v.string()).flip()

// Matrix
v.array(v.array(v.number())).minLength(1)

// Sorted ids
v.array(v.string().uuid()).sorted("asc").unique()

// Optional list with default
v.array(v.string()).default([]).optional()
```


### define-structural-shape/object-methods.md  `@warlock.js/seal/define-structural-shape/object-methods.md`

# `v.object({...})` — method reference

Picking guide for structural validators is in [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md). For field-level chaining (`.required` / `.optional` / `.attribute`), see [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md).

## Schema composition

These return a new `ObjectValidator` with a transformed schema. The TypeScript inference follows correctly — `Infer<>` reflects the post-composition shape.

### `.extend(schemaOrValidator)` — add fields, keep config

```ts
const baseUser = v.object({
  name: v.string(),
  email: v.string().email(),
}).allowUnknown();

const adminUser = baseUser.extend({
  role: v.string().oneOf(["admin", "superadmin"]),
});
// adminUser type: { name; email; role } — keeps allowUnknown()
```

Accepts a plain schema object **or** another `ObjectValidator` (only its schema is used — config is ignored). Use for reusable field collections (e.g. timestamp fields).

### `.merge(otherValidator)` — combine, override config

```ts
const base = v.object({ name: v.string() }).allowUnknown();
const audit = v.object({
  createdAt: v.date(),
  updatedAt: v.date(),
}).stripUnknown();

const merged = base.merge(audit);
// type: { name; createdAt; updatedAt }
// config: stripUnknown() from audit (overrides base's allowUnknown)
```

`.merge` combines schemas **and** configurations — the other validator wins. Rules, mutators, transformers, and attribute display names from both validators are appended.

### `.pick(...keys)` — keep only specified fields

```ts
const fullUser = v.object({
  id: v.int(),
  name: v.string(),
  email: v.string().email(),
  password: v.string(),
});

const loginSchema = fullUser.pick("email", "password");
// type: { email; password }
```

Returns `ObjectValidator<Pick<TSchema, K>>`. Keeps original config (`allowUnknown`, etc.).

### `.without(...keys)` — drop specified fields

```ts
const updateSchema = fullUser.without("id");
// type: { name; email; password }
```

Returns `ObjectValidator<Omit<TSchema, K>>`. Inverse of `.pick`. Keeps original config.

### `.partial(...keys?)` — mark fields optional

```ts
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.

### `.requiredFields(...keys?)` — mark fields required

```ts
const partialUser = fullUser.partial();    // all optional
const updateUser = partialUser.requiredFields("id", "email");
// id and email are required again, others stay optional
```

Inverse of `.partial`.

## Unknown-keys policy

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 |

`.allowUnknown()` only affects direct children — nested objects keep their own policies. For a fully permissive object including nested children, set `.allowUnknown()` on each level.

## Object-level mutators

| Method | Args | Effect |
|---|---|---|
| `.trim(recursive?)` | default `true` | recursively trim string values across the object |

For per-field mutators, attach on the field validator instead.

## Cross-field rules — context

The cross-field methods (`.sameAs`, `.requiredIf`, `.requiredWith`, etc.) are **field-level**, not object-level — you call them on the field validator inside `v.object`. The object validator's job is to hand them the parent context so sibling resolution works:

```ts
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.

## `Infer<>` semantics

```ts
Infer<typeof userSchema>
// { reqField: T; optField?: T }
```

- Required fields → required keys
- `.optional()` fields → optional keys (`?:`)
- `.omit()` / `.exclude()` fields → dropped from the inferred type
- `v.computed<T>()` / `v.managed<T>()` → present as `T` in inferred output (they produce values)

## Common chains

```ts
// User CRUD trio from one base
const baseUser = v.object({
  id: v.int(),
  name: v.string(),
  email: v.string().email(),
  password: v.string(),
});

const createUser = baseUser.without("id");
const updateUser = baseUser.partial().requiredFields("id");
const loginUser = baseUser.pick("email", "password");

// Reusable timestamps
const timestamps = v.object({
  createdAt: v.date(),
  updatedAt: v.date(),
});

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();

// Confirmation pattern with omit
const signupSchema = v.object({
  password: v.string().strongPassword(),
  passwordConfirm: v.string().sameAs("password").omit(),
  email: v.string().email(),
});
// Infer<> = { password; email } — passwordConfirm omitted from output
```


## extend-seal-with-plugins  `@warlock.js/seal/extend-seal-with-plugins/SKILL.md`

---
name: extend-seal-with-plugins
description: '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 — `@warlock.js/seal/pick-seal-primitive/SKILL.md`; bridge typing — `@warlock.js/seal/bridge-standard-schema/SKILL.md`; competing `zod` `.refine`/`.transform`.'
---

# Extend seal with plugins

Seal exposes a plugin system so you can add validator methods without forking the package. A plugin is an object with `name`, optional `version`/`description`, and an `install` function that runs once when the plugin is registered. The standard pattern is to `Object.assign(StringValidator.prototype, { ... })` to graft new methods onto a validator class.

## When to reach for a plugin

- The validator method you want **does not exist** in built-in seal — check [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md) and its method references first.
- The validation is **stable and reusable** across modules — domain-specific formats (IBAN, postal codes, tax IDs, license plates, internal ID schemes).
- You want the **chainable syntax** — `v.string().slug()` reads better than `v.string().pattern(/.../).addMutator(s => slugify(s))` at every call site.

**Don't** reach for a plugin when a one-off `.pattern()` would do. The boilerplate (declare module, register on boot) is justified only when you'll call the new method many times.

## The plugin shape

```ts
import type { SealPlugin } from "@warlock.js/seal";

type SealPlugin = {
  name: string;          // unique identifier — duplicates warn and skip install
  version?: string;
  description?: string;
  install: (context: { name: string; version?: string }) => void | Promise<void>;
  uninstall?: () => void | Promise<void>;
};
```

The `install` function is where you add methods. Typically you patch a validator class prototype:

```ts
import { StringValidator, type SealPlugin } from "@warlock.js/seal";

export const slugPlugin: SealPlugin = {
  name: "slug",
  version: "1.0.0",
  description: "Adds .slug() — pattern-only slug validation",

  install() {
    Object.assign(StringValidator.prototype, {
      slug(this: StringValidator, errorMessage?: string) {
        return this.pattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, errorMessage);
      },
    });
  },
};
```

`uninstall` is optional. Provide it when your plugin needs to clean up — e.g. removing prototype methods for hot-reload scenarios. Most production plugins skip it; methods grafted at boot stay for the process lifetime.

## Registering plugins

```ts
import { registerPlugin, unregisterPlugin, hasPlugin, getInstalledPlugins } from "@warlock.js/seal";

await registerPlugin(slugPlugin);
// console.warn if "slug" is already installed; otherwise install() runs and the plugin is tracked.

hasPlugin("slug");           // → true
getInstalledPlugins();       // → [slugPlugin]

await unregisterPlugin("slug");
// runs slugPlugin.uninstall?.(); removes from registry.
```

`registerPlugin` is async (the `install` function may be async). Await it during boot so the methods are available before the first request.

**Where to register:** the conventional place in a Warlock app is a side-effect file loaded by `warlock.config.ts` — e.g. `src/setup/seal-plugins.ts`:

```ts title="src/setup/seal-plugins.ts"
import { registerPlugin } from "@warlock.js/seal";
import { slugPlugin } from "./plugins/slug-plugin";
import { postalCodePlugin } from "./plugins/postal-code-plugin";

export async function setupSealPlugins() {
  await registerPlugin(slugPlugin);
  await registerPlugin(postalCodePlugin);
}
```

Then call `setupSealPlugins()` in a bootstrap connector. Registering at top-level module scope works too (it's idempotent — duplicates warn and skip), but explicit setup is clearer.

## TypeScript — declare the new methods

`Object.assign` on a prototype is invisible to TypeScript. Declare the new methods with module augmentation so call sites compile:

```ts title="src/setup/seal-plugins.types.ts"
import "@warlock.js/seal";

declare module "@warlock.js/seal" {
  interface StringValidator {
    /** Pattern-only slug — `"hello-world"`, not `"Hello World"`. */
    slug(errorMessage?: string): StringValidator;
  }
}
```

After this file is included in the project's `tsconfig.json` (via `include` or a side-effect import), `v.string().slug()` autocompletes and type-checks everywhere.

**Important.** The augmentation has to declare on the **class** (`StringValidator`), not the factory return type. The factory return widens with `& StandardSchemaV1<...>` (see [`@warlock.js/seal/bridge-standard-schema/SKILL.md`](@warlock.js/seal/bridge-standard-schema/SKILL.md)) — augmentations on the intersection don't propagate. Patch the class, augment the class; the factory return picks up the new methods through structural inference.

## Larger example — postal codes per country

```ts
import { StringValidator, type SealPlugin } from "@warlock.js/seal";

const PATTERNS: Record<string, RegExp> = {
  US: /^\d{5}(?:-\d{4})?$/,
  DE: /^\d{5}$/,
  UK: /^[A-Z]{1,2}\d[A-Z\d]? \d[A-Z]{2}$/i,
  EG: /^\d{5}$/,
};

export const postalCodePlugin: SealPlugin = {
  name: "postal-code",

  install() {
    Object.assign(StringValidator.prototype, {
      postalCode(this: StringValidator, country: keyof typeof PATTERNS, errorMessage?: string) {
        const pattern = PATTERNS[country];

        if (!pattern) {
          throw new Error(`postalCode: unknown country "${country}"`);
        }

        return this.pattern(pattern, errorMessage ?? `Invalid ${country} postal code`);
      },
    });
  },
};
```

```ts
// Module augmentation
declare module "@warlock.js/seal" {
  interface StringValidator {
    postalCode(country: "US" | "DE" | "UK" | "EG", errorMessage?: string): StringValidator;
  }
}

// Use site
const addressSchema = v.object({
  country: v.literal("US", "DE", "UK", "EG"),
  postal: v.string().postalCode("DE"),
});
```

## Patterns beyond `StringValidator`

The same approach works on any validator class. Pick the right prototype:

- `StringValidator` — string methods (`.slug`, `.postalCode`, `.licensePlate`).
- `NumberValidator` / `IntValidator` / `FloatValidator` — number methods.
- `DateValidator` — date methods (`.businessDayInCountry("US")`).
- `ArrayValidator` / `ObjectValidator` — structural methods (rarer).
- `BaseValidator` — universal methods (rare — usually a sign you want a separate `v.something()` factory instead).

For a method that creates a **new validator** (not chained from an existing one), expose it as a regular function alongside `v` rather than patching the factory. E.g. export `iban()` from your plugin module that returns a configured `v.string()`.

## Introspection — checking what's loaded

```ts
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.

## Things NOT to do

- Don't `Object.assign(BaseValidator.prototype, ...)` for type-specific methods. The method would exist on every validator (`v.boolean().slug()` typechecks but breaks at runtime). Patch the narrowest class that owns the method.
- Don't forget the module augmentation. Without it, the new methods exist at runtime but TS rejects every call site.
- Don't make the plugin's `install` function depend on shared state mutable from elsewhere. Plugins should be idempotent — installing twice (or registering across hot-reloads) should not break anything.
- 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.


## generate-json-schema  `@warlock.js/seal/generate-json-schema/SKILL.md`

---
name: generate-json-schema
description: 'Generate JSON Schema via `schema.toJsonSchema(target)` — `draft-2020-12` / `draft-07` / `openapi-3.0` / `openai-strict`. Triggers: `toJsonSchema`, `JsonSchemaTarget`, `draft-2020-12`, `draft-07`, `openapi-3.0`, `openai-strict`, `response_format`, `additionalProperties`, `nullable`; "how do I generate JSON Schema from seal", "OpenAI structured outputs from schema", "OpenAPI 3.0 nullable", "json_schema strict mode"; typical import `import { v } from "@warlock.js/seal"`. Skip: foundations — `@warlock.js/seal/seal-basics/SKILL.md`; bridge typing — `@warlock.js/seal/bridge-standard-schema/SKILL.md`; competing libs `zod-to-json-schema`, `ajv`, `@anatine/zod-openapi`.'
---

# JSON Schema generation

Every seal validator exposes `toJsonSchema(target)`. The result is a plain object — pass it straight to OpenAI's `response_format`, an OpenAPI spec, a UI form builder, or anywhere else JSON Schema is the contract.

```ts
const userSchema = v.object({
  email: v.string().email(),
  age: v.int().min(13).optional(),
});

userSchema.toJsonSchema("draft-2020-12");
// {
//   type: "object",
//   properties: {
//     email: { type: "string", format: "email" },
//     age: { type: "integer", minimum: 13 },
//   },
//   required: ["email"],
//   additionalProperties: false,
// }
```

## The four targets

```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
```

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"` |
| OpenAI `response_format: { type: "json_schema", strict: true }` | `"openai-strict"` |

## OpenAI structured outputs (`openai-strict`)

This target encodes the quirks of OpenAI's strict mode:

- **Every field listed in `required`** — strict mode forbids leaving fields out.
- **Optional fields encoded as `type: ["T", "null"]`** instead of being omitted from `required`.
- **`additionalProperties: false` on every object.**

```ts
const schema = v.object({
  reply: v.string(),
  citations: v.array(v.string()).optional(),
});

schema.toJsonSchema("openai-strict");
// {
//   type: "object",
//   properties: {
//     reply: { type: "string" },
//     citations: { type: ["array", "null"], items: { type: "string" } },
//   },
//   required: ["reply", "citations"],   // every field listed
//   additionalProperties: false,
// }
```

Hand to OpenAI:

```ts
import OpenAI from "openai";

const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [...],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "user_reply",
      strict: true,
      schema: schema.toJsonSchema("openai-strict"),
    },
  },
});
```

In `@warlock.js/ai`, this happens automatically when you set `output: schema` on a supervisor / agent — the runtime picks `openai-strict` for OpenAI providers. You only call `toJsonSchema()` directly when integrating with a non-warlock OpenAI usage.

## OpenAPI 3.0 nullable

```ts
v.string().nullable().toJsonSchema("openapi-3.0");
// { type: "string", nullable: true }

v.string().nullable().toJsonSchema("draft-2020-12");
// { type: ["string", "null"] }
```

OpenAPI 3.0 uses the boolean `nullable` keyword instead of a type union. Use this target when generating a `paths.openapi.yaml` consumed by Swagger UI or codegen tools.

## What's representable

Cleanly mapped:

- `v.string()` — `{ type: "string" }` (with `format: email/url/uuid`, `pattern`, `minLength`, `maxLength`, `enum`)
- `v.int()` / `v.float()` — `{ type: "integer" | "number" }` (with `minimum`, `maximum`, `multipleOf`)
- `v.boolean()` — `{ type: "boolean" }`
- `v.date()` — `{ type: "string", format: "date-time" | "date" | "time" }` (format derived from transformer if applicable)
- `v.literal(values)` — `{ const: value }` (single) or `{ enum: [...] }` (multiple)
- `v.array(item)` — `{ type: "array", items: ... }` (with `minItems`, `maxItems` from length rules; `.unique()`/`.sorted()` are runtime-only and not emitted)
- `v.object({...})` — `{ type: "object", properties, required, additionalProperties }`
- `v.union([...])` — `{ oneOf: [...] }`
- `v.tuple([...])` — `{ type: "array", prefixItems: [...] }` (draft-2020-12) or `{ type: "array", items: [...] }` (draft-07)
- `v.nullable()` — type union or `nullable: true` per target

## What's silently dropped

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`).
- **`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).

Boolean rules `accepted` / `declined` and similar coercion-style rules are also dropped — JSON Schema doesn't have a notion of "yes/no/on/off" beyond `enum`.

## 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:

- **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.
- **`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

Generating JSON Schema is cheap (pure-function tree walk), so don't worry about caching the result for schemas that change at startup. For dynamic schemas built per-request, generate per-request — there's no shared mutable state.


## handle-seal-errors  `@warlock.js/seal/handle-seal-errors/SKILL.md`

---
name: handle-seal-errors
description: 'Read `ValidationResult` — `isValid`, `errors[]`, `data`. Branch on `error.type`, customize messages, hook translation. Triggers: `ValidationResult`, `ValidationError`, `validate`, `isValid`, `errors`, `data`, `error.type`, `error.input`, `error.error`, `translationParams`, `.attribute`, `SealConfig`; "how to read seal errors", "branch on a specific rule failure", "customize validation error message", "translate seal error", "surface validation errors as 422"; typical import `import { validate, v } from "@warlock.js/seal"`. Skip: modifiers — `@warlock.js/seal/compose-seal-modifiers/SKILL.md`; structural shapes — `@warlock.js/seal/define-structural-shape/SKILL.md`; competing libs `zod` `.safeParse`, `yup` `ValidationError`, `joi`.'
---

# `ValidationResult` — reading errors

`validate(schema, data)` never throws. It returns a `ValidationResult`:

```ts
type ValidationResult = {
  isValid: boolean;
  data: any;             // shape after mutators + transformers (the validated value)
  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"
};
```

Branch on `isValid` first; reach for `errors[]` only when you need to act on a specific failure.

## Basic flow

```ts
import { validate, v } from "@warlock.js/seal";

const schema = v.object({
  email: v.string().email(),
  age: v.int().min(13).optional(),
});

const result = await validate(schema, input);

if (result.isValid) {
  return result.data;  // typed as the inferred shape (post-transformer)
}

return {
  status: 422,
  body: { errors: result.errors },
};
```

## Branching on a specific rule

```ts
const result = await validate(schema, input);

if (!result.isValid) {
  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"),
  );
  if (ageInvalid) {
    return { error: "Age must be 13 or older" };
  }
}
```

The `type` field is the **stable** identifier — the message is human-facing and may be localized. Branch on `type`, never on the message string.

## Common rule type names

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`) |

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.

## Customizing error messages

Two layers:

```ts
v.string().email("Please enter a valid email address").required("Email is required");
//                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^                ^^^^^^^^^^^^^^^^
//                per-rule override                                  per-rule override
```

Each chain method takes an optional `errorMessage` as its last argument. That overrides the rule's `defaultErrorMessage`. Use it when a single rule needs a tailored message in a specific schema.

For project-wide message overrides, hook into the translation layer (the framework calls `resolveTranslation` with the rule context — wire up your own `t()` function via `SealConfig`).

## Translation params

Rules can stash dynamic substitution params on the context. The default messages reference them:

```
"The :input must be at least :min characters"
```

`:input` is the field name (or its translated display name); `:min` and others come from rule-specific metadata. If you need to render the message yourself in a custom UI, the params are available on the rule's context.

For attribute display names ("email" → "Email Address"), use `.attributes({ email: "Email Address" })` on the parent `v.object` or pass via the `validate()` options. The `:input` placeholder picks up the configured display name.

## 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:

- A rule's callback threw (e.g. you wrote `async validate() { throw new Error(...) }`).
- A transformer threw on output.
- A mutator threw on input.

Those are bugs — fix them. Don't try/catch them in app code as a way to handle bad input.

## At the framework boundary

If you're surfacing seal errors through HTTP / RPC, the typical shape is:

```ts
if (!result.isValid) {
  return reply.code(422).send({
    error: "validation_failed",
    fields: result.errors.map(e => ({
      field: e.input,
      type: e.type,
      message: e.error,
    })),
  });
}
```

Avoid leaking `result.data` back to the client when rejecting — it might contain transformed sensitive fields.

For server-side logs, log `errors[]` with the field paths and rule types; redact values unless you're certain the field isn't sensitive. The `@warlock.js/logger` redaction layer is the right place to enforce that.


## overview  `@warlock.js/seal/overview/SKILL.md`

---
name: overview
description: 'Front-door orientation for `@warlock.js/seal` — framework-agnostic, type-safe validation. The `v` factory builds schemas, `validate(schema, data)` runs them, `Infer<typeof schema>` extracts the type. Primitives, structural shapes (object/array/record/tuple/union/discriminatedUnion/lazy), modifiers, mutators, a plugin system, JSON-Schema export, and a Standard Schema bridge. TRIGGER when: code imports `v`, `validate`, or `Infer` from `@warlock.js/seal`; user asks "what does @warlock.js/seal do", "validation library for Warlock", "compare seal with zod / yup / valibot", "infer a type from a schema", "JSON schema from a validator", "Standard Schema interop"; package.json adds `@warlock.js/seal`. Skip: specific task already known — load the matching task skill directly (`seal-basics`, `pick-seal-primitive`, `define-structural-shape`, `compose-seal-modifiers`, `handle-seal-errors`, `generate-json-schema`, `bridge-standard-schema`, `extend-seal-with-plugins`); framework-specific validators (FileValidator, database rules) live in `@warlock.js/core/v`, not here.'
---

# `@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.

Standalone — no framework required. Ships built-in with `@warlock.js/core`, which adds framework-specific validators (file uploads, database existence/uniqueness rules) on top.

## When to reach for it

- You want a single source of truth for a shape — runtime validation, the TS type, and JSON Schema all from one declaration.
- You'd reach for **zod** / **yup** / **valibot** but want the library the rest of Warlock already speaks (request validation, AI tool inputs, Cascade model schemas).
- You need **JSON Schema output** for OpenAI structured outputs or an OpenAPI spec.

Skip if you only need framework-bound validators (file uploads, DB rules) — those live in `@warlock.js/core/v`, which extends this package.

## The mental model in one paragraph

`v` is a builder: `v.string()`, `v.int()`, `v.object({...})`, `v.array(...)`, and so on, chained with modifiers (`.optional()`, `.nullable()`, `.default(...)`, `.min(...)`). `validate(schema, data)` returns a `ValidationResult` with `isValid`, `data` (the validated value), and `errors[]`. `Infer<typeof schema>` gives you the static type (with `Infer.Input` / `Infer.Output` distinguishing pre- and post-transform shapes). Because every schema implements Standard Schema, it slots into any `StandardSchemaV1<T>` consumer — and `schema.toJsonSchema(target)` emits JSON Schema for external tools.

## Skills index

Eight task skills. Most schemas only need `seal-basics` + `pick-seal-primitive` + `define-structural-shape`.

### Foundations

#### [`seal-basics/`](../seal-basics/SKILL.md)
Start here. The `v` factory, `validate(schema, data)`, and `Infer<typeof schema>`.

### Building schemas

#### [`pick-seal-primitive/`](../pick-seal-primitive/SKILL.md)
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/`](../define-structural-shape/SKILL.md)
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/`](../compose-seal-modifiers/SKILL.md)
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/`](../handle-seal-errors/SKILL.md)
Read a `ValidationResult` — `isValid`, `errors[]`, `data`. Branch on `error.type`, customize messages, hook translation.

#### [`generate-json-schema/`](../generate-json-schema/SKILL.md)
`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/`](../bridge-standard-schema/SKILL.md)
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.

#### [`extend-seal-with-plugins/`](../extend-seal-with-plugins/SKILL.md)
Author a plugin to add validator methods (`.slug`, `.postalCode`, …) — the `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation.

## Configuration

`configureSeal({ ... })` sets global behavior (translation hooks, first-error-only mode); `getSealConfig()` reads it; `resetSealConfig()` clears it. Most apps call `configureSeal` once at boot to wire i18n.

## What this package deliberately doesn't do

- **Framework-bound validation.** File-upload and database (exists/unique) rules live in `@warlock.js/core/v`, which builds on this package.
- **Coercion by default.** Seal validates the shape you declare; reshaping is explicit via mutators/transformers, not silent coercion.
- **Async-everywhere.** `validate()` is async to support rules that need it, but the core primitives are synchronous checks.

## See also

- [`@warlock.js/cascade`](../../cascade/skills/overview/SKILL.md) — uses seal schemas as `Model.schema`.
- [`@warlock.js/core`](../../core/skills/overview/SKILL.md) — re-exports `v` (aliased) and adds framework validators in `core/v`.
- [`mongez-agent-kit-authoring-skills`](../../../../domains/shared/skills/) (load via agent-kit sync) — how this becomes `.claude/skills/warlock-js-seal-overview/`.


## pick-seal-primitive  `@warlock.js/seal/pick-seal-primitive/SKILL.md`

---
name: pick-seal-primitive
description: 'Pick the right `v` factory primitive — string / int / literal / date / enum / computed / managed / instanceof / any. Triggers: `v.string`, `v.email`, `v.number`, `v.int`, `v.float`, `v.numeric`, `v.boolean`, `v.scalar`, `v.date`, `v.literal`, `v.enum`, `v.instanceof`, `v.computed`, `v.managed`, `v.any`; "v.string vs v.scalar", "v.literal vs v.enum", "v.date vs v.instanceof(Date)", "what is v.computed"; typical import `import { v } from "@warlock.js/seal"`. Skip: structural shapes — `@warlock.js/seal/define-structural-shape/SKILL.md`; modifiers — `@warlock.js/seal/compose-seal-modifiers/SKILL.md`; competing libs `zod`, `valibot`, `yup`.'
---

# 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.

## 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
```

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` |
| `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.

## 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
```

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.

## 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()` 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.

## 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.instanceof(File)                          // type: File
v.instanceof(Buffer)                        // type: Buffer
v.instanceof(MyClass)                       // type: MyClass
```

**`v.literal` vs `v.string().oneOf([...])` vs `v.enum([...])`:**

- `v.literal("a", "b")` infers as `"a" | "b"` (literal narrowing). **Use this for discriminator fields.**
- `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.instanceof(Ctor)` for File/Buffer/Uint8Array/custom classes. Returns `{}` from `toJsonSchema()` (not representable). For OpenAPI `File`, attach `{ type: "string", format: "binary" }` manually after generation.

## `v.any` — escape hatch

```ts
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.

## Derived: `v.computed` and `v.managed`

These two **don't validate input** — they produce a value as part of validation.

```ts
v.object({
  firstName: v.string(),
  lastName: v.string(),
  fullName: v.computed<string>((data) => `${data.firstName} ${data.lastName}`),
  createdAt: v.managed<Date>(() => new Date()),
  createdBy: v.managed<string>((context) => context.context?.userId),
});
```

- **`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).

## 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 [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md) |
| 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

Each primitive's full method list lives in a sibling file:

- [`string-methods.md`](./string-methods.md) — `.email` / `.url` / `.uuid` / `.pattern` / `.startsWith` / `.alpha` / `.trim` / `.slug` / `.mask` / `.base64Encode` / …
- [`number-methods.md`](./number-methods.md) — `.min` / `.max` / `.between` / `.greaterThan` / `.positive` / `.even` / `.multipleOf` / `.minSibling` / `.round` / …
- [`date-methods.md`](./date-methods.md) — `.min` / `.before` / `.after` / `.today` / `.past` / `.future` / `.weekDay` / `.minAge` / `.year` / `.quarter` / `.toISOString` / …
- [`boolean-methods.md`](./boolean-methods.md) — `.accepted` / `.declined` / `.mustBeTrue` / `.mustBeFalse` / `.acceptedIf` / `.declinedWithout` / …

For cross-cutting modifiers (`.optional`/`.nullable`/`.default`/`.catch`/`.in`/`.oneOf`), see [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md). For containers (object/array/record/tuple/union), see [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md).

## Things NOT to do

- Don't `new ObjectValidator()` (or any class) directly — factory returns carry the StandardSchema bridge that bare instantiation loses.
- 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.


### pick-seal-primitive/boolean-methods.md  `@warlock.js/seal/pick-seal-primitive/boolean-methods.md`

# `v.boolean()` — method reference

Picking guide is in [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md). Membership rules (`.in`/`.oneOf`) inherited from PrimitiveValidator — see [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md).

## Strict equality

| Method | Effect |
|---|---|
| `.mustBeTrue(msg?)` | strictly `=== true` (rejects `"yes"`, `1`, `"on"`) |
| `.mustBeFalse(msg?)` | strictly `=== false` |

Use these when the field is a real boolean checkbox value — e.g. "agree to terms" must be exactly `true`, not a truthy string.

## Form-style coercion — `accepted` / `declined`

The "accepted" rules treat `true`, `"yes"`, `"on"`, `1`, `"1"`, `"true"` as accepted. "Declined" treats their counterparts (`false`, `"no"`, `"off"`, `0`, etc.) as declined. Designed for form inputs where a checkbox/radio arrives as a string.

| Method | Effect |
|---|---|
| `.accepted(msg?)` | value must be accepted |
| `.declined(msg?)` | value must be declined |

## Conditional variants — accepted

| Method | Args | Effect |
|---|---|---|
| `.acceptedIf(field, value, msg?)` | sibling field equals value | must be accepted in that case |
| `.acceptedUnless(field, value, msg?)` | sibling field equals value | must be accepted unless that's true |
| `.acceptedIfRequired(field, msg?)` | sibling field is required | — |
| `.acceptedIfPresent(field, msg?)` | sibling field is present | — |
| `.acceptedWithout(field, msg?)` | sibling field is absent | — |

## Conditional variants — declined

| Method | Args | Effect |
|---|---|---|
| `.declinedIf(field, value, msg?)` | sibling field equals value | must be declined in that case |
| `.declinedUnless(field, value, msg?)` | sibling field equals value | must be declined unless that's true |
| `.declinedIfRequired(field, msg?)` | — | — |
| `.declinedIfPresent(field, msg?)` | — | — |
| `.declinedWithout(field, msg?)` | — | — |

All conditional variants only run inside `v.object` — sibling resolution silently passes otherwise.

## JSON Schema mapping

- `v.boolean()` → `{ type: "boolean" }`
- `.mustBeTrue()` / `.mustBeFalse()` — not currently emitted (could add `const: true/false` in the future)
- `.accepted()` / `.declined()` and their conditional variants — runtime coercion concerns, not representable

## Common chains

```ts
// Strict consent checkbox
v.boolean().mustBeTrue("You must accept the terms")

// Form-style "remember me" — accepts "on" / true / 1
v.boolean().accepted().optional()

// Cross-field — newsletter must be accepted if subscriptionType = "premium"
v.object({
  subscriptionType: v.string().oneOf(["free", "premium"]),
  newsletter: v.boolean().acceptedIf("subscriptionType", "premium"),
})

// Marketing opt-in — declined unless region is GDPR-exempt
v.object({
  region: v.string(),
  marketingOptIn: v.boolean().declinedUnless("region", "US"),
})
```


### pick-seal-primitive/date-methods.md  `@warlock.js/seal/pick-seal-primitive/date-methods.md`

# `v.date()` — method reference

`v.date()` ships a built-in mutator that normalizes strings, timestamps, and `Date` objects to a `Date` before rules run. Picking guide (`v.date()` vs `v.instanceof(Date)`) is in [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md).

## 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)` |

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 |
| `.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 |
| `.beforeToday(msg?)` | strictly before today |
| `.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 | — |

## 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 |
| `.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 |

## 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 |

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 |

## Format

| 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.

## 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"` |

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 |
|---|---|
| `.defaultNow()` | shorthand for `.default(() => new Date())` |

## JSON Schema mapping

- `v.date()` → `{ type: "string", format: "date-time" }` by default
- After `.toDateOnly()` or `.format("YYYY-MM-DD")` → `{ type: "string", format: "date" }`
- After `.toTimeOnly()` or `.format("HH:mm:ss")` → `{ type: "string", format: "time" }`
- Sibling-scoped rules and most relative checks are not representable — silently omitted

## Common chains

```ts
// Birthday — must be 13+ and in the past
v.date().past().minAge(13)

// Reservation — future, business day, between hours
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()

// Event window — within 30 future days, normalized to UTC
v.date().toUTC().withinFutureDays(30)

// Quarterly report
v.date().quarter(1).year(2026)

// Date-only, end-of-day for inclusive comparisons
v.date().toEndOfDay().toDateOnly()
```


### pick-seal-primitive/number-methods.md  `@warlock.js/seal/pick-seal-primitive/number-methods.md`

# `v.number()` / `v.int()` / `v.float()` / `v.numeric()` — method reference

All four share this surface. The picking guide (which factory to call) is in [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md). For `.optional()` / `.in()` / `.oneOf()`, see [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md).

## 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` | — |

`.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
})
```

Sibling references are **not representable in JSON Schema** — silently omitted from generated output.

## Range — explicit sibling scope

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 |
| `.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()` |

## 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` |

## 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` |

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 | format as fixed-point |

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.

## JSON Schema notes

- `v.number()` → `{ type: "number" }`
- `v.int()` → `{ type: "integer" }`
- `v.float()` → `{ type: "number" }` (no JSON Schema distinction from `number`)
- `v.numeric()` → `{ type: "number" }` (input coercion is a runtime concern)
- `exclusiveMinimum` / `exclusiveMaximum` are encoded as numbers in `draft-2020-12` and `openapi-3.0`, but as boolean flags + `minimum`/`maximum` in `draft-07`.

## Common chains

```ts
// Age
v.int().min(0).max(150)

// Price (cents)
v.int().min(0)

// Probability
v.number().between(0, 1)

// Even page index
v.int().min(0).even()

// Quantity divisible by box size
v.int().min(1).multipleOf(12)

// Coerced from form input
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()
```


### pick-seal-primitive/string-methods.md  `@warlock.js/seal/pick-seal-primitive/string-methods.md`

# `v.string()` — method reference

Reference for `v.string()` / `v.email()`. Covers length, format, content, color, mutators (case, trim, mask, slug, base64, …) and what each maps to in JSON Schema.

For the picking guide (`v.string` vs `v.scalar` vs `v.literal`), see [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md). For `.optional()` / `.nullable()` / `.default()` / `.in()` / `.oneOf()`, see [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md).

## 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)` |

## 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)` |

## 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)` |

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)` |

## 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("@")` |
| `.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 | — |

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" | — |

## 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 |

## 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" |

## Filter mutators

| Method | Effect |
|---|---|
| `.toAlpha()` | strip non-letters |
| `.toAlphanumeric()` | strip non-alphanumerics |
| `.removeSpecialCharacters()` | keep alphanumerics + whitespace |
| `.removeNumbers()` | strip digits |
| `.safeHtml()` | strip HTML tags |
| `.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 |

## 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 [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md)).

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()

// Username
v.string().min(3).max(30).alphanumeric().lowercase()

// Slug from title
v.string().slug()

// Strong password
v.string().strongPassword(12)

// URL with strict format
v.string().url().startsWith("https://")

// Sanitized HTML body
v.string().safeHtml().min(1)

// Masked phone for response
v.string().pattern(/^\+\d{8,}$/).mask(3, -2)

// Optional with default
v.string().email().default("guest@example.com").optional()
```


## seal-basics  `@warlock.js/seal/seal-basics/SKILL.md`

---
name: seal-basics
description: 'Start with @warlock.js/seal — the `v` factory, `validate(schema, data)`, and `Infer<typeof schema>`. Triggers: `v`, `validate`, `Infer`, `Infer.Input`, `Infer.Output`, `v.object`, `v.lazy`, `v.discriminatedUnion`, `v.computed`, `v.managed`, `ValidationResult`; "how do I start with seal", "what is the v factory", "validate a schema in warlock", "Infer.Input vs Infer.Output"; typical import `import { v, validate, type Infer } from "@warlock.js/seal"`. Skip: primitive picking — `@warlock.js/seal/pick-seal-primitive/SKILL.md`; modifiers — `@warlock.js/seal/compose-seal-modifiers/SKILL.md`; competing libs `zod`, `valibot`, `yup`, `joi`, `ajv`.'
---

# 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.

> This skill is the seal **map** — read it first, then load the specific skill for the task.

## Install

```bash
yarn add @warlock.js/seal
```

Most warlock projects already have `@warlock.js/seal` transitively via `@warlock.js/core` (which re-exports the `v` factory and `Infer` types). Import direct from the package you control: `@warlock.js/seal` if you build a leaf package, `@warlock.js/core` if you write app code.

## Minimal example

```ts
import { v, validate, type Infer } from "@warlock.js/seal";

const userSchema = v.object({
  email: v.string().email(),
  age: v.int().min(13).optional(),
  role: v.literal("admin", "user", "guest"),
});

type User = Infer<typeof userSchema>;
// { email: string; age?: number; role: "admin" | "user" | "guest" }

const result = await validate(userSchema, input);
if (result.isValid) {
  result.data;      // typed, post-transformer
} else {
  result.errors;    // [{ type, error, input }, ...]
}
```

## Foundations

The 12 things that are true in every seal use:

1. **Public API is the `v` factory.** Never `new ObjectValidator(...)` from app code — bare classes lose the StandardSchema bridge typing. See [`@warlock.js/seal/bridge-standard-schema/SKILL.md`](@warlock.js/seal/bridge-standard-schema/SKILL.md).
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 [`@warlock.js/seal/handle-seal-errors/SKILL.md`](@warlock.js/seal/handle-seal-errors/SKILL.md).
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.
9. **JSON Schema generation is built-in.** `schema.toJsonSchema(target)` for `"draft-2020-12"` (default), `"draft-07"`, `"openapi-3.0"`, `"openai-strict"`. See [`@warlock.js/seal/generate-json-schema/SKILL.md`](@warlock.js/seal/generate-json-schema/SKILL.md).
10. **`v.computed` / `v.managed` derive — they don't validate inputs.** They produce values from siblings or context, and are **skipped** when the parent `v.object` emits JSON Schema (runtime-only constructs — calling `.toJsonSchema()` on one directly throws).
11. **`v.lazy(() => schema)` for recursive shapes.** Defers resolution until validate-time so self-referencing types work.
12. **`v.discriminatedUnion(field, branches)` for tagged unions.** Routes by a literal discriminator field instead of `matchesType()` trial — precise errors, exact inference.

## `Infer.Input` vs `Infer.Output`

The two inference shapes describe the two halves of the pipeline:

- **`Infer.Input<T>`** — what the caller sends. `.optional()`, `.default()`, `.catch()` all make a key optional (any of them means "you don't have to supply this").
- **`Infer.Output<T>`** — what `data` contains after validation. `.default()` and `.catch()` guarantee a value, so keys with those brands are required even when chained with `.optional()`.

```ts
const schema = v.object({
  email: v.string().email().optional(),
  status: v.enum(Status).optional().default(Status.ACTIVE),
});

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
```

Both flavours widen with `| null` when `.nullable()` is set.

**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()`.

## 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)`) | [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md) |
| Building object / array / record / tuple / union schemas, discriminated unions, recursive schemas | [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md) |
| Modifiers — `.required` / `.optional` / `.nullable` / `.default` / `.catch` / `.omit`, transformer vs mutator pipelines, membership rules | [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md) |
| Reading `ValidationResult`, branching on `error.type`, error message customization, translation | [`@warlock.js/seal/handle-seal-errors/SKILL.md`](@warlock.js/seal/handle-seal-errors/SKILL.md) |
| Generating JSON Schema for OpenAI strict / OpenAPI / draft-07 | [`@warlock.js/seal/generate-json-schema/SKILL.md`](@warlock.js/seal/generate-json-schema/SKILL.md) |
| Why a `StandardSchemaV1<T>` slot accepts/rejects a schema, the phantom-intersection design, `Result<unknown>` errors | [`@warlock.js/seal/bridge-standard-schema/SKILL.md`](@warlock.js/seal/bridge-standard-schema/SKILL.md) |
| Authoring custom seal plugins to add validator methods | [`@warlock.js/seal/extend-seal-with-plugins/SKILL.md`](@warlock.js/seal/extend-seal-with-plugins/SKILL.md) |

## Things NOT to do

- Don't `new ObjectValidator(...)` from app code — use `v.object(...)` so the StandardSchema bridge attaches.
- Don't annotate a schema with the bare class type — strips the bridge intersection. Let inference run.
- Don't expect `validate()` to throw on bad input — bad input lands in `result.errors`. The only things that throw are bugs (a rule's callback threw, a transformer threw).
- Don't expect `.requiredIf()` / `.sameAs()` to work on a standalone validator outside `v.object` — sibling resolution silently passes.
- Don't put `.trim()` before `.min(3)` and expect it to trim first — `.trim()` is a transformer (post-validation). For pre-validation trim, attach with `.addMutator(s => s.trim())`.