zopia 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,7 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-29
+
+### ✨ Added
+- 🧠 **Exact IntelliSense for runtime tree consumption (S-95).** Every tree
+  generated with a manifest now also carries a types-only
+  **`.zopia-tree.d.ts`** declaration beside the manifest, and
+  `createApiDocs` / `flattenApiDocs` accept it as a type argument — turning the
+  permissive runtime typing into **exact** typing:
+  ```ts
+  import { createApiDocs, flattenApiDocs } from 'zopia/runtime';
+  import type { ApiDocsTree, ApiDocsFlat } from './api_docs/.zopia-tree';
+
+  const apiDocs = await createApiDocs<ApiDocsTree>('./api_docs');
+  apiDocs.users['{userId}'].get.pathShape;   // literal "/users/{userId}", autocompleted
+  const endpoints = flattenApiDocs<ApiDocsFlat>(apiDocs);
+  endpoints.getUser;                          // exact key, same leaf object
+  ```
+  Segment and method keys autocomplete exactly (unknown keys are **compile
+  errors**, not `any`), every leaf is typed as the generated module's own
+  `makeApiConfig()` export (literal `method`/`pathShape`, exact Zod request /
+  response shapes), and the flat record's keys derive through the same shared
+  naming rules as the generator's export identifiers (camelize,
+  reserved-word guard, `2`/`3`… collision suffixes) — parity with the runtime
+  keys is pinned by tests. The declaration is emitted in both layouts and in
+  every preset bucket root, follows the manifest lifecycle (pruned when
+  manifests are disabled, refreshed on regeneration, and a deleted declaration
+  reports `ZOPIA_WARN_STALE_TREE`), and is types-only: it imports nothing
+  beyond the tree itself (R-502 holds). `zopia generate` results report the
+  file with a new `kind: 'types'`. Conflicting paths that cannot share one
+  nested tree (below a method leaf, trailing-slash twins) render the
+  permissive intersection shape — matching the runtime's typed
+  `ZOPIA_SPEC_INVALID` failure. The shared deterministic tree ordering
+  (path segments, then canonical method order) moved to
+  `src/conversions/api-docs-layout.ts` so the runtime resolver and the
+  declaration emitter enumerate identically.
+
+## [0.4.0] - 2026-09-29
+
+### 🔄 Changed
+- 📦 **Slimmer npm package — practical docs only.** The published archive now
+  ships just the user-facing guides (`docs/07-api-docs.md`,
+  `docs/09-configuration.md`, `docs/10-usage.md`) next to `README.md` /
+  `CHANGELOG.md`; the development documentation (overview, targets, roadmap,
+  architecture, concepts, conversions, components, testing, standards, the
+  docs map, and the publish-workflow example) stays in the GitHub repository
+  and is linked from the README — npm users installing the package get
+  usage/installation docs, not project management artifacts. The tarball
+  shrinks **239 KB → 182 KB packed (915 KB → 750 KB unpacked, 50 → 39
+  files)**; `npm` force-includes `README*` from any directory, so the docs map
+  is explicitly negated (`!docs/README.md`) in `files`. `package:check` and
+  the release contract now enforce the slim archive: a missing practical doc
+  fails, and any development doc leaking into the pack fails. The release
+  standard (R-192) and the docs map describe the split.
+
 ### ✨ Added
+- 🌳 **Runtime tree consumption — `zopia/runtime` (S-94).** New opt-in subpath
+  export (`import { createApiDocs, flattenApiDocs } from 'zopia/runtime'`) that
+  turns a generated api-docs directory into the objects an application
+  consumes, with **zero changes to generation output**. `createApiDocs(dir)` —
+  the entire consumer DX — discovers the root `.zopia-manifest.json` plus every
+  one-level-deep preset bucket manifest (`multi-tag`/`multi-server`), merges
+  them (deduplicating by `${path}#${method}`, root manifest first), sorts
+  deterministically (path segments, then the canonical method order), and
+  returns one nested object keyed by the exact URL path segments with the
+  lowercase method as leaf key holding the endpoint module's `export default`
+  (loaded via `pathToFileURL`, Windows-safe). `flattenApiDocs(tree)` is the
+  flat freebie: a `Record<string, config>` keyed by `operationId`, deriving
+  missing names and collision suffixes through the **same shared rules the
+  generator uses for its export identifiers** (extracted to
+  `src/conversions/api-docs-names.ts`: camelize, reserved-word guard,
+  leading-numeric guard, `2`/`3`… suffixing — `await` → `awaitEndpoint`).
+  Missing/garbled manifests, unsafe manifest paths, import failures, and
+  modules without default exports fail typed (`ZOPIA_DOCS_MISSING_MANIFEST`,
+  `ZOPIA_MANIFEST_INVALID`, `ZOPIA_DOCS_IMPORT_FAILED`); paths that cannot
+  share one nested tree (below a method leaf, trailing-slash twins) fail typed
+  `ZOPIA_SPEC_INVALID`. Documented in
+  [docs/07-api-docs.md → Runtime tree consumption](docs/07-api-docs.md).
 - 📦 **npm publish pipeline** — `.github/workflows/publish.yml` publishes on GitHub Release creation (or manually) with the pinned Bun toolchain, verifies the release tag matches `package.json`'s version, and runs `npm publish --provenance --access public`. Its only credential is the repository-secret `NODE_AUTH_TOKEN` (npm `NPM_TOKEN`) — never handled in chat or commits; npm trusted-publishing (OIDC) is supported by the declared `id-token` permission.
 
 ### 🐛 Fixed

