@nestia/sdk 14.0.1 → 14.0.2

package/lib/structures/IReflectMcpOperation.d.ts

@@ -1,4 +1,5 @@
 import { IJsDocTagInfo } from "typia";
+import { IOperationMetadata } from "./IOperationMetadata";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectMcpOperationParameter } from "./IReflectMcpOperationParameter";
 import { IReflectType } from "./IReflectType";
@@ -8,6 +9,12 @@ import { IReflectType } from "./IReflectType";
  * Produced by {@link ReflectMcpOperationAnalyzer.analyze}; consumed by
  * {@link TypedMcpRouteAnalyzer.analyze} to produce the final
  * {@link ITypedMcpRoute}.
+ *
+ * @evidence contracts/common.md#principled-implementation The record joins the route metadata of the decorator with the compile-time metadata.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectMcpOperation describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
  */
 export interface IReflectMcpOperation {
     protocol: "mcp";
@@ -21,11 +28,23 @@ export interface IReflectMcpOperation {
     function: Function;
     parameters: IReflectMcpOperationParameter[];
     returnType: IReflectType | null;
+    /** Native JSON return analysis; optional for source-only reflected inputs. */
+    returnMetadata?: IOperationMetadata.IResponse["primitive"];
     imports: IReflectImport[];
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
 }
 export declare namespace IReflectMcpOperation {
+    /**
+     * The behavior hints of a tool: read-only, destructive, idempotent, and
+     * open-world.
+     *
+     * @evidence contracts/common.md#principled-implementation The four optional flags are the hints the MCP protocol defines.
+     * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+     * @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 type describes; its members are named for their meaning.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectMcpOperation.IAnnotations describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     interface IAnnotations {
         readOnlyHint?: boolean;
         destructiveHint?: boolean;

package/lib/structures/IReflectMcpOperationParameter.d.ts

@@ -1,16 +1,25 @@
 import { IJsDocTagInfo } from "typia";
+import { IOperationMetadata } from "./IOperationMetadata";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectType } from "./IReflectType";
 /**
  * Parameter descriptor for an MCP tool method. Reflected from
  * `"nestia/McpRoute/Parameters"` metadata plus compile-time type information
  * collected by the nestia transformer.
+ *
+ * @evidence contracts/common.md#principled-implementation A tool has at most one parameter, and the record is what the SDK needs to type it.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectMcpOperationParameter describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
  */
 export interface IReflectMcpOperationParameter {
     category: "params";
     name: string;
     index: number;
     type: IReflectType;
+    /** Native JSON wire analysis, retained independently of the source import. */
+    metadata?: IOperationMetadata.IResponse["primitive"];
     imports: IReflectImport[];
     description: string | null;
     jsDocTags: IJsDocTagInfo[];

package/lib/structures/IReflectOperationError.d.ts

@@ -1,5 +1,15 @@
 import { IComparable } from "tstl";
 import { IOperationMetadata } from "../structures/IOperationMetadata";
+/**
+ * An error or warning of the reflection: the file, the class, the function, the
+ * origin, and the contents.
+ *
+ * @evidence contracts/common.md#principled-implementation The members locate a problem down to the part of a function, and the namespace's key orders errors by that location so a report groups them.
+ * @evidence contracts/common.md#clear-and-simple-design A record and one key class in its namespace.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior. The key class only compares fields.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the record locates.
+ * @evidence contracts/portability.md#os-neutral-implementation file carries the original native source identity for diagnostics; class, function and from identify declarations rather than filesystem components.
+ */
 export interface IReflectOperationError {
     file: string;
     class: string;
@@ -8,9 +18,27 @@ export interface IReflectOperationError {
     contents: Array<string | IOperationMetadata.IError>;
 }
 export declare namespace IReflectOperationError {
+    /**
+     * An ordering key of an error: file, then class, then function, then origin.
+     *
+     * @evidence contracts/common.md#principled-implementation The key implements the strict weak order over the four fields that tstl's tree map requires, with an absent value ordered as the empty string.
+     * @evidence contracts/common.md#clear-and-simple-design One class with one method.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It compares fields and holds no state beyond the error.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the order.
+     * @evidence contracts/portability.md#os-neutral-implementation The key retains supplied source file spelling and declaration identifiers. Ordering is lexical for diagnostic grouping without asserting filesystem case or symlink equivalence.
+     */
     class Key implements Pick<IComparable<Key>, "less"> {
         readonly error: IReflectOperationError;
         constructor(error: IReflectOperationError);
+        /**
+         * Returns whether this key orders before the other.
+         *
+         * @evidence contracts/common.md#principled-implementation The fields are compared in order and the first that differs decides, which is a lexicographic order.
+         * @evidence contracts/common.md#clear-and-simple-design One method of chained comparisons.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts It compares only the four location fields.
+         * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+         * @evidence contracts/portability.md#os-neutral-implementation Comparison orders source identity strings and declaration fields lexically; it neither canonicalizes native paths nor treats ordering as filesystem equivalence.
+         */
         less(obj: Key): boolean;
     }
 }

package/lib/structures/IReflectOperationError.js

@@ -3,18 +3,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.IReflectOperationError = void 0;
 var IReflectOperationError;
 (function (IReflectOperationError) {
+    /**
+     * An ordering key of an error: file, then class, then function, then origin.
+     *
+     * @evidence contracts/common.md#principled-implementation The key implements the strict weak order over the four fields that tstl's tree map requires, with an absent value ordered as the empty string.
+     * @evidence contracts/common.md#clear-and-simple-design One class with one method.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It compares fields and holds no state beyond the error.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the order.
+     * @evidence contracts/portability.md#os-neutral-implementation The key retains supplied source file spelling and declaration identifiers. Ordering is lexical for diagnostic grouping without asserting filesystem case or symlink equivalence.
+     */
     class Key {
         constructor(error) {
             this.error = error;
         }
+        /**
+         * Returns whether this key orders before the other.
+         *
+         * @evidence contracts/common.md#principled-implementation The fields are compared in order and the first that differs decides, which is a lexicographic order.
+         * @evidence contracts/common.md#clear-and-simple-design One method of chained comparisons.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts It compares only the four location fields.
+         * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+         * @evidence contracts/portability.md#os-neutral-implementation Comparison orders source identity strings and declaration fields lexically; it neither canonicalizes native paths nor treats ordering as filesystem equivalence.
+         */
         less(obj) {
             var _a, _b, _c, _d;
             if (this.error.file !== obj.error.file)
                 return this.error.file < obj.error.file;
             else if (this.error.class !== obj.error.class)
                 return this.error.class < obj.error.class;
-            else if (this.error.function !== obj.error.function)
-                return ((_a = this.error.function) !== null && _a !== void 0 ? _a : "") < ((_b = obj.error.function) !== null && _b !== void 0 ? _b : "");
+            const leftFunction = (_a = this.error.function) !== null && _a !== void 0 ? _a : "";
+            const rightFunction = (_b = obj.error.function) !== null && _b !== void 0 ? _b : "";
+            if (leftFunction !== rightFunction)
+                return leftFunction < rightFunction;
             return ((_c = this.error.from) !== null && _c !== void 0 ? _c : "") < ((_d = obj.error.from) !== null && _d !== void 0 ? _d : "");
         }
     }

package/lib/structures/IReflectOperationError.js.map

@@ -1 +1 @@
-{"version":3,"file":"IReflectOperationError.js","sourceRoot":"","sources":["../../src/structures/IReflectOperationError.ts"],"names":[],"mappings":";;;AAWA,IAAiB,sBAAsB,CActC;AAdD,WAAiB,sBAAsB;IACrC,MAAa,GAAG;QACd,YAAmC,KAA6B;yBAA7B,KAAK;QAA2B,CAAC;QAE7D,IAAI,CAAC,GAAQ;;YAClB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,KAAK,CAAC,IAAI;gBACpC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;iBACrC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK,CAAC,KAAK;gBAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;iBACvC,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,KAAK,GAAG,CAAC,KAAK,CAAC,QAAQ;gBACjD,OAAO,OAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,mCAAI,EAAE,CAAC,GAAG,OAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,mCAAI,EAAE,CAAC,CAAC;YAClE,OAAO,OAAC,IAAI,CAAC,KAAK,CAAC,IAAI,mCAAI,EAAE,CAAC,GAAG,OAAC,GAAG,CAAC,KAAK,CAAC,IAAI,mCAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;KACF;IAZY,uBAAA,GAAG,MAYf,CAAA;AACH,CAAC,EAdgB,sBAAsB,aAAtB,sBAAsB,GAAtB,sBAAsB,QActC"}
+{"version":3,"file":"IReflectOperationError.js","sourceRoot":"","sources":["../../src/structures/IReflectOperationError.ts"],"names":[],"mappings":";;;AAqBA,IAAiB,sBAAsB,CAiCtC;AAjCD,WAAiB,sBAAsB;IACrC;;;;;;;;OAQG;IACH,MAAa,GAAG;QACd,YAAmC,KAA6B;yBAA7B,KAAK;QAA2B,CAAC;QAEpE;;;;;;;;WAQG;QACI,IAAI,CAAC,GAAQ;;YAClB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,KAAK,CAAC,IAAI;gBACpC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;iBACrC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK,CAAC,KAAK;gBAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;YAC5C,MAAM,YAAY,SAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,mCAAI,EAAE,CAAC;YAC/C,MAAM,aAAa,SAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,mCAAI,EAAE,CAAC;YAC/C,IAAI,YAAY,KAAK,aAAa;gBAAE,OAAO,YAAY,GAAG,aAAa,CAAC;YACxE,OAAO,OAAC,IAAI,CAAC,KAAK,CAAC,IAAI,mCAAI,EAAE,CAAC,GAAG,OAAC,GAAG,CAAC,KAAK,CAAC,IAAI,mCAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;KACF;IAtBY,uBAAA,GAAG,MAsBf,CAAA;AACH,CAAC,EAjCgB,sBAAsB,aAAtB,sBAAsB,GAAtB,sBAAsB,QAiCtC"}

package/lib/structures/IReflectType.d.ts

@@ -1,3 +1,12 @@
+/**
+ * A reflected type: its name and, for a generic, its type arguments.
+ *
+ * @evidence contracts/common.md#principled-implementation The name is the text the transform recorded and the arguments make the type recursive.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectType describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface IReflectType {
     name: string;
     typeArguments?: IReflectType[];

package/lib/structures/IReflectWebSocketOperation.d.ts

@@ -2,6 +2,16 @@ import { VERSION_NEUTRAL } from "@nestjs/common";
 import { IJsDocTagInfo } from "typia";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectWebSocketOperationParameter } from "./IReflectWebSocketOperationParameter";
+/**
+ * A reflected WebSocket operation: its name, paths, function, versions,
+ * parameters, and imports.
+ *
+ * @evidence contracts/common.md#principled-implementation The record joins the route metadata of the decorator with the compile-time metadata.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperation describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface IReflectWebSocketOperation {
     protocol: "websocket";
     name: string;

package/lib/structures/IReflectWebSocketOperationParameter.d.ts

@@ -1,12 +1,67 @@
 import { IJsDocTagInfo } from "typia";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectType } from "./IReflectType";
+/**
+ * A parameter of a WebSocket operation: an acceptor, a driver, a header, a path
+ * parameter, or a query.
+ *
+ * @evidence contracts/common.md#principled-implementation The union is discriminated by `category`, and a preconfigured form carries what the decorators alone record.
+ * @evidence contracts/common.md#clear-and-simple-design A union of five records plus the preconfigured form.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export type IReflectWebSocketOperationParameter = IReflectWebSocketOperationParameter.IAcceptor | IReflectWebSocketOperationParameter.IDriver | IReflectWebSocketOperationParameter.IHeader | IReflectWebSocketOperationParameter.IParam | IReflectWebSocketOperationParameter.IQuery;
 export declare namespace IReflectWebSocketOperationParameter {
+    /**
+     * The parameter category `acceptor` of a WebSocket operation.
+     *
+     * @evidence contracts/common.md#principled-implementation The alias fixes the category of the shared base.
+     * @evidence contracts/common.md#clear-and-simple-design One alias.
+     * @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 category.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IAcceptor describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export type IAcceptor = IBase<"acceptor">;
+    /**
+     * The parameter category `driver` of a WebSocket operation.
+     *
+     * @evidence contracts/common.md#principled-implementation The alias fixes the category of the shared base.
+     * @evidence contracts/common.md#clear-and-simple-design One alias.
+     * @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 category.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IDriver describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export type IDriver = IBase<"driver">;
+    /**
+     * The parameter category `header` of a WebSocket operation.
+     *
+     * @evidence contracts/common.md#principled-implementation The alias fixes the category of the shared base.
+     * @evidence contracts/common.md#clear-and-simple-design One alias.
+     * @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 category.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IHeader describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export type IHeader = IBase<"header">;
+    /**
+     * The parameter category `query` of a WebSocket operation.
+     *
+     * @evidence contracts/common.md#principled-implementation The alias fixes the category of the shared base.
+     * @evidence contracts/common.md#clear-and-simple-design One alias.
+     * @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 category.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IQuery describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export type IQuery = IBase<"query">;
+    /**
+     * A path parameter of a WebSocket operation with its field name.
+     *
+     * @evidence contracts/common.md#principled-implementation The record adds the field that names the path placeholder to the shared base.
+     * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+     * @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 type describes; its members are named for their meaning.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IParam describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export interface IParam extends IBase<"param"> {
         field: string;
     }

package/lib/structures/ITypedApplication.d.ts

@@ -3,6 +3,16 @@ import { INestiaProject } from "./INestiaProject";
 import { ITypedHttpRoute } from "./ITypedHttpRoute";
 import { ITypedMcpRoute } from "./ITypedMcpRoute";
 import { ITypedWebSocketRoute } from "./ITypedWebSocketRoute";
+/**
+ * The typed application: the project, the metadata dictionary, and the typed
+ * routes.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the input of every generator.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedApplication describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedApplication {
     project: INestiaProject;
     collection: IMetadataDictionary;

package/lib/structures/ITypedHttpRoute.d.ts

@@ -4,6 +4,16 @@ import { IReflectImport } from "./IReflectImport";
 import { ITypedHttpRouteException } from "./ITypedHttpRouteException";
 import { ITypedHttpRouteParameter } from "./ITypedHttpRouteParameter";
 import { ITypedHttpRouteSuccess } from "./ITypedHttpRouteSuccess";
+/**
+ * A typed HTTP route: one path of an operation with its parameters split by
+ * kind, its success, its exceptions, and its documentation.
+ *
+ * @evidence contracts/common.md#principled-implementation The reflected operation is expanded per path and its parameters are classified for the generators.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRoute describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedHttpRoute {
     protocol: "http";
     function: Function;

package/lib/structures/ITypedHttpRouteException.d.ts

@@ -1,6 +1,16 @@
 import { OpenApi } from "@typia/interface";
 import { MetadataSchema } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
+/**
+ * A typed exception: its status, description, examples, type, and resolved
+ * metadata.
+ *
+ * @evidence contracts/common.md#principled-implementation The resolved metadata is what the SDK and the Swagger generators print.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteException describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedHttpRouteException {
     status: number | "2XX" | "3XX" | "4XX" | "5XX";
     description: string | null;

package/lib/structures/ITypedHttpRouteParameter.d.ts

@@ -2,18 +2,63 @@ import { OpenApi } from "@typia/interface";
 import { IJsDocTagInfo } from "typia";
 import { MetadataSchema } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
+/**
+ * A typed parameter of a route: a body, headers, a path parameter, or a query.
+ *
+ * @evidence contracts/common.md#principled-implementation The union is discriminated by `category`, and each member carries the resolved metadata.
+ * @evidence contracts/common.md#clear-and-simple-design A union of four records.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export type ITypedHttpRouteParameter = ITypedHttpRouteParameter.IBody | ITypedHttpRouteParameter.IHeaders | ITypedHttpRouteParameter.IPath | ITypedHttpRouteParameter.IQuery;
 export declare namespace ITypedHttpRouteParameter {
+    /**
+     * The typed form of a body parameter.
+     *
+     * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+     * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+     * @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 type describes; its members are named for their meaning.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter.IBody describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export interface IBody extends IBase<"body"> {
         contentType: "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain";
         encrypted: boolean;
     }
+    /**
+     * The typed form of a headers parameter.
+     *
+     * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+     * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+     * @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 type describes; its members are named for their meaning.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter.IHeaders describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export interface IHeaders extends IBase<"headers"> {
         field: string | null;
     }
+    /**
+     * The typed form of a path parameter parameter.
+     *
+     * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+     * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+     * @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 type describes; its members are named for their meaning.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter.IPath describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export interface IPath extends IBase<"param"> {
         field: string;
     }
+    /**
+     * The typed form of a query parameter.
+     *
+     * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+     * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+     * @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 type describes; its members are named for their meaning.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter.IQuery describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+     */
     export interface IQuery extends IBase<"query"> {
         field: string | null;
     }

package/lib/structures/ITypedHttpRouteSuccess.d.ts

@@ -2,6 +2,16 @@ import { OpenApi } from "@typia/interface";
 import { MetadataSchema } from "../internal/legacy";
 import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
 import { IReflectType } from "./IReflectType";
+/**
+ * A typed success response: its type, status, content type, binary and
+ * encrypted flags, metadata, examples, and header directives.
+ *
+ * @evidence contracts/common.md#principled-implementation The header directives are the `@setHeader` and `@assignHeaders` tags, which the SDK function applies to the connection.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteSuccess describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedHttpRouteSuccess {
     type: IReflectType;
     status: number | null;

package/lib/structures/ITypedMcpRoute.d.ts

@@ -1,4 +1,5 @@
 import { IJsDocTagInfo } from "typia";
+import { MetadataSchema } from "../internal/legacy";
 import { IReflectController } from "./IReflectController";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectMcpOperation } from "./IReflectMcpOperation";
@@ -10,6 +11,12 @@ import { IReflectType } from "./IReflectType";
  * Carries everything the SDK generator needs to emit a typed client function:
  * the controller reference, accessor path, typia-derived input schema, and
  * input/output type info.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the tool operation in the form the SDK generator reads.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedMcpRoute describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
  */
 export interface ITypedMcpRoute {
     protocol: "mcp";
@@ -22,6 +29,10 @@ export interface ITypedMcpRoute {
     function: Function;
     input: IReflectMcpOperationParameter | null;
     returnType: IReflectType | null;
+    /** Resolved JSON wire graphs used by structural DTO cloning. */
+    inputMetadata?: MetadataSchema;
+    /** Absent when source-only analysis was requested without cloning. */
+    outputMetadata?: MetadataSchema;
     inputSchema: object;
     outputSchema: object | null;
     annotations: IReflectMcpOperation.IAnnotations | null;

package/lib/structures/ITypedWebSocketRoute.d.ts

@@ -3,6 +3,16 @@ import { IJsDocTagInfo } from "typia";
 import { IReflectController } from "./IReflectController";
 import { IReflectImport } from "./IReflectImport";
 import { ITypedWebSocketRouteParameter } from "./ITypedWebSocketRouteParameter";
+/**
+ * A typed WebSocket route: one path with its acceptor, header, path parameters,
+ * query, and driver separated.
+ *
+ * @evidence contracts/common.md#principled-implementation The reflected operation is expanded per path and its parameters are classified.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @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 type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedWebSocketRoute describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedWebSocketRoute {
     protocol: "websocket";
     controller: IReflectController;

package/lib/transform.d.ts

@@ -8,5 +8,11 @@ import type { ITtscPlugin, ITtscPluginFactoryContext } from "ttsc";
  * contributor — but only for projects that actually depend on `@nestia/sdk`. A
  * project depending on `@nestia/core` alone never links, compiles, or ships any
  * of this SDK transform code.
+ *
+ * @evidence contracts/common.md#principled-implementation The package root is resolved through `@nestia/sdk/package.json` from the consumer's project, so the source path is the installed package's, not a workspace layout, and the descriptor returns only a name and a source directory.
+ * @evidence contracts/common.md#clear-and-simple-design One function returning two properties; the transform itself is native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The resolution goes through the package manifest, as the development rules require, and nothing is patched.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the descriptor returns.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire anchors package resolution to the consumer project's package.json; Node resolution yields the installed manifest's native pathname and path.dirname/path.resolve derive the contributor source without a workspace-specific separator or shell lookup.
  */
 export default function createTtscPlugin(context: ITtscPluginFactoryContext): ITtscPlugin;

package/lib/transform.js

@@ -15,6 +15,12 @@ const node_path_1 = __importDefault(require("node:path"));
  * contributor — but only for projects that actually depend on `@nestia/sdk`. A
  * project depending on `@nestia/core` alone never links, compiles, or ships any
  * of this SDK transform code.
+ *
+ * @evidence contracts/common.md#principled-implementation The package root is resolved through `@nestia/sdk/package.json` from the consumer's project, so the source path is the installed package's, not a workspace layout, and the descriptor returns only a name and a source directory.
+ * @evidence contracts/common.md#clear-and-simple-design One function returning two properties; the transform itself is native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The resolution goes through the package manifest, as the development rules require, and nothing is patched.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the descriptor returns.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire anchors package resolution to the consumer project's package.json; Node resolution yields the installed manifest's native pathname and path.dirname/path.resolve derive the contributor source without a workspace-specific separator or shell lookup.
  */
 function createTtscPlugin(context) {
     const requireFrom = (0, node_module_1.createRequire)(node_path_1.default.join(context.projectRoot, "package.json"));

package/lib/transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"transform.js","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":";;;;;;AAAA,6CAA4C;AAC5C,0DAA6B;AAG7B;;;;;;;;;GASG;AACH,0BACE,OAAkC;IAElC,MAAM,WAAW,GAAG,IAAA,2BAAa,EAC/B,mBAAI,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,CAAC,CAC/C,CAAC;IACF,MAAM,IAAI,GAAW,mBAAI,CAAC,OAAO,CAC/B,WAAW,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAChD,CAAC;IACF,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC;KAC5C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"transform.js","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":";;;;;;AAAA,6CAA4C;AAC5C,0DAA6B;AAG7B;;;;;;;;;;;;;;;GAeG;AACH,0BACE,OAAkC;IAElC,MAAM,WAAW,GAAG,IAAA,2BAAa,EAC/B,mBAAI,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,CAAC,CAC/C,CAAC;IACF,MAAM,IAAI,GAAW,mBAAI,CAAC,OAAO,CAC/B,WAAW,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAChD,CAAC;IACF,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/lib/utils/ArrayUtil.d.ts

@@ -1,5 +1,35 @@
+/**
+ * Array helpers of the SDK generator.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds a membership test and a sequential asynchronous map.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts They are plain helpers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+ */
 export declare namespace ArrayUtil {
+    /**
+     * Reports whether the array contains every one of the items.
+     *
+     * Membership uses `includes`, so an `undefined` or `NaN` item is found when
+     * the array holds it.
+     *
+     * @evidence contracts/common.md#principled-implementation `Array.prototype.includes` compares by SameValueZero and the result is the conjunction over the items.
+     * @evidence contracts/common.md#clear-and-simple-design One `every` over `includes`.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No item is special-cased.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the conjunction and the comparison.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil.has operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+     */
     function has<T>(array: T[], ...items: T[]): boolean;
+    /**
+     * Maps the elements with an asynchronous function, one after another, and
+     * returns the results in order.
+     *
+     * @evidence contracts/common.md#principled-implementation Each call is awaited before the next starts, so the order of the results is the order of the elements and a rejection stops the mapping.
+     * @evidence contracts/common.md#clear-and-simple-design One loop.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No element is skipped or retried.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the sequential order.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil.asyncMap operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+     */
     function asyncMap<X, Y>(array: X[], closure: (input: X) => Promise<Y>): Promise<Y[]>;
-    function asyncFilter<T>(array: T[], closure: (input: T) => Promise<boolean>): Promise<T[]>;
 }

package/lib/utils/ArrayUtil.js

@@ -10,12 +10,43 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArrayUtil = void 0;
+/**
+ * Array helpers of the SDK generator.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds a membership test and a sequential asynchronous map.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts They are plain helpers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+ */
 var ArrayUtil;
 (function (ArrayUtil) {
+    /**
+     * Reports whether the array contains every one of the items.
+     *
+     * Membership uses `includes`, so an `undefined` or `NaN` item is found when
+     * the array holds it.
+     *
+     * @evidence contracts/common.md#principled-implementation `Array.prototype.includes` compares by SameValueZero and the result is the conjunction over the items.
+     * @evidence contracts/common.md#clear-and-simple-design One `every` over `includes`.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No item is special-cased.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the conjunction and the comparison.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil.has operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+     */
     function has(array, ...items) {
-        return items.every((elem) => array.find((org) => org === elem) !== undefined);
+        return items.every((item) => array.includes(item));
     }
     ArrayUtil.has = has;
+    /**
+     * Maps the elements with an asynchronous function, one after another, and
+     * returns the results in order.
+     *
+     * @evidence contracts/common.md#principled-implementation Each call is awaited before the next starts, so the order of the results is the order of the elements and a rejection stops the mapping.
+     * @evidence contracts/common.md#clear-and-simple-design One loop.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No element is skipped or retried.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the sequential order.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil.asyncMap operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+     */
     function asyncMap(array, closure) {
         return __awaiter(this, void 0, void 0, function* () {
             const ret = [];
@@ -25,15 +56,5 @@ var ArrayUtil;
         });
     }
     ArrayUtil.asyncMap = asyncMap;
-    function asyncFilter(array, closure) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const ret = [];
-            for (const elem of array)
-                if ((yield closure(elem)) === true)
-                    ret.push(elem);
-            return ret;
-        });
-    }
-    ArrayUtil.asyncFilter = asyncFilter;
 })(ArrayUtil || (exports.ArrayUtil = ArrayUtil = {}));
 //# sourceMappingURL=ArrayUtil.js.map

package/lib/utils/ArrayUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"ArrayUtil.js","sourceRoot":"","sources":["../../src/utils/ArrayUtil.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,IAAiB,SAAS,CAyBzB;AAzBD,WAAiB,SAAS;IACxB,SAAgB,GAAG,CAAI,KAAU,EAAE,GAAG,KAAU;QAC9C,OAAO,KAAK,CAAC,KAAK,CAChB,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,KAAK,SAAS,CAC1D,CAAC;IACJ,CAAC;IAJe,UAAA,GAAG,MAIlB,CAAA;IAED,SAAsB,QAAQ,CAC5B,KAAU,EACV,OAAiC;;YAEjC,MAAM,GAAG,GAAQ,EAAE,CAAC;YACpB,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,GAAG,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACxD,OAAO,GAAG,CAAC;QACb,CAAC;KAAA;IAPqB,UAAA,QAAQ,WAO7B,CAAA;IAED,SAAsB,WAAW,CAC/B,KAAU,EACV,OAAuC;;YAEvC,MAAM,GAAG,GAAQ,EAAE,CAAC;YACpB,KAAK,MAAM,IAAI,IAAI,KAAK;gBACtB,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI;oBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrD,OAAO,GAAG,CAAC;QACb,CAAC;KAAA;IARqB,UAAA,WAAW,cAQhC,CAAA;AACH,CAAC,EAzBgB,SAAS,aAAT,SAAS,GAAT,SAAS,QAyBzB"}
+{"version":3,"file":"ArrayUtil.js","sourceRoot":"","sources":["../../src/utils/ArrayUtil.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA;;;;;;;;GAQG;AACH,IAAiB,SAAS,CAmCzB;AAnCD,WAAiB,SAAS;IACxB;;;;;;;;;;;OAWG;IACH,SAAgB,GAAG,CAAI,KAAU,EAAE,GAAG,KAAU;QAC9C,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,CAAC;IAFe,UAAA,GAAG,MAElB,CAAA;IAED;;;;;;;;;OASG;IACH,SAAsB,QAAQ,CAC5B,KAAU,EACV,OAAiC;;YAEjC,MAAM,GAAG,GAAQ,EAAE,CAAC;YACpB,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,GAAG,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACxD,OAAO,GAAG,CAAC;QACb,CAAC;KAAA;IAPqB,UAAA,QAAQ,WAO7B,CAAA;AACH,CAAC,EAnCgB,SAAS,aAAT,SAAS,GAAT,SAAS,QAmCzB"}