@warlock.js/seal 4.0.174 → 4.1.2

package/skills/pick-seal-primitive/date-methods.md

@@ -0,0 +1,175 @@
+# `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()
+```

package/skills/pick-seal-primitive/number-methods.md

@@ -0,0 +1,123 @@
+# `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()
+```

package/skills/pick-seal-primitive/string-methods.md

@@ -0,0 +1,169 @@
+# `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()
+```

package/skills/seal-basics/SKILL.md

@@ -0,0 +1,106 @@
+---
+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())`.

package/cjs/config.d.ts

@@ -1,48 +0,0 @@
-/**
- * Seal Configuration
- *
- * Global configuration for the Seal validation library
- */
-import type { AttributeTranslation, RuleTranslation } from "./types";
-export type TranslateRuleCallback = (ruleTranslation: RuleTranslation) => string;
-export type TranslateAttributeCallback = (attributeTranslation: AttributeTranslation) => string;
-export type SealConfig = {
-    /**
-     * Translation function for error messages
-     * Default: returns the key with attributes replaced
-     */
-    translateRule?: TranslateRuleCallback;
-    /**
-     * Translation function for attribute messages
-     */
-    translateAttribute?: TranslateAttributeCallback;
-    /**
-     * Default to first error only in validation
-     * Default: true
-     */
-    firstErrorOnly?: boolean;
-};
-/**
- * Configure Seal globally
- *
- * @example
- * ```ts
- * import { configureSeal } from "@warlock.js/seal";
- * import { trans } from "@mongez/localization";
- *
- * configureSeal({
- *   translateRule: (ruleTranslation) => trans(`validation.${ruleTranslation.rule.name}`, ruleTranslation.attributes),
- *   translateAttribute: (attributeTranslation) => trans(`validation.attributes.${attributeTranslation.rule.name}.${attributeTranslation.attribute}`, attributeTranslation.context.allValues),
- * });
- * ```
- */
-export declare function configureSeal(options: Partial<SealConfig>): void;
-/**
- * Get current Seal configuration
- */
-export declare function getSealConfig(): SealConfig;
-/**
- * Reset configuration to defaults
- */
-export declare function resetSealConfig(): void;
-//# sourceMappingURL=config.d.ts.map

package/cjs/config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,CAClC,eAAe,EAAE,eAAe,KAC7B,MAAM,CAAC;AAEZ,MAAM,MAAM,0BAA0B,GAAG,CACvC,oBAAoB,EAAE,oBAAoB,KACvC,MAAM,CAAC;AAEZ,MAAM,MAAM,UAAU,GAAG;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC;;OAEG;IACH,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IAEhD;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AASF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAKtC"}

package/cjs/config.js

@@ -1,42 +0,0 @@
-'use strict';/**
- * Seal Configuration
- *
- * Global configuration for the Seal validation library
- */
-/**
- * Global Seal configuration
- */
-const config = {
-    firstErrorOnly: true,
-};
-/**
- * Configure Seal globally
- *
- * @example
- * ```ts
- * import { configureSeal } from "@warlock.js/seal";
- * import { trans } from "@mongez/localization";
- *
- * configureSeal({
- *   translateRule: (ruleTranslation) => trans(`validation.${ruleTranslation.rule.name}`, ruleTranslation.attributes),
- *   translateAttribute: (attributeTranslation) => trans(`validation.attributes.${attributeTranslation.rule.name}.${attributeTranslation.attribute}`, attributeTranslation.context.allValues),
- * });
- * ```
- */
-function configureSeal(options) {
-    Object.assign(config, options);
-}
-/**
- * Get current Seal configuration
- */
-function getSealConfig() {
-    return config;
-}
-/**
- * Reset configuration to defaults
- */
-function resetSealConfig() {
-    delete config.translateRule;
-    delete config.translateAttribute;
-    config.firstErrorOnly = true;
-}exports.configureSeal=configureSeal;exports.getSealConfig=getSealConfig;exports.resetSealConfig=resetSealConfig;//# sourceMappingURL=config.js.map

package/cjs/config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.js","sources":["../src/config.ts"],"sourcesContent":[null],"names":[],"mappings":"aAAA;;;;AAIG;AA8BH;;AAEG;AACH,MAAM,MAAM,GAAe;AACzB,IAAA,cAAc,EAAE,IAAI;CACrB,CAAC;AAEF;;;;;;;;;;;;;AAaG;AACG,SAAU,aAAa,CAAC,OAA4B,EAAA;AACxD,IAAA,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACjC,CAAC;AAED;;AAEG;SACa,aAAa,GAAA;AAC3B,IAAA,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;AAEG;SACa,eAAe,GAAA;IAC7B,OAAO,MAAM,CAAC,aAAa,CAAC;IAC5B,OAAO,MAAM,CAAC,kBAAkB,CAAC;AAEjC,IAAA,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;AAC/B"}