zopia 0.3.0 → 0.5.0

package/docs/02-targets.md

@@ -1,55 +0,0 @@
-# 🎯 Targets
-
-These are the **explicit, testable targets** of zopia. Every Phase 1 target maps
-to its governing document and automated release-gate coverage — see
-[Testing → Scenario matrix](11-testing.md).
-
-> ✅ **Complete** = implemented, documented, and covered by the release gate.
-> Deferred work is listed explicitly under [Roadmap → Phase 2](03-roadmap.md#-phase-2--breadth-v02x-).
-
-## 🔄 Conversion targets
-
-| # | 🎯 Target | Spec | Status |
-| --- | --- | --- | --- |
-| T-1 | **Convert Zod → JSON Schema** | [Conversions → Engine ①](06-conversions.md) | ✅ |
-| T-2 | **Convert JSON Schema → Zod** | [Conversions → Engine ②](06-conversions.md) | ✅ |
-| T-3 | **Convert OpenAPI → api docs** — Swagger 2.0 *and* OpenAPI 3.0/3.1 | [Conversions → Engine ③](06-conversions.md) | ✅ |
-| T-4 | **Convert api docs → OpenAPI** (the reverse direction) | [Conversions → Engine ④](06-conversions.md) | ✅ |
-
-## 📂 API docs targets
-
-| # | 🎯 Target | Spec | Status |
-| --- | --- | --- | --- |
-| T-5 | **Layout mode `directory`** — `api_docs/` + path segments as nested directories + a method-named directory at the last level + `index` file | [API docs format → directory mode](07-api-docs.md) | ✅ |
-| T-6 | **Layout mode `flat`** — `api_docs/` + one directory per API + method directory + `index` file | [API docs format → flat mode](07-api-docs.md#-mode--flat) | ✅ |
-| T-7 | **`index.ts` files are TypeScript** and fill **all practical content** of the endpoint (method, path, operationId, summary, description, tags, auth, content types, request, response, examples) using **`makeApiConfig()` from km-api** (the package's make function) | [API docs format → `index.ts` contract](07-api-docs.md#-the-indexts-contract) | ✅ |
-| T-8 | **Option `insertComponents: boolean`** — when `true`, components are written into `api_docs` as their own schema files; **default `false`** | [Components](08-components.md) · [Configuration](09-configuration.md) | ✅ |
-| T-9 | **Option `useComponentAsReference: boolean`** — endpoints import emitted components recursively; requires `insertComponents: true`; **default `false`** | [Components → option matrix](08-components.md) | ✅ |
-
-## 🔁 Reverse-conversion targets
-
-| # | 🎯 Target | Spec | Status |
-| --- | --- | --- | --- |
-| T-10 | **Reversible output** — the generated tree contains everything needed to regenerate the spec (paths, methods, schemas, metadata), guaranteed by the manifest | [API docs format → manifest](07-api-docs.md) | ✅ |
-| T-11 | **Round-trip stability** — `openapi → api docs → openapi` and `zod → JSON Schema → zod` converge: re-running the pipeline on its own output is a no-op (idempotent) | [Testing → round-trip tests](11-testing.md#-round-trip-property-tests) | ✅ |
-
-## 🏗️ Engineering targets
-
-| # | 🎯 Target | Spec | Status |
-| --- | --- | --- | --- |
-| T-12 | **JSDoc everywhere** — every exported function, type, constant, and class is documented (template + rules fixed) | [Standards → JSDoc standard](12-standards.md) | ✅ |
-| T-13 | **Tests in all scenarios** — Vitest suite covering the full scenario matrix (spec versions, ref graphs, modes, option combinations, zod features, edge cases), run with Bun | [Testing](11-testing.md) | ✅ |
-| T-14 | **Bun runs the project** — install, typecheck, test, coverage, CLI, and generated-TypeScript imports all work through one pinned-Bun gate | [Standards → Bun gate](12-standards.md#-bun-gate) | ✅ |
-| T-15 | **Standard documentation** — `docs/` directory with targets, roadmap, architecture, conventions; README links into it; beautiful, icon-based markdown | this document set · [Standards → Docs convention](12-standards.md#-docs-convention) | ✅ |
-| T-16 | **Quality bar** — pure, safe, clean code with descriptions; deterministic output; typed errors; no silent lossy conversions | [Standards](12-standards.md) | ✅ |
-| T-17 | **Changelog after commits** — `CHANGELOG.md` updated by every user-facing commit under `Unreleased` | [Standards → Changelog convention](12-standards.md#-changelog-convention) | ✅ |
-
-## 🗺️ Out of scope for the first phase
-
-> 📌 The reverse-conversion *capability* (T-4/T-10/T-11) **is** in the first
-> phase — it is part of the four targets above. What is deferred:
-
-- ~~📝 YAML spec input~~ → shipped in v0.2.x (D-16; `.yaml`/`.yml` files and inline YAML text reach the same normalized model as JSON)
-- 🔗 External (multi-file) `$ref`s → [Roadmap Phase 2](03-roadmap.md)
-- 🧩 Reusable **parameters / responses** as emitted components (Phase 1 emits `components.schemas` only) → [Roadmap Phase 2](03-roadmap.md)
-- ~~🖥️ `zopia validate` (spec linting)~~ → shipped in v0.3.x (S-89; [Roadmap Phase 3](03-roadmap.md)); incremental regeneration remains deferred

package/docs/03-roadmap.md

@@ -1,205 +0,0 @@
-# 🗺️ Roadmap
-
-zopia ships in phases. **Phase 0 is this documentation set** — the contracts
-are fixed before a line of code is written, so implementation never re-decides
-anything.
-
-## 🚦 Phase 0 — Documentation & standards ✅
-
-The standard documentation of the project:
-
-- 📚 `docs/` — overview, targets, roadmap, architecture, concepts, conversions,
-  api-docs format, components, configuration, usage, testing, standards
-- 🏠 `README.md` — project home with the documentation map
-- 📜 `CHANGELOG.md` — Keep-a-Changelog format + the "changelog after commits" rule
-- 🔐 `LICENSE` (MIT) · 🧹 `.gitignore`
-- 🔑 Key decisions **D-01 … D-15** recorded in [Standards](12-standards.md#-key-decisions)
-
-**Completed:** the documentation fixed the Phase 1 contracts before
-implementation; it now describes the implemented v0.1.0 behavior and deferred scope.
-
-## 🚀 Phase 1 — The four engines (v0.1.0) ✅
-
-**Released:** 2026-09-28. Everything in [Targets](02-targets.md) is marked ✅:
-
-- [x] ⚙️ Package scaffold — ESM `package.json` (Bun-first, zero direct runtime
-      dependencies; `zod` + `km-api ^0.4.1` peers from npm — D-15), strict `tsconfig`,
-      Vitest/V8, pinned Bun, and checked-in `bun.lock`
-- [x] ① **Engine 1** — `zodToJsonSchema()` on top of `z.toJSONSchema()`
-      ([rules](06-conversions.md))
-- [x] ② **Engine 2** — `jsonSchemaToZod()` recursive emitter
-      ([rules](06-conversions.md))
-- [x] ③ **Engine 3** — `openApiToApiDocs()` — normalize v2/v3 → operation IR
-      → render `directory` / `flat` trees of `index.ts` files
-      ([rules](06-conversions.md),
-      [format](07-api-docs.md))
-- [x] ④ **Engine 4** — `apiDocsToOpenApi()` — manifest-driven reverse
-      conversion to OpenAPI 3.0/3.1
-      ([rules](06-conversions.md))
-- [x] 🧱 Component options — `insertComponents`, `useComponentAsReference`,
-      nested references, and direct/mutual cycles ([rules](08-components.md))
-- [x] 📝 **YAML input** — owned deterministic YAML 1.2 core-schema parser,
-      `.yaml`/`.yml` paths and inline YAML text, anchors/aliases/merge keys,
-      stable `ZOPIA_SPEC_INVALID_YAML` ([rules](06-conversions.md#engine-③--openapi--api-docs), D-16)
-- [x] 🔗 **External `$ref`s** — same-folder references bundled inline for
-      spec file paths, byte-identical to inline twins ([rules](06-conversions.md#engine-③--openapi--api-docs), D-17)
-- [x] 📦 Manifest writer/reader — `.zopia-manifest.json` (D-06)
-- [x] ⚠️ **Warnings pipeline** — stable typed codes, exact JSON Pointer locations,
-      deterministic collection/callbacks, generated-code markers, and CLI stderr
-      reporting across engines ①–④ (R-144/R-408/D-12)
-- [x] ♻️ **Manifest staleness** — canonical source/config comparison, invalid and
-      incomplete-tree detection, source-located warnings, safe obsolete-artifact
-      pruning, and symlink-safe regeneration (R-741…R-743)
-- [x] 🔐 **Reverse security fallback** — manifest-authoritative requirements,
-      validated metadata, collision-safe deterministic bearer synthesis,
-      OpenAPI/Swagger representations, and operation-located warnings (R-656)
-- [x] 🛑 **Typed errors** — one immutable stable-code catalogue and `ZopiaError`
-      boundary across engines, manifests, generated-module imports, filesystem
-      operations, warnings, and CLI validation, with locations, hints, and causes
-      (R-141…R-143/R-404)
-- [x] 🔁 **Round-trip contract** — fixture-backed source-dialect identity across
-      Swagger 2.0 and OpenAPI 3.0/3.1, every layout/component mode, refs/cycles,
-      lossy-keyword overlays, path-item metadata, and byte-identical regeneration;
-      supported Zod ↔ JSON Schema pipelines converge after canonicalization
-      (T-10/T-11/R-409)
-- [x] ⌨️ **CLI contract** — strict `generate` / `reverse` grammar, complete option
-      mapping and help, isolated stdout/stderr channels, stable exit statuses,
-      trusted-tree disclosure, and direct/package execution ([usage](10-usage.md#-cli))
-- [x] 📸 **Golden generated-tree contract** — deliberate reproducible updates,
-      complete byte-for-byte tree comparisons in all canonical layouts, and
-      strict compilation against installed published `km-api@0.4.1`, including
-      `trace`, custom/default statuses, and extension media types (R-112/R-126)
-- [x] 📈 **Coverage gates** — V8 measures every source file; overall line/function
-      coverage is gated at 90%, branches at 85%, conversion engines at 95% lines,
-      and every source file at 80% lines, with omitted-file detection
-- [x] 🟣 **Bun gate** — pinned Bun 1.2.21, frozen `bun.lock` installation,
-      typecheck, Vitest, coverage, direct/package CLI smoke tests, and Bun-native
-      generated-TypeScript reverse imports run through one command (T-14/D-01)
-- [x] 🧪 **Vitest suite** — unit, integration, round-trip, golden-tree, JSDoc,
-      CLI, and package-release contracts run in the pinned Bun gate
-      ([testing](11-testing.md))
-- [x] 📖 **JSDoc audit** — every exported declaration and exposed interface/class
-      member has a useful summary; public callables document parameters and return
-      values; optional configuration fields state defaults; examples and links are
-      checked; and named-only exports are enforced by an AST contract suite (T-12,
-      R-131…R-135/R-1003)
-- [x] 📦 **Package/release readiness** — public npm metadata, an allowlisted
-      source archive, executable CLI, isolated packed-consumer import and CLI
-      smoke tests, and a mandatory prepublish gate (R-191…R-193)
-- [x] 📚 **Documentation status sync** — current module/test layouts, generated
-      examples, Phase 1 completion labels, and deferred boundaries agree with
-      the implementation and are guarded by a documentation contract test
-- [x] 📜 First versioned entry in `CHANGELOG.md` → **v0.1.0**
-
-### ✅ Definition of done — Phase 1 (met)
-
-The v0.1.0 release satisfies all of the following:
-
-1. 📄 `bun run test` is green — unit + integration + round-trip suites
-2. 📈 Coverage gates are met (see [Testing → Coverage gates](11-testing.md#-coverage-gates))
-3. 🔁 Round-trip: for every fixture spec, `openapi(docs(spec))` equals `spec` after canonicalization
-4. 🧩 All four engine docs sections are implemented exactly as specified (mapping tables are the contract)
-5. 📖 Every public symbol has JSDoc; `tsc --noEmit` (strict) passes
-6. 📜 `CHANGELOG.md` v0.1.0 entry exists and `README` status banner is updated
-7. ✅ **km-api dependency gate** (D-15) — `km-api@0.4.1` is published and zopia
-   uses `km-api: ^0.4.1` from npm; no Git submodule or unpublished commit remains.
-   The dependency remains installed and type-checkable in every release gate.
-
-## 🧰 Phase 2 — Breadth (v0.2.x) ✅
-
-- 📝 **YAML input** — ✅ accept `swagger.yaml` / `openapi.yaml` (D-13 lifts → D-16)
-- 🔗 **External `$ref`s** — ✅ resolve references to other files in the same folder (D-17)
-- 🧩 **Reusable parameters & responses** — ✅ emitted as their own component
-  files `components/parameters/<Name>/index.ts` and
-  `components/responses/<Name>/index.ts` with `<Name>Parameter` / `<Name>Response`
-  exports, kind barrels, manifest `kind` entries, and a reverse conversion that
-  refreshes declarations from the modules while restoring every use-site `$ref`
-  verbatim (D-18; km-api has no standalone-parameter concept, so modules hold the
-  derived schema only — name/location/`required` remain operation data)
-- 🧾 **`zopia.config.ts`** — ✅ project-level config file with working-directory
-  discovery, explicit `--config` paths, validated `{ generate, reverse }` defaults,
-  and stable precedence CLI flag > config value > built-in default (D-19);
-  CLI flags stay available
-- 📤 **OpenAPI 2.0 output** — ✅ engine ④ accepts `version: '2.0'` (CLI
-  `--version 2.0`, config `reverse.version`) and downgrades 3.x-sourced
-  manifests into Swagger 2.0 documents: `nullable` becomes `x-nullable`,
-  `requestBody` becomes `body`/`formData` parameters, `components` becomes
-  top-level `definitions`/`parameters`/`responses`, `servers` decomposes into
-  `host`/`basePath`/`schemes`, and unrepresentable 3.x features (webhooks,
-  `jsonSchemaDialect`, cookie params, `links`, multi-flow OAuth2, …) drop with
-  deterministic `ZOPIA_WARN_DIALECT_DOWNGRADE` warnings (D-20)
-- 🧪 **More JSON Schema keywords** — ✅ `propertyNames` graduates from the D-12
-  approximation to native conversion: the exact
-  `{ type: 'object', propertyNames: { type: 'string', <pattern/length constraints> }, additionalProperties: <schema> }`
-  form now converts to `z.record(key, value)` (and back) with no warning or
-  frozen overlay (D-22); every other listed keyword keeps its runtime-refinement
-  + frozen-overlay round-trip (`patternProperties`, `if/then/else`,
-  `minProperties/maxProperties`, non-native `propertyNames` forms, `contains`) (Phase 1: documented approximation + warning, D-12)
-- 🪝 **3.1 webhook endpoint generation** — ✅ `document.webhooks` operations now
-  generate real endpoint files under `webhooks/<name>/<method>/index.ts`
-  alongside path operations (D-23). The manifest records `webhooks[]` entries
-  with the same reference/overlay/security metadata as path endpoints plus
-  `webhookOrder` and a `webhooksOverlay` (item-level metadata, `x-` names, and
-  operation-less items stay verbatim), so engine ④ reassembles webhooks in exact
-  source order for 3.1 output and omits them with source-located
-  `ZOPIA_WARN_WEBHOOKS` warnings for 3.0/2.0 output. Operation-less webhook maps
-  keep the Phase 1 manifest-only behavior (no endpoint files, forward warning)
-- 👀 **Watch mode** — ✅ `zopia generate --watch` regenerates whenever the spec
-  file changes (S-88): an immediate initial run, 50 ms-coalesced re-runs that
-  serialize against in-flight generation, run errors printed to stderr while
-  watching continues, and abort/cleanup on exit. Uses `fs.watch` with the
-  existing stale-tree/prune pipeline, so spec edits refresh owned files in place
-
-## 🌌 Phase 3 — Ecosystem (v0.3+) ✅
-
-- 🧹 **`zopia validate`** — ✅ CLI command + `validateZopia()` API lint specs
-  and generated trees (S-89): specs are checked for dialect validity, broken
-  local `$ref`s, endpoint-planning failures (name collisions, cross-namespace
-  duplicate operationIds), and components unreachable from any operation
-  (transitive; Swagger `definitions` included). Generated trees are checked for
-  manifest presence/validity, a successful reverse dry-run, and km-api peer
-  drift. Findings are deterministic sorted diagnostics with stable
-  `ZOPIA_VALIDATE_*` lint codes; the CLI prints them on stdout and exits `1`
-  when any error-severity finding exists
-- ♻️ **Incremental regeneration** — ✅ unchanged generated files keep their
-  mtimes (byte-identical regeneration writes nothing); the opt-in merge-safe
-  custom layer (D-24, S-90) exports a `custom` companion namespace per
-  endpoint/webhook scaffolded once and never overwritten (`--custom`,
-  `generate.custom`, or the `custom` generate option)
-- 🔍 **Diff tool** — ✅ `zopia diff old.json new.json` + `diffOpenApiSpecs()`
-  API (S-91): semantic comparison of dialect, info, endpoints (with
-  parameter/request-body/response details), webhooks, schema components,
-  document fields, and `x-` extensions; key order is ignored; deterministic
-  `+`/`-`/`~` human-readable lines with a summary; differences are data on
-  stdout, so the CLI exits `0` for changed pairs
-- 🧩 **Presets** — ✅ split-generation layouts (S-92): `--preset multi-tag`
-  routes each operation by its primary tag, `--preset multi-server` by the
-  effective first server (repeatedly), producing one independently
-  reverse-convertible api-docs sub-tree per bucket; untagged/default-server
-  operations land in `untagged`/`https-default-server`-style buckets; nothing
-  to split → the normal single tree. Programmatic `preset` option plus
-  `generate.preset` configuration; `planPresetBuckets()` exposes the pure
-  deterministic planner (collision-safe slugs, `ZOPIA_WARN_PRESET_PRIMARY_TAG`
-  on multi-tagged operations) and results report `trees[]`
-- 🧑‍💻 **VS Code extension** — ✅ navigate spec ↔ generated code both ways
-  (S-93): manifest-driven navigation core (`loadNavigationIndex`,
-  `specToLocations`/`treeToSpecLocation`, one-pass JSON
-  `specPointersToLines`/`specPointerAtLine` cursor resolution, YAML
-  operationId fallback) plus the `zopia navigate` CLI (`--to-code` /
-  `--to-spec`) and a plain-JS extension package under `editors/vscode/`
-  resolving the workspace's own zopia install
-
-## 🧮 Versioning
-
-SemVer, strictly:
-
-| 🔖 Bump | When |
-| --- | --- |
-| `MAJOR` | A generated-file format or manifest format breaks (`zopia:manifest@1` → `@2`) |
-| `MINOR` | New option, new engine feature, new CLI flag — backward compatible |
-| `PATCH` | Bug fixes, doc corrections, mapping-table clarifications |
-
-## 🔗 Next
-
-- 🎯 The exact list of what Phase 1 builds → [Targets](02-targets.md)
-- 🏗️ How the pieces fit → [Architecture](04-architecture.md)

package/docs/04-architecture.md

@@ -1,345 +0,0 @@
-# 🏗️ Architecture
-
-This document describes **how zopia v0.1.0 is built**: module layout, conversion
-pipeline, stage-specific representations, reference handling, and the
-error/safety model. Code and documentation change together; disagreement is a
-release-blocking defect under the
-[docs convention](12-standards.md#-docs-convention).
-
-## 🧩 Module layout
-
-```text
-.                              # 📦 repository root
-├── bin/zopia.js                # ⌨️ npm executable; launches the Bun CLI
-├── src/
-│   ├── index.ts                # 🚪 public named-export surface
-│   ├── cli.ts                  # ⌨️ process entry point
-│   ├── cli-command.ts          #    strict parser, help, output/exit contract
-│   ├── config.ts               # 🧾 zopia.config.ts discovery, trusted import, validation (D-19)
-│   ├── errors.ts               # 🛑 typed error catalogue
-│   ├── warnings.ts             # ⚠️ structured warning pipeline
-│   ├── validation.ts           # 🧹 zopia validate lint batteries (specs + generated trees, S-89)
-│   ├── diff.ts                 # 🔍 zopia diff semantic spec comparison (S-91)
-│   └── conversions/
-│       ├── zod-to-json-schema.ts       # ① Zod → JSON Schema
-│       ├── json-schema-to-zod.ts       # ② JSON Schema → Zod
-│       ├── yaml.ts                     #    owned YAML 1.2 core-schema parser (D-16)
-│       ├── openapi.ts                  #    dialect/envelope normalization
-│       ├── openapi-ref.ts              #    local JSON Pointer resolution
-│       ├── openapi-external-ref.ts     #    same-folder external $ref bundling (D-17)
-│       ├── openapi-to-api-docs.ts      #    operation collection
-│       ├── openapi-ir.ts               #    operation-level generation IR
-│       ├── openapi-contracts.ts        #    request/response extraction
-│       ├── api-docs-layout.ts          #    directory/flat path mapping
-│       ├── api-docs-plan.ts            #    collision-safe file planning
-│       ├── api-docs-facade.ts          #    ergonomic access-path helper
-│       ├── api-docs-generate.ts        # ③ rendering + guarded writes
-│       ├── openapi-to-api-docs-public.ts # public Engine ③ wrapper
-│       ├── api-docs-presets.ts         #    split-generation bucket planner (S-92)
-│       ├── api-docs-navigation.ts      #    spec ↔ tree navigation index (S-93)
-│       ├── manifest-writer.ts          #    canonical manifest contract
-│       ├── manifest-staleness.ts       #    drift/ownership cleanup
-│       ├── manifest-to-openapi.ts      # ④ trusted import + reconstruction
-│       └── reverse-security.ts         #    reverse security fallback
-├── tests/                       # 🧪 focused, integration, contract, round-trip
-├── scripts/                     # 🟣 coverage, golden, package, release gates
-└── docs/                        # 📖 this documentation
-```
-
-`km-api@^0.4.1` is consumed from npm as a peer and development dependency
-(D-15). Generated endpoint files and the golden typecheck use that published
-surface directly; there is no vendored copy or package swap remaining.
-
-YAML input (v0.2.x, D-16) is parsed by the owned, deterministic parser in
-`src/conversions/yaml.ts` (YAML 1.2 core-schema scalars, block/flow
-collections, quoted and block scalars, anchors/aliases/`<<` merge keys,
-single-document streams). It stays pure (P-3) and adds no runtime dependency
-(D-11); every rejection is a typed `ZOPIA_SPEC_INVALID_YAML`.
-
-File-path inputs additionally resolve **same-folder external `$ref`s** before
-normalization (v0.2.x, D-17): `src/conversions/openapi-external-ref.ts` bundles
-references like `other.yaml#/pointer` (plus `other.json`/`other.yml`/`./…`
-spellings and whole-file targets) inline, with each sibling file read once
-(P-1), bundled content deep-cloned, and nested cross-file references resolved
-against their owning file. Targets outside the spec folder (URLs, absolute
-paths, `../`, subdirectories) still fail with `ZOPIA_REF_EXTERNAL`, exactly
-like external references in non-file inputs.
-
-> 📏 Production modules use `kebab-case.ts`; `src/index.ts` is the package-root
-> re-export surface. Focused and integration tests live under `tests/`, with
-> dedicated `tests/contract/` and `tests/roundtrip/` suites. See
-> [Standards → Naming](12-standards.md#-naming).
-
-## 🔄 The pipeline
-
-Conversion work is split between in-memory transforms and explicit adapters.
-Engines ①/② are in-memory; the public engine ③/④ wrappers own documented file
-reads, guarded generated-tree writes, trusted module imports, and warning
-collection. Process arguments/output remain in the CLI.
-
-```mermaid
-flowchart TB
-  subgraph IN ["③ OpenAPI → api docs"]
-    A["object · JSON/YAML text · .json/.yaml path"] --> B["normalizeOpenApiDocument()"]
-    B --> C["collectOpenApiOperations()"]
-    C --> D["buildOpenApiOperationIR() + extractOperationContracts()"]
-    D --> E["planApiDocsFiles()"]
-    E --> F["render endpoints/components"]
-    F --> G["createZopiaManifest()"]
-    G --> H["guarded writes + stale-owned cleanup"]
-    H --> I["📂 api_docs/**"]
-  end
-
-  subgraph OUT ["④ api docs → OpenAPI"]
-    J["📂 api_docs/**"] --> K["validate manifest + owned paths"]
-    K --> L["trusted import of endpoint/component .ts"]
-    L --> M["runtime Zod → schema serialization"]
-    M --> N["apply refs + manifest overlays"]
-    N --> O["dialect translation + canonical document"]
-  end
-```
-
-The manifest boundary in `src/conversions/manifest-writer.ts` separates pure,
-detached snapshot construction and canonical validation/serialization from
-atomic filesystem output. Engine ③ records source facts that generated Zod or
-km-api values cannot carry; engine ④ combines those snapshots with imported
-runtime values so developer edits remain authoritative where representable.
-
-Round-trip stability does not depend on one repository-wide `ApiModel`. The
-implemented boundaries use a validated document envelope, an operation-level
-IR for generation, normalized operation contracts, and the versioned manifest
-for reverse reconstruction. Each shape is narrower than the stage that consumes
-it, and fixture properties verify their composition (T-11/R-409).
-
-## 🧬 The internal representations
-
-The implementation uses stage-specific public shapes rather than one oversized
-model. The generation path starts with the validated source envelope:
-
-```ts
-interface NormalizedOpenApiDocument {
-  document: OpenApiDocument;
-  version: '2.0' | '3.0' | '3.1';
-  title?: string;
-  versionString?: string;
-}
-```
-
-Each collected operation is then narrowed to the data endpoint rendering needs:
-
-```ts
-interface OpenApiOperationIR {
-  path: string;
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'TRACE';
-  pathShape: string;
-  operationId: string;
-  summary?: string;
-  description?: string;
-  tags: string[];
-  deprecated: boolean;
-  security?: unknown[];
-  operation: Record<string, any>;
-  parameters: any[];
-  document: OpenApiDocument;
-}
-
-interface OperationContracts {
-  parameters: Array<{
-    name: string;
-    in: 'path' | 'query' | 'header' | 'cookie';
-    required: boolean;
-    schema?: unknown;
-  }>;
-  requestBody?: { contentType: string; schema?: unknown; required: boolean };
-  responses: Array<{
-    status: string;
-    description: string;
-    contentType?: string;
-    schema?: unknown;
-  }>;
-}
-```
-
-Reverse conversion is anchored by `ZopiaManifest`, not by a hidden in-memory
-model. It records source dialect/frame metadata, generated file ownership,
-operation snapshots, component schemas, source path order/empty Path Items,
-explicit schema-container presence, local-reference placements, and restoration
-overlays. Current writer shapes are validated before serialization;
-the reader retains explicit compatibility allowances for older optional fields.
-
-### 🔁 Canonical order (determinism, P-1)
-
-| 📦 Where | 📏 Order |
-| --- | --- |
-| collected operations | source path order; fixed method order `get, post, put, delete, head, options, patch, trace` |
-| public generated-file result | lexical order by portable relative `path` |
-| runtime schema properties | document order (JSON object key order of the source) |
-| generated TypeScript schema maps/literal-object keys | lexical order (reverse restores source `required` order only while membership is unchanged) |
-| OpenAPI output document | `openapi, info, servers, security, tags, paths, components, externalDocs` |
-| path keys inside `paths` | sorted by path string |
-
-> 📌 **Rule R-401** — anywhere zopia *creates* a list or object, the order above
-> applies. Anywhere zopia *mirrors* source data (runtime properties, params),
-> the source order applies. Generated TypeScript canonicalizes schema-map and
-> literal-object keys so parsing a canonical manifest cannot change the next
-> generated tree. No `Date.now()`, no `Math.random()` anywhere in the package
-> (P-1). Value-level normalizations (Zod sentinel bounds, const-union →
-> `enum`, the `io` input/output split for `required`/`default`) live with the
-> engines that apply them — see
-> [Conversions → R-615 / R-618 / R-654](06-conversions.md).
-
-## 🔗 The reference graph
-
-`$ref` is a graph, and it can cycle (e.g. `Comment.replies → Comment`):
-
-```mermaid
-flowchart LR
-  Post["📄 Post"] -->|"$.ref #/components/schemas/Author"| Author["👤 Author"]
-  Author -->|"$.ref #/components/schemas/Address"| Address["📍 Address"]
-  Comment["💬 Comment"] -->|"$.ref #/components/schemas/Comment"| Comment
-```
-
-**Implemented flow** (`openapi-ref.ts`, generation, and manifest modules):
-
-1. 🧷 **Bundle external refs** (file inputs only, D-17) — resolve same-folder
-   external references inline first so every later step sees one document.
-2. 🛑 **Preflight** — walk source values, reject remaining external refs,
-   validate local pointer escapes, and report missing targets with exact
-   locations.
-3. 🔗 **Resolve operation refs** — path-item and parameter chains use per-chain
-   seen sets, so malformed and circular non-schema references fail explicitly.
-4. 🧩 **Collect component dependencies** — rendering finds schema-component
-   targets while excluding literal/example data that merely contains `$ref` text.
-5. 🧵 **Render schemas** — engine ②'s local-definition state and component
-   dependency reachability detect recursive edges; self and mutual cycles become
-   `z.lazy()` references.
-6. 📦 **Record identity** — the manifest stores original reference placements;
-   reverse conversion combines those records with imported runtime schema
-   identity to restore local `$ref`s.
-
-> 📌 **Rule R-402** — circular schema components remain executable through
-> `z.lazy()`, while linear refs become direct references/imports. **Scope:**
-> graph nodes are schema components only. Reusable non-schema objects (Swagger
-> 2.0 global `parameters`/`responses`, OpenAPI 3
-> `components.parameters`/`responses`) *also* get their own component modules in
-> components mode (v0.2.x — D-18): a module holds only the declaration's derived
-> schema, and in-source declarations plus use-site `$ref` placements restore
-> verbatim on reverse conversion while the declaration refreshes from the
-> current module. Bare `$ref` use sites import from the per-kind barrels; merged
-> `$ref`-sibling forms still resolve at use sites for generated runtime configs.
-
-## 🧮 Schema reuse within generated files
-
-Default mode keeps every endpoint self-contained: each request/parameter/response
-schema occurrence is rendered in place. Engine ② may build a local-definition
-closure inside an expression when resolving `$defs` or inlined component refs;
-it does not hoist structurally identical endpoint contracts into shared top-level
-constants.
-
-> 📌 **Rule R-403** — schema reuse is explicit, not inferred from structural
-> equality. Default mode independently inlines each contract occurrence. With
-> `useComponentAsReference: true`, each referenced component export is imported
-> at most once per endpoint and reused wherever that identity occurs.
-
-## 🛑 Error model
-
-All errors crossing a zopia boundary extend one base class — **no raw `Error`, no thrown strings** (standards → Errors). `ZOPIA_ERROR_CODES` is the immutable runtime catalogue and the source of the `ZopiaErrorCode` union; `isZopiaError()` narrows unknown failures and `asZopiaError()` preserves an existing typed error or attaches a lower-level failure as `cause`.
-
-```ts
-export class ZopiaError extends Error {
-  /** 🆔 Stable machine-readable code, e.g. 'ZOPIA_REF_NOT_FOUND'. */
-  readonly code: ZopiaErrorCode;
-  /** 📍 JSON-pointer, option name, or file location, when discoverable. */
-  readonly at?: string;
-  /** 💡 Actionable, human-readable suggestion (always populated). */
-  readonly hint: string;
-  /** 🔗 Original parser, import, or filesystem failure, when translated. */
-  readonly cause?: unknown;
-}
-```
-
-| 🆔 Code | 📍 Where | 💥 When | 💡 Hint pattern |
-| --- | --- | --- | --- |
-| `ZOPIA_CONFIG_INVALID` | public options / CLI | an argument, option, or option combination is invalid | "correct the invalid option or argument" |
-| `ZOPIA_DOCS_IMPORT_FAILED` | engine ④ | generated modules cannot load, export one expected value, or serialize edited runtime schemas | "fix or regenerate the affected generated module" |
-| `ZOPIA_DOCS_MANIFEST_MISMATCH` | engine ④ preflight | a manifest-owned endpoint/component file is missing, renamed, or not a regular file | "regenerate the tree or restore its generated files" |
-| `ZOPIA_DOCS_MISSING_MANIFEST` | engine ④ entry | no `.zopia-manifest.json` exists at the selected path | "generate api docs first or pass the manifest path" |
-| `ZOPIA_FS_OUTSIDE_OUTDIR` | generation guard | a generated path escapes `outDir` or traverses an unsafe ancestor | "keep generated paths inside the output directory" |
-| `ZOPIA_FS_WRITE_FAILED` | writers / CLI | output inspection, directory creation, cleanup, or writing fails | "check the output path, permissions, and available disk space" |
-| `ZOPIA_MANIFEST_INVALID` | manifest writer/reader | manifest JSON or metadata violates `zopia:manifest@1` | "regenerate the manifest or fix its invalid metadata" |
-| `ZOPIA_REF_EXTERNAL` | external-ref bundling / reference validation | `$ref` escapes the spec folder, or a non-file input points to another file | "keep external targets next to the spec file" |
-| `ZOPIA_REF_NOT_FOUND` | reference validation | a local `$ref` is malformed, circular where unsupported, or unresolved | "check that the local JSON Pointer target exists" |
-| `ZOPIA_SCHEMA_INVALID` | engines ①/② | the Zod or JSON Schema input cannot be converted | "provide a valid Zod or JSON Schema value" |
-| `ZOPIA_SPEC_INVALID` | OpenAPI validation | the parsed document violates the supported Swagger/OpenAPI shape | "fix the invalid Swagger/OpenAPI document" |
-| `ZOPIA_SPEC_INVALID_JSON` | JSON entry points | source text is unreadable or not valid JSON | "provide readable, valid JSON" |
-| `ZOPIA_SPEC_INVALID_YAML` | YAML entry points | source text is unreadable, malformed/unsupported YAML, or holds a non-JSON value | "provide readable, valid YAML" |
-| `ZOPIA_SPEC_MISSING_PATHS` | normalizers | the document has no object-valued `paths` | "add a paths object" |
-| `ZOPIA_SPEC_PATH_REF` | operation collection | a path-item reference is invalid or circular | "use a valid local path-item reference" |
-| `ZOPIA_SPEC_UNSUPPORTED_VERSION` | normalization | neither Swagger 2.0 nor OpenAPI 3.0/3.1 is selected | "use Swagger 2.0, OpenAPI 3.0, or OpenAPI 3.1" |
-| `ZOPIA_WARNING_INVALID` | warnings pipeline | a warning iterable/code/location/message is malformed | "provide a valid warning code, location, and message" |
-
-> 📌 **Rule R-404** — every error is thrown as a `ZopiaError` with a stable
-> code, a location (`at`) when discoverable, and a `hint`. Tests assert on
-> `code`, never on message text.
-
-## ⚠️ Warning model
-
-Warnings are non-fatal conversion diagnostics. Every public engine uses the
-same `ZopiaWarning` contract and stable `ZopiaWarningCode` union:
-
-```ts
-interface ZopiaWarning {
-  code: ZopiaWarningCode;
-  at?: string;       // escaped RFC 6901 JSON Pointer, including leading #
-  message: string;
-}
-```
-
-| 🆔 Stable code | 📝 Meaning |
-| --- | --- |
-| `ZOPIA_WARN_UNREPRESENTABLE` | a Zod node cannot be represented in the selected schema dialect |
-| `ZOPIA_WARN_INVALID_SCHEMA` | a malformed JSON Schema keyword is ignored or approximated |
-| `ZOPIA_WARN_CUSTOM_FORMAT`, `ZOPIA_WARN_CONTENT_ENCODING`, `ZOPIA_WARN_INT64` | a string/numeric format or encoding has no exact runtime equivalent |
-| `ZOPIA_WARN_LEGACY_EXCLUSIVE_BOUND` | a legacy boolean exclusive bound requires normalization |
-| `ZOPIA_WARN_ONE_OF`, `ZOPIA_WARN_NOT`, `ZOPIA_WARN_UNIQUE_ITEMS`, `ZOPIA_WARN_FROZEN_SUBTREE` | an applicator or refinement needs an approximation or frozen manifest restoration |
-| `ZOPIA_WARN_REF` | a recoverable schema-reference conversion cannot be exact |
-| `ZOPIA_WARN_MULTI_CONTENT`, `ZOPIA_WARN_SERVER_VARIABLES`, `ZOPIA_WARN_WEBHOOKS` | an OpenAPI document fact has no direct generated-code representation |
-| `ZOPIA_WARN_STALE_TREE` | regeneration found source/config drift, missing owned files, manifest disablement, or invalid existing metadata |
-| `ZOPIA_WARN_DEFAULT_INFO`, `ZOPIA_WARN_DEFAULT_SECURITY` | reverse conversion synthesized documented fallback metadata or security |
-| `ZOPIA_WARN_DIALECT_DOWNGRADE` | OpenAPI 3.1-only content is omitted from 3.0 output |
-
-The shared collector validates codes, collapses line breaks in messages,
-deduplicates identical diagnostics, and sorts by location, code, then message.
-Nested engine warnings are rebased rather than string-concatenated ad hoc, so
-`at` always identifies the affected source or output node. Engine ① and engine
-④ invoke `onWarning` once per normalized warning; engines ②–④ also return
-normalized warning arrays. Engine ② mirrors losses with the canonical marker
-`// @zopia:warn CODE subject — message (pointer)`. The CLI renders the same
-warning as `Warning: CODE pointer: message` on **stderr**, leaving reverse JSON
-on stdout parseable.
-
-## 🛡️ Safety & boundaries
-
-| # | Rule | Where enforced |
-| --- | --- | --- |
-| R-405 | **Pure core** — schema/operation transforms work on in-memory values; documented file input, generated-tree writes/imports, and process output stay in public adapters and the CLI | conversion modules + `cli-command.ts` |
-| R-406 | **outDir guard** — every generated path is canonicalized and verified to stay inside `outDir`; regeneration refuses symlinked path ancestors, and manifest temporary writes use exclusive creation so stale symlinks cannot redirect output. Obsolete cleanup trusts only a fully validated manifest and never recursively deletes an output root | `api-docs-generate.ts` + manifest boundaries |
-| R-407 | **Trusted-input contract** — engine ④ imports generated `.ts` files (executes them). This is by design (D-08) and only for trees that carry a valid zopia manifest | `manifest-to-openapi.ts` |
-| R-408 | **No silent loss** — every lossy/unsupported conversion produces a normalized `ZopiaWarning` (D-12): `{ code, at?, message }` (shape fixed by R-144). Public wrappers return or callback each warning; engine ② and generated api-doc files mirror schema warnings as canonical `// @zopia:warn …` comments; CLI diagnostics go only to stderr | every engine + CLI |
-| R-409 | **Idempotent regeneration** — re-running engine ③ with identical input + options produces byte-identical output; regenerating source-preserving engine ④ output does too. Fixture properties cover Swagger 2.0 and OpenAPI 3.0/3.1 across layout/component modes, while stale source/config/incomplete-tree state is warned and repaired and only obsolete manifest-owned files are pruned; engine ④ output is canonical (R-401) | round-trip + staleness tests |
-
-## 📏 Performance
-
-- 🧮 Operation and local-reference passes are deterministic traversals with
-  explicit seen sets for reference chains.
-- 🌳 Component source is rendered and validated before its files are written;
-  endpoint files are then rendered and written in planned order.
-- 🧵 Cycle-aware definition/reachability state terminates recursive schemas and
-  emits lazy edges rather than expanding them forever.
-- 📦 Optional component extraction/reference imports avoid repeated component
-  definitions; default mode deliberately favors self-contained endpoint files.
-
-## 🔗 Next
-
-- 🧩 Vocabulary used above → [Concepts](05-concepts.md)
-- 🔄 Engine-by-engine rules → [Conversions](06-conversions.md)