@warlock.js/seal 4.0.171 → 4.1.1

package/llms.txt

@@ -0,0 +1,17 @@
+# Warlock Seal
+
+> Package: `@warlock.js/seal`
+
+> Comprehensive Validation library
+
+## Skills
+
+- [bridge-standard-schema](@warlock.js/seal/bridge-standard-schema/SKILL.md): Diagnose `StandardSchemaV1` interop — phantom-intersection at the `v` factory return, why typed slots reject a schema, cascade `Model<TSchema>` variance. Triggers: `StandardSchemaV1`, `~standard`, `Infer`, `ObjectValidator`, `StringValidator`, `LiteralValidator`, `BaseValidator`, `Model<TSchema>`, `StandardJSONSchemaV1`, `Result<unknown>`; "StandardSchemaV1 slot rejecting my schema", "Result<unknown> error", "drop as unknown as cast", "cascade Model schema variance"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: foundations — `@warlock.js/seal/seal-basics/SKILL.md`; JSON Schema gen — `@warlock.js/seal/generate-json-schema/SKILL.md`; competing spec `@standard-schema/spec`.
+- [compose-seal-modifiers](@warlock.js/seal/compose-seal-modifiers/SKILL.md): Apply cross-cutting modifiers — `.optional` / `.nullable` / `.default` / `.catch` / `.omit` / membership rules — plus the mutator-vs-transformer pipeline and `Infer.Input` vs `Infer.Output`. Triggers: `.optional`, `.required`, `.nullable`, `.default`, `.catch`, `.present`, `.requiredIf`, `.requiredWith`, `.in`, `.oneOf`, `.notIn`, `.omit`, `.attribute`, `.mutable`, `.addMutator`, `Infer.Input`, `Infer.Output`; "mark field optional in seal", "default value in schema", "mutator vs transformer", "when does .catch fire"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: primitives — `@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`.
+- [define-structural-shape](@warlock.js/seal/define-structural-shape/SKILL.md): Compose `v.object` / `v.array` / `v.record` / `v.tuple` / `v.union` / `v.discriminatedUnion` / `v.lazy`. Triggers: `v.object`, `v.array`, `v.record`, `v.tuple`, `v.union`, `v.discriminatedUnion`, `v.lazy`, `ObjectValidator`; "how do I build an object schema", "dynamic-keyed record", "tagged union with discriminator", "recursive schema", "self-referencing schema"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: leaf primitives — `@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`.
+- [extend-seal-with-plugins](@warlock.js/seal/extend-seal-with-plugins/SKILL.md): Author a custom seal plugin to add validator methods (`.slug`, `.postalCode`, etc) — `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation. Triggers: `SealPlugin`, `registerPlugin`, `unregisterPlugin`, `hasPlugin`, `getInstalledPlugins`, `StringValidator`, `NumberValidator`, `DateValidator`, `BaseValidator`, `install`, `uninstall`; "how do I add a custom validator method", "write a seal plugin", "extend v.string with .slug", "module augmentation for seal"; typical import `import { StringValidator, registerPlugin, type SealPlugin } from "@warlock.js/seal"`. Skip: built-in primitives — `@warlock.js/seal/pick-seal-primitive/SKILL.md`; bridge typing — `@warlock.js/seal/bridge-standard-schema/SKILL.md`; competing `zod` `.refine`/`.transform`.
+- [generate-json-schema](@warlock.js/seal/generate-json-schema/SKILL.md): 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`.
+- [handle-seal-errors](@warlock.js/seal/handle-seal-errors/SKILL.md): 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`.
+- [overview](@warlock.js/seal/overview/SKILL.md): 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.
+- [pick-seal-primitive](@warlock.js/seal/pick-seal-primitive/SKILL.md): 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`.
+- [seal-basics](@warlock.js/seal/seal-basics/SKILL.md): 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`.

package/package.json

@@ -1,49 +1,38 @@
 {
-    "name": "@warlock.js/seal",
-    "version": "4.0.171",
-    "description": "Comprehensive Validation library",
-    "main": "./cjs/index.js",
-    "dependencies": {
-        "@mongez/supportive-is": "^2.0.0",
-        "dayjs": "^1.11.9"
-    },
-    "scripts": {
-        "test": "vitest",
-        "test:run": "vitest run",
-        "test:coverage": "vitest run --coverage",
-        "test:ui": "vitest --ui",
-        "lint": "eslint ./tests/**/*.{ts,tsx,json,md}",
-        "lint:fix": "eslint ./tests/**/*.{ts,tsx,json,md} --fix",
-        "format": "prettier --write ./tests/**/*.{ts,tsx,json,md}",
-        "format:check": "prettier --check ./tests/**/*.{ts,tsx,json,md}"
-    },
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/warlockjs/seal"
-    },
-    "keywords": [
-        "validation",
-        "typescript",
-        "framework-agnostic",
-        "seal",
-        "warlock.js"
-    ],
-    "author": "hassanzohdy",
-    "license": "MIT",
-    "devDependencies": {
-        "@vitest/coverage-v8": "^4.0.6",
-        "@vitest/ui": "^4.0.6",
-        "@typescript-eslint/eslint-plugin": "^7.1.1",
-        "@typescript-eslint/parser": "^7.1.1",
-        "eslint": "^8.57.0",
-        "eslint-config-prettier": "^9.1.0",
-        "eslint-plugin-prettier": "^5.1.3",
-        "eslint-plugin-unused-imports": "^3.1.0",
-        "prettier": "^3.2.5",
-        "prettier-plugin-organize-imports": "^3.2.4",
-        "typescript": "^5.9.3",
-        "vitest": "^4.0.6"
-    },
-    "module": "./esm/index.js",
-    "typings": "./cjs/index.d.ts"
-}
+  "name": "@warlock.js/seal",
+  "description": "Comprehensive Validation library",
+  "keywords": [
+    "validation",
+    "typescript",
+    "framework-agnostic",
+    "seal",
+    "warlock.js"
+  ],
+  "author": "hassanzohdy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/warlockjs/seal"
+  },
+  "dependencies": {
+    "@mongez/supportive-is": "^2.1.3",
+    "@mongez/reinforcements": "^3.2.0",
+    "dayjs": "^1.11.9"
+  },
+  "version": "4.1.1",
+  "main": "./cjs/index.cjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./esm/index.d.mts",
+        "default": "./cjs/index.cjs"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,138 @@
+---
+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.

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

@@ -0,0 +1,271 @@
+---
+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.