@nekostack/schema 1.0.0

package/docs/MIGRATIONS.md

@@ -0,0 +1,406 @@
+# Migrations Contract (v0.8)
+
+> The v0.8 schema-data migration surface — authoring shape, registry semantics, planner + verifier + stub contracts, the schema/CLI ownership boundary, and the explicit non-goals (no `apply`, no transform execution). Pairs with [`PHASE_PLAN_v0.8.md`](./PHASE_PLAN_v0.8.md); the plan locks decisions, this file documents the contract that resulted.
+
+## Hard-locked boundary
+
+v0.8 ships **migration planning + verification + stub generation only**. v0.8 does **NOT** ship:
+
+- a `neko schema migrate apply` verb,
+- any code path that calls `migration.transform(input)`,
+- any other route by which v0.8 mutates data.
+
+Migration execution is deferred to **v0.9+** behind its own plan and explicit safety review.
+
+**Module top-level evaluation ≠ transform execution.** Migration files are loaded through `tsx` during discovery (Step 19), and any top-level code inside a `*.migration.ts` file evaluates at load time. Top-level evaluation failures are classified as `runtime_error` load failures by the existing tsx-loader contract. The authoring guidance (below) requires migration files to keep top-level code declarative and side-effect-free.
+
+---
+
+## Authored migration file shape
+
+The locked shape of a `*.migration.ts` file:
+
+```ts
+/**
+ * @migration by @nekostack/schema
+ * schemaId:         com.x.User
+ * fromVersion:      1.0.0
+ * toVersion:        2.0.0
+ * fromIrHash:       sha256:<64-hex>
+ * toIrHash:         sha256:<64-hex>
+ * fromSourceHash:   sha256:<64-hex>
+ * toSourceHash:     sha256:<64-hex>
+ * generator:        neko-schema-migrate-stub
+ * generatorVersion: @nekostack/schema@0.8.0
+ *
+ * DO NOT REMOVE THE HEADER. Authors EDIT THE BODY.
+ */
+import type { Migration } from "@nekostack/schema/cli";
+
+const migration: Migration<"com.x.User", "1.0.0", "2.0.0"> = {
+  schemaId: "com.x.User",
+  from: "1.0.0",
+  to: "2.0.0",
+  transform(input) {
+    // Author fills this in. v0.8 NEVER invokes this function.
+    throw new Error("Not yet implemented");
+  },
+};
+
+export default migration;
+```
+
+### `Migration<...>` type
+
+Defined in [`src/migrations/types.ts`](../src/migrations/types.ts):
+
+```ts
+interface Migration<
+  SchemaId extends string = string,
+  FromVersion extends string = string,
+  ToVersion extends string = string,
+  Input = unknown,
+  Output = unknown,
+> {
+  readonly schemaId: SchemaId;
+  readonly from: FromVersion;
+  readonly to: ToVersion;
+  readonly transform: (input: Input) => Output;
+}
+```
+
+**No `down` / `reverse` field** — forward-only migrations are v0.8 (Decision #2). Bidirectional migrations are a separate authorship surface and not a v0.8 concern.
+
+**One `schemaId` per migration** — cross-schema migrations are out of scope (Decision #4). Splitting `User → User + Profile` is two unrelated plans the consumer composes.
+
+### `Migration` import — `/cli` subpath only
+
+The `Migration` type is imported from `@nekostack/schema/cli`, **not** from root `@nekostack/schema`. Decision #6: the v0.8 surface is package-internal; engine-swap-safety lives at the root, not at this subpath. The negative root-leakage gate in [`tests/public-surface.test.ts`](../tests/public-surface.test.ts) asserts root carries none of the 28 v0.8 names (10 runtime + 18 types).
+
+### Top-level code rule
+
+The header is the contract; the body is the author's. The body MUST keep its top-level code:
+
+- declarative — no `if`/`switch`/`for` outside the `transform` function,
+- side-effect-free — no `console.log`, no `fs`, no `process.exit`, no `import()` calls.
+
+The eventual `transform` body is the only place where data work happens, and **v0.8 never invokes it**.
+
+---
+
+## Provenance header
+
+The header carries 9 fields. All are required — v0.8 has no backward-compatibility window for missing fields (Decision #7).
+
+| Field              | Source                                                                  |
+|--------------------|-------------------------------------------------------------------------|
+| `@migration by`    | Always `@nekostack/schema`                                              |
+| `schemaId`         | reverse-DNS id of the schema this migration targets                     |
+| `fromVersion`      | source semver-shaped string                                             |
+| `toVersion`        | destination semver-shaped string                                        |
+| `fromIrHash`       | `sha256:<hex>` of canonical IR of the from-version schema               |
+| `toIrHash`         | `sha256:<hex>` of canonical IR of the to-version schema                 |
+| `fromSourceHash`   | `sha256:<hex>` of raw UTF-8 source bytes of the from-version schema     |
+| `toSourceHash`     | `sha256:<hex>` of raw UTF-8 source bytes of the to-version schema       |
+| `generator`        | Always `neko-schema-migrate-stub`                                       |
+| `generatorVersion` | `@nekostack/schema@<package-version>`                                   |
+
+[`parseMigrationProvenanceFromText(content)`](../src/migrations/parse-provenance.ts) reads the header. The carrier is **JSDoc-only** — migration files are TypeScript modules, not data documents.
+
+### Fail-loud, never silent
+
+A `.migration.ts` file exists specifically to declare a `(schemaId, fromVersion, toVersion)` transition. Missing or malformed provenance is treated as an **invalid declaration**, not a silent skip — silent skip would let a broken migration mask itself as "no migration found." `buildMigrationRegistry` returns `Result.failure` with an `integrity_error` Issue carrying `metadata.reason`:
+
+| `metadata.reason`                | When                                                       |
+|----------------------------------|------------------------------------------------------------|
+| `unknown_format`                 | File doesn't start with `/**` JSDoc                        |
+| `missing_migration_provenance`   | No JSDoc block at all                                      |
+| `missing_field`                  | A required field is missing                                |
+| `malformed_hash`                 | A hash field doesn't match `sha256:<64-hex>`               |
+| `malformed_field`                | A field's value is empty                                   |
+
+This is an **intentional departure from v0.7 Decision #5** (which tolerates anonymous *schemas* because a schema file may legitimately export both indexed schemas and helper schemas). A migration file has no analogous "helper migration" use case.
+
+---
+
+## Migration registry — identity and indexing
+
+`buildMigrationRegistry(entries: readonly MigrationSourceEntry[]): Result<MigrationRegistry>` ([`src/migrations/build-migration-registry.ts`](../src/migrations/build-migration-registry.ts)) constructs the three-level lookup:
+
+```text
+MigrationRegistry = ReadonlyMap<
+  schemaId,
+  ReadonlyMap<
+    fromVersion,
+    ReadonlyMap<toVersion, MigrationEntry>
+  >
+>
+```
+
+### Identity
+
+A migration's identity is the `(schemaId, fromVersion, toVersion)` triple (Decision #8). Storage keys all three levels by this triple; provenance hashes are **binding** information, not identity (they let the verifier detect when the migration was authored against a schema state that has since changed).
+
+### Duplicate detection
+
+Two migration files claiming the same triple surface as `Result.failure` with a `duplicate_migration` Issue:
+
+```ts
+{
+  code: "duplicate_migration",
+  path: [],
+  message: "Duplicate migration for `com.x.User` 1.0.0 → 2.0.0 found in: a.migration.ts, b.migration.ts",
+  severity: "error",
+  metadata: {
+    schemaId: "com.x.User",
+    fromVersion: "1.0.0",
+    toVersion: "2.0.0",
+    sourcePaths: ["a.migration.ts", "b.migration.ts"],
+  },
+}
+```
+
+**First-seen wins** on a duplicate — the partial map isn't torn. Same rule as `buildRegistry`'s duplicate handling for v0.7's `duplicate_schema_id`.
+
+### Multi-failure aggregation
+
+The builder **never short-circuits** — duplicate-id Issues + malformed-provenance Issues are collected together in one `Result.failure`. The CLI dispatcher (Step 21+) renders a single human-readable report.
+
+---
+
+## Planner — `planMigration`
+
+[`src/migrations/plan-migration.ts`](../src/migrations/plan-migration.ts). The Round-3 locked signature consumes both registries plus the operand triple:
+
+```ts
+planMigration({
+  schemaRegistry,
+  migrationRegistry,
+  schemaId,
+  fromVersion,
+  toVersion,
+}): Result<MigrationPlan>
+```
+
+### Behavior
+
+1. **Resolve endpoints** in `schemaRegistry` via `findSchema`. Either missing → `Result.failure` with `migration_missing_endpoint`. No diff is computed when an endpoint is missing.
+2. **Compute the diff** via the v0.7 classifier `diffNodes(from.node, to.node)` (see [`DIFF_CLASSIFICATION.md`](./DIFF_CLASSIFICATION.md)). `worstSeverity` aggregation uses the same precedence `breaking > additive > cosmetic`, `null` when empty.
+3. **Look up the exact migration** for the triple (if any).
+4. **Severity-gate the chain requirement** per Decision #10:
+
+| `worstSeverity` | Chain                                  | Notes / Failure                                                                                       |
+|-----------------|----------------------------------------|-------------------------------------------------------------------------------------------------------|
+| `null`          | empty                                  | If an exact migration exists for the pair, attach an `over_specified` `PlanNote`.                     |
+| `"cosmetic"`    | empty                                  | Same `over_specified` rule.                                                                           |
+| `"additive"`    | empty (no migration) OR `[exact]`      | If an exact migration is registered, include it. Otherwise empty + `additive_no_migration` `PlanNote`.|
+| `"breaking"`    | **required** — DFS over adjacency map  | 0 chains → `migration_not_found` (no migrations for schemaId) / `migration_chain_broken` (some exist but no path). 1 chain → success. 2+ chains → `migration_ambiguous_chain` (planner refuses to pick).|
+
+### `MigrationPlan` shape
+
+```ts
+interface MigrationPlan {
+  readonly schemaId: string;
+  readonly chain: readonly MigrationEntry[];
+  readonly versionPath: readonly string[]; // [from, ...intermediates, to]
+  readonly worstSeverity: DiffSeverity | null;
+  readonly notes: readonly PlanNote[];
+}
+```
+
+`versionPath` always carries both endpoints. For an empty chain it's `[fromVersion, toVersion]`. For a non-empty chain it's derived from the chain entries' `toVersion`s.
+
+### `PlanNote` kinds
+
+```ts
+type PlanNote =
+  | { kind: "over_specified";        migration: MigrationEntry }
+  | { kind: "additive_no_migration"; worstSeverity: DiffSeverity };
+```
+
+Notes record *why* the plan came out the way it did when the chain decision is non-obvious.
+
+### Failure codes (planner)
+
+| Code                            | Condition                                                                  |
+|---------------------------------|----------------------------------------------------------------------------|
+| `migration_missing_endpoint`    | Either `fromVersion` or `toVersion` is absent from the schema registry.    |
+| `migration_not_found`           | `worstSeverity` is `breaking` and no migrations are registered for the id. |
+| `migration_chain_broken`        | `worstSeverity` is `breaking`, migrations exist but no path bridges.       |
+| `migration_ambiguous_chain`     | `worstSeverity` is `breaking` and two or more chains both reach the target.|
+
+### `transform` is never called
+
+Chain resolution is **structural**. The planner walks `(schemaId, fromVersion) → Map<toVersion, MigrationEntry>` adjacency and emits an ordered chain of entries. It does not — and cannot — call `migration.transform`. The static-scan purity gate ([`tests/migrations/handler-purity.test.ts`](../tests/migrations/handler-purity.test.ts)) deny-lists `.transform(` over the planner's full reach.
+
+### `UnsupportedNodeKindError` propagates
+
+If `diffNodes` is given an IR with an unsupported kind (`date` / `union` / `recursiveRef` / `transform`), the planner does **not** catch the throw — it propagates to the CLI dispatcher, which maps it to a non-zero exit code at the CLI boundary. Same fail-loud discipline as v0.3 / v0.6 generators.
+
+---
+
+## Verifier — `verifyMigrationProvenance`
+
+[`src/migrations/verify-provenance.ts`](../src/migrations/verify-provenance.ts):
+
+```ts
+verifyMigrationProvenance({ schemaRegistry, migrationRegistry }): Result<VerificationResult>
+```
+
+### Verdict matrix
+
+For every `MigrationEntry`, compare recorded provenance against current schema registry endpoints. Mirrors the v0.7 two-hash freshness matrix one row at a time:
+
+| irHash (both endpoints) | sourceHash (both endpoints) | Verdict             |
+|-------------------------|------------------------------|---------------------|
+| match                   | match                        | `bound`             |
+| match                   | at least one differs         | `cosmetic_drift`    |
+| at least one differs    | (any)                        | `drift`             |
+| endpoint absent         | n/a                          | `missing_endpoint`  |
+
+Per-verdict shape (discriminated union, `status` field):
+
+```ts
+{ status: "bound" | "cosmetic_drift" | "drift" | "missing_endpoint",
+  sourcePath, schemaId, fromVersion, toVersion }
+```
+
+### Result envelope
+
+- `Result.success` when every verdict is `bound` or `cosmetic_drift`. **`cosmetic_drift` does not fail the run** — CLI warns on stderr; exit stays `SUCCESS`.
+- `Result.failure` with one `Issue` per `drift` / `missing_endpoint` otherwise. CLI maps to `LOGICAL_FAILURE`.
+
+### Scope of "verification"
+
+**Provenance + chain integrity only.** The verifier does NOT prove transform correctness. A migration whose `transform` is `throw new Error("Not yet implemented")` verifies just as cleanly as a fully-authored one, as long as the provenance hashes bind. The verifier is a `provenance-says-what-it-says` check, not a behavior check. Transform behavior is v0.9+.
+
+### Failure codes (verifier)
+
+| Code                         | Condition                                                                              |
+|------------------------------|----------------------------------------------------------------------------------------|
+| `migration_drift`            | irHash mismatch at at least one endpoint.                                              |
+| `migration_missing_endpoint` | A migration references a schema version not in the registry. Same code as the planner. |
+
+`cosmetic_drift` does not surface as an Issue — it lives on the success branch's `verdicts[]` and `summary.cosmetic_drift` only.
+
+---
+
+## Stub — `stubMigration`
+
+[`src/migrations/stub.ts`](../src/migrations/stub.ts):
+
+```ts
+stubMigration({ schemaRegistry, schemaId, fromVersion, toVersion }): Result<MigrationStub>
+```
+
+Pure file-*content* generator. The CLI does the filesystem write (Step 23).
+
+### Suggested path
+
+```text
+<schema-dir>/migrations/<basename>.<from-slug>-to-<to-slug>.migration.ts
+```
+
+- `<basename>` strips `.schema.{ts,js,mts,cts}` from the from-version schema's filename.
+- `<from-slug>` / `<to-slug>` use the **v0.7-compatible slug rule** from `src/registry/handlers/generate.ts` (Round-2 lock):
+  ```text
+  lowercase  →  non-alphanumeric runs collapse to "-"  →  trim leading/trailing "-"
+  ```
+- Handles prerelease/build markers cleanly: `1.0.0-beta.1` → `1-0-0-beta-1`, `2.0.0+build.5` → `2-0-0-build-5`.
+
+### Generated content
+
+- Full 9-field JSDoc provenance header padded for visual alignment (matches the v0.2/v0.3 generator-header style).
+- `import type { Migration } from "@nekostack/schema/cli"` — NOT root.
+- Typed `Migration<schemaId, fromVersion, toVersion>` declaration.
+- `transform(input)` body that throws `"Not yet implemented"`. Authors edit the body; v0.8 never invokes it.
+- `export default migration`.
+
+The stub generator is pure — it does not write the file. The CLI's `stub` verb (Step 23) does `mkdir -p` + `writeFile` and **refuses to overwrite** an existing file at the suggested path (unlike `generate`'s overwrite-by-default behavior; `generate` overwrites generated artifacts, but `stub` would overwrite hand-authored code).
+
+### Failure
+
+| Code                         | Condition                                                                |
+|------------------------------|---------------------------------------------------------------------------|
+| `migration_missing_endpoint` | Either `fromVersion` or `toVersion` is absent from the schema registry.   |
+
+---
+
+## Schema/CLI ownership boundary
+
+Master plan Decision #1 (continued from v0.6 / v0.7):
+
+| Concern                                          | Owner                  |
+|--------------------------------------------------|------------------------|
+| Pure registry construction, planning, verification, stub-content generation | `@nekostack/schema` (v0.8 surface) |
+| Filesystem reads (`*.schema.ts`, `*.migration.ts`, generated artifacts)     | `@nekostack/cli`  |
+| Schema/migration module loading via `tsx`         | `@nekostack/cli`  |
+| Filesystem writes (stub files)                    | `@nekostack/cli`  |
+| stdout / stderr formatting                        | `@nekostack/cli`  |
+| Process exit codes                                | `@nekostack/cli`  |
+| `migration.transform` execution                   | **v0.9+**, no owner in v0.8 |
+
+The schema package is **data-in / data-out**. No `fs.*`, no dynamic `import()`, no `process.*`, no `console.*`. The static + runtime purity gate in [`tests/migrations/handler-purity.test.ts`](../tests/migrations/handler-purity.test.ts) covers all four migration handlers and their immediate reach (9 modules total) plus `.transform(` as a forbidden call pattern.
+
+---
+
+## Surface boundary
+
+| Path                            | What it exposes                                                                                |
+|---------------------------------|------------------------------------------------------------------------------------------------|
+| `@nekostack/schema`             | v0.6 public consumer API. **No v0.7 / v0.8 surface names appear here.**                        |
+| `@nekostack/schema/cli`         | Package-internal integration surface for `@nekostack/cli`. Exposes v0.7 + v0.8 surfaces.       |
+
+The boundary is gated by two complementary test files:
+
+- [`tests/registry-surface.test.ts`](../tests/registry-surface.test.ts) — positive gate. Asserts every v0.7 + v0.8 runtime name and type is reachable through `@nekostack/schema/cli`.
+- [`tests/public-surface.test.ts`](../tests/public-surface.test.ts) — negative gate. Asserts every v0.7 + v0.8 name is **absent** from `@nekostack/schema`. Type-level coverage uses `@ts-expect-error` directives — any future leakage makes a directive unused, which is itself a typecheck error.
+
+Wiring: `package.json` `exports` map declares both `"."` (root) and `"./cli"`; the `/cli` path resolves to [`src/cli-integration.ts`](../src/cli-integration.ts) which re-exports the v0.7 + v0.8 surfaces.
+
+---
+
+## Explicit non-goals
+
+The following are **out of scope** for v0.8. They live either in a later schema phase, in a sibling package, or — for the highest-risk items — behind v0.9+'s own plan and safety review:
+
+| Out-of-scope item                                  | Why deferred                                                                                                                              |
+|----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| **Migration execution (`apply`)**                  | The whole hard-locked boundary. v0.9+ revisits behind a separate plan with pre/post validation, audit log emission, rollback semantics, dry-run/apply split, online/offline. |
+| **Reversible / down migrations**                   | Bidirectional migrations are a separate authorship surface. Every `down` needs its own authorship + test + verification.                  |
+| **Cross-schema migrations**                        | One `schemaId` per migration. Splitting `User → User + Profile` is two unrelated plans the consumer composes.                              |
+| **Database DDL migrations (`ALTER TABLE`)**        | Owned by [`@nekostack/migrate`](../../migrate) per `BOUNDARIES.md` §25. v0.8's planner produces plans that `@nekostack/migrate` could consume, but DDL execution belongs there. |
+| **Online migrations**                              | Even when v0.9+ adds `apply`, the apply phase's plan decides offline-vs-online. v0.8 does not pre-decide.                                  |
+| **Branching migrations / version trees**           | Linear version chains only. `migration_ambiguous_chain` is fail-loud, not auto-resolved.                                                   |
+| **Multi-hop skip migrations**                      | Forced through intermediate versions; the planner enumerates simple paths, not skip-edges.                                                 |
+| **Transform correctness proof**                    | The verifier checks provenance + chain integrity. v0.8 cannot inspect a function body to know whether it correctly maps `s.output<v1>` to `s.output<v2>`. Authors write their own unit tests. |
+| **Migration scheduling / orchestration**           | v1.0+.                                                                                                                                     |
+| **Distributed migration coordination**             | Single-process planner. No locks, leases, cluster awareness.                                                                               |
+| **Authoring idioms / helper-library conventions**  | v0.8 locks the file shape, path convention, provenance carrier, and type signature. Author idioms (helper libraries, snapshot strategies) land separately if the community converges on a pattern. |
+
+---
+
+## Reference
+
+### Implementation files
+
+| Surface                                        | File                                                                                  |
+|------------------------------------------------|----------------------------------------------------------------------------------------|
+| Types                                          | [`../src/migrations/types.ts`](../src/migrations/types.ts)                            |
+| Provenance parser                              | [`../src/migrations/parse-provenance.ts`](../src/migrations/parse-provenance.ts)      |
+| Registry builder                               | [`../src/migrations/build-migration-registry.ts`](../src/migrations/build-migration-registry.ts) |
+| Planner                                        | [`../src/migrations/plan-migration.ts`](../src/migrations/plan-migration.ts)          |
+| Verifier                                       | [`../src/migrations/verify-provenance.ts`](../src/migrations/verify-provenance.ts)    |
+| Stub generator                                 | [`../src/migrations/stub.ts`](../src/migrations/stub.ts)                              |
+| Handlers — `list`, `plan`, `verify`, `stub`    | [`../src/migrations/handlers/`](../src/migrations/handlers/)                          |
+| Diff classifier (shared with v0.7)             | [`../src/registry/diff.ts`](../src/registry/diff.ts)                                  |
+| Integration barrel                             | [`../src/cli-integration.ts`](../src/cli-integration.ts)                              |
+
+### Phase + contract docs
+
+| Doc                                           | Subject                                                  |
+|-----------------------------------------------|----------------------------------------------------------|
+| [`./PHASE_PLAN_v0.8.md`](./PHASE_PLAN_v0.8.md) | Locked decisions, sequencing, validation gates           |
+| [`./DIFF_CLASSIFICATION.md`](./DIFF_CLASSIFICATION.md) | The classifier the planner consumes                       |
+| [`./REGISTRY.md`](./REGISTRY.md)              | v0.7 registry / freshness / generation contract           |
+| [`./HEADER_FORMAT.md`](./HEADER_FORMAT.md)    | The JSDoc provenance-header carrier (v0.2-era origin)     |

package/docs/MIGRATION_GUIDE.md

@@ -0,0 +1,150 @@
+# Migrating to NekoStack Schema
+
+> The definitive guide to moving from Zod (or raw JSON Schema) to a single-source-of-truth architecture.
+
+## The Problem: The "Silent Lie" of Modern Web Dev
+
+Every senior engineer has the same horror story: A developer adds a new optional field to a database table. They update the Prisma model. They update the TypeScript interface. They forget to update the Zod validator on the API route.
+
+Two months later, an integration partner complains their webhook is broken because the payload is missing a field the OpenAPI docs promised. The docs were generated from an outdated interface, the API is validating against an outdated Zod schema, and the database is rejecting nulls. 
+
+You have a "Silent Lie" in your architecture. Your contracts drifted because **you were trying to maintain the same shape in three different languages.**
+
+## The Solution: The Intermediate Representation (IR)
+
+`@nekostack/schema` solves this by forcing you to define the shape **once**, in a specialized DSL. That definition is compiled into an Intermediate Representation (IR). 
+
+From that IR, the system generates:
+1. Your Zod validators.
+2. Your TypeScript types.
+3. Your OpenAPI 3.1 Components.
+4. Your JSON Schema specifications.
+
+When you change the definition, **every artifact updates instantly**. Drift becomes mathematically impossible.
+
+---
+
+## Step 1: The Basic Rewrite
+
+Let's convert a standard Zod schema to NekoStack.
+
+**Before (Zod):**
+```ts
+import { z } from "zod";
+
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  role: z.enum(["admin", "member"]).default("member")
+});
+
+export type User = z.infer<typeof UserSchema>;
+```
+
+**After (NekoStack):**
+```ts
+import { s } from "@nekostack/schema";
+
+export const User = s.object({
+  id: s.string().uuid(),
+  email: s.string().email(),
+  role: s.enum(["admin", "member"]).default("member")
+})
+  .id("com.nekostack.auth.User")
+  .version("1.0.0")
+  .describe("The authenticated user record.");
+
+// s.infer works exactly like z.infer
+export type UserType = s.infer<typeof User>;
+```
+
+### What changed?
+1. `z` became `s`. The DSL is nearly identical.
+2. **The "Insurance Policy":** We added `.id()`, `.version()`, and `.describe()`. 
+
+**Why the ID?** Zod schemas are anonymous. If you want to safely migrate millions of user records from v1.0.0 to v2.0.0, the system needs to know *what* it is migrating. The reverse-DNS ID (`com.nekostack.auth.User`) gives your data a permanent address in the registry, ensuring you never accidentally apply a `Tenant` migration to a `User` record.
+
+---
+
+## Step 2: The "Magic Moment" (Generation)
+
+Once you define your schema, you no longer write types or OpenAPI specs by hand. 
+
+Run the CLI:
+```bash
+neko schema generate src/schemas/user.schema.ts
+```
+
+This generates four files alongside your source:
+* `user.zod.ts`: A fully functioning Zod 3.x schema.
+* `user.d.ts`: Your clean TypeScript definitions.
+* `user.openapi.json`: Your OpenAPI 3.1 component.
+* `user.json.schema.json`: Your Draft 2020-12 specification.
+
+You just automated away 20% of your maintenance work.
+
+### Visualizing the Truth
+**Why the IR is not a lossy process:** In many generators, you lose metadata (like JSDoc descriptions or custom validation tags) when moving from a schema to an OpenAPI spec. NekoStack IR is designed as a **Super-Set.** It captures the structural intent *and* the descriptive metadata of your schema. When you generate an OpenAPI spec, you aren't guessing—you are projecting the IR into the OpenAPI standard. If the IR contains a rule that OpenAPI cannot represent, NekoStack will stop the build, preventing you from shipping an API doc that lies about your actual runtime behavior.
+
+---
+
+## Step 3: Runtime Validation
+
+You do **not** import Zod to validate your data. `@nekostack/schema` absorbs the workflow to provide a stricter, safer guarantee.
+
+```ts
+import { parse, safeParse, validate } from "@nekostack/schema";
+
+// 1. Parse (Throws on failure, fills defaults)
+const user = parse(User, req.body); 
+
+// 2. SafeParse (Returns a Result, fills defaults)
+const result = safeParse(User, req.body);
+if (!result.success) {
+  // result.issues uses stable NekoStack IssueCodes, not raw Zod strings
+  console.log(result.issues[0].code); // "invalid_type"
+}
+
+// 3. Validate (Structural check only. Does NOT fill defaults)
+const isValid = validate(User, req.body);
+```
+
+### The "Validate vs. Parse" Split
+Zod conflates "checking" data with "mutating/filling" data. NekoStack splits them. If you are validating an incoming webhook, you want `parse` (to fill the default `role: "member"`). If you are verifying a database row you just read, you want `validate` (to ensure it is structurally sound without accidentally overwriting data).
+
+---
+
+## Step 4: The Safety Net (CI/CD)
+
+The true value of NekoStack isn't saving keystrokes; it's saving production.
+
+When you run `neko schema check` in your CI pipeline, the system verifies the **IR Hash** embedded in every generated artifact. 
+
+If a developer changes the `User` schema but forgets to run `generate` and commits the PR, the CI build will fail instantly with a `Stale Artifact` error. **The Silent Lie is dead.**
+
+---
+
+## Deep Dive: Nuances & Gaps
+
+While moving from Zod is mostly copy-paste, you must be aware of NekoStack's stricter safety boundaries:
+
+### 1. `null` vs `undefined`
+Zod is often loose with absence. NekoStack is literal.
+* `.optional()` means the key can be missing (undefined).
+* `.nullable()` means the value can literally be `null`.
+* `.nullish()` means both.
+If you define a field as `.default("x")`, NekoStack treats it as **input-optional, but output-required**.
+
+### 2. Transform Precedence
+When a field has both a `.default()` and a `.transform()`, **NekoStack applies the default first**. The transform function will always receive the defaulted value, never `undefined`. This ensures your database mutations have a predictable starting state, an edge case raw Zod leaves ambiguous.
+
+### 3. Recursive Schemas (`s.lazy()`)
+In Zod, you can create infinitely recursive anonymous schemas. In NekoStack, any schema referenced by `s.lazy()` **must** have an `.id()`. This forces you to name your recursive structures, ensuring the generated JSON Schema can emit valid `$ref` URLs rather than creating infinite expansion loops.
+
+---
+
+## Next Steps
+
+1. Read the [Issue Codes Catalog](./ISSUE_CODES.md) to see how NekoStack normalizes errors.
+2. See [EXAMPLES.md](./EXAMPLES.md) for advanced compositions (`pick`, `omit`, `extend`).
+3. Ready for the next level? Learn how to safely evolve your data with [Migrations](./MIGRATIONS.md).

package/docs/OPENAPI_MAPPING.md

@@ -0,0 +1,66 @@
+# OpenAPI 3.1 Mapping Contract
+
+> How `generateOpenApiSchemaComponent` translates a `SchemaNode` into an **OpenAPI 3.1 Schema Object** that lives under `components.schemas.<Name>`. This file documents the **deltas from JSON Schema** — the rest of the mapping is shared with [`JSON_SCHEMA_MAPPING.md`](./JSON_SCHEMA_MAPPING.md) via the internal [`src/generators/schema-fragment.ts`](../src/generators/schema-fragment.ts) module.
+
+## Why this doc is short
+
+OpenAPI 3.1 explicitly aligns its Schema Object with **JSON Schema draft 2020-12** — the spec calls it a superset. Everything in `JSON_SCHEMA_MAPPING.md` (absence semantics, object policy, refinement mapping, throw contract, `x-nekostack-*` extensions) applies unchanged to OpenAPI 3.1 component schemas because the same shared fragment emitter produces them.
+
+This doc only records what's **different**.
+
+## Output unit
+
+`generateOpenApiSchemaComponent(node)` returns a **single component schema** — the value that would live at `components.schemas.<Name>` in a full OpenAPI document. Composing it into paths / operations / responses / requestBodies / etc. is the consumer's job (or `@nekostack/api`'s when that package exists).
+
+**Not in scope for v0.4:**
+- Full OpenAPI documents
+- Other component types (responses, parameters, requestBodies, examples, headers, securitySchemes, links, callbacks, pathItems)
+- OpenAPI 3.0 target (3.0 uses `nullable: true`; 3.1 uses `type: ["x", "null"]` — v0.4 ships 3.1 only)
+
+## Differences from JSON Schema output
+
+| | JSON Schema (`generateJsonSchema`) | OpenAPI 3.1 component (`generateOpenApiSchemaComponent`) |
+|---|---|---|
+| `$schema` | `"https://json-schema.org/draft/2020-12/schema"` | **omitted** — OpenAPI 3.1 documents declare the dialect once at the document root via `jsonSchemaDialect`; components inherit it |
+| `$id` | URN by default; URL via `options.idBase` | **omitted** — component identity is the position in the document (`#/components/schemas/<Name>`) |
+| `x-nekostack.generator` | `"jsonSchema"` | `"openApi"` |
+| `irHash` in provenance | sha256 of canonical IR | **identical** (same node → same hash, proven by test) |
+| Output bytes | canonical JSON + trailing newline | canonical JSON + trailing newline (same convention) |
+
+That's it. Everything else — `type`, `properties`, `required`, `additionalProperties`, `default`, `pattern`, `format`, `enum`, `const`, `description`, `deprecated`, the `x-nekostack-strip` extension, the `x-nekostack-default-applied-by` extension, all portable refinement keyword mappings — is shared via `emitSchemaFragment` and produces the same bytes.
+
+## Why the shared fragment
+
+Decision #3 of the v0.4 plan flipped the original "parallel implementation" direction to a shared `emitSchemaFragment`. Rationale: duplicating the v0.3 mapping in a separate `openapi.ts` would create a drift vector. Bug fixes would have to land twice; behavior could silently diverge across the two generators despite OpenAPI 3.1 explicitly being a superset of JSON Schema draft 2020-12.
+
+The wrappers (`json-schema.ts`, `openapi.ts`) own only what genuinely differs: root document structure, `$schema` / `$id` decisions, and the `generator` field value in provenance. Anything related to IR translation lives in `schema-fragment.ts` and is exercised by both generators' test suites.
+
+## Throw contract
+
+Identical to JSON Schema (same `kind` values; the `generator` field flips to `"openApi"`):
+
+| Case | `kind` | `generator` |
+|---|---|---|
+| IR kind `date` / `union` / `recursiveRef` / `transform` | the kind name | `"openApi"` |
+| Runtime refinement | `"runtimeRefinement"` | `"openApi"` |
+| `regex` with non-empty flags | `"regexFlags"` | `"openApi"` |
+
+Tests assert on `code` / `kind` / `generator` per the v0.2 stable-error contract.
+
+## Round-trip validation
+
+[`../tests/generators/openapi-redocly.test.ts`](../tests/generators/openapi-redocly.test.ts) composes every emitted component schema into a synthetic OpenAPI 3.1 document and validates via `@redocly/openapi-core`. Catches spec/tooling issues that mere JSON validity wouldn't surface.
+
+Per the v0.4 plan's fallback clause: if `@redocly/openapi-core`'s programmatic API turns out to be impractical, tests may switch to spawning the Redocly CLI instead. The validation requirement — compose into synthetic doc, assert clean — does not change.
+
+The OpenAPI Specification is authoritative; Redocly is the actively-maintained validation tool we delegate to.
+
+## When this doc gets longer
+
+When v0.5+ adds OpenAPI-specific behaviors:
+- `discriminator` keyword (needs union builders + a discriminator field selector).
+- `example` / `externalDocs` / `xml` keywords (need IR-level support).
+- OpenAPI 3.0 target as a generator option (if a real consumer needs it).
+- Per-server / per-path schema variants.
+
+Each gets a section here. Until then, the JSON_SCHEMA_MAPPING.md mapping table is the authoritative reference; this doc records only the table-of-deltas above.