@warlock.js/seal 4.0.174 → 4.1.1

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

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

package/skills/define-structural-shape/array-methods.md

@@ -0,0 +1,78 @@
+# `v.array(itemValidator)` — method reference
+
+The inner validator runs against each element. Failure on any element fails the array. Picking guide (array vs tuple vs record) is in [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md).
+
+## Length
+
+| Method | Args | JSON Schema | Example |
+|---|---|---|---|
+| `.min(n, msg?)` | n/a — see note below | — | use `.minLength(n)` |
+| `.minLength(n, msg?)` | inclusive lower bound | `minItems: n` | `v.array(v.string()).minLength(1)` |
+| `.maxLength(n, msg?)` | inclusive upper bound | `maxItems: n` | `v.array(v.string()).maxLength(10)` |
+| `.length(n, msg?)` | exact length | `minItems=maxItems=n` | `v.array(v.string()).length(3)` |
+| `.between(a, b, msg?)` | inclusive range | `minItems: a, maxItems: b` | `v.array(v.string()).between(1, 10)` |
+| `.lengthBetween(a, b, msg?)` | alias for `.between()` | `minItems: a, maxItems: b` | — |
+
+**Note on `.min`/`.max`:** the array validator does not expose `.min`/`.max` directly — use `.minLength`/`.maxLength` (or `.between`/`.length`). This is intentional: `.min`/`.max` would conflict with primitive value-comparison semantics if they ever bled into here.
+
+## Uniqueness & sort
+
+| Method | Args | Effect |
+|---|---|---|
+| `.unique(msg?)` | — | every element is distinct |
+| `.sorted(direction?, msg?)` | `"asc"` (default) or `"desc"` | array is monotonically sorted |
+
+## Mutators (pre-validation reshape)
+
+| Method | Args | Effect |
+|---|---|---|
+| `.flip()` | — | reverse the array |
+| `.reverse()` | — | alias for `.flip()` |
+| `.onlyUnique()` | — | dedupe before validation |
+| `.sort(direction?, key?)` | `"asc"` (default) or `"desc"`; optional sort key for object items | sort before validation |
+
+`onlyUnique()` and `unique()` differ: the mutator silently dedupes; the rule fails when duplicates are present. Pick by intent — coerce vs reject.
+
+## Inner validator notes
+
+```ts
+v.array(v.string().email())              // every element must be a valid email
+v.array(userSchema)                      // every element must satisfy userSchema
+v.array(v.array(v.int()))                // matrix-ish — Infer is recursive
+```
+
+Element validators run with element-level context. `path` becomes `${parent}.${index}` for error messages. Cross-field rules inside element schemas resolve to that element's fields, not the array.
+
+## JSON Schema mapping
+
+- `v.array(item)` → `{ type: "array", items: <item.toJsonSchema()> }`
+- `.minLength(n)` → `minItems: n`
+- `.maxLength(n)` → `maxItems: n`
+- `.length(n)` → `minItems: n, maxItems: n`
+- `.between(a, b)` → `minItems: a, maxItems: b`
+- `.unique()` and `.sorted()` are NOT representable — silently omitted
+
+## Common chains
+
+```ts
+// Tags
+v.array(v.string().min(1)).unique().between(1, 10)
+
+// User list
+v.array(userSchema).minLength(1)
+
+// Pre-sorted, deduped
+v.array(v.string()).onlyUnique().sort("asc")
+
+// Reverse-emit
+v.array(v.string()).flip()
+
+// Matrix
+v.array(v.array(v.number())).minLength(1)
+
+// Sorted ids
+v.array(v.string().uuid()).sorted("asc").unique()
+
+// Optional list with default
+v.array(v.string()).default([]).optional()
+```

package/skills/define-structural-shape/object-methods.md

