@nekostack/schema 1.0.0

package/docs/COMPOSITION.md

@@ -0,0 +1,206 @@
+# Composition Contract
+
+> How the seven `ObjectSchema` composition operators behave. This file is the contract; the implementation lives in [`../src/builders/object.ts`](../src/builders/object.ts) and the type helpers in [`../src/types.ts`](../src/types.ts).
+
+## Quick reference
+
+```ts
+const A = s.object({ id: s.string(), name: s.string() });
+const B = s.object({ id: s.number(), email: s.string() });
+
+A.extend({ email: s.string() });     // add new fields; throws on key collision
+A.pick({ id: true });                // keep only named keys
+A.omit({ id: true });                // remove named keys
+A.partial();                         // all fields optional + default stripped
+A.partial({ name: true });           // granular form: only the named keys
+A.required();                        // all fields required + default stripped
+A.required({ name: true });          // granular form
+A.merge(B);                          // throws: 'id' conflict
+A.merge(B, { conflict: "right" });   // right wins
+A.merge(B, { unknownKeys: "left" }); // resolves an unknownKeys mismatch
+A.override({ id: s.number() });      // replace; throws if key absent
+```
+
+## The three universal rules
+
+Every composition operator follows these:
+
+1. **Returns a new `ObjectSchema`.** No mutation of the receiver or arguments.
+2. **Fails loudly.** Collisions, unknown keys, missing keys, and unknownKeys mismatches throw — never silently. Silent composition is the failure mode v0.5 exists to prevent.
+3. **Drops top-level metadata.** Composed schemas lose `id` / `version` / `description` / `deprecated`. The author must re-tag the result explicitly. This prevents implicit identity preservation that would cause v0.7 registry collisions ("two different `com.x.User` schemas — one's the original, one's a `pick`-narrowed view").
+
+Field-level metadata is preserved across all operators.
+
+## The seven operators
+
+### `extend(extension)` — add fields
+
+```ts
+const A = s.object({ id: s.string() });
+A.extend({ name: s.string() });
+// { id, name }
+
+A.extend({ id: s.number() });
+// throws: key 'id' already exists in base
+```
+
+Throws on any key in `extension` that already exists in the base. To deliberately replace a field, use `override`. To combine two schemas with explicit conflict policy, use `merge`.
+
+### `pick(mask)` / `omit(mask)` — narrow
+
+```ts
+const Base = s.object({ id: s.string(), name: s.string(), age: s.number() });
+Base.pick({ id: true, name: true });   // { id, name }
+Base.omit({ age: true });              // { id, name }
+
+Base.pick({ missing: true });
+// throws: key 'missing' does not exist in base shape
+```
+
+Both throw on any key in the mask that's not in the base — catches refactor drift where a key was renamed and a downstream `pick` still references the old name.
+
+### `partial(mask?)` — make optional, strip default
+
+```ts
+const A = s.object({ id: s.string(), role: s.string().default("member") });
+const P = A.partial();
+// Both fields become input-optional + output-optional.
+// IMPORTANT: `role` loses its default. A partial schema should not silently
+// inject defaults into a PATCH/update payload.
+
+A.partial({ id: true });
+// granular form: only `id` becomes optional; `role` unchanged
+```
+
+`partial` and `required` are **symmetric on `default`**: both strip it. Rationale: in the v0.1 absence-semantics contract, `default(v)` means input-optional + output-required (runtime fills the missing value). Preserving `default` through `partial()` would leave output-required while claiming to be optional — a direct contradiction. The symmetric strip is the only self-consistent rule.
+
+If you need to preserve defaults across composition, don't use `partial` / `required` — re-author the field explicitly or compose at the IR level.
+
+### `required(mask?)` — make required, strip default
+
+```ts
+const A = s.object({
+  id: s.string().optional(),
+  role: s.string().default("member"),
+});
+const R = A.required();
+// Both fields become input-required + output-required.
+// `role` loses its default — required + default-bearing was semantically
+// contradictory anyway ("the field is required, but accepts missing input?").
+```
+
+### `merge(other, options?)` — combine
+
+```ts
+const A = s.object({ id: s.string(), shared: s.string() });
+const B = s.object({ name: s.string(), shared: s.number() });
+
+A.merge(B);
+// throws: field 'shared' exists in both operands.
+// Pass { conflict: "left" } or { conflict: "right" } to resolve.
+
+A.merge(B, { conflict: "left" });   // shared is string (A's type)
+A.merge(B, { conflict: "right" });  // shared is number (B's type)
+```
+
+`merge` has two independent knobs:
+
+| Knob | Default | Meaning |
+|---|---|---|
+| `conflict` | `"throw"` | How field-level overlaps are resolved |
+| `unknownKeys` | `"throw"` | How object-level `unknownKeys` policy mismatches are resolved |
+
+Both default to `"throw"`. Same-policy merges (both operands `strict`, both `passthrough`, both `stripUnknown`) don't need the `unknownKeys` option. Mismatched merges must resolve explicitly:
+
+```ts
+const Strict = s.object({ id: s.string() });               // strict
+const Loose = s.object({ name: s.string() }).passthrough(); // passthrough
+
+Strict.merge(Loose);
+// throws: unknownKeys policies differ.
+
+Strict.merge(Loose, { unknownKeys: "right" });
+// passthrough wins; merged object accepts unknown keys
+```
+
+The two knobs are independent: `A.merge(B, { unknownKeys: "right" })` works when fields don't conflict but policies do.
+
+Why fail-loudly on `unknownKeys`: it's a real validation-semantics policy (strict vs passthrough changes which inputs validate), not cosmetic. Silently dropping the right operand's policy would be exactly the failure mode v0.5's other operators are built to prevent.
+
+#### Type-level overload selection
+
+`merge` has three overloads:
+
+```ts
+merge(other)                                          // → ObjectSchema<MergeThrowShape<S, Other>>
+merge(other, { conflict?: "throw", unknownKeys?: ... }) // → ObjectSchema<MergeThrowShape<S, Other>>
+merge(other, { conflict: "left",  unknownKeys?: ... }) // → ObjectSchema<MergeLeftShape<S, Other>>
+merge(other, { conflict: "right", unknownKeys?: ... }) // → ObjectSchema<MergeRightShape<S, Other>>
+```
+
+`MergeThrowShape<S, Other>` is `Identity<S & Other>`. It preserves disjoint merges and lets TypeScript surface some conflicts through normal intersection behavior where possible, but **runtime conflict detection is the load-bearing guarantee**. Consumers must not rely on `MergeThrowShape` as the sole conflict detector — call `merge` with explicit `conflict: "left"` / `"right"` when you intend to resolve overlaps, and let the runtime throw catch the unintended ones.
+
+`MergeLeftShape` / `MergeRightShape` resolve overlaps by picking the corresponding side's field type.
+
+### `override(overrides)` — replace existing keys
+
+```ts
+const Base = s.object({ id: s.string(), name: s.string() });
+
+Base.override({ id: s.number() });
+// id is now a number; name unchanged
+
+Base.override({ missing: s.string() });
+// throws: key 'missing' does not exist in base
+```
+
+Throws on any key in `overrides` that's NOT in the base. To add new fields, use `extend`. To replace an existing field's schema with a different type (string → number, etc.), use `override`. The `OverrideMask<S>` constraint permits any `AnySchema` as a value — that's the whole point.
+
+`extend` and `override` are deliberately asymmetric: `extend` rejects existing keys, `override` rejects missing keys. The pair covers add and replace without overlap.
+
+## Object-level `unknownKeys` policy
+
+Single-object operators (`pick` / `omit` / `partial` / `required` / `extend`) preserve the base's policy. Only `merge` can encounter a mismatch — handled by the `unknownKeys` knob on `MergeOptions` (see above).
+
+## Object-level refinements
+
+v0.1 doesn't yet support object-level refinements (only field-level). The `Schema` base class has a `refinements` array, but `ObjectSchema` in practice doesn't accumulate them. If a future feature adds object-level validators (e.g., cross-field constraints), composition needs to revisit them.
+
+For now: single-object operators pass through any object-level refinements unchanged; `merge` drops the right operand's object-level refinements. Document re-asserts the policy when object-level refinements ship.
+
+## Type inference contract
+
+All operators preserve the v0.1 absence-semantics contract end-to-end. The per-operator type-level behavior:
+
+| Operator | Effect on per-field `TInputKey` / `TOutputKey` |
+|---|---|
+| `extend(E)` | Each E field's keys carry through unchanged |
+| `pick` / `omit` | Surviving fields' keys carry through unchanged |
+| `partial()` | Affected fields' keys both become `"optional"`; TInput/TOutput widen with `\| undefined` |
+| `required()` | Affected fields' keys both become `"required"`; TInput/TOutput narrow via `Exclude<…, undefined>` |
+| `merge` (`"left"`) | Left's keys win for overlaps |
+| `merge` (`"right"`) | Right's keys win for overlaps |
+| `merge` (`"throw"`) | TS intersection (`S & Other`); preserves disjoint/compatible merges, but runtime conflict detection is the load-bearing guarantee |
+| `override` | Replacement field's keys fully replace the base field's |
+
+`s.input<typeof Composed>` and `s.output<typeof Composed>` produce the right shapes per the v0.1 contract — type-level tests in [`../tests/composition.test-d.ts`](../tests/composition.test-d.ts) cover every operator.
+
+## Generator parity
+
+Composition produces a plain `ObjectNode` — no new IR kind, no generator changes. The four generators (TS, Zod, JSON Schema, OpenAPI) handle composed schemas via the shared `emitSchemaFragment`. This is asserted in [`../tests/composition-generator-parity.test.ts`](../tests/composition-generator-parity.test.ts): for each operator, the composed schema's generator output is byte-identical to an equivalent hand-written `s.object({...})`.
+
+Notably, `partial`'s default-strip is observable end-to-end: the Zod chain has no `.default()` call; the JSON Schema output has no `default` key or `x-nekostack-default-applied-by` extension.
+
+## What composition does NOT do
+
+| Feature | Reason it's deferred |
+|---|---|
+| Composition on non-object schemas (`s.array().extend()`) | No sensible meaning |
+| Deep / recursive composition (nested-field merge) | Adds complexity v0.5 doesn't need; shallow is sufficient |
+| Cross-schema `$ref` | v0.7 registry-lite |
+| Composition history metadata (`metadata.derivedFrom`) | Could help v0.7 diffing; not load-bearing for v0.5 |
+| `merge` with `conflict: "merge"` (recursive type-union) | Too complex; only `"left"` / `"right"` ship in v0.5 |
+| Static `s.merge(A, B)` top-level form | Method-on-instance is sufficient |
+| `omitMatching` / `pickMatching` with predicates | Not needed for the static-key surface |
+
+If a real consumer hits one of these, they ship in their own phase plan.