package/README.md

@@ -13,7 +13,7 @@
 [![Runtime](https://img.shields.io/badge/Runtime-Bun%201.x-black.svg)](https://bun.sh/)
 [![Tests](https://img.shields.io/badge/Tests-vitest-10b981.svg)](https://vitest.dev/)
 
-✅ **Status — Phase 3 complete · v0.3.0 released**
+✅ **Status — Phase 3 complete · v0.5.0 released**
 
 </div>
 
@@ -91,25 +91,62 @@ await openApiToApiDocs('swagger.json', {
 const { openapi } = await apiDocsToOpenApi('api_docs', { version: '3.1' });
 ```
 
+### 🌳 Consuming the tree at runtime
+
+When wiring endpoints dynamically beats importing generated files one by one,
+import the opt-in runtime subpath and point it at any directory zopia ever
+generated into (`directory`, `flat`, and `multi-tag` / `multi-server` splits
+all resolve through their manifests):
+
+```ts
+import { createApiDocs, flattenApiDocs } from 'zopia/runtime';
+import type { ApiDocsFlat, ApiDocsTree } from './api_docs/.zopia-tree';
+
+// Nested: URL path segments → lowercase method → the makeApiConfig object
+const apiDocs = await createApiDocs<ApiDocsTree>('api_docs');
+const getUser = apiDocs.users['{userId}'].get;   // default export of that index.ts
+
+// Flat freebie: keyed by operationId, same leaf objects, deterministic order
+const endpoints = flattenApiDocs<ApiDocsFlat>(apiDocs);
+endpoints.getUser === getUser;                    // → true
+```
+
+Every generated tree also ships a types-only `.zopia-tree.d.ts` — pass its
+types as shown and IntelliSense becomes **exact**: keys autocomplete, and
+misspelled segments, methods, or endpoint names are compile errors.
+
+Generation output is untouched — the resolver only reads manifests and imports
+modules. See [docs/07-api-docs.md → Runtime tree consumption](docs/07-api-docs.md#-runtime-tree-consumption--createapidocs).
+
 ## 📚 Documentation
 
-Everything about the project — targets, architecture, conversion rules,
-output format, configuration, testing, standards — lives in [`docs/`](docs/).
+The **practical guides ship inside the npm package** — usage, configuration,
+and the generated output format. The development documentation (project
+targets, roadmap, architecture, testing strategy, engineering standards)
+stays in the
+[GitHub repository](https://github.com/komeilm76/zopia/tree/main/docs).
+
+**📦 Packed with the npm package** (relative links, in `docs/`):
 
 | 📄 Document | Contents |
 | --- | --- |
-| 🧭 [Overview](docs/01-overview.md) | What zopia is, the problem it solves, principles, non-goals |
-| 🎯 [Targets](docs/02-targets.md) | The explicit, testable targets of this project |
-| 🗺️ [Roadmap](docs/03-roadmap.md) | Phases, milestones, definition of done |
-| 🏗️ [Architecture](docs/04-architecture.md) | Modules, pipeline, internal model, error model, safety |
-| 🧩 [Concepts](docs/05-concepts.md) | Glossary — Swagger 2.0, OpenAPI 3.x, JSON Schema, `$ref`, Zod v4, km-api |
-| 🔄 [Conversions](docs/06-conversions.md) | The four engines: algorithms, mapping tables, edge cases |
-| 📄 [API docs format](docs/07-api-docs.md) | `directory` & `flat` layouts, `index.ts` contract, manifest |
-| 🧱 [Components](docs/08-components.md) | `insertComponents` / `useComponentAsReference`, `$ref` graphs |
-| ⚙️ [Configuration](docs/09-configuration.md) | Full option reference, defaults, validation rules |
 | 🚀 [Usage](docs/10-usage.md) | Installation, programmatic API, CLI, end-to-end example |
-| 🧪 [Testing](docs/11-testing.md) | Vitest strategy, scenario matrix, fixtures, coverage gates |
-| 📏 [Standards](docs/12-standards.md) | Code, JSDoc, commits, changelog, releases, key decisions |
+| ⚙️ [Configuration](docs/09-configuration.md) | Full option reference, defaults, validation rules |
+| 📄 [API docs format](docs/07-api-docs.md) | `directory` & `flat` layouts, `index.ts` contract, manifest, runtime consumption |
+
+**🐙 GitHub-only** (development docs, not packed):
+
+| 📄 Document | Contents |
+| --- | --- |
+| 🧭 [Overview](https://github.com/komeilm76/zopia/blob/main/docs/01-overview.md) | What zopia is, the problem it solves, principles, non-goals |
+| 🎯 [Targets](https://github.com/komeilm76/zopia/blob/main/docs/02-targets.md) | The explicit, testable targets of this project |
+| 🗺️ [Roadmap](https://github.com/komeilm76/zopia/blob/main/docs/03-roadmap.md) | Phases, milestones, definition of done |
+| 🏗️ [Architecture](https://github.com/komeilm76/zopia/blob/main/docs/04-architecture.md) | Modules, pipeline, internal model, error model, safety |
+| 🧩 [Concepts](https://github.com/komeilm76/zopia/blob/main/docs/05-concepts.md) | Glossary — Swagger 2.0, OpenAPI 3.x, JSON Schema, `$ref`, Zod v4, km-api |
+| 🔄 [Conversions](https://github.com/komeilm76/zopia/blob/main/docs/06-conversions.md) | The four engines: algorithms, mapping tables, edge cases |
+| 🧱 [Components](https://github.com/komeilm76/zopia/blob/main/docs/08-components.md) | `insertComponents` / `useComponentAsReference`, `$ref` graphs |
+| 🧪 [Testing](https://github.com/komeilm76/zopia/blob/main/docs/11-testing.md) | Vitest strategy, scenario matrix, fixtures, coverage gates |
+| 📏 [Standards](https://github.com/komeilm76/zopia/blob/main/docs/12-standards.md) | Code, JSDoc, commits, changelog, releases, key decisions |
 
 ## 🏗️ Project structure
 
@@ -139,7 +176,7 @@ zopia/
 
 ## 🧪 Development
 
-zopia is a **Bun-first** project (see [docs/12-standards.md](docs/12-standards.md)):
+zopia is a **Bun-first** project (see [docs/12-standards.md](https://github.com/komeilm76/zopia/blob/main/docs/12-standards.md)):
 
 ```bash
 bun install --frozen-lockfile # 📦 reproducible install from bun.lock
@@ -157,7 +194,7 @@ bun run release:check         # 🚢 complete pinned-Bun prepublish gate
 
 ## 🤝 Contributing
 
-Read [docs/12-standards.md](docs/12-standards.md) first — it defines code style,
+Read [docs/12-standards.md](https://github.com/komeilm76/zopia/blob/main/docs/12-standards.md) first — it defines code style,
 JSDoc rules, the commit convention, and the changelog rule. Every feature ships
 **with** its documentation in the same commit.
 

package/docs/07-api-docs.md

@@ -106,6 +106,98 @@ templates, duplicate parameters, unsupported methods, and unsafe roots. Engine
 does not emit a facade module in v0.1.0: direct imports are the generated
 file-level API, and the manifest remains authoritative (D-06).
 
+## 🌳 Runtime tree consumption — `createApiDocs`
+
+> 🎯 **S-94** — *an opt-in runtime API, shipped in the `zopia` package itself,
+> converts a generated tree directory into the nested / flat objects an
+> application consumes. No generation output changes: the feature only reads
+> and imports.*
+
+```ts
+import { createApiDocs, flattenApiDocs } from 'zopia/runtime';
+import type { ApiDocsFlat, ApiDocsTree } from './api_docs/.zopia-tree';
+
+const apiDocs = await createApiDocs<ApiDocsTree>('api_docs');   // ← the entire consumer DX
+const endpoint = apiDocs.applicant['{applicantId}'].exame['{examId}'].get;
+// → the endpoint module's makeApiConfig object (its default export), EXACTLY typed
+
+const endpoints = flattenApiDocs<ApiDocsFlat>(apiDocs);        // the flat freebie
+endpoints.getExam;                                             // same leaf object
+```
+
+**Exact IntelliSense (S-95).** Called without a type argument, the helpers
+return permissively typed results (every node is a branch ∪ config). Passing
+the generated **`.zopia-tree.d.ts`** types — written beside every retained
+manifest, in both layouts and every preset bucket root — makes the result
+**exact**: segment and method keys autocomplete, unknown keys are compile
+errors (not `any`), every leaf carries the generated module's own
+`makeApiConfig()` type (literal `method`/`pathShape`, exact Zod request and
+response shapes), and the flat record's keys are the derived endpoint names
+(same shared rules as the generator's export identifiers, including collision
+suffixes). The declaration is types-only — it imports nothing beyond the tree
+itself (R-502 holds) — and follows the manifest lifecycle: refreshed on
+regeneration, pruned when manifests are disabled, and a deleted declaration
+reports `ZOPIA_WARN_STALE_TREE`. `zopia generate` results list it with
+`kind: 'types'`.
+
+**Manifest discovery & merge (B-conditions).** The resolver reads the root
+`.zopia-manifest.json` **plus** every one-level-deep preset bucket manifest
+(`multi-tag` / `multi-server` splits write one manifest per bucket directory),
+merging all of them and deduplicating by `${path}#${method}` — the root
+manifest wins duplicates, buckets follow in sorted directory order. Any
+directory that was ever a zopia output root is accepted, including a single
+preset bucket root. Entries are then sorted deterministically: URL path
+segments first, then the canonical method order
+(`get, post, put, delete, head, options, patch, trace`).
+
+**Nesting.** Branch keys are the URL path segments **exactly and in order**
+(including literal `{param}` segments), the leaf key is the lowercase method,
+and the leaf value is the endpoint module's **default export**, loaded with
+dynamic `import()` through `pathToFileURL` (Windows-safe). Because which keys
+exist depends on the source spec, the default `ApiDocsTree` return type is
+permissive (branch ∪ config) — pass the generated `.zopia-tree.d.ts` type for
+exact keys (see below). A tree `/` path nests its methods at the root
+(`apiDocs.get`). Paths that cannot coexist in one nested tree — a path
+continuing below another path's method leaf, or two paths differing only by a
+trailing slash — fail with a typed `ZOPIA_SPEC_INVALID` instead of silently
+dropping an endpoint. Key insertion follows the deterministic sort, so the
+same tree always enumerates keys in the same order (P-1).
+
+**Errors** reuse the manifest conventions: a missing manifest →
+`ZOPIA_DOCS_MISSING_MANIFEST`; garbled JSON or unusable `apis[]` records →
+`ZOPIA_MANIFEST_INVALID`; a module that cannot be imported or has no default
+export → `ZOPIA_DOCS_IMPORT_FAILED` naming the file. Reading is pure — nothing
+on disk is written.
+
+**The flatten freebie.** `flattenApiDocs(apiDocs)` deep-walks the tree in its
+deterministic leaf order and returns a flat `Record<string, config>` keyed by
+each config's `operationId`. When a leaf has no usable `operationId`, or two
+keys collide, the name is derived by the **same rules the generator uses for
+its `export const` identifiers** (R-732: camelize, reserved-word guard,
+leading-numeric guard, `2`/`3`… uniqueness suffix — `await` → `awaitEndpoint`,
+`get-a` + `getA` → `getA` + `getA2`), so the flat keys always match the
+modules' named exports. The shared rules live in
+`src/conversions/api-docs-names.ts` and both call-sites (generation and
+runtime) use them.
+
+**A small km-api hand-off** — every leaf *is* a `makeApiConfig()` object, so
+the km-api surface is available directly:
+
+```ts
+import { createApiDocs } from 'zopia/runtime';
+
+const apiDocs = await createApiDocs('api_docs');
+const getUser = apiDocs.users['{userId}'].get;
+
+getUser.method;                          // "GET"
+getUser.pathShape;                       // "/users/{userId}"
+getUser.request.params.parse({ userId: '22ccbc6a-…' }); // ✅ Zod-validated path params
+getUser.response[200].parse({ id: 'u1', email: 'a@b.c' }); // ✅ Zod-validated response
+```
+
+> 💡 Generated webhook modules are not URL-path endpoints and stay outside the
+> nested tree — import them directly or reverse-convert the tree (engine ④).
+
 ## 🧬 Operation contract extraction
 
 Before rendering an endpoint, zopia normalizes each operation into an
@@ -177,7 +269,7 @@ With the default options (`insertComponents: false`), every `index.ts` imports
 **only** `zod` and `km-api` (R-502): each component use is inlined into its
 request/parameter/response expression (R-403). Cross-file imports appear
 **only** when `useComponentAsReference` is `true` — see
-[Components](08-components.md).
+[Components](https://github.com/komeilm76/zopia/blob/main/docs/08-components.md).
 
 ## 📦 The manifest — `.zopia-manifest.json`
 
@@ -333,5 +425,5 @@ Security requirements remain manifest-owned because km-api stores only `auth: 'Y
 
 ## 🔗 Next
 
-- 🧱 What changes when components are emitted → [Components](08-components.md)
+- 🧱 What changes when components are emitted → [Components](https://github.com/komeilm76/zopia/blob/main/docs/08-components.md)
 - ⚙️ Every option that shapes this output → [Configuration](09-configuration.md)

package/docs/09-configuration.md

@@ -107,7 +107,7 @@ interface ZopiaReverseOptions {
 
 ## 📄 `ZodToJsonSchemaOptions` — engine ①
 
-See [Conversions → Engine ①](06-conversions.md)
+See [Conversions → Engine ①](https://github.com/komeilm76/zopia/blob/main/docs/06-conversions.md)
 (`target`, `$schema`, `io`).
 
 ## 📄 `JsonSchemaToZodOptions` — engine ②
@@ -164,4 +164,4 @@ zopia diff <old-spec> <new-spec>          (no options yet; `--config path` accep
 ## 🔗 Next
 
 - 🚀 How options are used end-to-end → [Usage](10-usage.md)
-- 📂 What each option changes in the tree → [API docs format](07-api-docs.md) · [Components](08-components.md)
+- 📂 What each option changes in the tree → [API docs format](07-api-docs.md) · [Components](https://github.com/komeilm76/zopia/blob/main/docs/08-components.md)

package/docs/10-usage.md

@@ -178,8 +178,37 @@ stderr, hint included) · `2` internal error (should never happen — report it)
 | R-101 | 📂 **Import, don't re-type** — your app imports the generated `index.ts` files; their Zod schemas *are* the validation | — |
 | R-102 | 🔄 **Spec or generation options changed?** re-run `zopia generate` — output is idempotent (P-1); manifest staleness warns on source/config/incomplete-tree drift and safely prunes only obsolete manifest-owned files (`ZOPIA_WARN_STALE_TREE`) | [07 → Regeneration](07-api-docs.md#-regeneration--manual-edits-phase-1-policy) |
 | R-103 | ✍️ **Hand edits** — Phase 1 overwrites them on regeneration (see the file banner); the merge-safe custom layer arrives in Phase 3 | [07 → Regeneration](07-api-docs.md#-regeneration--manual-edits-phase-1-policy) |
-| R-104 | 🧪 **km-api helpers** — `makeFullPath`, `makeParams`, `convertResponseType`, … are available on every generated config for free | [Concepts → km-api](05-concepts.md#-km-api) |
+| R-104 | 🧪 **km-api helpers** — `makeFullPath`, `makeParams`, `convertResponseType`, … are available on every generated config for free | [Concepts → km-api](https://github.com/komeilm76/zopia/blob/main/docs/05-concepts.md#-km-api) |
 | R-105 | 🚫 **No zopia import in app code** — generated files depend only on `zod` + `km-api` (R-502) | — |
+| R-106 | 🌳 **Runtime tree loading** — when wiring endpoints dynamically beats importing files one by one, `createApiDocs()` from the opt-in `zopia/runtime` subpath turns the whole directory into one nested object (plus the `flattenApiDocs` flat record); generation output is untouched | [07 → Runtime tree consumption](07-api-docs.md#-runtime-tree-consumption--createapidocs) |
+
+### 🌳 Consuming the tree at runtime
+
+Import the dedicated subpath (the package root stays free of
+filesystem-importing APIs) and point it at any directory zopia ever generated
+into — `directory`, `flat`, and split `multi-tag` / `multi-server` trees all
+resolve through their manifests:
+
+```ts
+import { createApiDocs, flattenApiDocs } from 'zopia/runtime';
+import type { ApiDocsFlat, ApiDocsTree } from './api_docs/.zopia-tree';
+
+// Nested: exact URL path segments, lowercase method leaf, default-export config
+const apiDocs = await createApiDocs<ApiDocsTree>('api_docs');
+const getUser = apiDocs.users['{userId}'].get;   // the makeApiConfig object
+
+// Flat: keyed by operationId (derived with the generator's own naming rules)
+const endpoints = flattenApiDocs<ApiDocsFlat>(apiDocs);
+endpoints.getUser === getUser;                    // → true
+```
+
+The type import is optional — without it the results stay permissively typed —
+but with it every key is exact: `apiDocs.users.` autocompletes `{userId}`,
+`endpoints.` autocompletes the endpoint names, and misspelled keys are compile
+errors.
+
+Failures are typed `ZopiaError`s with `at`/`hint` — see
+[API docs → Runtime tree consumption](07-api-docs.md#-runtime-tree-consumption--createapidocs).
 
 ## 🧯 Error handling
 
@@ -200,9 +229,9 @@ try {
 ```
 
 The full error-code table lives in
-[Architecture → Error model](04-architecture.md#-error-model).
+[Architecture → Error model](https://github.com/komeilm76/zopia/blob/main/docs/04-architecture.md#-error-model).
 
 ## 🔗 Next
 
 - ⚙️ Every option → [Configuration](09-configuration.md)
-- 🧪 How all of this is tested → [Testing](11-testing.md)
+- 🧪 How all of this is tested → [Testing](https://github.com/komeilm76/zopia/blob/main/docs/11-testing.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zopia",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Type-safe OpenAPI, JSON Schema, and Zod conversion toolkit.",
   "keywords": [
     "api-docs",
@@ -27,7 +27,10 @@
   "files": [
     "bin",
     "src",
-    "docs",
+    "docs/07-api-docs.md",
+    "docs/09-configuration.md",
+    "docs/10-usage.md",
+    "!docs/README.md",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
@@ -72,6 +75,11 @@
       "types": "./src/index.ts",
       "import": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./runtime": {
+      "types": "./src/runtime.ts",
+      "import": "./src/runtime.ts",
+      "default": "./src/runtime.ts"
     }
   }
 }

package/src/conversions/api-docs-generate.ts

@@ -1,11 +1,13 @@
 import { lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { asZopiaError, ZopiaError } from '../errors';
+import { endpointExportName } from './api-docs-names';
 import { buildOpenApiOperationIR } from './openapi-ir';
 import { deriveReusableParameterSchema, deriveReusableResponseSchema, extractOperationContracts, reusableDeclarations } from './openapi-contracts';
 import { jsonSchemaToZod } from './json-schema-to-zod';
 import { assertUniqueOperationIdsAcrossScopes, planApiDocsFiles, planWebhookDocsFiles, webhookRuntimePath, type ApiDocsFilePlan } from './api-docs-plan';
 import { isPortableApiDocsSegment, type ApiDocsMode } from './api-docs-layout';
+import { renderApiDocsTreeTypes, ZOPIA_TREE_TYPES_FILE } from './api-docs-tree-types';
 import type { OpenApiDocument } from './openapi';
 import { createZopiaManifest, hashOpenApiDocument, writeZopiaManifest, ZOPIA_MANIFEST_FILE } from './manifest-writer';
 import { inspectZopiaManifestStaleness, removeObsoleteManifestFiles } from './manifest-staleness';
@@ -61,7 +63,7 @@ function collectComponentRefs(value: unknown, names = new Set<string>(), mapEntr
   return names;
 }
 function schemaCode(schema: unknown, name: string): string {
-  const safeName = exportName(name);
+  const safeName = endpointExportName(name);
   const converted = jsonSchemaToZod(schema === undefined ? true : schema as any, { rootName: safeName });
   const source = converted.code.trimEnd();
   const direct = source.match(new RegExp(`^const ${safeName.replace(/[$]/g, '\\$&')} = ([\\s\\S]*);$`));
@@ -222,23 +224,16 @@ function resolveObject(value: unknown, source: OpenApiDocument): any {
   }
   return current;
 }
-function exportName(operationId: string): string {
-  const parts = operationId.split(/[^A-Za-z0-9_$]+/).filter(Boolean);
-  let name = parts.map((part, index) => index === 0 ? part : part[0].toUpperCase() + part.slice(1)).join('') || 'endpoint';
-  if (!/^[A-Za-z_$]/.test(name)) name = `endpoint${name}`;
-  if (['arguments', 'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'eval', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'implements', 'import', 'in', 'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private', 'protected', 'public', 'return', 'static', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield'].includes(name)) name = `${name}Endpoint`;
-  return name;
-}
 function componentExportName(componentName: string): string {
-  const name = exportName(componentName);
+  const name = endpointExportName(componentName);
   return name.endsWith('Schema') ? name : `${name}Schema`;
 }
 function componentParameterExportName(componentName: string): string {
-  const name = exportName(componentName);
+  const name = endpointExportName(componentName);
   return name.endsWith('Parameter') ? name : `${name}Parameter`;
 }
 function componentResponseExportName(componentName: string): string {
-  const name = exportName(componentName);
+  const name = endpointExportName(componentName);
   return name.endsWith('Response') ? name : `${name}Response`;
 }
 function componentReaches(source: OpenApiDocument, from: string, target: string, seen = new Set<string>()): boolean {
@@ -352,7 +347,7 @@ function renderEndpoint(operation: any, source: OpenApiDocument, mode: ApiDocsMo
   const examplesValue = { ...(Object.keys(requestExamples).length ? { request: requestExamples } : {}), ...(Object.keys(responseExamples).length ? { response: responseExamples } : {}) };
   const examples = Object.keys(examplesValue).length ? `examples: JSON.parse(${JSON.stringify(stableDataJson(examplesValue))}),` : '';
   const opId = operation.operationId;
-  const exportId = exportName(opId);
+  const exportId = endpointExportName(opId);
   const tags = ir.tags;
   const auth = ir.security !== undefined && ir.security.length > 0 && ir.security.every((requirement) => Object.keys(requirement as Record<string, unknown>).length > 0) ? 'YES' : 'NO';
   const sourceName = JSON.stringify(`${source.info.title} v${source.info.version}`).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
@@ -458,7 +453,11 @@ async function generateApiDocsFilesInternal(input: OpenApiDocument | string, opt
       reservedFiles.push(`${directory}/index.ts`, ...names.map((name) => `${directory}/${name}/index.ts`));
     }
   }
-  if (retainManifest) reservedFiles.push(ZOPIA_MANIFEST_FILE);
+  if (retainManifest) {
+    reservedFiles.push(ZOPIA_MANIFEST_FILE);
+    // The exact-tree declaration is emitted beside the manifest and shares its lifecycle.
+    reservedFiles.push(ZOPIA_TREE_TYPES_FILE);
+  }
   const plans = avoidReservedFileCollisions(planApiDocsFiles(source, mode), reservedFiles);
   const webhookPlans = avoidReservedFileCollisions(planWebhookDocsFiles(source, mode), [...reservedFiles, ...plans.map((plan) => plan.file)]);
   // OpenAPI requires operationId to be unique document-wide; $ref aliases can make the
@@ -561,6 +560,14 @@ async function generateApiDocsFilesInternal(input: OpenApiDocument | string, opt
   if (manifest) {
     const manifestPath = await writeZopiaManifest(root, manifest);
     generated.push({ file: ZOPIA_MANIFEST_FILE, absolutePath: manifestPath, operationId: 'manifest' });
+    // Exact IntelliSense: the declaration mirrors the runtime tree/flat shapes (S-95).
+    const treeTypesPath = await writeGeneratedFile(root, ZOPIA_TREE_TYPES_FILE, renderApiDocsTreeTypes(plans.map((plan) => ({
+      file: plan.file,
+      path: plan.path,
+      method: plan.method,
+      operationId: plan.operationId,
+    }))), previouslyOwned);
+    generated.push({ file: ZOPIA_TREE_TYPES_FILE, absolutePath: treeTypesPath, operationId: 'tree-types' });
   }
   await removeObsoleteManifestFiles(root, previous.ownedFiles, generated.map(({ file }) => file));
   return generated;

package/src/conversions/api-docs-layout.ts

@@ -4,6 +4,47 @@ import { OPENAPI_METHODS, type OpenApiMethod } from './openapi-to-api-docs';
 /** Filesystem layout used for generated endpoint modules. */
 export type ApiDocsMode = 'directory' | 'flat';
 
+/**
+ * Split one OpenAPI path template into its literal segment keys.
+ *
+ * Empty segments are dropped, so the root path `/` has no segments and its
+ * methods nest directly at the tree root. This is the single segmentation rule
+ * shared by the runtime tree resolver and the generated `.zopia-tree.d.ts`.
+ *
+ * @param path OpenAPI path template beginning with `/`.
+ * @returns Path segments in order, including literal `{param}` segments.
+ */
+export function apiDocsPathSegments(path: string): string[] {
+  return path.split('/').filter(Boolean);
+}
+
+/**
+ * Compare two endpoint entries by the canonical deterministic tree order:
+ * URL path segments lexically, shorter segment chains first, then the
+ * canonical method order (`get, post, put, delete, head, options, patch, trace`).
+ *
+ * The runtime tree resolver inserts keys in this order and the generated
+ * `.zopia-tree.d.ts` declares them in this order, so both surfaces enumerate
+ * identically (R-732/S-94).
+ *
+ * @param left Endpoint entry with an OpenAPI `path` and lowercase `method`.
+ * @param right Endpoint entry with an OpenAPI `path` and lowercase `method`.
+ * @returns Negative when `left` sorts first, positive when `right` does, zero when equal.
+ */
+export function compareApiDocsEntries(left: { path: string; method: string }, right: { path: string; method: string }): number {
+  const leftSegments = apiDocsPathSegments(left.path);
+  const rightSegments = apiDocsPathSegments(right.path);
+  const depth = Math.min(leftSegments.length, rightSegments.length);
+  for (let index = 0; index < depth; index += 1) {
+    const order = leftSegments[index] < rightSegments[index] ? -1 : leftSegments[index] > rightSegments[index] ? 1 : 0;
+    if (order !== 0) return order;
+  }
+  const lengthOrder = leftSegments.length - rightSegments.length;
+  if (lengthOrder !== 0) return lengthOrder;
+  const methods = OPENAPI_METHODS as readonly string[];
+  return methods.indexOf(left.method) - methods.indexOf(right.method);
+}
+
 /**
  * Return whether one generated-tree path segment is portable across supported filesystems.
  *

package/src/conversions/api-docs-names.ts

@@ -0,0 +1,54 @@
+/**
+ * 📛 Shared endpoint identifier rules (R-732).
+ *
+ * The single source of truth for deriving safe export identifiers from
+ * operation IDs — and for the numeric uniqueness suffix applied when two
+ * derived identifiers collide. Generation (Engine ③'s `export const` names
+ * and the collectors' deterministic operation IDs) and the runtime tree
+ * resolver (`flattenApiDocs` record keys) call these helpers so both surfaces
+ * keep producing identical names by construction.
+ */
+
+/** ECMAScript keywords and literals never emitted as generated identifiers. */
+const RESERVED_IDENTIFIER_NAMES: ReadonlySet<string> = new Set([
+  'arguments', 'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'eval', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'implements', 'import', 'in', 'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private', 'protected', 'public', 'return', 'static', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield',
+]);
+
+/**
+ * Derive the endpoint export identifier from one operation ID.
+ *
+ * Applies the fixed naming contract of R-732: split on non-identifier
+ * characters, camel-case the parts (camelize), fall back to `endpoint` when
+ * nothing remains, prefix `endpoint` when the result starts with a digit or
+ * other non-identifier character, and append `Endpoint` when the result is a
+ * reserved ECMAScript keyword or literal (e.g. `await` → `awaitEndpoint`).
+ *
+ * @param operationId Explicit or deterministically derived operation identifier.
+ * @returns Safe camel-case TypeScript identifier for the module export.
+ */
+export function endpointExportName(operationId: string): string {
+  const parts = operationId.split(/[^A-Za-z0-9_$]+/).filter(Boolean);
+  let name = parts.map((part, index) => index === 0 ? part : part[0].toUpperCase() + part.slice(1)).join('') || 'endpoint';
+  if (!/^[A-Za-z_$]/.test(name)) name = `endpoint${name}`;
+  if (RESERVED_IDENTIFIER_NAMES.has(name)) name = `${name}Endpoint`;
+  return name;
+}
+
+/**
+ * Return the first free variant of a derived identifier, suffixing `2`, `3`, …
+ *
+ * This is the exact uniqueness rule the operation collectors apply when a
+ * derived operation ID collides (`getA` → `getA2` → `getA3`): the first
+ * candidate is the base itself, and every subsequent candidate appends the
+ * next integer directly to the base.
+ *
+ * @param base Identifier before any uniqueness suffix.
+ * @param used Already-claimed identifiers this derivation must not clobber.
+ * @returns `base` itself when free, otherwise the first suffixed variant.
+ */
+export function uniqueEndpointName(base: string, used: ReadonlySet<string>): string {
+  let name = base;
+  let suffix = 1;
+  while (used.has(name)) name = `${base}${++suffix}`;
+  return name;
+}