@warlock.js/seal 5.23.2 → 5.25.0

package/package.json

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

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

@@ -1,138 +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.
+---
+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/define-structural-shape/SKILL.md

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