@nekostack/schema 1.0.0

package/docs/REGISTRY.md

@@ -0,0 +1,336 @@
+# Registry Contract
+
+> The v0.7 registry / freshness / generation surface lives inside `@nekostack/schema` as a set of pure primitives. The CLI (`@nekostack/cli`, sequencing Steps 21–34) owns every filesystem and process concern and calls into this surface for the logic. This file is the contract; the implementations live under [`../src/registry/`](../src/registry/) and the integration barrel is [`../src/cli-integration.ts`](../src/cli-integration.ts).
+
+## Ownership boundary (Master plan Decision #1)
+
+The schema package is **pure**:
+
+> No `fs.*`. No dynamic `import()`. No `process.*`. No `console.*`. Takes data in, returns data out.
+
+The CLI is the **filesystem shell**:
+
+| Responsibility | Owner |
+|---|---|
+| Discover `*.schema.{ts,js}` files | CLI |
+| Read source bytes | CLI |
+| Dynamic-import schema modules via `tsx` | CLI |
+| Read committed artifacts from disk | CLI |
+| Write regenerated artifacts to disk | CLI |
+| stdout / stderr formatting | CLI |
+| Exit codes | CLI |
+| Build the in-memory `Registry` | schema |
+| Classify diff severity | schema |
+| Compute freshness verdicts | schema |
+| Plan generation (emit-ready payloads) | schema |
+
+The CLI calls `buildRegistry` once after discovery and passes the resulting `Registry` to every handler. The handlers never re-read files; the data they need is already in their `*Opts` argument. This separation is gated by [`../tests/registry/handler-purity.test.ts`](../tests/registry/handler-purity.test.ts).
+
+## Subpath visibility (Master plan Decision #10)
+
+The registry surface is reachable through one — and only one — path:
+
+```text
+@nekostack/schema          public v0.6 consumer API (s, parse, safeParse, …)
+@nekostack/schema/cli      package-internal CLI integration API (this file)
+```
+
+Root `@nekostack/schema` does NOT export any registry / handler / freshness / generation name. The Step 16 negative gate in [`../tests/public-surface.test.ts`](../tests/public-surface.test.ts) enforces this — adding a v0.7 name to the root barrel causes that suite to fail. The positive gate in [`../tests/registry-surface.test.ts`](../tests/registry-surface.test.ts) verifies the `/cli` subpath does expose the surface. Together the two suites lock the boundary.
+
+If a future phase ships `@nekostack/registry` as its own package, the `/cli` barrel moves there with zero impact on root consumers.
+
+## Input shape — `RegistrySourceEntry`
+
+One discovered schema source file after the CLI has read its bytes and dynamic-imported it:
+
+```ts
+interface RegistrySourceEntry {
+  readonly sourcePath: string;          // CLI-relative source location
+  readonly sourceText: string;          // exact UTF-8 bytes the CLI read
+  readonly schemas: readonly AnySchema[]; // every Schema instance exported
+}
+```
+
+A file may legitimately declare more than one schema. The registry indexes each named one independently. See [`../src/registry/types.ts`](../src/registry/types.ts).
+
+## Indexed shape — `RegistryEntry`
+
+One indexed schema. The registry stores these by `(schemaId, schemaVersion)`:
+
+```ts
+interface RegistryEntry {
+  readonly schemaId: string;
+  readonly schemaVersion: string | undefined;
+  readonly irHash: `sha256:${string}`;
+  readonly sourceHash: `sha256:${string}`;
+  readonly sourcePath: string;
+  readonly schema: AnySchema;
+}
+```
+
+`schemaVersion` is `undefined` when the source schema omitted `.version(...)`. The internal map key for the unversioned case is the empty string `""` so the `Registry` lookup type stays uniform; the `schemaVersion` field on the entry remains `undefined`.
+
+## Registry map shape
+
+```ts
+type Registry = ReadonlyMap<
+  string,                                  // outer key: schemaId
+  ReadonlyMap<string, RegistryEntry>       // inner key: schemaVersion or ""
+>;
+```
+
+`buildRegistry` is the only legitimate producer of `Registry` values. Downstream callers treat them as opaque and use `findSchema` for lookup or `listHandler` for enumeration.
+
+## Hash discipline (Master plan Decision #7 / #8)
+
+Two distinct hashes — they capture different things and are both required for the freshness matrix.
+
+### `sourceHash`
+
+`sha256` of the source file's **raw UTF-8 bytes** ([`../src/registry/source-hash.ts`](../src/registry/source-hash.ts)):
+
+```ts
+sourceHashFromText(text): `sha256:${hex}`
+```
+
+Captures source identity exactly — comments, whitespace, declaration order all contribute. Same source file → same `sourceHash`, even if the resulting IR is unchanged. `buildRegistry` computes this once per `RegistrySourceEntry`; every `RegistryEntry` produced from the same source file shares the same `sourceHash` value.
+
+### `irHash`
+
+`sha256` of the canonical IR serialization ([`../src/ir/hash.ts`](../src/ir/hash.ts)):
+
+```ts
+irHash(schema.node): hex   // wrapped as `sha256:${hex}` on RegistryEntry
+```
+
+Captures semantic identity. Refactoring the source — renaming a helper, reordering exports, changing comments — does not change `irHash`. The v0.2+ generator-header contract documents this hash in every artifact (see [`./HEADER_FORMAT.md`](./HEADER_FORMAT.md)); v0.7 extends the header to also include `sourceHash`.
+
+### Why both
+
+A diff between *the registry's recorded hashes* and *the artifact's emitted hashes* tells the CLI exactly what kind of staleness it is looking at — semantic vs. cosmetic — without re-running generators. The two-hash freshness matrix below codifies that read.
+
+## `buildRegistry` — duplicates, anonymous, unversioned
+
+```ts
+buildRegistry(entries): Result<Registry>
+```
+
+Pure. No `fs.*`, no `import()`, no `path.*`. Implementation: [`../src/registry/build-registry.ts`](../src/registry/build-registry.ts).
+
+Rules:
+
+- **Anonymous schemas** (no `.id()`) are silently ignored by the indexer. They remain legal per v0.1 — they just don't participate in registry lookup. The CLI emits a stderr warning per anonymous schema it sees (Master plan Decision #5); this layer is silent.
+- **Unversioned schemas** (`.id()` but no `.version()`) are indexed under the empty-string inner key. The on-entry `schemaVersion` field stays `undefined`.
+- **Duplicate `(schemaId, versionKey)` pairs** across the entry list are collected into one `Issue` per duplicate with code `"duplicate_schema_id"`. The function returns `Result.failure` with the issue list; it never throws. The first-seen entry is kept in the partial map so downstream code in the same call doesn't read a torn state.
+
+The `duplicate_schema_id` Issue carries `metadata.sourcePaths`, `metadata.schemaId`, and `metadata.schemaVersion` so the CLI can render a precise message ("`X` v1.0.0 is declared in both `a.schema.ts` and `b.schema.ts`").
+
+## `findSchema` — lookup rules
+
+```ts
+findSchema(registry, schemaId, version?): RegistryEntry | undefined
+```
+
+Implementation: [`../src/registry/build-registry.ts`](../src/registry/build-registry.ts).
+
+| Inputs | Result |
+|---|---|
+| `findSchema(reg, "X", "1.0.0")` | The entry whose `schemaVersion === "1.0.0"`, or `undefined` if no such entry. |
+| `findSchema(reg, "X", "")` | The unversioned entry for `X`, if one exists. The empty string is the intentional way to address an unversioned schema by exact lookup. |
+| `findSchema(reg, "X")` (version omitted, both versioned and unversioned exist) | The **highest semver** entry. Versioned always wins over unversioned when at least one versioned entry exists. |
+| `findSchema(reg, "X")` (version omitted, only unversioned exists) | The unversioned entry. |
+| `findSchema(reg, "X", …)` with `X` not in the registry | `undefined`. |
+
+Semver comparison is numeric on `major.minor.patch`. Non-conforming version strings fall back to `localeCompare` so the lookup never throws on a non-standard version.
+
+## `listHandler` — enumeration
+
+```ts
+listHandler({ registry }): Result<{ entries: readonly RegistryEntry[] }>
+```
+
+Implementation: [`../src/registry/handlers/list.ts`](../src/registry/handlers/list.ts).
+
+Deterministic order:
+
+1. Across `schemaId`: alphabetical ascending.
+2. Within one `schemaId`: versioned entries first, ascending by numeric `major.minor.patch` semver; the unversioned entry (if any) comes **last**.
+
+Returns `success: true` with an empty array for an empty registry. `listHandler` has no failure mode — `success: false` is unreachable.
+
+## `checkHandler` — two-hash freshness matrix
+
+```ts
+checkHandler({ registry, committedArtifacts }): Result<{ verdicts }>
+```
+
+Implementation: [`../src/registry/handlers/check.ts`](../src/registry/handlers/check.ts).
+
+The CLI reads each artifact's bytes from disk and hands them in. The handler parses provenance ([`../src/registry/parse-provenance.ts`](../src/registry/parse-provenance.ts)), looks up the matching `RegistryEntry`, and emits one `FreshnessVerdict` per artifact.
+
+### Verdict matrix
+
+| Artifact `irHash` vs registry | Artifact `sourceHash` vs registry | Verdict | Meaning |
+|---|---|---|---|
+| matches | matches | `clean` | Artifact is current; nothing to do. |
+| matches | differs | `cosmetic_drift` | Source text edited without semantic effect. CLI prints a stderr warning; CI still passes. |
+| differs | differs | `stale` | Regenerate required. CLI exits 1. |
+| differs | matches | `integrity_error` | The impossible row — should never happen unless the artifact was hand-edited or the recorded `sourceHash` was tampered with. CLI exits 4 and refuses to auto-regenerate. |
+
+### v0.6 backward compatibility (Master plan Decision #8)
+
+Artifacts emitted before Step 4 of v0.7 — `@nekostack/schema@0.6.0` and earlier — have no `sourceHash` field/line. `parseProvenanceFromText` returns `sourceHash: undefined` for those. The handler treats them as:
+
+| Artifact `irHash` vs registry | Verdict (no `sourceHash` recorded) |
+|---|---|
+| matches | `clean` |
+| differs | `stale` |
+
+Absent `sourceHash` is **never** an `integrity_error` by itself — the artifact simply predates the two-hash discipline. Once the user regenerates at v0.7+, full matrix participation resumes.
+
+### Failure paths
+
+`checkHandler` returns `Result.failure` (and emits no verdicts for that call) on any of:
+
+- **Malformed provenance** — `parseProvenanceFromText` returns an `integrity_error` Issue with `metadata.reason` (`unknown_format`, `missing_provenance`, `missing_field`, `malformed_hash`, `json_parse_error`, `malformed_field`). The handler forwards each issue with the artifact path attached.
+- **Anonymous artifact** (provenance `schemaId === null`) — `schema_not_found` with `metadata.reason = "anonymous_artifact"`. Anonymous schemas are not indexed, so there is nothing to validate against.
+- **`schemaId` not in registry** — `schema_not_found`. The user likely deleted a schema source file but forgot to delete its artifacts.
+- **`schemaId` present but version missing** — `version_not_found`. Distinct from `schema_not_found` so the CLI can format orphan-by-id vs. orphan-by-version differently.
+
+Per-artifact verdicts are returned only when **every** artifact parses and resolves cleanly. A single failure causes the whole call to fail — this matches the CLI's exit semantics (a `check` run either passes or surfaces the full issue list).
+
+## `generateHandler` — artifact planning
+
+```ts
+generateHandler({ entries }): Result<{ artifacts: readonly GeneratedArtifact[] }>
+```
+
+Implementation: [`../src/registry/handlers/generate.ts`](../src/registry/handlers/generate.ts).
+
+For every **named** schema in every `RegistrySourceEntry`, emits all four artifact kinds — `typescript`, `zod`, `jsonSchema`, `openApi` — as `GeneratedArtifact` payloads. The CLI is responsible for writing each payload to its `suggestedPath`; this handler never touches the filesystem.
+
+```ts
+interface GeneratedArtifact {
+  readonly schemaId: string;
+  readonly kind: GeneratorKind;
+  readonly suggestedPath: string;
+  readonly content: string;
+  readonly irHash: `sha256:${string}`;
+  readonly sourceHash: `sha256:${string}`;
+}
+```
+
+- **Anonymous schemas** (no `.id()`) are silently skipped — they cannot participate in registry lookup downstream. The CLI warns; the handler is silent (Decision #5).
+- **`sourceHash` is computed once per entry** via `sourceHashFromText(entry.sourceText)` and passed through to each generator's `ProvenanceOptions` so the emitted artifact bytes carry the source-side hash. `irHash` is computed per schema from `schema.node` and stamped on each `GeneratedArtifact`; it is **not** part of `ProvenanceOptions`.
+- **Partial generation is not supported in v0.7** (Master plan Decision #6). `GenerateOpts` carries no `kinds` filter. Every named schema produces exactly four artifacts; the `check` verb expects all four to be present on disk.
+
+## Generated-artifact path convention (Master plan Decision #6)
+
+Locked single-schema layout — given `schemas/user.schema.ts`:
+
+```text
+schemas/user.schema.ts                            (source)
+  ↓
+schemas/generated/user.types.ts                   (typescript)
+schemas/generated/user.zod.ts                     (zod)
+schemas/generated/user.json.schema.json           (jsonSchema)
+schemas/generated/user.openapi.json               (openApi)
+```
+
+The basename strips a `.schema.{ts,js,mts,cts}` suffix when present; falls back to "filename minus last extension" otherwise. Path manipulation is plain strings — no `node:path` import — so the handler stays trivially platform-agnostic. Forward slashes are the canonical separator; the CLI normalizes to platform separators on write.
+
+`suggestedPathFor(sourcePath, kind, options?)` is exported from `@nekostack/schema/cli` so the CLI can advertise the same convention for `check`'s artifact-lookup without re-deriving the rule.
+
+### Multi-schema source-file disambiguation
+
+When a single source file declares **two or more** named schemas, each schema's four artifacts gain a slugged discriminator so paths don't collide:
+
+```ts
+// schemas/account.schema.ts
+export const Tenant = s.object(...).id("com.x.Tenant");
+export const Audit  = s.object(...).id("com.x.AuditEvent");
+```
+
+```text
+schemas/generated/account.com-x-tenant.types.ts
+schemas/generated/account.com-x-tenant.zod.ts
+schemas/generated/account.com-x-tenant.json.schema.json
+schemas/generated/account.com-x-tenant.openapi.json
+schemas/generated/account.com-x-auditevent.types.ts
+... (and so on)
+```
+
+Discriminator slug rule:
+
+```text
+lowercase → non-alphanumeric runs collapse to "-" → leading/trailing "-" trimmed
+```
+
+If the same `schemaId` appears at multiple versions inside one file (rare; v0.7 doesn't endorse but does tolerate), the discriminator additionally embeds the slugged version (`com-x-tenant-1-0-0`, `com-x-tenant-2-0-0`) so per-schema paths stay unique. Single-schema files never get a discriminator — the path is exactly the simple form above.
+
+## Pure-handler gate
+
+[`../tests/registry/handler-purity.test.ts`](../tests/registry/handler-purity.test.ts) gates the schema-side boundary. Each of the four handlers (`list`, `diff`, `check`, `generate`) plus their transitive reach is asserted to:
+
+- Not import `node:fs` / `fs` / `fs/promises` (static file-level scan over each handler's module-graph reach).
+- Not call `console.log` / `console.error` / `console.warn` / `console.info` / `console.debug` at module load or invocation time (runtime spy + static pattern).
+- Not call `process.exit` / `process.abort` (runtime spy + static pattern).
+- Not invoke dynamic `import()` (static pattern).
+
+Sentinel tests verify the gate catches what it claims. Any future handler change that crosses the boundary fails this suite before it reaches review.
+
+## Integration surface — `@nekostack/schema/cli`
+
+The barrel ([`../src/cli-integration.ts`](../src/cli-integration.ts)) re-exports exactly the names the CLI needs:
+
+**Runtime exports**
+
+```text
+sourceHashFromText        parseProvenanceFromText
+buildRegistry             findSchema
+diffNodes
+listHandler  diffHandler  checkHandler  generateHandler
+suggestedPathFor          GENERATOR_KINDS
+```
+
+**Type exports**
+
+```text
+RegistrySourceEntry  RegistryEntry  Registry
+DiffSeverity  DiffKind  DiffChange
+FreshnessVerdict
+GeneratorKind  GeneratedArtifact  CommittedArtifact
+GenerateOpts  GenerateResult
+CheckOpts     CheckResult
+DiffOpts      DiffResult
+ListOpts      ListResult
+```
+
+The `package.json` `exports` map ([`../package.json`](../package.json)) wires:
+
+```jsonc
+{
+  ".":     "./src/index.ts",          // v0.6 public surface
+  "./cli": "./src/cli-integration.ts" // v0.7 CLI integration surface
+}
+```
+
+The `/cli` subpath is **package-internal**. External consumers of `@nekostack/schema` should not import from it; names exposed there are subject to internal change between minor versions and engine-swap-safety lives at the root, not at this subpath.
+
+## Implementation reference
+
+| Surface | File |
+|---|---|
+| Types | [`../src/registry/types.ts`](../src/registry/types.ts) |
+| `sourceHashFromText` | [`../src/registry/source-hash.ts`](../src/registry/source-hash.ts) |
+| `parseProvenanceFromText` | [`../src/registry/parse-provenance.ts`](../src/registry/parse-provenance.ts) |
+| `buildRegistry`, `findSchema` | [`../src/registry/build-registry.ts`](../src/registry/build-registry.ts) |
+| `diffNodes` | [`../src/registry/diff.ts`](../src/registry/diff.ts) |
+| `listHandler` | [`../src/registry/handlers/list.ts`](../src/registry/handlers/list.ts) |
+| `diffHandler` | [`../src/registry/handlers/diff.ts`](../src/registry/handlers/diff.ts) |
+| `checkHandler` | [`../src/registry/handlers/check.ts`](../src/registry/handlers/check.ts) |
+| `generateHandler`, `suggestedPathFor`, `GENERATOR_KINDS` | [`../src/registry/handlers/generate.ts`](../src/registry/handlers/generate.ts) |
+| Integration barrel | [`../src/cli-integration.ts`](../src/cli-integration.ts) |
+| Master plan source of truth | [`./PHASE_PLAN_v0.7.md`](./PHASE_PLAN_v0.7.md) |
+| Diff classification contract | [`./DIFF_CLASSIFICATION.md`](./DIFF_CLASSIFICATION.md) |
+| Generator-header format | [`./HEADER_FORMAT.md`](./HEADER_FORMAT.md) |

package/docs/RUNTIME.md

@@ -0,0 +1,279 @@
+# Runtime Validation
+
+> The v0.6 runtime API for `@nekostack/schema`. Defines what `parse` / `safeParse` / `validate` do, how their output relates to a schema's input vs. output type, what the issue contract is, and where Zod fits inside the wrapper. For the v0.1 absence-semantics table this doc references, see [`ABSENCE_SEMANTICS.md`](./ABSENCE_SEMANTICS.md). For the locked phase plan, see [`PHASE_PLAN_v0.6.md`](./PHASE_PLAN_v0.6.md).
+
+## Purpose
+
+v0.6 makes runtime validation a NekoStack-owned workflow. A consumer never imports Zod for validation; they import `@nekostack/schema`, define a schema once via `s.*`, and use `parse` / `safeParse` / `validate` against it. Zod executes behind the wrapper, but the consumer's vocabulary is `Schema<I, O>`, `Result<T>`, `Issue[]`, `ParseError` — not `ZodSchema`, `ZodError`, or a Zod issue code.
+
+This is the [thesis-fit](../../../PRODUCT_THESIS.md) lens applied to validation: the package absorbs the workflow, not just adapts an external tool.
+
+## Public API
+
+```ts
+import { s, parse, safeParse, validate, ParseError } from "@nekostack/schema";
+import type { Result, Issue } from "@nekostack/schema";
+
+declare const User: ReturnType<typeof s.object>;
+
+parse(User, input);      // s.output<typeof User>            (throws ParseError)
+safeParse(User, input);  // Result<s.output<typeof User>>
+validate(User, input);   // Result<s.input<typeof User>>
+```
+
+Three free functions, one error class. The schema-as-first-arg shape is deliberate — it keeps every entry point a plain function so it composes with any wiring layer (HTTP handlers, form validators, agent tool implementations) without becoming method-bound to a class.
+
+## `parse`
+
+```ts
+function parse<S>(schema: S, input: unknown): s.output<S>
+```
+
+- Throws [`ParseError`](#parseerror) on failure. The thrown error carries the full normalized `Issue` list.
+- Uses **output semantics**: the return type matches `s.output<S>`. Default values are filled before the value is returned.
+- Use when the caller doesn't have a meaningful "what to do on failure" branch — `parse` is the friction-causing default; failure is loud.
+
+```ts
+const User = s.object({ name: s.string().default("anon") });
+parse(User, {});            // → { name: "anon" }
+parse(User, { name: 42 });  // throws ParseError([{ code: "invalid_type", path: ["name"], ... }])
+```
+
+## `safeParse`
+
+```ts
+function safeParse<S>(schema: S, input: unknown): Result<s.output<S>>
+```
+
+- Never throws. Returns `{ success: true, data }` or `{ success: false, issues }`.
+- Same output semantics + default-fill behavior as `parse`. Differs only in the error mode.
+- Use when the caller wants to inline-branch on success/failure.
+
+```ts
+const r = safeParse(User, {});
+if (r.success) {
+  r.data.name; // "anon"
+} else {
+  r.issues.forEach((i) => console.log(i.code, i.path));
+}
+```
+
+## `validate`
+
+```ts
+function validate<S>(schema: S, input: unknown): Result<s.input<S>>
+```
+
+- Structural check. Returns `Result<s.input<S>>`.
+- Uses **input semantics**: the return type is the *input* shape — default-bearing fields are object-optional in Input but object-required in Output (see [`ABSENCE_SEMANTICS.md`](./ABSENCE_SEMANTICS.md)).
+- Does **not** apply defaults. Does **not** run transforms.
+- **Still runs portable refinements** — `min` / `max` / `regex` / `email` / `int` / etc. are all enforced.
+- Use when the caller wants to know whether the input would pass a `parse` *without* paying for transforms or accepting a default-filled object.
+
+```ts
+const User = s.object({ name: s.string().min(3).default("anon") });
+validate(User, {});            // → { success: true, data: {} }            (no fill; absent is valid)
+validate(User, { name: "rin" });// → { success: true, data: { name: "rin" }} (passes through)
+validate(User, { name: "ab" }); // → { success: false, issues: [{ code: "too_small", ... }] } (refinement still runs)
+```
+
+The split between `parse` and `validate` is the v0.6-locked Decision #8 read of the v0.1 absence-semantics table — see [Validate-only IR variant](#validate-only-ir-variant) below for how it is realized internally.
+
+## Default semantics
+
+A field declared with `.default(v)` is **input-optional, output-required** (v0.1 Invariant 4):
+
+| Entry point | Missing default-bearing field | Explicit value |
+|---|---|---|
+| `parse(schema, input)` | fills `v` in output | passed through |
+| `safeParse(schema, input)` | fills `v` in `data` on success | passed through |
+| `validate(schema, input)` | accepted; **not filled**; absent in returned data | passed through |
+
+`null` is **not** equivalent to "missing." `default(v)` does not imply `nullable`; `null` on a non-nullable default-bearing field is rejected by all three entry points. To accept both null and missing, chain `.nullable().default(v)`.
+
+## Unknown-key policies
+
+Every object has an explicit policy. The compile path realizes the policy directly into the underlying Zod schema; behavior is identical across `parse` / `safeParse` / `validate`.
+
+| Policy | `parse` / `safeParse` | `validate` |
+|---|---|---|
+| `strict` (default) | rejects with one `unknown_key` issue per offending key | rejects with `unknown_key` issues |
+| `passthrough` | accepts; **preserves** unknown keys in returned data | accepts; preserves |
+| `stripUnknown` | accepts; **drops** unknown keys from returned data | accepts; drops |
+
+Zod batches all offending keys into a single `unrecognized_keys` issue; the issue-normalization layer splits them so one `unknown_key` lands per key. Per-emitted path is `[...originalPath, key]`.
+
+Nested objects each carry their own policy. An outer-strict + inner-passthrough composition is legal; each level enforces its own rule independently.
+
+## Issue normalization
+
+The runtime never surfaces a `ZodError`. Every failure path produces a `readonly Issue[]` using NekoStack's stable [`IssueCode`](../src/errors/issue.ts) vocabulary, per Decision #12:
+
+| Zod issue code | NekoStack `IssueCode` | Notes |
+|---|---|---|
+| `invalid_type` (received `undefined`, expected ≠ undefined) | `missing_required` | "field is absent" beats "field has wrong type" |
+| `invalid_type` (other) | `invalid_type` | |
+| `unrecognized_keys` | `unknown_key` | one issue per key (Zod batches, the normalizer splits) |
+| `invalid_literal` | `invalid_literal` | `expected` / `received` preserved |
+| `invalid_enum_value` | `invalid_enum` | `expected` carries the option list |
+| `invalid_union` / `invalid_union_discriminator` | `invalid_union` | discriminator folded — no v0.6 public surface |
+| `invalid_arguments` / `invalid_return_type` | `invalid_type` | + `metadata.source = "zod"`, `metadata.zodCode = <original>` |
+| `too_small` | `too_small` | + constraint metadata (`minimum`, `inclusive`, `exact`, `type`) |
+| `too_big` | `too_big` | + constraint metadata (`maximum`, `inclusive`, `exact`, `type`) |
+| `invalid_string` | `invalid_format` | + `metadata.validation` (`"email"` / `"url"` / `"uuid"` / `"regex"` / …) |
+| `invalid_date` | `invalid_type` | DateNode has no v0.6 builder |
+| `custom` | `custom_refinement_failed` | |
+| **anything else** | `custom_refinement_failed` | + `metadata.source = "zod"`, `metadata.zodCode = <original>` |
+
+The last row is the **fallback contract** (Decision #12 round-2): adding a new Zod code in a future Zod release must not crash the normalizer. `metadata.source` is the discriminator consumers key off; `metadata.zodCode` is what they use for triage.
+
+Every emitted `Issue` also carries:
+
+- `path` — Zod path, copied (not referenced — defensive against Zod array mutation).
+- `message` — Zod's human message, verbatim.
+- `expected` / `received` — verbatim where Zod provides them.
+- `schemaId` / `schemaVersion` — copied from `schema.metadata` when present; omitted when absent.
+- `severity: "error"` — always, in v0.6. The `"warning"` channel is reserved for later.
+
+## `ParseError`
+
+```ts
+class ParseError extends Error {
+  readonly code: "parse_failed";
+  readonly issues: readonly Issue[];
+}
+```
+
+- Thrown only by `parse`. `safeParse` and `validate` return `Result` and never throw.
+- The `issues` array is a defensive copy and frozen — mutating it post-construction has no effect.
+- `name` is `"ParseError"` so `e.name === "ParseError"` works for non-`instanceof` discrimination.
+- `code === "parse_failed"` is the stable literal for switching. **Don't** depend on `message` — it's human-readable but not part of the contract.
+
+```ts
+try {
+  parse(User, input);
+} catch (e) {
+  if (e instanceof ParseError) {
+    for (const i of e.issues) handle(i);
+  } else {
+    throw e;
+  }
+}
+```
+
+## Internal engine
+
+Zod is the **internal execution engine** for v0.6. It is not part of the user-facing surface:
+
+- A consumer of `@nekostack/schema` does **not** import Zod.
+- The runtime API accepts NekoStack `Schema` builders, not `ZodSchema` instances.
+- `parse` / `safeParse` / `validate` return NekoStack types (`Result`, `Issue`, `ParseError`) — never a `ZodError`.
+- A future runtime that replaces Zod with a pure IR-walker engine **must** be a no-op for consumers.
+
+This is the thesis-fit boundary applied to engines: the wrapper has absorbed the workflow. If a consumer needs to know which engine is underneath to use the package correctly, the wrapper is leaking — that's a regression, not a feature.
+
+Under the hood, two consumers share one **semantic mapping** (Decision #6, [`ZOD_MODIFIER_ORDERING.md`](./ZOD_MODIFIER_ORDERING.md)):
+
+```
+src/generators/zod-mapping.ts        # shared semantic mapping
+       │                               (IR traversal + v0.2 modifier
+       │                                ordering; ZodEmitter<T> + emit<T>())
+       │
+       ├─→ src/generators/zod.ts            (ZodEmitter<string>)
+       │                                    (deterministic TS source —
+       │                                     used by the generator pipeline)
+       │
+       └─→ src/runtime/zod-compile.ts       (ZodEmitter<ZodTypeAny>)
+                                            (live runtime value —
+                                             used by the cache below)
+```
+
+No `eval` of generated source. No source-to-value parsing. No value-to-source serialization. Each consumer realizes the mapping independently in its own concrete output type.
+
+## Compile cache
+
+```
+src/runtime/compile.ts:
+  const cache = new WeakMap<SchemaNode, ZodTypeAny>();
+```
+
+- Cache key is **`SchemaNode` object identity**, not IR equality.
+- First call per `SchemaNode`: build the live Zod schema via the value consumer, store in the cache.
+- Subsequent calls with the same `SchemaNode`: return the cached `ZodTypeAny` reference.
+- Two distinct `SchemaNode` instances with byte-identical IR do **not** share — explicit dedup via `irHash` (v0.2) is a v0.7 registry concern, not a runtime concern.
+- Lazy: schemas defined but never validated never compile.
+- The IR is deep-frozen by the builder, so storing the live Zod schema next to its key is safe — the IR cannot mutate out from under the cached value.
+- `WeakMap` lets the entire `(node, compiled)` pair be garbage-collected when the consumer drops its reference to the schema.
+
+**Concurrency.** Node is single-threaded; first-call wins by default and there's no race. A future worker-threads consumer that shares a `SchemaNode` across threads will get a per-thread cache. Documented here; no v0.6 mitigation.
+
+## Validate-only IR variant
+
+`validate` cannot simply reuse the parse-time compiled Zod, because the parse-time schema fills defaults and the validate contract says it must not. Decision #8 is the resolution:
+
+- For every default-bearing field, drop `modifiers.default` and set `modifiers.optional = true`.
+- Keep `nullable` / `nullish`, refinements, metadata, and the `unknownKeys` policy.
+- Recurse through object fields and array elements.
+
+The transform lives in `src/runtime/strip-defaults.ts`. The variant is **not** the same `SchemaNode` as the original — the compile cache keys on identity, so the variant lands in its own cache slot automatically.
+
+To keep `validate` cache-friendly, `src/runtime/parse.ts` adds a second `WeakMap`:
+
+```
+src/runtime/parse.ts:
+  const validateNodeCache = new WeakMap<SchemaNode, SchemaNode>();
+```
+
+- Cache key: the **original** `SchemaNode` (the one the consumer wrote).
+- Cache value: the stripped variant tree.
+- First `validate` call per schema: strip once, cache the variant. Repeated `validate(sameSchema, ...)` calls reuse the variant and therefore the same compiled Zod.
+
+**Issue normalization for `validate` is passed the original `schema.node`**, never the variant — so `schemaId` / `schemaVersion` always come from the consumer-authored metadata regardless of which compile path produced the failure.
+
+## Semantic parity
+
+The runtime is cross-checked against three independent engines (Decision #19), live in [`tests/semantic-parity.test.ts`](../tests/semantic-parity.test.ts):
+
+1. **NekoStack runtime** — `safeParse(schema, input).success`.
+2. **Generated-Zod execution** — emit source via `generateZod(schema.node)`, load + execute the emitted const expression with a real Zod runtime, call its `.safeParse(input)`. Explicitly **not** `compileZodSchema(...)` — the point is to cross-check the v0.2 source generator and the v0.6 runtime compiler.
+3. **Ajv 2020** — compile the output of `generateJsonSchema(schema.node)` and run the validator.
+4. **Small IR-walker oracle** — a direct interpreter over `SchemaNode` for the v0.6 supported subset. Knows nothing about Zod or JSON Schema.
+
+Compare-only contract: **accept/reject**. Issue shapes are intentionally not compared across engines.
+
+Redocly's role is separate (Decision #19a): [`tests/runtime-openapi-spec-validity.test.ts`](../tests/runtime-openapi-spec-validity.test.ts) verifies that every runtime-supported schema still emits an OpenAPI 3.1 component that passes structural validation. Redocly is **not** a runtime input oracle; treating it as one was the round-2 audit correction.
+
+## Unsupported behavior
+
+The v0.6 runtime supports the same IR subset the v0.2 generators cover:
+
+| Kind / feature | Status |
+|---|---|
+| `string` / `number` / `boolean` / `literal` / `enum` / `array` / `object` | supported |
+| `optional` / `nullable` / `nullish` / `default` modifiers | supported |
+| Portable refinements (`minLength`, `maxLength`, `length`, `regex`, `email`, `uuid`, `url`, `int`, `min`, `max`, `gt`, `lt`, `multipleOf`, `minItems`, `maxItems`) | supported |
+| `date` IR | **throws `UnsupportedNodeKindError`** at compile time |
+| `union` IR | **throws** at compile time |
+| `recursiveRef` IR | **throws** at compile time |
+| `transform` IR | **throws** at compile time |
+| Runtime refinements (`{ kind: "runtime", ... }`) | **throws** at compile time (Invariant 7 — fail loudly, never silently drop) |
+| Regex with non-empty flags in `generateJsonSchema` | throws (JSON Schema's `pattern` has no flag support); the runtime path itself supports flags |
+
+The throws are intentional. Silently dropping a runtime refinement would compile a validator that accepts inputs the IR intends to reject — exactly the kind of subtle data-loss bug the package exists to prevent.
+
+## Non-goals
+
+- **`ValidateError` to mirror `ParseError`.** `validate` returns `Result` only in v0.6. A `validateOrThrow` companion may land later if a consumer asks; the absence is intentional, not an oversight.
+- **Method-style API (`schema.parse(input)`).** v0.6 ships the free functions. A `Schema.prototype.parse` alias could be added in a v0.6.x without breaking anything; the locked surface is the free-function form.
+- **Schema-version negotiation.** Cross-version compatibility checks are a v0.7 registry concern.
+- **Error message localization.** v0.6 surfaces Zod's English messages verbatim; `@nekostack/locale` integration is deferred.
+- **`schemaId` / `schemaVersion` auto-population on every issue.** v0.6 populates these from `schema.metadata` when present; consumers that want them everywhere set the metadata. A registry could auto-fill in v0.7.
+- **Worker-thread shared cache.** Per-thread caches are the v0.6 behavior; sharing across threads is a future concern.
+
+## See also
+
+- [`ABSENCE_SEMANTICS.md`](./ABSENCE_SEMANTICS.md) — the v0.1 absence-semantics table that `default` / `optional` / `nullable` / `nullish` are realizations of.
+- [`ZOD_MODIFIER_ORDERING.md`](./ZOD_MODIFIER_ORDERING.md) — the locked modifier-application order shared by the source generator and the runtime compiler.
+- [`USAGE.md`](./USAGE.md) — v0.2 generator surface (TypeScript types, Zod source). The runtime API in this doc consumes the same schema definitions.
+- [`PHASE_PLAN_v0.6.md`](./PHASE_PLAN_v0.6.md) — locked plan and the twenty-one decisions backing this contract.
+- [`INVARIANTS.md`](./INVARIANTS.md) — cross-cutting invariants, including the engine-swap-safe and cache-invariance rules added in v0.6.