zopia 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-30
+
+### 🐛 Fixed
+- 🐛 **Duplicate `.int()` in generated Zod schemas for `int32` and `int64`
+  formats (#4).** Integer properties carrying an integer format emitted
+  `z.number().int().int()...` — the `integer` type already appends `.int()`
+  and the format branch appended it again. Now every combination
+  (`integer`/`number` × `int32`/`int64`/`uint32`/`uint64`) emits exactly one
+  `.int()`, with bounds (`int32` → `-2147483648...2147483647`,
+  `uint32` → `0...4294967295`) and `.nonnegative()` for the unsigned formats
+  unchanged. Runtime validation, warning codes, and reverse-conversion
+  overlays are untouched; covered by new unit and end-to-end regression
+  tests that assert the emitted code (not just parse behavior).
+
+## [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

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.4.0 released**
+✅ **Status — Phase 3 complete · v0.5.1 released**
 
 </div>
 
@@ -100,16 +100,21 @@ 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('api_docs');
+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(apiDocs);
+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).
 

package/docs/07-api-docs.md

@@ -115,15 +115,31 @@ file-level API, and the manifest remains authoritative (D-06).
 
 ```ts
 import { createApiDocs, flattenApiDocs } from 'zopia/runtime';
+import type { ApiDocsFlat, ApiDocsTree } from './api_docs/.zopia-tree';
 
-const apiDocs = await createApiDocs('api_docs');   // ← the entire consumer DX
+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)
+// → the endpoint module's makeApiConfig object (its default export), EXACTLY typed
 
-const endpoints = flattenApiDocs(apiDocs);        // the flat freebie
-endpoints.getExam;                                 // same leaf object
+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),
@@ -138,8 +154,9 @@ segments first, then the canonical method 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 `ApiDocsTree` type types every node
-permissively (branch ∪ config). A tree `/` path nests its methods at the root
+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

package/docs/10-usage.md

@@ -191,16 +191,22 @@ 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('api_docs');
+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(apiDocs);
+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).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zopia",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Type-safe OpenAPI, JSON Schema, and Zod conversion toolkit.",
   "keywords": [
     "api-docs",

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

@@ -7,6 +7,7 @@ import { deriveReusableParameterSchema, deriveReusableResponseSchema, extractOpe
 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';
@@ -452,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
@@ -555,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-tree-types.ts

@@ -0,0 +1,113 @@
+/**
+ * 🧠 Generated exact tree types (S-95).
+ *
+ * Renders the `.zopia-tree.d.ts` declaration emitted beside every retained
+ * manifest: a types-only artifact describing the **exact** nested shape the
+ * runtime resolver (`createApiDocs`) builds and the **exact** flat record
+ * `flattenApiDocs` returns, so consumers get precise IntelliSense — literal
+ * path-segment keys, method leaves typed as the generated module's own
+ * `makeApiConfig()` export, and typo-proof access (unknown keys are compile
+ * errors). Nothing runtime is emitted; the file is pure declaration.
+ *
+ * Ordering and naming are shared with the runtime: entries sort through
+ * `compareApiDocsEntries` and flat keys derive through `endpointExportName` /
+ * `uniqueEndpointName` — the same rules as the generator's `export const`
+ * names — so the declared types match the runtime objects by construction.
+ */
+
+import { apiDocsPathSegments, compareApiDocsEntries } from './api-docs-layout';
+import { endpointExportName, uniqueEndpointName } from './api-docs-names';
+
+/** File name of the generated exact-tree declaration, written beside the manifest. */
+export const ZOPIA_TREE_TYPES_FILE = '.zopia-tree.d.ts';
+
+/** One endpoint record the declaration is rendered from. */
+export interface ApiDocsTreeTypePlan {
+  /** Portable endpoint-module path relative to the tree root (POSIX, with `.ts`). */
+  file: string;
+  /** OpenAPI path template — the authority for the nested key chain. */
+  path: string;
+  /** Lowercase HTTP method — the leaf key. */
+  method: string;
+  /** Declared or deterministically derived operation identifier. */
+  operationId: string;
+}
+
+/** Internal tree node while assembling the declaration: a branch, a method leaf, or both. */
+interface TypeTreeNode {
+  /** Child branches/leaves by key; insertion follows the deterministic entry order. */
+  children?: Map<string, TypeTreeNode>;
+  /** Module type reference when this node is (also) a method leaf. */
+  leaf?: { module: string; exportName: string };
+}
+
+/** Import-free module type reference: `typeof import('<module>').<exportName>`. */
+const typeReference = (module: string, exportName: string): string => `typeof import('${module}').${exportName}`;
+
+/** Module specifier of one endpoint plan: the portable file path without the `.ts` extension. */
+const moduleSpecifier = (file: string): string => `./${file.replace(/\.ts$/, '')}`;
+
+/**
+ * Render the `.zopia-tree.d.ts` declaration for one tree root.
+ *
+ * @param apis Endpoint records (path operations only — webhooks are not URL-path endpoints).
+ * @returns The complete declaration file text: an `ApiDocsTree` type keyed by exact URL path segments with lowercase-method leaves, and an `ApiDocsFlat` type keyed by the derived endpoint names.
+ */
+export function renderApiDocsTreeTypes(apis: readonly ApiDocsTreeTypePlan[]): string {
+  const sorted = [...apis].sort(compareApiDocsEntries);
+  const root: TypeTreeNode = {};
+  for (const api of sorted) {
+    let node: TypeTreeNode = root;
+    for (const segment of apiDocsPathSegments(api.path)) {
+      let child = node.children?.get(segment);
+      if (!child) {
+        child = {};
+        (node.children ??= new Map<string, TypeTreeNode>()).set(segment, child);
+      }
+      node = child;
+    }
+    (node.children ??= new Map<string, TypeTreeNode>()).set(api.method, { leaf: { module: moduleSpecifier(api.file), exportName: endpointExportName(api.operationId) } });
+  }
+
+  const renderNode = (node: TypeTreeNode, depth: number): string => {
+    if (!node.children || node.children.size === 0) return 'Record<string, never>';
+    const indent = '  '.repeat(depth);
+    const lines: string[] = [];
+    for (const [key, child] of node.children) {
+      const childType = child.leaf
+        ? child.children && child.children.size > 0
+          // A path continuing below another path's method leaf: the key is both the
+          // endpoint config and a deeper branch — the permissive intersection shape.
+          ? `(${typeReference(child.leaf.module, child.leaf.exportName)} & ${renderNode(child, 1)})`
+          : typeReference(child.leaf.module, child.leaf.exportName)
+        : renderNode(child, depth + 1);
+      lines.push(`${indent}  readonly ${JSON.stringify(key)}: ${childType};`);
+    }
+    return `{\n${lines.join('\n')}\n${indent}}`;
+  };
+
+  const flatLines: string[] = [];
+  const used = new Set<string>();
+  for (const api of sorted) {
+    const key = uniqueEndpointName(endpointExportName(api.operationId), used);
+    used.add(key);
+    flatLines.push(`  readonly ${JSON.stringify(key)}: ${typeReference(moduleSpecifier(api.file), endpointExportName(api.operationId))};`);
+  }
+
+  return [
+    '/**',
+    ' * Generated by zopia — do not edit by hand.',
+    ' *',
+    ' * Exact types of this api-docs tree as loaded at runtime by the',
+    ' * `createApiDocs()` / `flattenApiDocs()` helpers of the zopia `zopia/runtime`',
+    ' * subpath (types-only: this file imports nothing beyond the tree itself):',
+    ' *',
+    " *   const apiDocs = await createApiDocs<ApiDocsTree>('./<this-tree>');   // nested: exact segments → method",
+    ' *   const endpoints = flattenApiDocs<ApiDocsFlat>(apiDocs);             // flat: exact endpoint names',
+    ' */',
+    `export type ApiDocsTree = ${renderNode(root, 0)};`,
+    '',
+    `export type ApiDocsFlat = ${flatLines.length ? `{\n${flatLines.join('\n')}\n}` : 'Record<string, never>'};`,
+    '',
+  ].join('\n').replace(/[ \t]+$/gm, '');
+}

package/src/conversions/json-schema-to-zod.ts

@@ -684,11 +684,17 @@ function jsonSchemaToZodInternal(input: JsonSchema | string, options: JsonSchema
       }
     }
     if ((node.format === 'int32' || node.format === 'int64') && (node.type === 'integer' || node.type === 'number')) {
-      const integer = (result.schema as any).int(); const code = `${result.code}.int()`;
-      result = node.format === 'int32' ? { schema: integer.min(-2147483648).max(2147483647), code: `${code}.min(-2147483648).max(2147483647)` } : { schema: integer, code };
+      // `integer` schemas already carry .int() from the type switch above — appending it again
+      // duplicated the call in generated code (issue #4); only `number` schemas need it added here.
+      const alreadyInteger = node.type === 'integer';
+      const integer = alreadyInteger ? result.schema : (result.schema as any).int();
+      const code = alreadyInteger ? result.code : `${result.code}.int()`;
+      result = node.format === 'int32' ? { schema: (integer as any).min(-2147483648).max(2147483647), code: `${code}.min(-2147483648).max(2147483647)` } : { schema: integer, code };
     }
     if ((node.format === 'uint32' || node.format === 'uint64') && (node.type === 'integer' || node.type === 'number')) {
-      const integer = (result.schema as any).int().nonnegative(); const code = `${result.code}.int().nonnegative()`;
+      const alreadyInteger = node.type === 'integer';
+      const integer = alreadyInteger ? (result.schema as any).nonnegative() : (result.schema as any).int().nonnegative();
+      const code = alreadyInteger ? `${result.code}.nonnegative()` : `${result.code}.int().nonnegative()`;
       result = node.format === 'uint32' ? { schema: integer.max(4294967295), code: `${code}.max(4294967295)` } : { schema: integer, code };
     }
     if (node.format && node.type === 'string') {

package/src/conversions/manifest-staleness.ts

@@ -1,6 +1,7 @@
 import { lstat, readFile, realpath, rmdir, rm, stat } from 'node:fs/promises';
 import { asZopiaError } from '../errors';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { ZOPIA_TREE_TYPES_FILE } from './api-docs-tree-types';
 import type { ApiDocsMode } from './api-docs-layout';
 import {
   validateZopiaManifest,
@@ -55,7 +56,8 @@ function compareText(left: string, right: string): number {
 const isManifestComponent = (value: unknown): value is { kind?: string; file?: unknown } => typeof value === 'object' && value !== null;
 
 function collectOwnedFiles(manifest: GeneratedZopiaManifest): string[] {
-  const files = new Set<string>([ZOPIA_MANIFEST_FILE]);
+  // The exact-tree declaration is written and pruned together with the manifest.
+  const files = new Set<string>([ZOPIA_MANIFEST_FILE, ZOPIA_TREE_TYPES_FILE]);
   for (const api of manifest.apis) files.add(api.file);
   for (const webhook of manifest.webhooks ?? []) files.add(webhook.file);
   for (const component of manifest.components) if (component.file !== null) files.add(component.file);
@@ -110,7 +112,7 @@ export async function inspectZopiaManifestStaleness(outputDir: string, identity:
     return {
       status: 'stale',
       reasons: ['invalid-manifest', ...(!identity.manifest ? ['manifest-disabled' as const] : [])],
-      ownedFiles: [ZOPIA_MANIFEST_FILE],
+      ownedFiles: [ZOPIA_MANIFEST_FILE, ZOPIA_TREE_TYPES_FILE],
     };
   }
 

package/src/conversions/manifest-writer.ts

@@ -16,7 +16,7 @@ export const ZOPIA_MANIFEST_SCHEMA = 'zopia:manifest@1' as const;
 export const ZOPIA_MANIFEST_FILE = '.zopia-manifest.json' as const;
 
 /** Package version recorded by the current manifest writer. */
-export const ZOPIA_VERSION = '0.4.0' as const;
+export const ZOPIA_VERSION = '0.5.1' as const;
 
 /** Supported source dialect labels stored in a manifest. */
 export type ZopiaManifestSourceKind = 'swagger-2.0' | 'openapi-3.0' | 'openapi-3.1';

package/src/conversions/openapi-to-api-docs-public.ts

@@ -12,6 +12,7 @@ import { normalizeOpenApiDocument, type OpenApiDocument } from './openapi';
 import { parseYaml } from './yaml';
 import { jsonSchemaToZod, type JsonSchema } from './json-schema-to-zod';
 import { hashOpenApiDocument, ZOPIA_MANIFEST_FILE } from './manifest-writer';
+import { ZOPIA_TREE_TYPES_FILE } from './api-docs-tree-types';
 import { formatManifestStaleness, inspectZopiaManifestStaleness } from './manifest-staleness';
 import { join } from 'node:path';
 import { planPresetBuckets, ZOPIA_GENERATE_PRESETS, type ZopiaGeneratePreset, type ZopiaPresetTree } from './api-docs-presets';
@@ -39,7 +40,7 @@ export interface ZopiaGeneratedFile {
   /** Portable path relative to `outDir`. */
   path: string;
   /** Generated artifact category. */
-  kind: 'endpoint' | 'component' | 'manifest';
+  kind: 'endpoint' | 'component' | 'manifest' | 'types';
 }
 
 /** Result returned by the Engine ③ public API. */
@@ -459,7 +460,7 @@ export async function openApiToApiDocs(input: string | Record<string, unknown>,
     : []);
   const files: ZopiaGeneratedFile[] = generated.map(({ file }): ZopiaGeneratedFile => ({
     path: file,
-    kind: file === ZOPIA_MANIFEST_FILE ? 'manifest' : componentFiles.has(file) ? 'component' : 'endpoint',
+    kind: file === ZOPIA_MANIFEST_FILE ? 'manifest' : file === ZOPIA_TREE_TYPES_FILE ? 'types' : componentFiles.has(file) ? 'component' : 'endpoint',
   })).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
   const warningCollector = new ZopiaWarningCollector(); warningCollector.addAll(warnings);
   return { files, warnings: warningCollector.toArray(), ...(config.manifest ? { manifestPath: ZOPIA_MANIFEST_FILE } : {}) };

package/src/runtime/create-api-docs.ts

@@ -17,6 +17,7 @@ import { isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { asZopiaError, ZopiaError } from '../errors';
 import { endpointExportName, uniqueEndpointName } from '../conversions/api-docs-names';
+import { apiDocsPathSegments, compareApiDocsEntries } from '../conversions/api-docs-layout';
 import { deriveOperationId, OPENAPI_METHODS, type OpenApiMethod } from '../conversions/openapi-to-api-docs';
 import { ZOPIA_MANIFEST_FILE } from '../conversions/manifest-writer';
 
@@ -65,11 +66,7 @@ interface DiscoveredManifest {
 const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);
 const compareText = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
 const isMissingFileError = (error: unknown): boolean => isRecord(error) && (error.code === 'ENOENT' || error.code === 'ENOTDIR');
-
-/** Split one OpenAPI path template into its literal segment keys (empty segments dropped, so `/` has none). */
-function pathSegments(path: string): string[] {
-  return path.split('/').filter(Boolean);
-}
+const isSupportedApiDocsMethod = (method: string): boolean => (OPENAPI_METHODS as readonly string[]).includes(method);
 
 /** Guard one manifest file reference: relative, POSIX-separated, and unable to escape the tree root. */
 function isSafeTreeFile(file: string): boolean {
@@ -87,7 +84,7 @@ function manifestApiEntries(manifest: unknown, manifestPath: string): Array<{ fi
     if (!isRecord(api)
       || typeof api.file !== 'string' || !isSafeTreeFile(api.file)
       || typeof api.path !== 'string' || !api.path.startsWith('/')
-      || typeof api.method !== 'string' || !(OPENAPI_METHODS as readonly string[]).includes(api.method)) {
+      || typeof api.method !== 'string' || !isSupportedApiDocsMethod(api.method)) {
       throw new ZopiaError('ZOPIA_MANIFEST_INVALID', `invalid zopia manifest API entry ${index}: ${manifestPath}`, { at: `${manifestPath}#apis/${index}`, hint: 'regenerate the tree to rebuild a valid manifest' });
     }
     entries.push({ file: api.file, path: api.path, method: api.method });