package/docs/DIFF_CLASSIFICATION.md

@@ -0,0 +1,137 @@
+# Diff Classification Contract
+
+> The locked breaking / additive / cosmetic table that `diffNodes` and `diffHandler` implement, plus the lens, aggregation, and unsupported-kind rules. This file is the contract; the implementations live in [`../src/registry/diff.ts`](../src/registry/diff.ts) and [`../src/registry/handlers/diff.ts`](../src/registry/handlers/diff.ts). Every row in the table below has a fixture pair in [`../tests/registry/diff-classifier.test.ts`](../tests/registry/diff-classifier.test.ts), and the aggregation rule is gated by [`../tests/registry/handlers/diff-handler.test.ts`](../tests/registry/handlers/diff-handler.test.ts).
+
+## Severity lens
+
+**Input-acceptance compatibility** is the primary lens.
+
+> *Would data that the **old** schema accepted still be accepted by the **new** schema?*
+
+- **No** → `breaking`.
+- **Yes**, and the new schema *also* accepts inputs the old one rejected → `additive`.
+- **Same accepted set** (no validation effect) → `cosmetic`.
+
+Output-shape compatibility is **a separate concern**. It is reflected in the change's `kind` field — `default_removed`, `default_value_changed`, etc. — but does *not* split the severity. Consumers needing an output-side reading apply their own lens over `change.kind`.
+
+This lens is deliberate. The Master plan locked the single-severity rule (Decision #11) so the CLI's exit-code mapping (Decision #13) stays mechanical: any `breaking` row anywhere in a diff means a non-zero exit. A multi-lens classifier would either re-introduce judgment or require a flag-per-lens that v0.7 has not budgeted.
+
+## Severity values
+
+| Severity | Meaning | CLI exit (Step 28+) |
+|---|---|---|
+| `breaking` | At least one input the old schema accepted is rejected by the new schema. | non-zero |
+| `additive` | The new schema's accepted set is a strict superset of the old one's. | zero (with notice) |
+| `cosmetic` | The accepted sets are identical; only metadata or ordering changed. | zero |
+
+The values are declared in [`../src/registry/types.ts`](../src/registry/types.ts) and the type is re-exported from the integration subpath [`@nekostack/schema/cli`](../src/cli-integration.ts).
+
+## `worstSeverity` aggregation
+
+`diffHandler` collapses the change list into one severity for CLI consumption:
+
+```text
+worstSeverity = max(severity over changes), where breaking > additive > cosmetic
+worstSeverity = null  ⇔  changes.length === 0
+```
+
+Precedence is locked: `breaking > additive > cosmetic`. The implementation lives in `computeWorstSeverity` ([`../src/registry/handlers/diff.ts`](../src/registry/handlers/diff.ts)). `null` is the sentinel for "no changes detected" — distinct from `cosmetic`, which means "changes exist but none affect validation."
+
+This is also the realization rule for Master plan Decision #13: a `schemaVersion` bump paired with structural changes inherits the worst structural severity, because every change keeps its own row in the list and the `schemaVersion` row's `cosmetic` severity loses the `max` against any `breaking`/`additive` structural row.
+
+## Classification table (locked — Master plan Decision #12)
+
+Every row is gated by a fixture pair in `diff-classifier.test.ts`. Adding, removing, or reclassifying a row is a contract change and requires a Master plan amendment.
+
+| Change | Severity | `DiffChange.kind` | Notes |
+|---|---|---|---|
+| Top-level `kind` mismatch (e.g. `string` → `number`) | breaking | `type_changed` | Walker stops descending; no per-field diff is emitted past this point. |
+| Add **required** field | breaking | `field_added` | Old data lacking the field now fails. |
+| Add **nullable-only** field (required key, value may be `null`) | breaking | `field_added` | `nullable` does not imply `optional`; old data lacking the field still fails. |
+| Add **optional** field | additive | `field_added` | Absence permitted; old data still validates. |
+| Add **nullish** field (`optional + nullable`) | additive | `field_added` | Absence permitted. |
+| Add **default-bearing** field | additive | `field_added` | Input-optional; old data validates and gains the default at output. |
+| Remove field (any modifier) | breaking | `field_removed` | Consumers reading the field break; old data with the field newly becomes an unknown key. |
+| Tighten refinement (`min` ↑, `max` ↓, new `regex`, `length` change, `multipleOf` change) | breaking | `refinement_changed` | Inputs that passed may now fail. |
+| Loosen refinement (`min` ↓, `max` ↑, removed `regex`) | additive | `refinement_changed` | Strictly more accepting. |
+| Tighten unknown-keys (`passthrough` → `strict`, `stripUnknown` → `strict`) | breaking | `unknown_keys_changed` | Inputs with unknowns now rejected. |
+| Loosen unknown-keys (`strict` → `passthrough`, `strict` → `stripUnknown`) | additive | `unknown_keys_changed` | More accepting. |
+| `passthrough` ↔ `stripUnknown` | cosmetic | `unknown_keys_changed` | Same accepted input set; output-side preserve-vs-drop differs but is *not* the lens. |
+| Add enum value | additive | `enum_value_added` | Strictly more accepting. |
+| Remove enum value | breaking | `enum_value_removed` | Inputs with that value now fail. |
+| Change literal value | breaking | `literal_changed` | The only accepted value changed. |
+| Add `default` to existing required field | additive | `default_added` | Input becomes input-optional; output unaffected for existing inputs. Tracked as one row (the implicit `optional` flip from `.default()` is masked — see [`./ABSENCE_SEMANTICS.md`](./ABSENCE_SEMANTICS.md)). |
+| Remove `default` from a default-bearing field | breaking | `default_removed` | Field flips to input-required and output loses the fill. |
+| Change default value | breaking | `default_value_changed` | Downstream observers see a different filled value at output. |
+| `optional` → `nullable` | breaking | `absence_modifier_changed` | Drops absence-permission; old data lacking the key fails. |
+| `nullable` → `optional` | breaking | `absence_modifier_changed` | Drops `null`-permission; old data with `null` fails. |
+| `optional` → `nullish` | additive | `absence_modifier_changed` | Adds `null`-permission on top of absence. |
+| `nullable` → `nullish` | additive | `absence_modifier_changed` | Adds absence-permission on top of `null`. |
+| `nullish` → `optional` or `nullish` → `nullable` | breaking | `absence_modifier_changed` | Drops half of the previously-accepted absence/`null` permission. |
+| Description / metadata-only edit | cosmetic | `metadata_changed` | No validation effect. Also covers `deprecated` flips and `schemaId` edits. |
+| Refinement reorder (same set, different order) | cosmetic | `refinements_reordered` | Semantic equivalence — see [`./ZOD_MODIFIER_ORDERING.md`](./ZOD_MODIFIER_ORDERING.md) for the normalization contract. |
+| `schemaVersion`-only change | cosmetic | `schema_version_changed` | Tracked separately. See the aggregation rule below. |
+
+### Absence-state superset rule
+
+The `absence_modifier_changed` severity is computed mechanically from the input-acceptance superset table in `absenceSeverity` ([`../src/registry/diff.ts`](../src/registry/diff.ts)):
+
+```text
+required  ⊂  optional
+required  ⊂  nullable
+required  ⊂  optional ⊂ nullish
+required  ⊂  nullable ⊂ nullish
+```
+
+A transition is `additive` if the new state's accepted set is a superset of the old's; otherwise `breaking`. The masked-`optional` rule (a node carrying `.default()` is not separately reported as having become "optional") prevents the same change from being counted twice.
+
+### Refinement-direction rule
+
+Refinement param changes route through `refinementParamSeverity`. Numeric lower-bounds (`minLength`, `min`, `minItems`, `gt`) are `additive` when decreased and `breaking` when increased; numeric upper-bounds (`maxLength`, `max`, `maxItems`, `lt`) are the mirror. Equality-style refinements (`length`, `multipleOf`, `regex`) are conservatively `breaking` on any value change — the accepted set transformation is not monotone in the parameter.
+
+## `schemaVersion` aggregation rule (Master plan Decision #13)
+
+- A change to `metadata.version` alone, with no other changes, produces a single `schema_version_changed` row at `cosmetic` severity and `worstSeverity: "cosmetic"`.
+- A `metadata.version` change *paired* with structural changes still produces the `schema_version_changed` row, but `worstSeverity` is the worst severity across the full change list — never silently demoted to `cosmetic` by the presence of the version bump.
+
+The CLI surfaces `worstSeverity` directly; this rule keeps a version bump from masking a breaking change.
+
+## Unsupported IR kinds
+
+Per Master plan Decision #14, `diffNodes` **throws** `UnsupportedNodeKindError({ generator: "diff", kind })` for any IR kind not in the v0.7 supported set:
+
+```text
+supported:   string, number, boolean, literal, enum, array, object
+unsupported: date, union, recursiveRef, transform
+```
+
+`diffHandler` does **not** catch — the throw propagates to the CLI dispatcher (Step 28+), which maps it to a non-zero exit code at the CLI boundary. This matches the v0.3 / v0.6 generator discipline (see [`./IR_CONTRACT.md`](./IR_CONTRACT.md)). Wrapping into an `integrity_error` `Issue` would be semantically wrong: the IR is well-formed; v0.7 simply does not know how to diff it.
+
+## Output-side reading (not the lens)
+
+Some rows have a divergent output-side reading. They are *not* classified differently — single-lens is the locked contract — but consumers wanting to reason about output shape can branch on the change's `kind`:
+
+| `kind` | Input-lens severity | Output-shape implication |
+|---|---|---|
+| `default_added` | additive | New inputs that omit the field now produce a filled value at output; existing inputs unchanged. |
+| `default_removed` | breaking | Output loses the fill; consumers expecting the field to always be present break. |
+| `default_value_changed` | breaking | Output value differs for the same input; downstream observers see new values. |
+| `unknown_keys_changed` (`passthrough` ↔ `stripUnknown`) | cosmetic | Output differs: `passthrough` preserves unknown keys, `stripUnknown` drops them. |
+
+The intent is that any consumer with an output-side concern reads `change.kind` and applies its own lens. The classifier itself stays single-severity.
+
+## Migrations are deferred
+
+v0.7 classifies diffs; it does **not** propose, generate, or apply migrations. Migration emission is out of scope and is a v0.8+ concern. Consumers who want a migration today read the `DiffChange[]` payload and synthesize one externally.
+
+## Implementation reference
+
+| Surface | File |
+|---|---|
+| `diffNodes(before, after): readonly DiffChange[]` | [`../src/registry/diff.ts`](../src/registry/diff.ts) |
+| `diffHandler({ before, after }): DiffResult` | [`../src/registry/handlers/diff.ts`](../src/registry/handlers/diff.ts) |
+| Types (`DiffSeverity`, `DiffKind`, `DiffChange`, `DiffOpts`, `DiffResult`) | [`../src/registry/types.ts`](../src/registry/types.ts) |
+| `UnsupportedNodeKindError` | [`../src/generators/errors.ts`](../src/generators/errors.ts) |
+| Row-by-row classification fixtures | [`../tests/registry/diff-classifier.test.ts`](../tests/registry/diff-classifier.test.ts) |
+| `worstSeverity` aggregation gate | [`../tests/registry/handlers/diff-handler.test.ts`](../tests/registry/handlers/diff-handler.test.ts) |
+| Master plan source of truth | [`./PHASE_PLAN_v0.7.md`](./PHASE_PLAN_v0.7.md) (Decisions #11 / #12 / #13 / #14) |

package/docs/EXAMPLES.md

@@ -0,0 +1,221 @@
+# Examples — `@nekostack/schema`
+
+Three realistic example schemas under [`../examples/`](../examples/), each with its committed generated artifacts under [`../examples/generated/`](../examples/generated/). These files are validated by [`../tests/examples/regenerate.test.ts`](../tests/examples/regenerate.test.ts): if a schema changes and the generated files aren't refreshed, the test fails.
+
+To regenerate after a deliberate schema change:
+
+```
+cd packages/schema
+npx vitest run tests/examples/regenerate.test.ts -u
+```
+
+(`-u` updates snapshots — the generated files ARE the snapshots.)
+
+## 1. Tenant — basic entity
+
+**Source:** [`../examples/tenant.schema.ts`](../examples/tenant.schema.ts)
+
+**Generated:**
+- [`../examples/generated/tenant.types.ts`](../examples/generated/tenant.types.ts) — TS output type
+- [`../examples/generated/tenant.zod.ts`](../examples/generated/tenant.zod.ts) — Zod 3.x validator
+- [`../examples/generated/tenant.json.schema.json`](../examples/generated/tenant.json.schema.json) — JSON Schema draft 2020-12 (URN `$id`)
+- [`../examples/generated/tenant.openapi.json`](../examples/generated/tenant.openapi.json) — OpenAPI 3.1 component schema (no `$schema`, no `$id`; identity is the position in the composed document)
+
+**What it demonstrates:**
+- Schema metadata (`.id()`, `.version()`, `.describe()`) in the generated header.
+- UUID + email + regex portable refinements.
+- Enum field with a default (`plan: "free"`).
+- Nullable field (`billingEmail` — required key, value may be `null`).
+- Nested object with required + optional fields.
+- Strict-by-default object policy → emitted `.strict()` in Zod.
+
+## 2. AuditEvent — the input/output split
+
+**Source:** [`../examples/audit-event.schema.ts`](../examples/audit-event.schema.ts)
+
+**Generated:**
+- [`../examples/generated/audit-event.both.ts`](../examples/generated/audit-event.both.ts) — TS, **`mode: "both"`**, emits `AuditEventInput` + `AuditEventOutput` side-by-side
+- [`../examples/generated/audit-event.zod.ts`](../examples/generated/audit-event.zod.ts) — Zod 3.x validator
+- [`../examples/generated/audit-event.json.schema.json`](../examples/generated/audit-event.json.schema.json) — JSON Schema draft 2020-12 (input-validation; default fields omitted from `required`, `x-nekostack-default-applied-by: "runtime"` on `severity`)
+- [`../examples/generated/audit-event.openapi.json`](../examples/generated/audit-event.openapi.json) — OpenAPI 3.1 component schema (same body shape as the JSON Schema above — shared internal fragment emitter; the `irHash` in `x-nekostack` provenance is identical, proving same-source generation)
+
+**Why this is the headline example:**
+
+`AuditEvent.severity` has `.default("info")`. Look at the generated `audit-event.both.ts` — the difference between `Input` and `Output` is one character:
+
+```ts
+export type AuditEventInput  = { ...; severity?: "info" | "warning" | "error"; ... };
+export type AuditEventOutput = { ...; severity:  "info" | "warning" | "error"; ... };
+```
+
+The Input accepts missing `severity` (the default fills it in). The Output is fully populated. The v0.1 absence-semantics contract survives generation — that's the entire point of v0.2.
+
+**Other absence-semantics rows exercised:**
+- `correlationId.optional()` → `?:` in both Input and Output
+- `actorId.nullable()` → `: string | null` (required key) in both
+- `payload` uses `.passthrough()` → emitted `.passthrough()` in Zod; accepts arbitrary extra keys
+
+## 3. Entitlement — array + deprecated + nullable-as-sentinel
+
+**Source:** [`../examples/entitlement.schema.ts`](../examples/entitlement.schema.ts)
+
+**Generated:**
+- [`../examples/generated/entitlement.types.ts`](../examples/generated/entitlement.types.ts) — TS output type
+- [`../examples/generated/entitlement.zod.ts`](../examples/generated/entitlement.zod.ts) — Zod 3.x validator
+- [`../examples/generated/entitlement.json.schema.json`](../examples/generated/entitlement.json.schema.json) — JSON Schema draft 2020-12
+- [`../examples/generated/entitlement.openapi.json`](../examples/generated/entitlement.openapi.json) — OpenAPI 3.1 component schema
+
+**What it demonstrates:**
+- Boolean with default (`enabled: true`).
+- Numeric field with `int + min` portable refinements + nullable (`quota` — null encodes "unlimited", a common SaaS pattern).
+- Array with `max` items (`tags`).
+- Field-level `.deprecated()` flag (`legacyTier`) — surfaces in JSDoc; consumers using a strict TS-aware tool will see the `@deprecated` tag.
+- Mixed required + optional fields in one object.
+
+## Validating input at runtime (v0.6)
+
+Once a schema is defined, `parse` / `safeParse` / `validate` from `@nekostack/schema` are the runtime-validation entry points. The generated Zod file is no longer required to validate input — generators emit artifacts for interoperability and documentation; the runtime API is the in-process path.
+
+### `parse` — throws `ParseError` on failure, fills defaults on success
+
+```ts
+import { parse, ParseError } from "@nekostack/schema";
+import { AuditEvent } from "../examples/audit-event.schema.js";
+
+try {
+  const event = parse(AuditEvent, {
+    id: "evt_01",
+    occurredAt: "2026-05-18T10:00:00Z",
+    actorId: null,
+    action: "tenant.created",
+    payload: { tenantId: "t_1" },
+    // severity omitted — default("info") fills it
+  });
+  event.severity; // "info" (default filled — see audit-event.both.ts for the type-level reason this works)
+} catch (e) {
+  if (e instanceof ParseError) {
+    for (const i of e.issues) console.log(i.code, i.path, i.message);
+  } else {
+    throw e;
+  }
+}
+```
+
+### `safeParse` — returns `Result`, no throw, also fills defaults
+
+```ts
+import { safeParse } from "@nekostack/schema";
+import { Tenant } from "../examples/tenant.schema.js";
+
+const r = safeParse(Tenant, untrustedInput);
+if (r.success) {
+  // r.data: s.output<typeof Tenant>
+} else {
+  // r.issues: readonly Issue[] — every issue uses the NekoStack IssueCode vocabulary
+}
+```
+
+### `validate` — structural check; does **not** fill defaults; refinements still run
+
+```ts
+import { validate } from "@nekostack/schema";
+import { AuditEvent } from "../examples/audit-event.schema.js";
+
+const r = validate(AuditEvent, {
+  id: "evt_01",
+  occurredAt: "2026-05-18T10:00:00Z",
+  actorId: null,
+  action: "tenant.created",
+  payload: { tenantId: "t_1" },
+  // severity absent — accepted, but NOT filled in r.data
+});
+if (r.success) {
+  // r.data shape matches s.input<typeof AuditEvent>
+  // "severity" in r.data === false
+}
+```
+
+The split: `parse` / `safeParse` apply the default and return the fully-populated output; `validate` accepts the absence and returns the input verbatim. See [`RUNTIME.md` → Default semantics](./RUNTIME.md#default-semantics) for the table and the v0.1 rationale.
+
+### Unknown-key policies execute at runtime
+
+```ts
+import { s, parse } from "@nekostack/schema";
+
+const Strict      = s.object({ id: s.string() });                  // default
+const Pass        = s.object({ id: s.string() }).passthrough();
+const Strip       = s.object({ id: s.string() }).stripUnknown();
+
+parse(Strict, { id: "x", extra: 1 });    // throws ParseError([{ code: "unknown_key", path: ["extra"], ... }])
+parse(Pass,   { id: "x", extra: 1 });    // → { id: "x", extra: 1 }
+parse(Strip,  { id: "x", extra: 1 });    // → { id: "x" }
+```
+
+`unrecognized_keys` is split — when an input has two unknown keys, the returned `issues` array contains two `unknown_key` issues, one per key, each with `path: [...originalPath, key]`. See [`RUNTIME.md` → Unknown-key policies](./RUNTIME.md#unknown-key-policies).
+
+## Reading the generated files
+
+Every committed generated artifact has the deterministic header:
+
+```ts
+/**
+ * @generated by @nekostack/schema
+ * schemaId:         com.nekostack.tenant.Tenant
+ * schemaVersion:    1.0.0
+ * irHash:           sha256:<64-char-hex>
+ * generator:        typescript | zod
+ * generatorVersion: @nekostack/schema@0.7.0
+ *
+ * DO NOT EDIT MANUALLY.
+ */
+```
+
+Same IR → same `irHash` across runs and across generators. Re-running the regenerate test on an unchanged schema produces byte-identical output. This is what makes v0.7's freshness check possible.
+
+## Composition example (v0.5)
+
+The example schemas above can be composed:
+
+```ts
+import { Tenant } from "../examples/tenant.schema.js";
+
+// Create-form input: client doesn't send the server-assigned id.
+const TenantCreateInput = Tenant.omit({ id: true });
+
+// PATCH/update shape: every field optional, defaults stripped.
+const TenantPatch = Tenant.partial();
+
+// Safe-to-expose subset (e.g., for a tenant directory listing).
+const TenantPublic = Tenant.pick({ id: true, slug: true, name: true });
+```
+
+All four generators handle composed schemas via the shared `emitSchemaFragment` — output is byte-identical to a hand-written equivalent. See [`COMPOSITION.md`](./COMPOSITION.md) for the full operator contract.
+
+## Optional `sourceHash` provenance (v0.7+)
+
+> The example artifacts in [`../examples/generated/`](../examples/generated/) **include** `sourceHash` because the regenerate test ([`../tests/examples/regenerate.test.ts`](../tests/examples/regenerate.test.ts)) computes it from each schema source file's UTF-8 text. The slice remains **optional** for direct generator callers outside that path — omitting it produces byte-identical output to v0.6 and earlier.
+
+Every generator accepts an optional `ProvenanceOptions.sourceHash` slice on its options object. When you provide it, the emitted artifact gains an extra provenance field (`sourceHash:` line in JSDoc-headered TS/Zod output; `x-nekostack.sourceHash` extension in JSON Schema / OpenAPI). When you omit it, the generators emit byte-identical output to v0.6 and earlier — no new field appears anywhere.
+
+```ts
+import { generateTypeScript, sourceHashFromText } from "@nekostack/schema";
+import { readFileSync } from "node:fs";
+import { Tenant } from "../examples/tenant.schema.js";
+
+const text = readFileSync("../examples/tenant.schema.ts", "utf8");
+const ts = generateTypeScript(Tenant.node, {
+  sourceHash: sourceHashFromText(text),
+});
+```
+
+The slice is **not required**, exists purely for provenance, and is **never** an integrity error when missing — pre-v0.7 artifacts without `sourceHash` continue to parse and validate as `clean` (when `irHash` matches the schema) or `stale` (when it doesn't). The two-hash freshness matrix (full contract in [`REGISTRY.md` → `checkHandler`](./REGISTRY.md#checkhandler--two-hash-freshness-matrix)) is the consumer of the field; in v0.7+ the `neko schema check` CLI is what computes and writes it. Hand-authored generation scripts can plug it in today, but the value adds is provenance-completeness, not correctness.
+
+## What these examples deliberately don't show (yet)
+
+- **Full OpenAPI documents** (paths, operations, responses, security schemes) — `@nekostack/api`'s concern. v0.4 ships component schemas only.
+- **Composed-schema example artifacts under `examples/generated/`** — could add `tenant-patch.zod.ts` etc. in a future dogfood pass if the example surface grows enough to warrant it. v0.5 stays focused on the operator contract; ad-hoc consumer-side composition doesn't need its own snapshotted output here.
+- **`Tenant.extend({ ... })`, `pick({ id: true })`, etc.** — v0.5 composition operators; see [`COMPOSITION.md`](./COMPOSITION.md) for the full contract.
+- **Date / union / runtime-refinement schemas** — v0.6's runtime fails loudly (`UnsupportedNodeKindError`) on these IR kinds; builders are deferred to later phases. The v0.7 `diffNodes` likewise throws on these kinds — diffing them is a v0.8+ concern.
+- **A `neko schema` CLI** — v0.7 shipped at [`schema-v0.7.0`](https://github.com/cmclicker/NekoStack/releases/tag/schema-v0.7.0); use `neko schema list / diff / check / generate` directly. The v0.8 `neko schema migrate *` verbs (`list` / `plan` / `verify` / `stub`) are in progress on [`feat/schema-v0.8-candidate`](https://github.com/cmclicker/NekoStack/tree/feat/schema-v0.8-candidate) ([PR #28](https://github.com/cmclicker/NekoStack/pull/28)) and not yet shipped.
+- **Example schema-data migrations under `examples/migrations/`** — v0.8 ships the planning / verification / stub contract in [`MIGRATIONS.md`](./MIGRATIONS.md); committed `.migration.ts` example files (e.g., a `Tenant 1.0.0 → 2.0.0` data migration paired with the existing `tenant.schema.ts` example) could be added in a dogfood pass once the schema versions actually evolve. The example surface is deliberately frozen at the v0.6 set for now to keep the regenerate-test scope tight.
+- **A migration *runner / apply / executor*** — `@nekostack/schema` does **not** ship one and never will. v0.8 owns planning + verification + stub generation only; executing a migration's `transform(input)` against real data is a hard-locked non-goal of the schema package. See [`MIGRATIONS.md`](./MIGRATIONS.md) for the full non-goals table.

package/docs/HEADER_FORMAT.md

@@ -0,0 +1,66 @@
+# Generated-file Header Format
+
+> The deterministic preamble prepended to every artifact produced by `generateTypeScript` and `generateZod` (v0.2+). This file is the contract; the implementation lives in [`../src/generators/header.ts`](../src/generators/header.ts).
+
+## Shape
+
+A JSDoc block comment, one field per line, in fixed order:
+
+```ts
+/**
+ * @generated by @nekostack/schema
+ * schemaId:         <id-or-null>
+ * schemaVersion:    <version-or-null>
+ * irHash:           sha256:<64-char-lowercase-hex>
+ * generator:        <typescript|zod>
+ * generatorVersion: <single-source-of-truth-string>
+ *
+ * DO NOT EDIT MANUALLY.
+ */
+```
+
+Anonymous schemas (no `.id()`) add a `// anonymous schema` line immediately after `@generated by`, so the omission is intentional and visible.
+
+## Fields
+
+| Field | Value | Source |
+|---|---|---|
+| `@generated by` | Always `@nekostack/schema` | constant |
+| `schemaId` | The schema's reverse-DNS id, or `null` for anonymous | `node.metadata.id` |
+| `schemaVersion` | The schema's semver, or `null` for unversioned | `node.metadata.version` (falls back to `options.schemaVersion`) |
+| `irHash` | `sha256:<hex>` of canonical IR serialization | [`irHash(node)`](../src/ir/hash.ts) |
+| `generator` | `"typescript"` or `"zod"` | `options.generator` |
+| `generatorVersion` | Single string for all generators in this package version | [`GENERATOR_VERSION`](../src/generators/version.ts) |
+
+## Why two hashes (eventually)
+
+`irHash` is here in v0.2. `sourceHash` is **not yet** in the header.
+
+- **`irHash`** captures semantic IR identity. If the schema's normalized IR changes, the hash changes. Same IR + same generator version → byte-identical output.
+- **`sourceHash`** would capture the source file's bytes (comments, whitespace, ordering). It's needed for CI to distinguish "the schema author edited the file but the IR is unchanged" (regenerate the header only) from "the schema author changed the IR" (full regeneration). Computing it requires walking source files, which is a CLI concern — deferred to v0.7 (`neko schema check`).
+
+Once v0.7 lands, the header gains a `sourceHash:` line above `irHash:`. The v0.2 header format is a strict subset of the eventual v0.7 format.
+
+## Determinism
+
+Same IR + same generator + same generator version → byte-identical header (and byte-identical full file).
+
+Tested in [`../tests/generators/header.test.ts`](../tests/generators/header.test.ts) — the "is deterministic" case asserts byte equality across two invocations.
+
+## What consumers MAY do with the header
+
+- Read `irHash` to verify a committed artifact matches a current IR.
+- Read `schemaId` + `schemaVersion` to identify which schema this file represents.
+- Refuse to consume artifacts whose `generatorVersion` is older than expected.
+
+## What consumers MUST NOT do
+
+- Parse or scrape data out of `// anonymous schema` comments. Use the typed fields (`schemaId === null` is the contract).
+- Edit a generated file by hand. The `DO NOT EDIT MANUALLY.` line is informative; CI may enforce it later by re-running the generator and asserting byte-identical output.
+- Depend on field-line ordering changing — it is fixed and part of this contract.
+
+## Version history
+
+| Version | Change |
+|---|---|
+| v0.2 | Initial format. `sourceHash` deferred to v0.7 with CLI integration. |