@@ -0,0 +1,166 @@
+# `v.object({...})` — method reference
+
+Picking guide for structural validators is in [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md). For field-level chaining (`.required` / `.optional` / `.attribute`), see [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md).
+
+## Schema composition
+
+These return a new `ObjectValidator` with a transformed schema. The TypeScript inference follows correctly — `Infer<>` reflects the post-composition shape.
+
+### `.extend(schemaOrValidator)` — add fields, keep config
+
+```ts
+const baseUser = v.object({
+  name: v.string(),
+  email: v.string().email(),
+}).allowUnknown();
+
+const adminUser = baseUser.extend({
+  role: v.string().oneOf(["admin", "superadmin"]),
+});
+// adminUser type: { name; email; role } — keeps allowUnknown()
+```
+
+Accepts a plain schema object **or** another `ObjectValidator` (only its schema is used — config is ignored). Use for reusable field collections (e.g. timestamp fields).
+
+### `.merge(otherValidator)` — combine, override config
+
+```ts
+const base = v.object({ name: v.string() }).allowUnknown();
+const audit = v.object({
+  createdAt: v.date(),
+  updatedAt: v.date(),
+}).stripUnknown();
+
+const merged = base.merge(audit);
+// type: { name; createdAt; updatedAt }
+// config: stripUnknown() from audit (overrides base's allowUnknown)
+```
+
+`.merge` combines schemas **and** configurations — the other validator wins. Rules, mutators, transformers, and attribute display names from both validators are appended.
+
+### `.pick(...keys)` — keep only specified fields
+
+```ts
+const fullUser = v.object({
+  id: v.int(),
+  name: v.string(),
+  email: v.string().email(),
+  password: v.string(),
+});
+
+const loginSchema = fullUser.pick("email", "password");
+// type: { email; password }
+```
+
+Returns `ObjectValidator<Pick<TSchema, K>>`. Keeps original config (`allowUnknown`, etc.).
+
+### `.without(...keys)` — drop specified fields
+
+```ts
+const updateSchema = fullUser.without("id");
+// type: { name; email; password }
+```
+
+Returns `ObjectValidator<Omit<TSchema, K>>`. Inverse of `.pick`. Keeps original config.
+
+### `.partial(...keys?)` — mark fields optional
+
+```ts
+fullUser.partial()                // every field becomes optional
+fullUser.partial("password")      // only `password` becomes optional
+```
+
+Walks the schema and applies `.optional()` to each named field (or all if no keys given). `Infer<>` makes those keys optional.
+
+### `.requiredFields(...keys?)` — mark fields required
+
+```ts
+const partialUser = fullUser.partial();    // all optional
+const updateUser = partialUser.requiredFields("id", "email");
+// id and email are required again, others stay optional
+```
+
+Inverse of `.partial`.
+
+## Unknown-keys policy
+
+By default, extra keys in input are silently dropped from `data` (no error, no forward).
+
+| Method | Effect |
+|---|---|
+| `.allowUnknown(allow = true)` | extra **direct-child** keys forward as-is |
+| `.stripUnknown()` | explicit drop (mutator-based — affects `data` shape) |
+| `.allow(...keys)` | whitelist specific extras to forward without validation |
+
+`.allowUnknown()` only affects direct children — nested objects keep their own policies. For a fully permissive object including nested children, set `.allowUnknown()` on each level.
+
+## Object-level mutators
+
+| Method | Args | Effect |
+|---|---|---|
+| `.trim(recursive?)` | default `true` | recursively trim string values across the object |
+
+For per-field mutators, attach on the field validator instead.
+
+## Cross-field rules — context
+
+The cross-field methods (`.sameAs`, `.requiredIf`, `.requiredWith`, etc.) are **field-level**, not object-level — you call them on the field validator inside `v.object`. The object validator's job is to hand them the parent context so sibling resolution works:
+
+```ts
+v.object({
+  password: v.string(),
+  passwordConfirm: v.string().sameAs("password"),
+})
+```
+
+If you call cross-field rules outside a `v.object`, sibling resolution silently passes — there's nobody to compare against.
+
+## `Infer<>` semantics
+
+```ts
+Infer<typeof userSchema>
+// { reqField: T; optField?: T }
+```
+
+- Required fields → required keys
+- `.optional()` fields → optional keys (`?:`)
+- `.omit()` / `.exclude()` fields → dropped from the inferred type
+- `v.computed<T>()` / `v.managed<T>()` → present as `T` in inferred output (they produce values)
+
+## Common chains
+
+```ts
+// User CRUD trio from one base
+const baseUser = v.object({
+  id: v.int(),
+  name: v.string(),
+  email: v.string().email(),
+  password: v.string(),
+});
+
+const createUser = baseUser.without("id");
+const updateUser = baseUser.partial().requiredFields("id");
+const loginUser = baseUser.pick("email", "password");
+
+// Reusable timestamps
+const timestamps = v.object({
+  createdAt: v.date(),
+  updatedAt: v.date(),
+});
+
+const userWithAudit = baseUser.extend(timestamps);
+
+// Permissive container that forwards extras
+const eventEnvelope = v.object({
+  type: v.literal("user.created", "user.updated"),
+  payload: v.object({}).allowUnknown(),
+}).allowUnknown();
+
+// Confirmation pattern with omit
+const signupSchema = v.object({
+  password: v.string().strongPassword(),
+  passwordConfirm: v.string().sameAs("password").omit(),
+  email: v.string().email(),
+});
+// Infer<> = { password; email } — passwordConfirm omitted from output
+```

