@nestia/sdk 14.0.1 → 14.0.3

package/src/generates/internal/SdkHttpCloneProgrammer.ts

@@ -15,13 +15,42 @@ import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 
+/**
+ * Composes the DTO declarations of the HTTP routes.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns each named object, alias and recursive collection into a declaration, placed in a tree of modules by its dotted name.
+ * @evidence contracts/common.md#clear-and-simple-design One declaration-tree operation dispatches object, alias and recursive collection bodies through their owning writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Implicit object and alias names are not declared; native-marked recursive collections supply named declarations so recursive references have a definition.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpCloneProgrammer {
+  /**
+   * A module of the declaration tree: its name, its children, and the writer of
+   * its own declaration.
+   *
+   * @evidence contracts/common.md#principled-implementation A module without a writer only holds children.
+   * @evidence contracts/common.md#clear-and-simple-design A three-member record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneProgrammer.IModule composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IModule {
     name: string;
     children: Map<string, IModule>;
     programmer: null | ((importer: ImportDictionary) => Node);
   }
 
+  /**
+   * Returns the declaration tree of the application's named types, keyed by
+   * their top-level name.
+   *
+   * @evidence contracts/common.md#principled-implementation Named objects and aliases are registered, and implicit names are skipped. Recursive arrays and tuples also need declarations: each writes one collection body whose nested uses are named references. Finite and object-mediated collections stay inline.
+   * @evidence contracts/common.md#clear-and-simple-design Four collection loops feed the same declaration tree, so all named forms share namespace and import decisions.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The implicit test is the shared definition.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write = (app: ITypedApplication): Map<string, IModule> => {
     // COMPOSE THE DICTIONARY
     const dict: Map<string, IModule> = new Map();
@@ -39,6 +68,32 @@ export namespace SdkHttpCloneProgrammer {
           name: k,
           programmer: (importer) => writeAlias(app.project)(importer)(v),
         });
+    for (const [k, v] of app.collection.arrays.entries())
+      if (v.recursive)
+        prepare({
+          dict,
+          name: k,
+          programmer: (importer) =>
+            factory.createTypeAliasDeclaration(
+              [factory.createModifier(SyntaxKind.ExportKeyword)],
+              StringUtil.accessorsOf(k).at(-1)!,
+              [],
+              SdkTypeProgrammer.write_array_type(app.project)(importer)(v),
+            ),
+        });
+    for (const [k, v] of app.collection.tuples.entries())
+      if (v.recursive)
+        prepare({
+          dict,
+          name: k,
+          programmer: (importer) =>
+            factory.createTypeAliasDeclaration(
+              [factory.createModifier(SyntaxKind.ExportKeyword)],
+              StringUtil.accessorsOf(k).at(-1)!,
+              [],
+              SdkTypeProgrammer.write_tuple_type(app.project)(importer)(v),
+            ),
+        });
     return dict;
   };
 

package/src/generates/internal/SdkHttpCloneReferencer.ts

@@ -1,13 +1,37 @@
+import { TsPrinter } from "@ttsc/factory";
+
 import { MetadataSchema, nameOf } from "../../internal/legacy";
+import { INestiaProject } from "../../structures/INestiaProject";
 import { IReflectType } from "../../structures/IReflectType";
 import { ITypedApplication } from "../../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
+import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
-import { StringUtil } from "../../utils/StringUtil";
+import { ImportDictionary } from "./ImportDictionary";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
+import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 import { SdkWebSocketCloneProgrammer } from "./SdkWebSocketCloneProgrammer";
 
+/**
+ * Rewrites the routes to refer to the cloned DTOs.
+ *
+ * @evidence contracts/common.md#principled-implementation HTTP and MCP JSON types and their namespace/tag imports are emitted together from resolved metadata by the cloned declaration writer; WebSocket declarations retain their source types and redirect only cloned imports.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and three visitors.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The routes are rewritten in place, once.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneReferencer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpCloneReferencer {
+  /**
+   * Rewrites the HTTP, MCP and WebSocket routes so their types and imports
+   * refer to the `structures` files.
+   *
+   * @evidence contracts/common.md#principled-implementation HTTP and MCP JSON routes use structural TypeNodes and the writer's registered imports. Empty and any/unknown forms retain their baked keyword distinction because they require no cloned component binding; WebSocket source types only redirect imports actually cloned.
+   * @evidence contracts/common.md#clear-and-simple-design One loop.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The routes are edited in place, as the generation owns them.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneReferencer.replace composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const replace = (
     app: ITypedApplication,
     websocket: Set<string> = new Set(),
@@ -16,7 +40,7 @@ export namespace SdkHttpCloneReferencer {
     for (const route of app.routes)
       if (route.protocol === "http")
         visitHttpRoute({
-          directory,
+          project: app.project,
           route,
         });
       else if (route.protocol === "websocket")
@@ -25,43 +49,70 @@ export namespace SdkHttpCloneReferencer {
           directory,
           route,
         });
+      else if (route.protocol === "mcp") visitMcpRoute(app.project, route);
+  };
+
+  const visitMcpRoute = (
+    project: INestiaProject,
+    route: ITypedMcpRoute,
+  ): void => {
+    const importer = new ImportDictionary(
+      `${project.config.output}/functional/${route.accessor.join("/")}/index.ts`,
+    );
+    if (route.input && route.inputMetadata)
+      visitType({
+        importer,
+        project,
+        metadata: route.inputMetadata,
+        type: route.input.type,
+        name: (name) => (route.input!.type = { name }),
+      });
+    if (route.returnType && route.outputMetadata)
+      visitType({
+        importer,
+        project,
+        metadata: route.outputMetadata,
+        type: route.returnType,
+        name: (name) => (route.returnType = { name }),
+      });
+    route.imports = importer.toImports();
   };
 
   const visitHttpRoute = (props: {
-    directory: string;
+    project: INestiaProject;
     route: ITypedHttpRoute;
   }): void => {
-    const unique: Set<string> = new Set();
+    const importer = new ImportDictionary(
+      `${props.project.config.output}/functional/${props.route.accessor.join("/")}/index.ts`,
+    );
     for (const p of SdkHttpParameterProgrammer.getSignificant(
       props.route,
       true,
     ))
       visitType({
-        unique,
+        importer,
+        project: props.project,
         metadata: p.metadata,
         type: p.type,
         name: (name) => (p.type = { name }),
       });
     for (const v of Object.values(props.route.exceptions))
       visitType({
-        unique,
+        importer,
+        project: props.project,
         metadata: v.metadata,
         type: v.type,
         name: (name) => (v.type = { name }),
       });
     if (props.route.success.binary === false)
       visitType({
-        unique,
+        importer,
+        project: props.project,
         metadata: props.route.success.metadata,
         type: props.route.success.type,
         name: (name) => (props.route.success.type = { name }),
       });
-    props.route.imports = Array.from(unique).map((str) => ({
-      file: `${props.directory}/${str}`,
-      asterisk: null,
-      default: null,
-      elements: [str],
-    }));
+    props.route.imports = importer.toImports();
   };
 
   const visitWebSocketRoute = (props: {
@@ -113,20 +164,43 @@ export namespace SdkHttpCloneReferencer {
   };
 
   const visitType = (p: {
-    unique: Set<string>;
+    importer: ImportDictionary;
+    project: INestiaProject;
     metadata: MetadataSchema;
     type: IReflectType;
     name: (key: string) => void;
   }): void => {
-    const enroll = (key: string) => {
-      if (key.length && StringUtil.isImplicit(key) === false)
-        p.unique.add(StringUtil.accessorsOf(key)[0]!);
-    };
-    for (const alias of p.metadata.aliases) enroll(alias.type!.name);
-    for (const array of p.metadata.arrays) enroll(array.type!.name);
-    for (const tuple of p.metadata.tuples) enroll(tuple.type!.name);
-    for (const object of p.metadata.objects) enroll(object.type!.name);
-    p.name(nameOf(p.metadata));
+    // Empty and any/unknown metadata carries no structural declaration from
+    // which to recover its source-level keyword distinction. These forms require
+    // no cloned component binding; retain the producer's baked name (or declared
+    // route type for authored metadata without a bake).
+    if (
+      p.metadata.any ||
+      (p.metadata.nullable === false &&
+        p.metadata.escaped === null &&
+        p.metadata.rest === null &&
+        [
+          p.metadata.atomics,
+          p.metadata.constants,
+          p.metadata.templates,
+          p.metadata.arrays,
+          p.metadata.tuples,
+          p.metadata.objects,
+          p.metadata.aliases,
+          p.metadata.natives,
+          p.metadata.sets,
+          p.metadata.maps,
+          p.metadata.functions,
+        ].every((members) => members.length === 0))
+    ) {
+      p.name(nameOf(p.metadata) || getFullText(p.type));
+      return;
+    }
+    p.name(
+      new TsPrinter().print(
+        SdkTypeProgrammer.write(p.project)(p.importer)(p.metadata),
+      ),
+    );
   };
 }
 

package/src/generates/internal/SdkHttpFunctionProgrammer.ts

@@ -20,7 +20,26 @@ import { SdkAliasCollection } from "./SdkAliasCollection";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkImportWizard } from "./SdkImportWizard";
 
+/**
+ * Writes the function of an HTTP route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace prints the exported async function with its parameters and the fetcher call and its headers.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and the body writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The names come from the parameter programmer.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpFunctionProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpFunctionProgrammer {
+  /**
+   * Returns the exported async function of a route: `connection`, then the
+   * parameters, returning the output or `void`.
+   *
+   * @evidence contracts/common.md#principled-implementation The identifiers were decided once by the parameter programmer, and the body calls the plain or the encrypted fetcher.
+   * @evidence contracts/common.md#clear-and-simple-design One declaration built from the parameter and body helpers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The function uses the route's assigned name; SdkFileProgrammer may assign a private binding and export it under the public accessor when the module scope collides.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpFunctionProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>

package/src/generates/internal/SdkHttpNamespaceProgrammer.ts

@@ -26,7 +26,26 @@ import { SdkHttpSimulationProgrammer } from "./SdkHttpSimulationProgrammer";
 import { SdkImportWizard } from "./SdkImportWizard";
 import { SdkPathTemplate } from "./SdkPathTemplate";
 
+/**
+ * Writes the namespace of an HTTP route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the route's types, its metadata, its path builder, and, when configured, its random, simulate, and stringify functions.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and four writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The parts follow the configuration.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpNamespaceProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpNamespaceProgrammer {
+  /**
+   * Returns the namespace of a route: its types, `METADATA`, `path`, and, by
+   * configuration, `random`, `simulate`, and `stringify`.
+   *
+   * @evidence contracts/common.md#principled-implementation `stringify` exists only for a JSON or encrypted body when `json` is on, and the simulator only when `simulate` is on.
+   * @evidence contracts/common.md#clear-and-simple-design One declaration composed of the writers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The optional members follow the flags.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpNamespaceProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>

package/src/generates/internal/SdkHttpParameterProgrammer.ts

@@ -13,7 +13,26 @@ import { StringUtil } from "../../utils/StringUtil";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkAliasCollection } from "./SdkAliasCollection";
 
+/**
+ * The parameters of an HTTP route's SDK function.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace decides the identifiers, lists the entries, and writes the declarations and the arguments in positional or keyword mode.
+ * @evidence contracts/common.md#clear-and-simple-design Several small functions over one entry type.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The three consumers share one decision.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpParameterProgrammer {
+  /**
+   * One parameter of a route: its key, whether it is required, its type, and
+   * the reflected parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation The record is what a declaration or an argument needs.
+   * @evidence contracts/common.md#clear-and-simple-design A four-member record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.IEntry composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IEntry {
     key: string;
     required: boolean;
@@ -40,6 +59,12 @@ export namespace SdkHttpParameterProgrammer {
    * generated code actually references for this route and configuration, and an
    * own identifier yields only to the names its scope can see, so nothing is
    * renamed where no name is shadowed.
+   *
+   * @evidence contracts/common.md#principled-implementation One decision serves the three scopes, so they cannot disagree.
+   * @evidence contracts/common.md#clear-and-simple-design A record of names and two lookups.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.INames composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export interface INames {
     connection: string;
@@ -52,13 +77,39 @@ export namespace SdkHttpParameterProgrammer {
     value: string;
     elem: string;
 
-    /** Local identifier of a significant parameter in positional mode. */
+    /**
+     * Local identifier of a significant parameter in positional mode.
+     *
+     * @evidence contracts/common.md#principled-implementation A parameter yields to a name the SDK cannot change and keeps its own otherwise.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the decision.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.INames.parameter composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
     parameter: (p: ITypedHttpRouteParameter) => string;
 
-    /** Reads a significant parameter: `props.<name>` or its local. */
+    /**
+     * Reads a significant parameter: `props.<name>` or its local.
+     *
+     * @evidence contracts/common.md#principled-implementation The read follows the mode of the function.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the decision.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.INames.access composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
     access: (p: ITypedHttpRouteParameter) => Expression;
   }
 
+  /**
+   * Decides the identifiers of a route's function, `path()`, and `simulate()`
+   * once.
+   *
+   * @evidence contracts/common.md#principled-implementation The fixed names each scope references are collected, and every own identifier avoids them and the other own identifiers it can see.
+   * @evidence contracts/common.md#clear-and-simple-design One function over the scope sets.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only shadowed names are renamed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.getNames composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getNames = (props: {
     project: INestiaProject;
     route: ITypedHttpRoute;
@@ -172,6 +223,16 @@ export namespace SdkHttpParameterProgrammer {
     };
   };
 
+  /**
+   * Returns every parameter of a route: path, query, header, query object,
+   * body, and header object.
+   *
+   * @evidence contracts/common.md#principled-implementation The list is the concatenation in that order.
+   * @evidence contracts/common.md#clear-and-simple-design One list.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds no parameter.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.getAll composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getAll = (
     route: ITypedHttpRoute,
   ): ITypedHttpRouteParameter[] => [
@@ -183,6 +244,16 @@ export namespace SdkHttpParameterProgrammer {
     ...(route.headerObject ? [route.headerObject] : []),
   ];
 
+  /**
+   * Returns the parameters that make up a call: path, query, the query object,
+   * and the body when asked.
+   *
+   * @evidence contracts/common.md#principled-implementation Headers travel in the connection and are not arguments.
+   * @evidence contracts/common.md#clear-and-simple-design One list.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The body is included by the caller's choice.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.getSignificant composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getSignificant = (route: ITypedHttpRoute, body: boolean) => [
     ...route.pathParameters,
     ...route.queryParameters,
@@ -190,6 +261,17 @@ export namespace SdkHttpParameterProgrammer {
     ...(body && route.body ? [route.body] : []),
   ];
 
+  /**
+   * Returns the entries of a route: path and query parameters, the query
+   * object, and the body when asked, with the type each has in the function or
+   * in the test.
+   *
+   * @evidence contracts/common.md#principled-implementation The type is the alias `Query` or `Body` in the function, and the reflected or cloned type in a test.
+   * @evidence contracts/common.md#clear-and-simple-design One list of three groups.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An empty route has no entries.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.getEntries composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getEntries = (props: {
     project: INestiaProject;
     importer: ImportDictionary;
@@ -262,6 +344,16 @@ export namespace SdkHttpParameterProgrammer {
     ];
   };
 
+  /**
+   * Returns the parameter declarations of a route's function: one `props`
+   * object in keyword mode, and one positional parameter per entry otherwise.
+   *
+   * @evidence contracts/common.md#principled-implementation A required parameter cannot follow an optional one, so an optional one before a required one trades its `?` for `undefined` in its type.
+   * @evidence contracts/common.md#clear-and-simple-design One function of two modes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names come from `getNames`.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.getParameterDeclarations composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getParameterDeclarations = (props: {
     project: INestiaProject;
     importer: ImportDictionary;
@@ -328,6 +420,16 @@ export namespace SdkHttpParameterProgrammer {
           factory.createKeywordTypeNode(SyntaxKind.UndefinedKeyword),
         ]);
 
+  /**
+   * Returns the arguments to call a route's function with: the `props` object
+   * in keyword mode, and the parameters otherwise.
+   *
+   * @evidence contracts/common.md#principled-implementation The identifiers are those declared by `getNames`.
+   * @evidence contracts/common.md#clear-and-simple-design One function of two modes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No argument is invented for an empty route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpParameterProgrammer.getArguments composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getArguments = (props: {
     project: INestiaProject;
     route: ITypedHttpRoute;

package/src/generates/internal/SdkHttpRouteProgrammer.ts

@@ -9,7 +9,27 @@ import { SdkHttpFunctionProgrammer } from "./SdkHttpFunctionProgrammer";
 import { SdkHttpNamespaceProgrammer } from "./SdkHttpNamespaceProgrammer";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 
+/**
+ * Writes an HTTP route into the SDK: its function and its namespace.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace pairs the two declarations and describes the function.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and one description helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The description is from the route's own comment.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpRouteProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpRouteProgrammer {
+  /**
+   * Returns the function and the namespace of a route, the function carrying
+   * the route's description, `@param`, and exception tags, and a `@nestia`
+   * postfix.
+   *
+   * @evidence contracts/common.md#principled-implementation The two nodes share the identifiers of one decision.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The description keeps the names the function declares.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpRouteProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>

package/src/generates/internal/SdkHttpSimulationProgrammer.ts

@@ -23,7 +23,32 @@ import { SdkAliasCollection } from "./SdkAliasCollection";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkImportWizard } from "./SdkImportWizard";
 
+/**
+ * Writes the mockup functions of an HTTP route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace prints random for the response type and simulate for structural parameter assertions followed by random response creation. Simulation operates on typed SDK arguments rather than parsing HTTP transport values.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions and their helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Generated validation calls typia.assert through NestiaSimulator's error adapter. It does not reproduce arbitrary server pipes or the server transform's prune and equality modes; simulation rejects structural type violations without contacting a server.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * efficient algorithms: Response construction has a fixed AST skeleton; request assertion emission visits significant parameters once and allocates one validator expression per parameter. Type and parameter projection costs belong to the called programmers.
+ * reuse equivalent work: These writers construct route-specific mutable AST nodes and coordinate no completed or in-flight generation across requests.
+ * bound retention and release resources: Returned ASTs transfer to the file writer. The emitted binary random function closes its empty stream during construction; the programmer itself retains no stream or producer task.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpSimulationProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpSimulationProgrammer {
+  /**
+   * Returns `random`: it makes a value of the response, a closed empty stream
+   * for a binary one. Binary readers receive EOF without waiting for payload.
+   *
+   * @evidence contracts/common.md#principled-implementation Ordinary responses call typia.random of the output type. Binary responses construct a stream with the existing binary chunk type and a start callback that closes its own controller synchronously; no bytes are enqueued, so the first read reports EOF under Streams semantics.
+   * @evidence contracts/common.md#clear-and-simple-design The existing binary versus ordinary expression branch owns response generation. Its inline stream source supplies closure without another runtime helper, import or transport.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The binary case has no random content.
+   * @evidence contracts/common.md#meaningful-documentation The prose states that binary random output is closed and readers receive EOF without waiting for payload.
+   * bound retention and release resources: The emitted binary source queues no bytes or producer task and closes each empty stream during construction. The writer returns its AST without retaining stream handles; runtime readers belong to the generated SDK caller.
+   * efficient algorithms: After response-type projection, either branch allocates a fixed AST skeleton; the binary branch emits one empty stream constructor without traversing or generating payload bytes.
+   * reuse equivalent work: The returned AST belongs to this route and importer. Each generated runtime call needs its own random value or stream, so neither mutable syntax nor runtime response identity is shared.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpSimulationProgrammer.random composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const random =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -47,7 +72,34 @@ export namespace SdkHttpSimulationProgrammer {
             ? factory.createNewExpression(
                 factory.createIdentifier("ReadableStream"),
                 [SdkAliasCollection.binaryChunk() as TypeNode],
-                [],
+                [
+                  factory.createObjectLiteralExpression([
+                    factory.createPropertyAssignment(
+                      "start",
+                      factory.createArrowFunction(
+                        undefined,
+                        undefined,
+                        [
+                          factory.createParameterDeclaration(
+                            undefined,
+                            undefined,
+                            "controller",
+                          ),
+                        ],
+                        undefined,
+                        undefined,
+                        factory.createCallExpression(
+                          IdentifierFactory.access(
+                            factory.createIdentifier("controller"),
+                            "close",
+                          ),
+                          undefined,
+                          [],
+                        ),
+                      ),
+                    ),
+                  ]),
+                ],
               )
             : factory.createCallExpression(
                 IdentifierFactory.access(
@@ -61,6 +113,19 @@ export namespace SdkHttpSimulationProgrammer {
       );
     };
 
+  /**
+   * Returns `simulate`: it asserts the parameters and returns a random output,
+   * wrapped as a propagation when configured.
+   *
+   * @evidence contracts/common.md#principled-implementation The status of the wrapper is the declared one or the method's default. A response without a content type has no Content-Type entry; a declared media type supplies a string header, preserving the propagation header contract.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The parameters are validated before a response is made.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * efficient algorithms: Parameter declarations and assertion nodes grow linearly with significant route parameters; propagation adds a fixed response wrapper and one catch block. The private assertion writer handles the connection headers separately rather than duplicating every parameter validation.
+   * reuse equivalent work: Simulation syntax contains this route's names, arguments, output type and importer aliases; this operation coordinates no reusable result across generation requests.
+   * bound retention and release resources: This function returns an AST to its caller and owns no retained cache, stream, handle or background task; runtime random response creation is documented by random.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpSimulationProgrammer.simulate composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const simulate =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -125,9 +190,11 @@ export namespace SdkHttpSimulationProgrammer {
                           ),
                           factory.createPropertyAssignment(
                             "headers",
-                            LiteralFactory.write({
-                              "Content-Type": route.success.contentType,
-                            }),
+                            LiteralFactory.write(
+                              route.success.contentType === null
+                                ? {}
+                                : { "Content-Type": route.success.contentType },
+                            ),
                           ),
                           factory.createPropertyAssignment("data", caller()),
                         ],
@@ -240,7 +307,7 @@ export namespace SdkHttpSimulationProgrammer {
           ),
         )
         .map(factory.createExpressionStatement);
-      // the headers travel in the connection, validated as the server does
+      // Headers travel in the connection and receive a structural assertion.
       if (route.headerObject !== null)
         individual.push(
           factory.createExpressionStatement(