@@ -152,19 +149,7 @@ function mergeApiEntries(manifests: readonly DiscoveredManifest[]): MergedApiEnt
       merged.push({ root, file: api.file, path: api.path, method: api.method });
     }
   }
-  return merged.sort((left, right) => {
-    const leftSegments = pathSegments(left.path);
-    const rightSegments = pathSegments(right.path);
-    const depth = Math.min(leftSegments.length, rightSegments.length);
-    for (let index = 0; index < depth; index += 1) {
-      const order = compareText(leftSegments[index], rightSegments[index]);
-      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 merged.sort((left, right) => compareApiDocsEntries(left, right));
 }
 
 /** Import one generated endpoint module through its file URL — `pathToFileURL` keeps absolute (Windows-style) paths safe. */
@@ -231,6 +216,17 @@ function isEndpointConfig(value: unknown): value is ApiDocsEndpointConfig & Reco
  * tree always enumerates its keys in the same order. The tree is only read and
  * imported — nothing on disk is written.
  *
+ * **Exact IntelliSense (S-95):** every tree generated with a manifest also
+ * carries a `.zopia-tree.d.ts` declaration. Pass its `ApiDocsTree` type as the
+ * type argument to type the result exactly — literal path-segment keys,
+ * method-leaf configs typed as the generated module's own `makeApiConfig()`
+ * export, and unknown keys become compile errors:
+ *
+ * ```ts
+ * import type { ApiDocsTree } from './api_docs/.zopia-tree';
+ * const apiDocs = await createApiDocs<ApiDocsTree>('./api_docs');
+ * ```
+ *
  * @param docsDir Generated api-docs output directory (tree root or preset bucket root; absolute or relative).
  * @returns Nested tree keyed by exact URL path segments with lowercase-method leaves holding the endpoint configs.
  * @throws {ZopiaError} `ZOPIA_CONFIG_INVALID` when `docsDir` is not a usable path.
@@ -242,13 +238,14 @@ function isEndpointConfig(value: unknown): value is ApiDocsEndpointConfig & Reco
  * ```ts
  * import { createApiDocs } from './src/runtime';
  *
- * const apiDocs = await createApiDocs('api_docs');
- * const endpoint = apiDocs.users['{userId}'].get;
- * console.log(endpoint.method, endpoint.pathShape);
+ * // Exact typing: pass the generated `.zopia-tree.d.ts` tree type.
+ * type MyTree = { readonly users: { readonly get: { readonly pathShape: string } } };
+ * const apiDocs = await createApiDocs<MyTree>('api_docs');
+ * console.log(apiDocs.users.get.pathShape);
  * ```
  * @see [docs/07-api-docs.md → Runtime tree consumption](../../docs/07-api-docs.md)
  */
-export async function createApiDocs(docsDir: string): Promise<ApiDocsTree> {
+export async function createApiDocs<TTree extends object = ApiDocsTree>(docsDir: string): Promise<TTree> {
   if (typeof docsDir !== 'string' || docsDir.trim() === '' || docsDir.includes('\0')) {
     throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'docsDir must be a non-empty directory path', { at: 'docsDir', hint: 'provide the generated api-docs output directory (tree root or preset bucket root)' });
   }
@@ -265,9 +262,9 @@ export async function createApiDocs(docsDir: string): Promise<ApiDocsTree> {
     if (!isRecord(config)) {
       throw new ZopiaError('ZOPIA_DOCS_IMPORT_FAILED', `generated endpoint module has no default export: ${entry.file}`, { at: entry.file, hint: "regenerate the tree, or restore the module's default endpoint-config export" });
     }
-    insertEndpoint(tree, pathSegments(entry.path), entry.method, config, entry.file);
+    insertEndpoint(tree, apiDocsPathSegments(entry.path), entry.method, config, entry.file);
   }
-  return tree as ApiDocsTree;
+  return tree as unknown as TTree;
 }
 
 /**
@@ -283,20 +280,31 @@ export async function createApiDocs(docsDir: string): Promise<ApiDocsTree> {
  * a null prototype, so even an `operationId` spelled `__proto__` stays a plain
  * own key.
  *
- * @param apiDocs Nested tree returned by {@link createApiDocs}.
+ * **Exact IntelliSense (S-95):** pass the generated `.zopia-tree.d.ts`
+ * `ApiDocsFlat` type as the type argument to key the record exactly —
+ * `endpoints.getUser` autocompletes and unknown names become compile errors:
+ *
+ * ```ts
+ * import type { ApiDocsFlat } from './api_docs/.zopia-tree';
+ * const endpoints = flattenApiDocs<ApiDocsFlat>(apiDocs);
+ * ```
+ *
+ * @param apiDocs Nested tree returned by {@link createApiDocs} (exact generated tree types are accepted).
  * @returns Flat record of every endpoint config keyed by its derived endpoint name, in tree leaf order.
  * @throws {ZopiaError} `ZOPIA_CONFIG_INVALID` when `apiDocs` is not the nested tree object (a non-object input or a non-tree value inside it).
  * @throws {ZopiaError} `ZOPIA_SPEC_INVALID` when a leaf without a usable `operationId` cannot be named (its `pathShape` is not an OpenAPI `/`-rooted template or its `method` is not one of the eight standard methods).
  * @example
  * ```ts
- * import { createApiDocs, flattenApiDocs } from './src/runtime';
+ * import { createApiDocs, flattenApiDocs, type ApiDocsEndpointConfig } from './src/runtime';
  *
- * const endpoints = flattenApiDocs(await createApiDocs('api_docs'));
+ * // Exact typing: pass the generated `.zopia-tree.d.ts` flat type.
+ * type MyFlat = { readonly getUser: ApiDocsEndpointConfig };
+ * const endpoints = flattenApiDocs<MyFlat>(await createApiDocs('api_docs'));
  * console.log(endpoints.getUser.pathShape);
  * ```
  * @see [docs/07-api-docs.md → Runtime tree consumption](../../docs/07-api-docs.md)
  */
-export function flattenApiDocs(apiDocs: ApiDocsTree): Record<string, ApiDocsEndpointConfig> {
+export function flattenApiDocs<TFlat extends Record<string, ApiDocsEndpointConfig> = Record<string, ApiDocsEndpointConfig>>(apiDocs: object): TFlat {
   if (!isRecord(apiDocs)) {
     throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'flattenApiDocs expects the tree object returned by createApiDocs', { at: 'apiDocs', hint: 'pass the createApiDocs result (a nested object of endpoint configs)' });
   }
@@ -317,5 +325,5 @@ export function flattenApiDocs(apiDocs: ApiDocsTree): Record<string, ApiDocsEndp
     }
   };
   walk(apiDocs);
-  return flat;
+  return flat as unknown as TFlat;
 }