@warlock.js/seal 5.19.1 → 5.20.0

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

@@ -1,138 +1,138 @@
----
-name: define-structural-shape
-description: "Structural validators — picking guide in @warlock.js/seal; use when you need to define structural shape."
----
-
-# 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.

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

@@ -1,178 +1,178 @@
----
-name: extend-seal-with-plugins
-description: "Extend seal with plugins in @warlock.js/seal; use when you need to extend seal with plugins."
----
-
-# 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.
+---
+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.