@warlock.js/seal 5.19.0 → 5.20.0

package/llms.txt

@@ -6,12 +6,12 @@
 
 ## Skills
 
-- [bridge-standard-schema](@warlock.js/seal/bridge-standard-schema/SKILL.md): The Standard Schema bridge in @warlock.js/seal; use when you need to bridge standard schema.
-- [compose-seal-modifiers](@warlock.js/seal/compose-seal-modifiers/SKILL.md): Cross-cutting modifiers + the pipeline in @warlock.js/seal; use when you need to compose seal modifiers.
-- [define-structural-shape](@warlock.js/seal/define-structural-shape/SKILL.md): Structural validators — picking guide in @warlock.js/seal; use when you need to define structural shape.
-- [extend-seal-with-plugins](@warlock.js/seal/extend-seal-with-plugins/SKILL.md): Extend seal with plugins in @warlock.js/seal; use when you need to extend seal with plugins.
-- [generate-json-schema](@warlock.js/seal/generate-json-schema/SKILL.md): JSON Schema generation in @warlock.js/seal; use when you need to generate json schema.
-- [handle-seal-errors](@warlock.js/seal/handle-seal-errors/SKILL.md): ValidationResult — reading errors in @warlock.js/seal; use when you need to handle seal errors.
+- [bridge-standard-schema](@warlock.js/seal/bridge-standard-schema/SKILL.md): (no description)
+- [compose-seal-modifiers](@warlock.js/seal/compose-seal-modifiers/SKILL.md): (no description)
+- [define-structural-shape](@warlock.js/seal/define-structural-shape/SKILL.md): (no description)
+- [extend-seal-with-plugins](@warlock.js/seal/extend-seal-with-plugins/SKILL.md): (no description)
+- [generate-json-schema](@warlock.js/seal/generate-json-schema/SKILL.md): (no description)
+- [handle-seal-errors](@warlock.js/seal/handle-seal-errors/SKILL.md): (no description)
 - [overview](@warlock.js/seal/overview/SKILL.md): @warlock.js/seal overview for orientation and choosing the focused skill for the task.
-- [pick-seal-primitive](@warlock.js/seal/pick-seal-primitive/SKILL.md): Picking the right primitive in @warlock.js/seal; use when you need to choose seal primitive.
+- [pick-seal-primitive](@warlock.js/seal/pick-seal-primitive/SKILL.md): (no description)
 - [seal-basics](@warlock.js/seal/seal-basics/SKILL.md): Start here for @warlock.js/seal schemas, validation, parsing, and typed structural contracts.

package/package.json

@@ -5,8 +5,8 @@
     "environment": "universal"
   },
   "dependencies": {
-    "@mongez/supportive-is": "^2.1.4",
-    "@mongez/reinforcements": "^4.0.1",
+    "@mongez/supportive-is": "^2.1.5",
+    "@mongez/reinforcements": "^4.0.2",
     "dayjs": "^1.11.9"
   },
   "repository": {
@@ -22,7 +22,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.19.0",
+  "version": "5.20.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: "The Standard Schema bridge in @warlock.js/seal; use when you need to bridge standard schema."
----
-
-# 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.