package/skills/extend-seal-with-plugins/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: extend-seal-with-plugins
+description: 'Author a custom seal plugin to add validator methods (`.slug`, `.postalCode`, etc) — `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation. Triggers: `SealPlugin`, `registerPlugin`, `unregisterPlugin`, `hasPlugin`, `getInstalledPlugins`, `StringValidator`, `NumberValidator`, `DateValidator`, `BaseValidator`, `install`, `uninstall`; "how do I add a custom validator method", "write a seal plugin", "extend v.string with .slug", "module augmentation for seal"; typical import `import { StringValidator, registerPlugin, type SealPlugin } from "@warlock.js/seal"`. Skip: built-in primitives — `@warlock.js/seal/pick-seal-primitive/SKILL.md`; bridge typing — `@warlock.js/seal/bridge-standard-schema/SKILL.md`; competing `zod` `.refine`/`.transform`.'
+---
+
+# Extend seal with plugins
+
+Seal exposes a plugin system so you can add validator methods without forking the package. A plugin is an object with `name`, optional `version`/`description`, and an `install` function that runs once when the plugin is registered. The standard pattern is to `Object.assign(StringValidator.prototype, { ... })` to graft new methods onto a validator class.
+
+## When to reach for a plugin
+
+- The validator method you want **does not exist** in built-in seal — check [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md) and its method references first.
+- The validation is **stable and reusable** across modules — domain-specific formats (IBAN, postal codes, tax IDs, license plates, internal ID schemes).
+- You want the **chainable syntax** — `v.string().slug()` reads better than `v.string().pattern(/.../).addMutator(s => slugify(s))` at every call site.
+
+**Don't** reach for a plugin when a one-off `.pattern()` would do. The boilerplate (declare module, register on boot) is justified only when you'll call the new method many times.
+
+## The plugin shape
+
+```ts
+import type { SealPlugin } from "@warlock.js/seal";
+
+type SealPlugin = {
+  name: string;          // unique identifier — duplicates warn and skip install
+  version?: string;
+  description?: string;
+  install: (context: { name: string; version?: string }) => void | Promise<void>;
+  uninstall?: () => void | Promise<void>;
+};
+```
+
+The `install` function is where you add methods. Typically you patch a validator class prototype:
+
+```ts
+import { StringValidator, type SealPlugin } from "@warlock.js/seal";
+
+export const slugPlugin: SealPlugin = {
+  name: "slug",
+  version: "1.0.0",
+  description: "Adds .slug() — pattern-only slug validation",
+
+  install() {
+    Object.assign(StringValidator.prototype, {
+      slug(this: StringValidator, errorMessage?: string) {
+        return this.pattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, errorMessage);
+      },
+    });
+  },
+};
+```
+
+`uninstall` is optional. Provide it when your plugin needs to clean up — e.g. removing prototype methods for hot-reload scenarios. Most production plugins skip it; methods grafted at boot stay for the process lifetime.
+
+## Registering plugins
+
+```ts
+import { registerPlugin, unregisterPlugin, hasPlugin, getInstalledPlugins } from "@warlock.js/seal";
+
+await registerPlugin(slugPlugin);
+// console.warn if "slug" is already installed; otherwise install() runs and the plugin is tracked.
+
+hasPlugin("slug");           // → true
+getInstalledPlugins();       // → [slugPlugin]
+
+await unregisterPlugin("slug");
+// runs slugPlugin.uninstall?.(); removes from registry.
+```
+
+`registerPlugin` is async (the `install` function may be async). Await it during boot so the methods are available before the first request.
+
+**Where to register:** the conventional place in a Warlock app is a side-effect file loaded by `warlock.config.ts` — e.g. `src/setup/seal-plugins.ts`:
+
+```ts title="src/setup/seal-plugins.ts"
+import { registerPlugin } from "@warlock.js/seal";
+import { slugPlugin } from "./plugins/slug-plugin";
+import { postalCodePlugin } from "./plugins/postal-code-plugin";
+
+export async function setupSealPlugins() {
+  await registerPlugin(slugPlugin);
+  await registerPlugin(postalCodePlugin);
+}
+```
+
+Then call `setupSealPlugins()` in a bootstrap connector. Registering at top-level module scope works too (it's idempotent — duplicates warn and skip), but explicit setup is clearer.
+
+## TypeScript — declare the new methods
+
+`Object.assign` on a prototype is invisible to TypeScript. Declare the new methods with module augmentation so call sites compile:
+
+```ts title="src/setup/seal-plugins.types.ts"
+import "@warlock.js/seal";
+
+declare module "@warlock.js/seal" {
+  interface StringValidator {
+    /** Pattern-only slug — `"hello-world"`, not `"Hello World"`. */
+    slug(errorMessage?: string): StringValidator;
+  }
+}
+```
+
+After this file is included in the project's `tsconfig.json` (via `include` or a side-effect import), `v.string().slug()` autocompletes and type-checks everywhere.
+
+**Important.** The augmentation has to declare on the **class** (`StringValidator`), not the factory return type. The factory return widens with `& StandardSchemaV1<...>` (see [`@warlock.js/seal/bridge-standard-schema/SKILL.md`](@warlock.js/seal/bridge-standard-schema/SKILL.md)) — augmentations on the intersection don't propagate. Patch the class, augment the class; the factory return picks up the new methods through structural inference.
+
+## Larger example — postal codes per country
+
+```ts
+import { StringValidator, type SealPlugin } from "@warlock.js/seal";
+
+const PATTERNS: Record<string, RegExp> = {
+  US: /^\d{5}(?:-\d{4})?$/,
+  DE: /^\d{5}$/,
+  UK: /^[A-Z]{1,2}\d[A-Z\d]? \d[A-Z]{2}$/i,
+  EG: /^\d{5}$/,
+};
+
+export const postalCodePlugin: SealPlugin = {
+  name: "postal-code",
+
+  install() {
+    Object.assign(StringValidator.prototype, {
+      postalCode(this: StringValidator, country: keyof typeof PATTERNS, errorMessage?: string) {
+        const pattern = PATTERNS[country];
+
+        if (!pattern) {
+          throw new Error(`postalCode: unknown country "${country}"`);
+        }
+
+        return this.pattern(pattern, errorMessage ?? `Invalid ${country} postal code`);
+      },
+    });
+  },
+};
+```
+
+```ts
+// Module augmentation
+declare module "@warlock.js/seal" {
+  interface StringValidator {
+    postalCode(country: "US" | "DE" | "UK" | "EG", errorMessage?: string): StringValidator;
+  }
+}
+
+// Use site
+const addressSchema = v.object({
+  country: v.literal("US", "DE", "UK", "EG"),
+  postal: v.string().postalCode("DE"),
+});
+```
+
+## Patterns beyond `StringValidator`
+
+The same approach works on any validator class. Pick the right prototype:
+
+- `StringValidator` — string methods (`.slug`, `.postalCode`, `.licensePlate`).
+- `NumberValidator` / `IntValidator` / `FloatValidator` — number methods.
+- `DateValidator` — date methods (`.businessDayInCountry("US")`).
+- `ArrayValidator` / `ObjectValidator` — structural methods (rarer).
+- `BaseValidator` — universal methods (rare — usually a sign you want a separate `v.something()` factory instead).
+
+For a method that creates a **new validator** (not chained from an existing one), expose it as a regular function alongside `v` rather than patching the factory. E.g. export `iban()` from your plugin module that returns a configured `v.string()`.
+
+## Introspection — checking what's loaded
+
+```ts
+hasPlugin("slug");                 // boolean
+getInstalledPlugins();             // SealPlugin[]
+```
+
+Use these in startup diagnostics or in tests that need to assert a plugin is registered before exercising a method that depends on it.
+
+## Things NOT to do
+
+- Don't `Object.assign(BaseValidator.prototype, ...)` for type-specific methods. The method would exist on every validator (`v.boolean().slug()` typechecks but breaks at runtime). Patch the narrowest class that owns the method.
+- Don't forget the module augmentation. Without it, the new methods exist at runtime but TS rejects every call site.
+- Don't make the plugin's `install` function depend on shared state mutable from elsewhere. Plugins should be idempotent — installing twice (or registering across hot-reloads) should not break anything.
+- Don't ship a plugin that overrides a built-in method without a clear reason. If you must, `uninstall` should restore the original — but the better path is a different method name.
+- Don't author one plugin per method. Group related methods (e.g. "country-specific validators") into one plugin so the install/uninstall lifecycle is coherent.