@nekostack/schema 1.0.0

package/docs/SCOPE.md

@@ -0,0 +1,119 @@
+# @nekostack/schema — Scope
+
+Authoritative for what this package owns. If a capability is not listed under "Owned," it is somebody else's responsibility — see [`../../../BOUNDARIES.md`](../../../BOUNDARIES.md) for the full capability map.
+
+## Owned
+
+- Canonical IR (`SchemaNode` AST) — the contract every generator must consume
+- Schema authoring DSL (`s.string()`, `s.object()`, …)
+- Schema metadata: id, version, description, deprecated
+- Schema modifiers: optional, nullable, nullish, default
+- Object unknown-key policy: strict (default), stripUnknown, passthrough
+- Type inference (`s.infer`, `s.input`, `s.output`)
+- **Runtime validation API (v0.6+):** `parse` / `safeParse` / `validate`
+- **Runtime unknown-key enforcement (v0.6+):** strict / passthrough / stripUnknown execute at runtime, not just at generation time
+- **Issue model + normalized `IssueCode` vocabulary** — consumer-facing error contract (Zod errors are normalized through this layer; downstream code sees `Issue`, never `ZodError`)
+- **`ParseError`** (thrown only by `parse`; `safeParse` / `validate` return `Result`)
+- **Result type** consumed by `safeParse` / `validate`
+- Canonical IR serialization (sorted keys, undefined-stripped) — foundation for `irHash`
+- **`sourceHash` provenance (v0.7+):** `sourceHashFromText(text)` and the `ProvenanceOptions.sourceHash` slice on every generator. The slice is **optional** — generators omit the `sourceHash` line/extension when the option is absent, so all pre-v0.7 callers continue to produce byte-identical output.
+- **Registry-lite primitives (v0.7+, integration-subpath only — see boundary note below):** `buildRegistry`, `findSchema`, `parseProvenanceFromText`, `diffNodes`, the four pure handlers (`listHandler`, `diffHandler`, `checkHandler`, `generateHandler`), `suggestedPathFor`, `GENERATOR_KINDS`, and the supporting type surface. Reachable through `@nekostack/schema/cli` only; root `@nekostack/schema` does not export any of these. Documented in [`REGISTRY.md`](./REGISTRY.md).
+- **Diff classification (v0.7+):** the locked breaking / additive / cosmetic table + `worstSeverity` aggregation. Pure data-in / data-out; never touches the filesystem. Documented in [`DIFF_CLASSIFICATION.md`](./DIFF_CLASSIFICATION.md).
+- **Freshness verdict logic (v0.7+):** the two-hash matrix (`clean` / `cosmetic_drift` / `stale` / `integrity_error`) — pure classification given a registry and pre-read artifact bytes. The CLI owns the filesystem reads; this package owns the verdict.
+- **Migration primitives (v0.8+, integration-subpath only — see boundary note below):** `parseMigrationProvenanceFromText`, `buildMigrationRegistry`, `planMigration`, `verifyMigrationProvenance`, `stubMigration`, `suggestedMigrationPathFor`, the four pure handlers (`listMigrationsHandler`, `planMigrationHandler`, `verifyMigrationsHandler`, `stubMigrationHandler`), and the supporting type surface (`Migration`, `AnyMigration`, `MigrationRegistry`, `MigrationPlan`, `MigrationVerdict`, `VerificationResult`, `MigrationStub`, the four `*Opts` / `*Result` pairs). Reachable through `@nekostack/schema/cli` only; root `@nekostack/schema` does not export any of these. **No apply verb, no transform execution** — this package owns *planning* and *verification* of authored migrations, never their application. Documented in [`MIGRATIONS.md`](./MIGRATIONS.md).
+
+## Not owned
+
+| Capability | Lives in |
+|---|---|
+| API routing / request-response boundary validation | `@nekostack/api` |
+| Form rendering + state management | `@nekostack/form` |
+| Database schema definition + DDL | `@nekostack/migrate` |
+| OpenAPI route descriptions | `@nekostack/api` |
+| Runtime telemetry / event payloads | `@nekostack/telemetry`, `@nekostack/events` |
+| Auth policy / access decisions | `@nekostack/auth` |
+| Cross-record / continuity validation | `@nekostack/validator` |
+| App-level validation flows | application code |
+| Branded ID primitives (UUID/ULID brands) | `@nekostack/id` |
+| Schema-data migration *execution* (running a migration's `transform` function over real data) | NOT in `@nekostack/schema`. v0.8 ships planning + verification + stub generation only; an "apply" verb is explicitly out of scope. The eventual runner — if any — lives in a downstream package, never in `@nekostack/schema`. |
+| Database / DDL migrations | `@nekostack/migrate` (always — `@nekostack/schema` migrations are schema-data only) |
+| Rollback / reverse migrations | not supported (v0.8 is forward-only; one direction per authored file) |
+| Cross-schema migrations (a single migration touching more than one `schemaId`) | not supported (Decision #4 — one `schemaId` per migration; split into separate migrations) |
+| Filesystem walking of migration directories / dynamic loading of authored migration modules / stdout / exit codes for `neko schema migrate *` | `@nekostack/cli` (Master plan Decision #1 stays in force for v0.8) |
+| Global CLI runtime / plugin discovery | `@nekostack/cli` |
+| Filesystem reads / writes (source discovery, artifact reads, regenerated-artifact writes) | `@nekostack/cli` (Master plan Decision #1 — schema is pure) |
+| Dynamic schema loading via `tsx` | `@nekostack/cli` |
+| stdout / stderr formatting + CLI exit codes | `@nekostack/cli` |
+| `neko schema *` CLI commands (`list` / `diff` / `check` / `generate`) | `@nekostack/cli` (v0.7 — consumes the registry primitives exposed under `@nekostack/schema/cli`) |
+| Runtime validation *engine* (the bytecode-level matcher) | external (Zod is the v0.6 internal engine; consumers don't see it) |
+| Transforms / unions / runtime refinements in v0.6 / v0.7 | deferred (v0.6 / v0.7 support the v0.2 subset; date/union/recursiveRef/transform/runtime-refinement IR throws `UnsupportedNodeKindError` at compile time and at diff time) |
+
+## v0.6-specific scope
+
+v0.6 ships (in addition to everything v0.1–v0.5 already shipped):
+- `parse(schema, input): s.output<S>` — throws `ParseError` on failure
+- `safeParse(schema, input): Result<s.output<S>>` — non-throwing Result variant
+- `validate(schema, input): Result<s.input<S>>` — structural check; no default fill, no transforms; portable refinements still run
+- `ParseError extends Error` (frozen defensive issue copy; `code = "parse_failed"`)
+- Issue normalization layer translating Zod issues into the v0.1 `IssueCode` vocabulary (Decision #12)
+- Compile cache keyed by `SchemaNode` identity
+- Validate-only IR variant transform (defaults stripped, default-bearing fields flipped to optional)
+- Four-oracle semantic-parity test matrix (Decision #19)
+- OpenAPI spec-validity carry-forward (Decision #19a) tied to runtime fixture shapes
+
+v0.6 explicitly **does not** ship:
+- Date / union / recursiveRef / transform IR support (still throws `UnsupportedNodeKindError` at compile time)
+- Runtime refinements (custom predicates) — IR shape declared, but builders and runtime execution remain deferred; the runtime fails loudly when one appears in IR
+- Method-style API (`schema.parse(input)`) — free functions only in v0.6
+- `ValidateError` companion to `ParseError` — `validate` returns `Result` only
+- Schema registry / freshness / diffing — v0.7
+- Schema-version negotiation — v0.7
+- Locale / i18n of error messages
+- CLI commands — v0.7 (`@nekostack/cli` consumes the runtime)
+
+If something on the "does not ship" list appears in code, the scope was crossed and the PR should be rejected.
+
+## v0.7-specific scope (in progress — see [`ROADMAP.md`](./ROADMAP.md))
+
+v0.7 ships (schema-side) — *additive* over v0.6, no public-surface breakage at root `@nekostack/schema`:
+
+- `sourceHash` provenance slice on every generator (optional; opt-in via `ProvenanceOptions.sourceHash`).
+- `parseProvenanceFromText` — read the JSDoc-header or `x-nekostack` provenance off a committed artifact.
+- Registry primitives — `buildRegistry`, `findSchema` — pure, `Result<Registry>` failure path, never throws.
+- Diff classifier — `diffNodes` + the `worstSeverity` aggregation in `diffHandler`. Locked Decision #12 table; see [`DIFF_CLASSIFICATION.md`](./DIFF_CLASSIFICATION.md).
+- Four pure handlers — `list`, `diff`, `check`, `generate`. Data-in / data-out, gated by [`../tests/registry/handler-purity.test.ts`](../tests/registry/handler-purity.test.ts).
+- Integration subpath — `@nekostack/schema/cli` exposes the v0.7 surface for `@nekostack/cli` only. Root `@nekostack/schema` retains the v0.6 contract unchanged. See [`REGISTRY.md`](./REGISTRY.md).
+
+v0.7 explicitly **does not** ship (this package):
+
+- Filesystem I/O of any kind — owned by `@nekostack/cli` (Master plan Decision #1).
+- Schema-file discovery, dynamic `import()` of schemas via `tsx` — `@nekostack/cli`.
+- stdout / stderr formatting, exit-code mapping — `@nekostack/cli`.
+- `neko schema *` commands themselves — `@nekostack/cli` (companion plan steps 21–34).
+- Partial generation (subset of artifact kinds) — Master plan Decision #6 locks all-or-nothing per schema.
+- Migration proposal / generation / application — covered by v0.8 (in progress; see below) for the planning + verification + stub surface; **execution** of a migration's `transform` function remains explicitly out of scope.
+
+## v0.8-specific scope (in progress — see [`ROADMAP.md`](./ROADMAP.md) and [`PHASE_PLAN_v0.8.md`](./PHASE_PLAN_v0.8.md))
+
+v0.8 ships (schema-side) — *additive* over v0.7, no public-surface breakage at root `@nekostack/schema`. The contract is described in full in [`MIGRATIONS.md`](./MIGRATIONS.md).
+
+- **Schema-data migrations only** — authored `Migration<SchemaId, FromVersion, ToVersion, Input, Output>` modules carrying a pure `transform(input)` function plus a 9-field JSDoc provenance header. No database DDL, no rollback, no cross-schema migrations, no transform-correctness proof.
+- **`parseMigrationProvenanceFromText(text)`** — read the 9-field JSDoc provenance carrier (Decision #7) off a committed migration file. Fail-loud `integrity_error` + `metadata.reason` on malformed input; never silently skips (round-2 audit correction).
+- **`buildMigrationRegistry(entries)`** — pure constructor with first-seen-wins duplicate handling; three-level shape supporting exact-triple `(schemaId, fromVersion, toVersion)` lookup AND `(schemaId, fromVersion) → outgoing edges` for chain enumeration.
+- **`planMigration({ schemaRegistry, migrationRegistry, schemaId, fromVersion, toVersion })`** — diff-aware planner. Consumes both registries so it can honor Decision #10's severity → migration-requirement dispatch. The locked rules are: `null` / `cosmetic` diff → empty chain (no notes); `null` / `cosmetic` diff *with* an exact migration also authored → empty chain plus an `over_specified` `PlanNote` (the migration is not included in the chain); `additive` diff *with* an exact migration → chain containing that migration (no notes); `additive` diff *without* a migration → empty chain plus an `additive_no_migration` `PlanNote`; `breaking` diff → chain is **required** (DFS enumeration over the `(schemaId, fromVersion)` adjacency, failure if no chain reaches `toVersion`). Never calls `transform`.
+- **`verifyMigrationProvenance({ schemaRegistry, migrationRegistry })`** — four-way verdict mirroring the v0.7 freshness matrix: `bound` / `cosmetic_drift` / `drift` / `missing_endpoint`. Requires **both** registries because it compares each migration's provenance `from{Ir,Source}Hash` / `to{Ir,Source}Hash` against whatever the current schema registry reports for the two endpoint versions. Pure classifier; the CLI owns the filesystem reads. `bound` and `cosmetic_drift` are success-compatible (`cosmetic_drift` is warning-class on the success branch); `drift` and `missing_endpoint` are failure-class and carry stable metadata reasons.
+- **`stubMigration(opts)` + `suggestedMigrationPathFor(opts)`** — pure file-content generator emitting the JSDoc header + `import type { Migration } from "@nekostack/schema/cli"` + typed declaration + `transform(input) { throw "Not yet implemented"; }` body + default export. The slug rule is byte-compatible with v0.7's `suggestedPathFor`.
+- **Four pure handlers** — `listMigrationsHandler`, `planMigrationHandler`, `verifyMigrationsHandler`, `stubMigrationHandler`. Data-in / data-out; the schema package never touches the filesystem and never calls `.transform(...)`. Cross-handler purity gated by [`../tests/migrations/handler-purity.test.ts`](../tests/migrations/handler-purity.test.ts) (static-import scan + sentinel coverage).
+- **Integration subpath extension** — `@nekostack/schema/cli` exports the v0.8 surface alongside the v0.7 surface. Root `@nekostack/schema` retains the v0.6 contract unchanged; the negative-leakage gate in [`../tests/public-surface.test.ts`](../tests/public-surface.test.ts) extends to every v0.8 runtime + type name.
+
+v0.8 explicitly **does not** ship (this package, ever — these are hard-locked non-goals, not "later" items):
+
+- **Migration apply / runner / executor** — no verb on the schema side runs `transform(input)` against real data. Master plan Decision #2 (forward-only) and the [`MIGRATIONS.md`](./MIGRATIONS.md) non-goals table are the contract.
+- **Rollback / reverse migrations** — Decision #2 is forward-only.
+- **Cross-schema migrations** — Decision #4 — exactly one `schemaId` per authored migration.
+- **Multi-hop skip** — chain enumeration is required; the planner never silently bypasses intermediate versions.
+- **Database / DDL migrations** — `@nekostack/migrate`'s concern, not `@nekostack/schema`'s.
+- **Transform correctness proof** — the package never executes a migration's `transform`, so it has no opinion on whether the transform is correct. Verification covers provenance integrity only ("provenance says what it says"), not behavioral validity.
+- **Filesystem I/O, dynamic `import()` of migration modules, stdout/stderr, exit codes** — owned by `@nekostack/cli` (Master plan Decision #1 stays in force).
+
+**Top-level evaluation nuance** — authored migration files are TypeScript modules. When the CLI loads them via `tsx` (Step 19 of the v0.8 plan), their top-level code evaluates. The schema package itself never imports authored migration files and never triggers their evaluation; it sees them only as parsed provenance + opaque `Migration` records produced by the CLI loader. Authors who put side-effecting code at module top-level will pay for it inside the CLI, not inside the schema package.

package/docs/USAGE.md

@@ -0,0 +1,376 @@
+# Usage — `@nekostack/schema`
+
+> What v0.6 lets you do as an author, end-to-end. For the runtime contract, see [`RUNTIME.md`](./RUNTIME.md). For the why and the scope boundaries, see [`SCOPE.md`](./SCOPE.md). For the full surface, see [`../README.md`](../README.md).
+
+## What v0.6 is good for
+
+v0.6 is the phase where `@nekostack/schema` becomes the **runtime-validation workflow**, not just a code generator. From a single schema definition:
+
+1. **Validate input directly** via `parse` / `safeParse` / `validate` — no Zod import in your code.
+2. A **TypeScript type alias** matching the schema's runtime shape (with the v0.1 input/output split honored).
+3. A **Zod 3.x validator** as a portable artifact for interoperability (microservices that don't import `@nekostack/schema`, third-party tools, etc.).
+4. A **JSON Schema draft 2020-12** + **OpenAPI 3.1 component** for cross-language contracts and API documentation.
+5. A **deterministic header** on every generated file recording schema id, version, IR hash, and generator version.
+
+Zod is the internal execution engine for runtime validation. A consumer of `@nekostack/schema` does **not** import Zod for runtime validation; the surface is `parse` / `safeParse` / `validate` from `@nekostack/schema`. See [`RUNTIME.md`](./RUNTIME.md) for the full contract — including default semantics, unknown-key policies, issue normalization, and what the validate-only IR variant does. You **cannot** yet use this package for a CLI workflow (v0.7).
+
+## Defining a schema
+
+```ts
+import { s } from "@nekostack/schema";
+
+export const Tenant = s
+  .object({
+    id: s.string().uuid(),
+    slug: s.string().min(2).max(50).regex(/^[a-z0-9-]+$/),
+    name: s.string().min(1).max(120),
+    plan: s.enum(["free", "pro", "enterprise"] as const).default("free"),
+    billingEmail: s.string().email().nullable(),
+  })
+  .id("com.nekostack.tenant.Tenant")
+  .version("1.0.0")
+  .describe("A NekoStack workspace tenant.");
+```
+
+Three things every "real" schema should do, derived from v0.1:
+
+- Give it an `.id("com.org.area.Name")` — generators put it in the header; v0.7 will look it up here.
+- Give it a `.version("x.y.z")` — generators emit it; future breaking-change detection (v0.7) keys off it.
+- Give it a `.describe("...")` — generators emit it as JSDoc / Zod `.describe()`.
+
+Anonymous schemas (no `.id()`) work — generators emit `schemaId: null` with a visible `// anonymous schema` comment — but they're not registry-addressable.
+
+## Validating input at runtime
+
+```ts
+import { s, parse, safeParse, validate, ParseError } from "@nekostack/schema";
+import { Tenant } from "./tenant.schema.js";
+
+// Throw on failure — the friction-causing default.
+const tenant = parse(Tenant, input);
+//    ^ s.output<typeof Tenant> (defaults filled)
+
+// Return a Result instead of throwing.
+const r = safeParse(Tenant, input);
+if (r.success) {
+  r.data;          // s.output<typeof Tenant>
+} else {
+  r.issues;        // readonly Issue[]
+}
+
+// Structural check only — does NOT fill defaults, does NOT run transforms.
+const v = validate(Tenant, input);
+if (v.success) {
+  v.data;          // s.input<typeof Tenant> (default-bearing fields stay absent)
+}
+
+// ParseError carries the full normalized issue list.
+try {
+  parse(Tenant, input);
+} catch (e) {
+  if (e instanceof ParseError) {
+    for (const i of e.issues) {
+      // i.code         — stable NekoStack IssueCode
+      // i.path         — Zod path, copied
+      // i.expected/received — verbatim from Zod when available
+      // i.schemaId / i.schemaVersion — from schema.metadata when present
+      // i.severity     — always "error" in v0.6
+    }
+  } else {
+    throw e;
+  }
+}
+```
+
+Three things to know:
+
+- **`parse` / `safeParse` fill defaults.** `validate` accepts a missing default-bearing field but does **not** fill it. See [`RUNTIME.md` → Default semantics](./RUNTIME.md#default-semantics).
+- **Unknown keys are rejected by default.** The object policy is `strict`. Use `.passthrough()` to preserve them in the output, `.stripUnknown()` to drop them. Same behavior across `parse`, `safeParse`, and `validate`.
+- **Issues use a stable NekoStack vocabulary.** Consumers see `Issue` / `IssueCode` from `@nekostack/schema`, never a `ZodError`. The Zod engine is internal and may be replaced in a future phase without changing the consumer-facing contract. The full mapping table is in [`RUNTIME.md` → Issue normalization](./RUNTIME.md#issue-normalization).
+
+## Generating a TypeScript type
+
+```ts
+import { generateTypeScript } from "@nekostack/schema";
+import { Tenant } from "./tenant.schema.js";
+
+const ts = generateTypeScript(Tenant.node);
+// Returns a complete .ts module as a string: header + `export type Tenant = { ... };`
+```
+
+Output mode controls the input/output split:
+
+| `options.mode` | Emits | Use when |
+|---|---|---|
+| *(omitted)* / `"output"` | `export type <Name> = ...` | You want the post-default, post-transform type (matches `s.infer<T>` / `s.output<T>`). |
+| `"input"` | `export type <Name>Input = ...` | You're typing API request bodies / form values before defaults apply. |
+| `"both"` | `export type <Name>Input` + `export type <Name>Output` | You want both sides explicit. |
+
+The two sides genuinely differ for any schema with a `.default(v)` field — default-bearing fields are object-optional in Input, object-required in Output. See [`ABSENCE_SEMANTICS.md`](./ABSENCE_SEMANTICS.md) for the full table.
+
+`mode: "both"` is the safest default for shared API contracts.
+
+## Generating a Zod validator (as an artifact)
+
+> Since v0.6, generated Zod is an **interoperability artifact**, not your runtime path. Use `parse` / `safeParse` / `validate` for in-process validation; emit Zod source for downstream services or third-party tools that want to consume a portable Zod schema without importing `@nekostack/schema`.
+
+```ts
+import { generateZod } from "@nekostack/schema";
+import { Tenant } from "./tenant.schema.js";
+
+const zod = generateZod(Tenant.node);
+// Returns: header + `import { z } from "zod"` + `export const schema = z.object({...}).strict()...`
+```
+
+The emitted source and the runtime compiler share a single semantic mapping (Decision #6 of the v0.6 plan), so the generated Zod file and `parse(Tenant, input)` agree on accept/reject for every input. The four-oracle parity matrix in [`tests/semantic-parity.test.ts`](../tests/semantic-parity.test.ts) is what asserts that.
+
+Modifier ordering is fixed; see [`ZOD_MODIFIER_ORDERING.md`](./ZOD_MODIFIER_ORDERING.md). The headline rule: **default is always last**, so the v0.1 absence-semantics contract survives translation.
+
+Consumer of the generated file needs Zod installed; `@nekostack/schema` already depends on Zod for its own runtime, so no extra setup is needed for in-process validation.
+
+## Generating a JSON Schema
+
+```ts
+import { generateJsonSchema } from "@nekostack/schema";
+import { Tenant } from "./tenant.schema.js";
+
+const json = generateJsonSchema(Tenant.node);
+// Returns: a complete draft-2020-12 JSON document as a string.
+```
+
+Default `$id` is URN-shaped (`urn:nekostack:schema:<id>:<version>`). For URL-shaped IDs (when you actually host schemas at a real URL), pass `idBase`:
+
+```ts
+generateJsonSchema(Tenant.node, { idBase: "https://schemas.example.com" });
+// $id: "https://schemas.example.com/com.nekostack.tenant.Tenant/1.0.0"
+```
+
+Important properties:
+
+- **Models accepted input.** JSON Schema treats `default` as annotation, not behavior — validators don't fill defaults. The output represents what the wire input is allowed to look like; the runtime (or generated Zod) is responsible for applying defaults.
+- **`stripUnknown` is encoded as `additionalProperties: true` + `x-nekostack-strip: true`.** JSON Schema can't express mutation; the runtime strips. The extension key tells NekoStack-aware consumers to do that.
+- **Throws on semantic-loss cases.** Runtime refinements (custom predicates) and regex with non-empty flags throw `UnsupportedNodeKindError` rather than emit JSON Schema that changes validation behavior. See [`JSON_SCHEMA_MAPPING.md`](./JSON_SCHEMA_MAPPING.md) for the full contract.
+- **Provenance under `x-nekostack`.** JSON has no comment syntax, so the v0.2-style header is moved into a single `x-nekostack: { generator, generatorVersion, irHash, schemaId, schemaVersion }` object.
+
+Optional consumer dep: `ajv` (any version that supports draft 2020-12 — import via `ajv/dist/2020.js`). Not required to *generate*, only to *validate*.
+
+## Generating an OpenAPI 3.1 component schema
+
+```ts
+import { generateOpenApiSchemaComponent } from "@nekostack/schema";
+import { Tenant } from "./tenant.schema.js";
+
+const component = generateOpenApiSchemaComponent(Tenant.node);
+// Returns: canonical JSON for the value at `components.schemas.Tenant` in
+// an OpenAPI 3.1 document. Compose into your own document.
+```
+
+The output is a **component schema fragment**, not a full OpenAPI document. Paths / operations / responses / security schemes / etc. are not in scope for `@nekostack/schema` — they belong to a future `@nekostack/api` package.
+
+Differences from `generateJsonSchema`:
+- **No `$schema`** — OpenAPI 3.1 documents declare the schema dialect at the document root via `jsonSchemaDialect`; components inherit it.
+- **No `$id`** — component identity is the position in the document (`#/components/schemas/<Name>`).
+- **`x-nekostack.generator: "openApi"`** — distinguishes the artifact from JSON Schema output.
+
+Everything else (absence semantics, object policy, refinement mapping, throw behavior on runtime refinements + regex with flags, `x-nekostack-strip` / `x-nekostack-default-applied-by`) is **identical to JSON Schema** because both generators share the same internal fragment emitter. See [`OPENAPI_MAPPING.md`](./OPENAPI_MAPPING.md) for the delta table and [`JSON_SCHEMA_MAPPING.md`](./JSON_SCHEMA_MAPPING.md) for the full mapping.
+
+Optional consumer dep: `@redocly/openapi-core` (or any OpenAPI 3.1 validator) if you want to validate the composed document.
+
+## Composing existing object schemas
+
+```ts
+import { s } from "@nekostack/schema";
+
+const User = s.object({
+  id: s.string().uuid(),
+  email: s.string().email(),
+  role: s.string().default("member"),
+});
+
+// Common patterns:
+const UserInputForCreate = User.omit({ id: true });           // server fills id
+const UserPatch = User.partial();                              // PATCH/update shape
+const UserPublic = User.pick({ id: true, email: true });       // safe-to-expose subset
+const UserAdmin = User.extend({ permissions: s.array(s.string()) });
+const UserWithNumericId = User.override({ id: s.number() });
+```
+
+Seven operators are available on every `ObjectSchema`: `extend`, `pick`, `omit`, `partial`, `required`, `merge`, `override`. All return a new `ObjectSchema` (no mutation), fail loudly on conflicts / unknown keys / missing keys, drop top-level metadata (re-tag with `.id().version().describe()` if needed), and preserve field-level metadata. See [`COMPOSITION.md`](./COMPOSITION.md) for the full contract — especially:
+
+- **`partial()` and `required()` both strip `default`.** A partial schema should not silently inject defaults into a PATCH payload; a required + default-bearing field is semantically contradictory.
+- **`merge` throws on field conflict AND on `unknownKeys` mismatch by default.** Resolve explicitly via `{ conflict: "left" | "right" }` and `{ unknownKeys: "left" | "right" }`.
+- **`extend` and `override` are asymmetric on purpose** — `extend` rejects existing keys; `override` rejects missing keys. The pair covers add and replace without overlap.
+
+Composition produces a plain `ObjectNode` — no generator changes; the TS / Zod / JSON Schema / OpenAPI generators handle composed schemas identically to hand-written equivalents (asserted by parity tests).
+
+## Generated-file headers
+
+Every output file starts with a deterministic JSDoc block — full spec in [`HEADER_FORMAT.md`](./HEADER_FORMAT.md):
+
+```ts
+/**
+ * @generated by @nekostack/schema
+ * schemaId:         com.nekostack.tenant.Tenant
+ * schemaVersion:    1.0.0
+ * irHash:           sha256:7f3e2a9b...
+ * generator:        typescript
+ * generatorVersion: @nekostack/schema@0.7.0
+ *
+ * DO NOT EDIT MANUALLY.
+ */
+```
+
+Consumers may:
+- Read `irHash` to detect stale generated artifacts.
+- Read `schemaId` / `schemaVersion` to identify which schema this file represents.
+- Refuse to load files with an older `generatorVersion`.
+
+Consumers must NOT:
+- Edit a generated file by hand (CI may enforce later).
+- Parse data out of free-form comments — use the typed fields.
+
+## Computing `irHash` directly
+
+```ts
+import { irHash } from "@nekostack/schema";
+irHash(Tenant.node); // → "7f3e2a9b..." (64-char hex, sha256 of canonical IR serialization)
+```
+
+Same IR → same hash, every time. Semantic change → different hash. This is the foundation v0.7's CI freshness check uses; you can use it now to gate your own deploys ("if `irHash(latest) !== headerOf(committedFile).irHash`, regenerate").
+
+## Workflow today (no CLI yet)
+
+There is no `neko schema generate` command in v0.6, and the v0.7 CLI is in progress but not yet shipped — see [`ROADMAP.md`](./ROADMAP.md). The intended workflow until v0.7 lands:
+
+1. Author the schema in `your-package/schemas/foo.schema.ts`.
+2. **For runtime validation:** import `parse` / `safeParse` / `validate` from `@nekostack/schema` and call them directly. No generated artifact required.
+3. **For artifact generation** (cross-language contracts, microservice interop, documentation): write a script (or a vitest snapshot test — see this package's [`tests/examples/regenerate.test.ts`](../tests/examples/regenerate.test.ts) for a worked example) that calls `generateTypeScript` / `generateZod` / `generateJsonSchema` / `generateOpenApiSchemaComponent` and writes the result to disk.
+4. Commit both the source schema and any generated files.
+5. Review diffs as ordinary code review.
+
+Once v0.7's CLI ships, `neko schema generate` / `check` / `diff` / `list` replace the hand-written generation script and add freshness CI.
+
+## `@nekostack/schema/cli` — internal integration only (v0.7)
+
+> Not a public consumer API. This is the subpath `@nekostack/cli` imports from to build the v0.7 `neko schema *` commands.
+
+The v0.7 registry / freshness / generation primitives are reachable through a separate subpath:
+
+```text
+@nekostack/schema           public v0.6 consumer surface (parse, safeParse, validate, s, generators, …)
+@nekostack/schema/cli       package-internal CLI integration surface (buildRegistry, diffNodes, four handlers, …)
+```
+
+If you are writing application code or a library that uses `@nekostack/schema` directly, **do not** import from `@nekostack/schema/cli`. The names exposed there are subject to internal change between minor versions; engine-swap-safety lives at the root, not at this subpath. The negative gate in [`../tests/public-surface.test.ts`](../tests/public-surface.test.ts) enforces that root `@nekostack/schema` does not leak any v0.7 registry name.
+
+The subpath exists so the eventual `neko schema *` CLI (companion plan in [`../../cli/docs/PHASE_PLAN_v0.7.md`](../../cli/docs/PHASE_PLAN_v0.7.md)) has a stable, package-internal seam to import from. Full surface and contract in [`REGISTRY.md`](./REGISTRY.md); diff classification in [`DIFF_CLASSIFICATION.md`](./DIFF_CLASSIFICATION.md).
+
+## Schema-data migrations (v0.8 — in progress, preview only)
+
+> v0.8 is **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)), not yet shipped. The schema-side primitives below already exist on the branch; the CLI-side `neko schema migrate *` verbs are still being wired up. This section is a preview of the v0.8 workflow once it lands — the contract is locked in [`MIGRATIONS.md`](./MIGRATIONS.md).
+
+v0.8 lets you describe how to migrate **data** from one version of a schema to a newer version of the same schema. It ships planning, verification, and stub generation — it does **not** ship an apply verb, and the package never executes a migration's `transform(input)`. If you need to run a migration against real data, that lives in your own code or a downstream package.
+
+A migration is a TypeScript module under your package's migration directory. The locked file shape (Decision #5 + Decision #6) is the JSDoc-only nine-field provenance carrier emitted by `stubMigration`, an `import type { Migration } from "@nekostack/schema/cli"`, a typed declaration, and a default export:
+
+```ts
+/**
+ * @migration by @nekostack/schema
+ * schemaId:         com.nekostack.tenant.Tenant
+ * fromVersion:      1.0.0
+ * toVersion:        2.0.0
+ * fromIrHash:       sha256:<hex of the v1 IR>
+ * toIrHash:         sha256:<hex of the v2 IR>
+ * fromSourceHash:   sha256:<hex of the v1 schema source file's UTF-8 bytes>
+ * toSourceHash:     sha256:<hex of the v2 schema source file's UTF-8 bytes>
+ * 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";
+import type { TenantV1 } from "../generated/tenant-1.0.0.types.js";
+import type { TenantV2 } from "../generated/tenant-2.0.0.types.js";
+
+const migration: Migration<
+  "com.nekostack.tenant.Tenant",
+  "1.0.0",
+  "2.0.0",
+  TenantV1,
+  TenantV2
+> = {
+  schemaId: "com.nekostack.tenant.Tenant",
+  from: "1.0.0",
+  to: "2.0.0",
+  transform(input) {
+    return { ...input, /* v2 shape */ };
+  },
+};
+
+export default migration;
+```
+
+> **`fromSourceHash` / `toSourceHash` bind the *endpoint schemas'* source bytes**, not the migration file's own source hash. There is no per-migration-file `sourceHash` in the v0.8 header — the verifier compares `from{Ir,Source}Hash` and `to{Ir,Source}Hash` to whatever the schema registry currently reports for the two endpoint versions, so the migration stays anchored to a specific shape of both endpoints. The `Migration` object on disk uses the compact `from` / `to` keys; the `MigrationEntry` produced by `buildMigrationRegistry` exposes the same triple as `(schemaId, fromVersion, toVersion)` for index lookup.
+
+Three rules:
+
+- **One `schemaId` per migration** (Decision #4). A single migration may never straddle two schemas; split it.
+- **Forward-only** (Decision #2). `fromVersion` is always older than `toVersion`; no reverse module shape, no rollback.
+- **Fail-loud provenance.** All nine header fields are required. Missing or malformed headers fail with `code: "integrity_error"` and a stable `metadata.reason` — they are never silently skipped.
+
+Once v0.8's CLI ships, four verbs will mirror the v0.7 `neko schema *` shape:
+
+| Verb | What it does | Pure surface it consumes |
+|---|---|---|
+| `neko schema migrate list` | Enumerate authored migrations grouped by `(schemaId, fromVersion)` | `listMigrationsHandler` |
+| `neko schema migrate plan` | Compute the migration chain (or "none needed", or "over-specified") for a `(schemaId, fromVersion, toVersion)` path | `planMigrationHandler` (consumes BOTH schema and migration registries) |
+| `neko schema migrate verify` | Classify every authored migration as `bound` / `cosmetic_drift` / `drift` / `missing_endpoint` against the current schema registry | `verifyMigrationsHandler({ schemaRegistry, migrationRegistry })` (consumes BOTH registries — provenance hashes are compared to current endpoint-schema hashes) |
+| `neko schema migrate stub` | Generate a skeleton migration file (header + typed declaration + `transform(input) { throw "Not yet implemented"; }`) | `stubMigrationHandler` + `suggestedMigrationPathFor` |
+
+The schema package never walks the migration directory, never imports your authored migration modules, and never calls `.transform(...)` — those responsibilities all sit in `@nekostack/cli`. Master plan Decision #1 (schema is pure) stays in force; the migration handlers' purity is gated by [`../tests/migrations/handler-purity.test.ts`](../tests/migrations/handler-purity.test.ts).
+
+The contract details — provenance header field-by-field, planner severity dispatch table, verifier verdict matrix, schema/CLI ownership, non-goals — live in [`MIGRATIONS.md`](./MIGRATIONS.md).
+
+## Handling unsupported IR
+
+A `SchemaNode` whose kind isn't generator-ready throws `UnsupportedNodeKindError` with a stable shape. v0.3 extends the set with two new `kind` values: `"runtimeRefinement"` (from any generator) and `"regexFlags"` (JSON Schema only — regex with non-empty flags).
+
+```ts
+import { UnsupportedNodeKindError } from "@nekostack/schema";
+
+try {
+  generateZod(someExoticNode);
+} catch (e) {
+  if (e instanceof UnsupportedNodeKindError) {
+    // e.code      === "UNSUPPORTED_NODE_KIND"
+    // e.kind      === "date" | "union" | "recursiveRef" | "transform" | "runtimeRefinement" | "regexFlags"
+    // e.generator === "typescript" | "zod" | "jsonSchema" | "openApi"
+  }
+}
+```
+
+Runtime-only refinements (custom predicates added via a future `.refine(fn)` builder) also throw, intentionally. Generators that can't honor the validation must not silently emit code that omits it.
+
+For the JSON Schema generator specifically, regex with non-empty flags also throws (`kind: "regexFlags"`) — JSON Schema `pattern` has no flag support, and emitting source-only would silently drop case-insensitivity / unicode / etc.
+
+## What's still deferred (cross-reference to scope)
+
+| Want | Wait for | Why |
+|---|---|---|
+| Full OpenAPI document (paths/operations/responses/security/etc.) | `@nekostack/api` package | Schema package generates component schemas only |
+| OpenAPI 3.0 target (`nullable: true` form) | future generator option | v0.4 ships 3.1 only |
+| Deep / recursive composition (nested-field merge) | future | v0.5 ships shallow operators only |
+| Composition history (`metadata.derivedFrom`) | future | Could aid v0.7 diffing; not needed for v0.5 |
+| `neko schema generate / check / diff` CLI | v0.7 | Registry-lite phase |
+| Automatic CLI-populated `sourceHash` in committed artifacts | v0.7 CLI | Direct generator calls can already pass `sourceHash` via `ProvenanceOptions.sourceHash` — see the "Optional `sourceHash` provenance (v0.7+)" section in [`EXAMPLES.md`](./EXAMPLES.md). The CLI will compute it from source files automatically. |
+| `$defs` extraction / cross-package `$ref` | v0.7 (registry-lite) | No IR construct in v0.3 needs it |
+| Output-shape JSON Schema (default-applied, all fields required) | deferred | JSON Schema can't represent the input/output split as a single document |
+| Schema-data migrations: planning + verification + stub generation | v0.8 ([PR #28](https://github.com/cmclicker/NekoStack/pull/28), in progress) | See the v0.8 preview section above and [`MIGRATIONS.md`](./MIGRATIONS.md). |
+| **Executing** a schema-data migration's `transform(input)` | never in `@nekostack/schema` | Hard-locked non-goal of the v0.8 contract; the package owns planning + verification + stub generation only. If you need a runner, it lives in your own code or a downstream package. |
+| Database / DDL migrations | `@nekostack/migrate` | Always — `@nekostack/schema` migrations are schema-data only. |
+| Reverse / rollback migrations | not supported | v0.8 is forward-only (Decision #2). |
+| Date types (`isoDateTime` etc.) | future | IR exists; builders deferred |
+
+## Worked examples
+
+[`EXAMPLES.md`](./EXAMPLES.md) walks through the three example schemas in [`../examples/`](../examples/) and links each generated artifact. Read that next.

package/docs/ZOD_MODIFIER_ORDERING.md

@@ -0,0 +1,77 @@
+# Zod Modifier Ordering Contract
+
+> The fixed order in which `generateZod` applies modifiers to a Zod chain. This file is the contract; the implementation lives in [`../src/generators/zod.ts`](../src/generators/zod.ts).
+
+## Why ordering matters
+
+Zod modifier order changes input and output typing AND runtime acceptance behavior. `z.string().optional().default("x")` and `z.string().default("x").optional()` are NOT interchangeable. The v0.1 absence-semantics table is a contract; preserving it through generated Zod requires fixed ordering.
+
+## The order
+
+For any IR `SchemaNode`, the emitted chain is constructed in this exact sequence:
+
+1. **Base schema** — `z.string()`, `z.number()`, `z.boolean()`, `z.literal(...)`, `z.enum(...)` / `z.union(...)`, `z.array(...)`, `z.object({...})`.
+2. **Portable refinements** — each `kind: "portable"` entry of `node.refinements`, applied in IR insertion order. Examples: `.min(3)`, `.max(50)`, `.email()`, `.regex(...)`, `.int()`, `.gt()`, `.multipleOf()`. Runtime refinements are **not** skipped silently — they throw (see ["Runtime refinements"](#runtime-refinements) below).
+3. **Description** — `.describe(text)` if `node.metadata.description` is set.
+4. **Nullability** — `.nullable()` if `modifiers.nullable && !modifiers.optional`.
+5. **Optionality** — `.optional()` if `modifiers.optional && !modifiers.nullable`.
+6. **Nullish** — `.nullish()` if BOTH `modifiers.optional && modifiers.nullable`.
+7. **Default LAST** — `.default(value)` if `modifiers.default` is set.
+
+Steps 4 / 5 / 6 are mutually exclusive. Step 7 always comes last.
+
+## Runtime refinements
+
+Runtime refinements are **unsupported** in v0.2 generator output. They represent custom predicates only the runtime can evaluate; emitting Zod that omits them would silently accept inputs the IR intends to reject — a direct Invariant 7 violation.
+
+If a node contains any `kind: "runtime"` refinement, `generateZod` throws `UnsupportedNodeKindError` with:
+
+- `code: "UNSUPPORTED_NODE_KIND"`
+- `kind: "runtimeRefinement"`
+- `generator: "zod"`
+
+They are not emitted, not approximated, not skipped. Tests assert on the field shape (not message text). The same rule applies to `generateTypeScript`: a node carrying a runtime refinement represents validation intent the TS-only generator cannot guarantee, so it also throws.
+
+When runtime refinements become representable in some generator (likely never for JSON Schema/OpenAPI; possibly via an opt-in shape for Zod in a later phase), this section gets updated and the implementations relax in lockstep — never one without the other.
+
+## Object unknown-keys
+
+Applied to the base `z.object({...})` expression (effectively part of step 1), always explicit even though Zod's runtime default is `.strip()`:
+
+| IR `unknownKeys` | Emitted |
+|---|---|
+| `"strict"` | `.strict()` |
+| `"stripUnknown"` | `.strip()` |
+| `"passthrough"` | `.passthrough()` |
+
+## Worked examples
+
+| v0.1 builder call | Emitted Zod chain |
+|---|---|
+| `s.string()` | `z.string()` |
+| `s.string().min(3)` | `z.string().min(3)` |
+| `s.string().optional()` | `z.string().optional()` |
+| `s.string().nullable()` | `z.string().nullable()` |
+| `s.string().nullish()` | `z.string().nullish()` |
+| `s.string().default("x")` | `z.string().optional().default("x")` |
+| `s.string().min(3).email().optional()` | `z.string().min(3).email().optional()` |
+| `s.string().nullable().default("x")` | `z.string().nullish().default("x")` (see "Collapse rule" below) |
+| `s.string().describe("d").optional()` | `z.string().describe("d").optional()` |
+| `s.object({id: s.string()}).passthrough()` | `z.object({ id: z.string() }).passthrough()` |
+
+## Collapse rule
+
+v0.1's `.default()` sets `modifiers.optional = true` (because a defaulted field accepts missing input). When the user also calls `.nullable()`, the resulting IR has BOTH `optional` and `nullable` set, which step 6 collapses to `.nullish()`. So:
+
+- `s.string().nullable().default("x")` → `z.string().nullish().default("x")`
+- `s.string().nullish().default("x")` → `z.string().nullish().default("x")`
+
+Both produce **identical Zod runtime behavior** (accept null, accept undefined → default applies). The collapse is correctness-preserving, not a loss.
+
+## Required test matrix
+
+[`../tests/generators/zod-modifier-composition.test.ts`](../tests/generators/zod-modifier-composition.test.ts) asserts on the emitted chain string for each row. [`../tests/generators/zod-execution.test.ts`](../tests/generators/zod-execution.test.ts) loads the generated code into a real Zod runtime and verifies behavior matches the v0.1 absence-semantics table for the same eight rows.
+
+## Why a contract doc and not just code
+
+Future generators (JSON Schema v0.3, OpenAPI v0.4) face the same question: in what order do modifiers compose? The constraints differ (no runtime in JSON Schema — `default` is metadata, not behavior), but the contract approach must repeat: pick an order, document it, test it. This doc is the template.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nekostack/schema",
+  "version": "1.0.0",
+  "private": false,
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./cli": {
+      "types": "./dist/src/cli-integration.d.ts",
+      "default": "./dist/src/cli-integration.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "docs/*.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "peerDependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@redocly/openapi-core": "^1.34.0",
+    "@types/node": "^22.10.0",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "fast-check": "^3.19.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "zod": "^3.22.0"
+  }
+}