@nestia/sdk 14.0.0 → 14.0.2

package/src/executable/sdk.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import cp from "child_process";
 import fs from "fs";
+import path from "path";
 import process from "process";
 
 import { CommandParser } from "./internal/CommandParser";
@@ -31,13 +32,35 @@ function dependencies(argv: string[]): void {
   const module = options.manager ?? options.module ?? "npm";
   const prefix: string = module === "yarn" ? "yarn add" : `${module} install`;
 
-  for (const lib of ["@nestia/e2e", "@nestia/fetcher", "typia"]) {
+  // typia is the release the Nestia transform links, saved exactly: its latest
+  // may be another, which @nestia/core refuses
+  for (const lib of [
+    "@nestia/e2e",
+    "@nestia/fetcher",
+    `typia@${linkedTypiaVersion()} -E`,
+  ]) {
     const command: string = `${prefix} ${lib}`;
     console.log(`\n$ ${command}`);
     cp.execSync(command, { stdio: "inherit" });
   }
 }
 
+/**
+ * The typia release the Nestia transform links: the one `@nestia/core`
+ * resolves, which its exact dependency holds at that release.
+ */
+function linkedTypiaVersion(): string {
+  const core: string = path.dirname(
+    require.resolve("@nestia/core/package.json"),
+  );
+  return JSON.parse(
+    fs.readFileSync(
+      require.resolve("typia/package.json", { paths: [core] }),
+      "utf8",
+    ),
+  ).version;
+}
+
 async function initialize(): Promise<void> {
   if (fs.existsSync("nestia.config.ts") === true)
     halt(

package/src/factories/ExpressionFactory.ts

@@ -9,15 +9,36 @@ import {
  * Numeric-literal helper that handles negative values via a leading
  * `MinusToken` prefix unary, matching how the TypeScript factory itself emits
  * negative numeric literals.
+ *
+ * Infinity is written `1e999`, a numeric literal that evaluates to it and can
+ * also appear in a literal type; `Infinity` names a value, not a type.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the number literal builder.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ExpressionFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace ExpressionFactory {
+  /**
+   * Builds a numeric literal, with a prefix minus for a negative value.
+   *
+   * @evidence contracts/common.md#principled-implementation A negative literal is a prefix unary minus on a positive literal in the syntax tree, so the builder produces that shape.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the negative case.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ExpressionFactory.number constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const number = (
     value: number,
   ): NumericLiteral | PrefixUnaryExpression =>
     value < 0
       ? factory.createPrefixUnaryExpression(
           SyntaxKind.MinusToken,
-          factory.createNumericLiteral(Math.abs(value)),
+          literal(-value),
         )
-      : factory.createNumericLiteral(value);
+      : literal(value);
+
+  const literal = (value: number): NumericLiteral =>
+    factory.createNumericLiteral(value === Infinity ? "1e999" : value);
 }

package/src/factories/IdentifierFactory.ts

@@ -19,11 +19,23 @@ const isVariableName = (str: string): boolean => VARIABLE_REGEX.test(str);
 /**
  * Identifier and member-access helpers. The surface kept here is the subset
  * nestia generators actually call (`identifier`, `access`, `parameter`).
+ *
+ * @evidence contracts/common.md#principled-implementation The functions choose an identifier or a string literal by the syntax of the name, so any string can be a key.
+ * @evidence contracts/common.md#clear-and-simple-design Three functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The identifier test is inlined and conservative.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IdentifierFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace IdentifierFactory {
   /**
    * Build an identifier or string literal depending on whether `name` is a
    * valid JavaScript identifier.
+   *
+   * @evidence contracts/common.md#principled-implementation The name is tested against the identifier grammar, and a valid name outside the conservative pattern becomes an equivalent quoted key.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The test applies to every name.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the two results.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IdentifierFactory.identifier constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const identifier = (name: string): Identifier | StringLiteral =>
     isVariableName(name)
@@ -33,6 +45,12 @@ export namespace IdentifierFactory {
   /**
    * Member access on `input` by `key`. Falls back to element access when the
    * key is not a valid identifier.
+   *
+   * @evidence contracts/common.md#principled-implementation The key becomes a property when it is an identifier and an element access otherwise.
+   * @evidence contracts/common.md#clear-and-simple-design One function delegating the naming rule.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It never concatenates source text.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the forms.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IdentifierFactory.access constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const access = (
     input: Expression,
@@ -60,6 +78,12 @@ export namespace IdentifierFactory {
   /**
    * Parameter declaration with default `any` type when the caller omits one.
    * Passing a `QuestionToken` as `init` marks the parameter optional.
+   *
+   * @evidence contracts/common.md#principled-implementation The question token becomes the optional marker and any other initializer is passed through.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the optional marker.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IdentifierFactory.parameter constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const parameter = (
     name: string | Identifier,

package/src/factories/LiteralFactory.ts

@@ -1,4 +1,4 @@
-import { type Expression, factory } from "@ttsc/factory";
+import { type Expression, SyntaxKind, factory } from "@ttsc/factory";
 
 import { ExpressionFactory } from "./ExpressionFactory";
 import { IdentifierFactory } from "./IdentifierFactory";
@@ -15,40 +15,78 @@ const isNode = (value: unknown): value is Expression =>
   typeof (value as { kind?: unknown }).kind === "string";
 
 /**
- * Recursive value-to-AST-literal builder. Hands back already-AST inputs
- * unchanged (so callers can mix factory output with raw JS values inside the
- * same object/array), and emits the appropriate literal node otherwise.
+ * Recursive value-to-AST-literal builder. Arrow-function, call-expression and
+ * identifier nodes pass through only when the caller explicitly requests
+ * expression preservation. Ordinary values may contain the same `kind` names.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps values to literal nodes by type.
+ * @evidence contracts/common.md#clear-and-simple-design One function and two helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is by type.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation LiteralFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace LiteralFactory {
-  export const write = (input: any): Expression => {
+  /**
+   * Builds the expression of a value; arrow function, call, and identifier
+   * nodes pass through when `preserveExpressions` is true. Functions become
+   * `undefined`; other unsupported types throw, and object properties whose
+   * values are undefined are omitted.
+   *
+   * @evidence contracts/common.md#principled-implementation The value is dispatched by type in a fixed order and containers are written element by element.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The dispatch is general.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the mapping.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation LiteralFactory.write constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  export const write = (
+    input: any,
+    preserveExpressions = false,
+  ): Expression => {
     if (input === null) return factory.createNull();
-    if (isNode(input) && PASSTHROUGH_KINDS.has(input.kind)) return input;
-    if (Array.isArray(input)) return writeArray(input);
-    if (typeof input === "object") return writeObject(input as object);
+    if (
+      preserveExpressions &&
+      isNode(input) &&
+      PASSTHROUGH_KINDS.has(input.kind)
+    )
+      return input;
+    if (Array.isArray(input)) return writeArray(input, preserveExpressions);
+    if (typeof input === "object")
+      return writeObject(input as object, preserveExpressions);
     if (typeof input === "boolean")
       return input ? factory.createTrue() : factory.createFalse();
     if (typeof input === "number") return ExpressionFactory.number(input);
     if (typeof input === "string") return factory.createStringLiteral(input);
     if (typeof input === "bigint")
-      return factory.createStringLiteral(input.toString());
+      return input < BigInt(0)
+        ? factory.createPrefixUnaryExpression(
+            SyntaxKind.MinusToken,
+            factory.createBigIntLiteral((-input).toString()),
+          )
+        : factory.createBigIntLiteral(input.toString());
     if (typeof input === "function")
       return factory.createIdentifier("undefined");
     throw new TypeError("LiteralFactory.write: unsupported input type.");
   };
 
-  const writeObject = (obj: object): Expression =>
+  const writeObject = (obj: object, preserveExpressions: boolean): Expression =>
     factory.createObjectLiteralExpression(
       Object.entries(obj)
         .filter(([, value]) => value !== undefined)
         .map(([key, value]) =>
           factory.createPropertyAssignment(
             IdentifierFactory.identifier(key),
-            write(value),
+            write(value, preserveExpressions),
           ),
         ),
       true,
     );
 
-  const writeArray = (array: readonly any[]): Expression =>
-    factory.createArrayLiteralExpression(array.map(write), true);
+  const writeArray = (
+    array: readonly any[],
+    preserveExpressions: boolean,
+  ): Expression =>
+    factory.createArrayLiteralExpression(
+      array.map((value) => write(value, preserveExpressions)),
+      true,
+    );
 }

package/src/factories/StatementFactory.ts

@@ -8,8 +8,26 @@ import {
 
 import { TypeFactory } from "./TypeFactory";
 
-/** Variable-statement helpers. `constant` emits `const`, `mut` emits `let`. */
+/**
+ * Variable-statement helpers. `constant` emits `const`, `mut` emits `let`.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace builds `let` and `const` statements.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions, one for let and one for const.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation StatementFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace StatementFactory {
+  /**
+   * Builds a `let` statement; without a type and an initializer it is typed
+   * `any`.
+   *
+   * @evidence contracts/common.md#principled-implementation A declaration without either would be implicitly any, so the type is stated.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the default type.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation StatementFactory.mut constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const mut = (props: {
     name: string;
     type?: TypeNode | undefined;
@@ -34,6 +52,15 @@ export namespace StatementFactory {
       ),
     );
 
+  /**
+   * Builds a `const` statement from a name, a type, and a value.
+   *
+   * @evidence contracts/common.md#principled-implementation The declaration list carries the const flag and the given parts.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states its inputs.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation StatementFactory.constant constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const constant = (props: {
     name: string;
     type?: TypeNode | undefined;

package/src/factories/TypeFactory.ts

@@ -6,6 +6,12 @@ import { type KeywordTypeNode, SyntaxKind, factory } from "@ttsc/factory";
  * Wraps {@link factory.createKeywordTypeNode} with a name-based interface so
  * generator code reads as `TypeFactory.keyword("any")` instead of selecting the
  * `SyntaxKind.AnyKeyword` token by hand.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps names to the keyword syntax kinds.
+ * @evidence contracts/common.md#clear-and-simple-design One table, one type, and one function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TypeFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace TypeFactory {
   const KEYWORDS = {
@@ -20,8 +26,26 @@ export namespace TypeFactory {
     undefined: SyntaxKind.UndefinedKeyword,
   } as const;
 
+  /**
+   * The names of the supported keyword types.
+   *
+   * @evidence contracts/common.md#principled-implementation The type is the key set of the table, so a keyword is one table entry.
+   * @evidence contracts/common.md#clear-and-simple-design One derived type.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the set.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation TypeFactory.Keyword is the key union of the syntax-kind table and defines no native path conversion or process boundary.
+   */
   export type Keyword = keyof typeof KEYWORDS;
 
+  /**
+   * Builds the keyword type node of a name.
+   *
+   * @evidence contracts/common.md#principled-implementation The name is looked up in the table.
+   * @evidence contracts/common.md#clear-and-simple-design One lookup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states its input.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation TypeFactory.keyword constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const keyword = (type: Keyword): KeywordTypeNode =>
     factory.createKeywordTypeNode(KEYWORDS[type]);
 }

package/src/generates/CloneGenerator.ts

@@ -15,17 +15,38 @@ import { SdkHttpCloneProgrammer } from "./internal/SdkHttpCloneProgrammer";
 import { SdkHttpCloneReferencer } from "./internal/SdkHttpCloneReferencer";
 import { SdkWebSocketCloneProgrammer } from "./internal/SdkWebSocketCloneProgrammer";
 
+/**
+ * Writes the DTO declarations of the SDK: the `structures` files that the
+ * functions import when `clone` is on.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace composes the declarations from the analyzed types, rewrites the routes to reference them, and prints one file per top-level module.
+ * @evidence contracts/common.md#clear-and-simple-design One public function with two private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every declaration goes through the shared printer, and no type is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation The writer passes native output locations to Node fs and FilePrinter; module specifiers are produced separately by ImportDictionary. The structures suffix uses forward slashes, which Node accepts on Windows and POSIX, without treating spelling as canonical file identity.
+ */
 export namespace CloneGenerator {
+  /**
+   * Writes the `structures` directory of the SDK output.
+   *
+   * Structural route references are updated even when every JSON DTO is inline
+   * and no structure file is needed. WebSocket source cloning stays separate.
+   *
+   * @evidence contracts/common.md#principled-implementation HTTP and MCP JSON declarations share the analyzed collection; WebSocket sources are copied separately. Route references are updated even for inline-only graphs, then named modules are written sequentially so a failure stops at the first file.
+   * @evidence contracts/common.md#clear-and-simple-design One function over the two programmers, the referencer, and the file writer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The directory is created recursively and its failure is not swallowed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Node mkdir creates the output structures directory and FilePrinter writes generated declarations; WebSocket source lookup and copying remain delegated to its source-cloning owner. Filesystem errors propagate rather than being translated into platform-specific shell commands.
+   */
   export const write = async (app: ITypedApplication): Promise<void> => {
     const dict: Map<string, SdkHttpCloneProgrammer.IModule> =
       SdkHttpCloneProgrammer.write(app);
     const websocket: Set<string> = await SdkWebSocketCloneProgrammer.write(app);
-    if (dict.size === 0 && websocket.size === 0) return;
-
     SdkHttpCloneReferencer.replace(app, websocket);
-    try {
-      await fs.promises.mkdir(`${app.project.config.output}/structures`);
-    } catch {}
+    if (dict.size === 0 && websocket.size === 0) return;
+    await fs.promises.mkdir(`${app.project.config.output}/structures`, {
+      recursive: true,
+    });
     for (const [key, value] of dict)
       await writeDtoFile(app.project)(key, value);
   };

package/src/generates/E2eGenerator.ts

@@ -4,7 +4,26 @@ import path from "path";
 import { ITypedApplication } from "../structures/ITypedApplication";
 import { E2eFileProgrammer } from "./internal/E2eFileProgrammer";
 
+/**
+ * Writes the e2e test functions of the SDK.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace creates the output directories and writes one test file per HTTP route.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and one directory helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only HTTP routes have a test, and no route is skipped by name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation The output root is resolved with Node path.resolve, descendants use path.join and recursive fs.mkdir creates them. SDK import paths are passed to E2eFileProgrammer independently from native directory paths.
+ */
 export namespace E2eGenerator {
+  /**
+   * Writes one test function per HTTP route under `features/api/automated` of
+   * the e2e output directory, creating the directories as needed.
+   *
+   * @evidence contracts/common.md#principled-implementation The directories are created recursively, so an existing tree is reused, and each route's file is written in sequence.
+   * @evidence contracts/common.md#clear-and-simple-design One loop over the routes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts WebSocket and MCP routes are not tests of the HTTP SDK and are left out by protocol.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Native output and SDK roots use path.resolve and path.join before mkdir or file generation. No shell or filesystem case assumption participates; the generated HTTP route names have already passed accessor analysis.
+   */
   export const generate = async (app: ITypedApplication): Promise<void> => {
     console.log("Generating E2E Test Functions");
 

package/src/generates/SdkGenerator.ts

@@ -1,5 +1,4 @@
 import fs from "fs";
-import NodePath from "path";
 
 import { INestiaConfig } from "../INestiaConfig";
 import { IReflectOperationError } from "../structures/IReflectOperationError";
@@ -7,13 +6,34 @@ import { IReflectType } from "../structures/IReflectType";
 import { ITypedApplication } from "../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
 import { ITypedMcpRoute } from "../structures/ITypedMcpRoute";
+import { SDK_BUNDLE_PATH } from "../utils/SdkBundlePath";
 import { StringUtil } from "../utils/StringUtil";
 import { CloneGenerator } from "./CloneGenerator";
 import { SdkDistributionComposer } from "./internal/SdkDistributionComposer";
 import { SdkFileProgrammer } from "./internal/SdkFileProgrammer";
 import { SdkHttpParameterProgrammer } from "./internal/SdkHttpParameterProgrammer";
 
+/**
+ * Generates the SDK library and validates the analyzed routes it needs.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace bundles the static files, writes the DTOs and the functions, composes the distribution package, and reports the errors the generation would meet.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions, one public constant, and the private validators.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Validation and generation share the same route model.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Static bundle enumeration and output creation use Node fs; declaration/module path conversion and distribution process launching are delegated to ImportDictionary and SdkDistributionComposer. Existing file spelling is checked by the filesystem rather than an OS-name case rule.
+ */
 export namespace SdkGenerator {
+  /**
+   * Writes the SDK into the configured output directory: the bundled files, the
+   * DTOs when `clone` is on, the functions, and the distribution package when
+   * `distribute` is set.
+   *
+   * @evidence contracts/common.md#principled-implementation The steps run in dependency order, the bundle first and the distribution last. An absent output option throws before writing; a configured directory that does not exist is created recursively.
+   * @evidence contracts/common.md#clear-and-simple-design One function that delegates each step.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The steps are sequential and each awaits the previous one.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Node mkdir and the bundle writer accept the configured native output path; subsequent file and process boundaries belong to their delegated writers. Configuration omission is distinct from a missing on-disk directory.
+   */
   export const generate = async (app: ITypedApplication): Promise<void> => {
     if (app.project.config.output === undefined)
       throw new Error("Output directory is not defined.");
@@ -40,6 +60,18 @@ export namespace SdkGenerator {
       });
   };
 
+  /**
+   * Returns the errors of routes that cannot become an SDK: MCP tools with
+   * duplicate names or accessors, and, without `clone`, HTTP routes whose
+   * parameter or return types are implicit, plus implicit exception types when
+   * propagation is enabled.
+   *
+   * @evidence contracts/common.md#principled-implementation The MCP checks always apply, and the implicit return check applies only where the SDK would have to name the type, because `clone` writes it as a declaration instead.
+   * @evidence contracts/common.md#clear-and-simple-design One function over three checks.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is collected, not thrown, so one run reports every error.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Validation judges analyzed route types and names and performs no native filesystem or process operation.
+   */
   export const validate = (
     app: ITypedApplication,
   ): IReflectOperationError[] => {
@@ -118,7 +150,7 @@ export namespace SdkGenerator {
         props.errors.push({
           file: props.route.controller.file,
           class: props.route.controller.class.name,
-          function: props.route.name,
+          function: props.route.key,
           from: `parameter ${JSON.stringify(p.name)}`,
           contents: [`implicit (unnamed) parameter type.`],
         });
@@ -129,7 +161,7 @@ export namespace SdkGenerator {
           props.errors.push({
             file: props.route.controller.file,
             class: props.route.controller.class.name,
-            function: props.route.name,
+            function: props.route.key,
             from: `exception ${JSON.stringify(key)}`,
             contents: [`implicit (unnamed) exception type.`],
           });
@@ -140,7 +172,7 @@ export namespace SdkGenerator {
       props.errors.push({
         file: props.route.controller.file,
         class: props.route.controller.class.name,
-        function: props.route.name,
+        function: props.route.key,
         from: "success",
         contents: [`implicit (unnamed) return type.`],
       });
@@ -162,6 +194,12 @@ export namespace SdkGenerator {
    * Files the user already has are never touched, so that hand-written
    * customizations (e.g. extra re-exports in `module.ts`) survive regeneration.
    * Only missing files are filled in from the bundle.
+   *
+   * @evidence contracts/common.md#principled-implementation A file that the user has customized is never overwritten, and only files that are missing are filled in from the bundle.
+   * @evidence contracts/common.md#clear-and-simple-design One loop with two guards.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The existing target is checked before the write.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation fs.readdir/stat enumerate the installed bundle and fs.existsSync checks each target under the filesystem's own policy before writing UTF-8. Forward slash suffixes are accepted by Node on supported native platforms; concurrent generation into the same output is not an exclusive ownership guarantee.
    */
   export const bundle = async (output: string): Promise<void> => {
     const files: string[] = await fs.promises.readdir(BUNDLE_PATH);
@@ -177,12 +215,5 @@ export namespace SdkGenerator {
     }
   };
 
-  export const BUNDLE_PATH = NodePath.join(
-    __dirname,
-    "..",
-    "..",
-    "assets",
-    "bundle",
-    "api",
-  );
+  export const BUNDLE_PATH = SDK_BUNDLE_PATH;
 }