@nestia/sdk 14.0.0 → 14.0.2

package/lib/structures/IReflectHttpOperationException.d.ts

@@ -1,11 +1,22 @@
-import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
+import { IMetadataComponents, IMetadataSchema, OpenApi } from "@typia/interface";
 import { MetadataFactory } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
+/**
+ * A reflected exception of an operation: its status, description, examples,
+ * type, metadata, components, and validator.
+ *
+ * @evidence contracts/common.md#principled-implementation The declaration fields come from `@TypedException` and the reflected fields from the transform.
+ * @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 IReflectHttpOperationException 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 IReflectHttpOperationException {
     status: number | "2XX" | "3XX" | "4XX" | "5XX";
     description: string | null;
     example?: any;
-    examples?: Record<string, any>;
+    /** Named examples, as OpenAPI Example Objects. */
+    examples?: Record<string, OpenApi.IExample>;
     type: IReflectType;
     metadata: IMetadataSchema;
     components: IMetadataComponents;

package/lib/structures/IReflectHttpOperationParameter.d.ts

@@ -1,18 +1,65 @@
-import { IJsDocTagInfo, IMetadataComponents, IMetadataSchema } from "@typia/interface";
+import { IJsDocTagInfo, IMetadataComponents, IMetadataSchema, OpenApi } from "@typia/interface";
 import { MetadataFactory } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
+/**
+ * A reflected parameter of an HTTP operation: a body, headers, a path
+ * parameter, or a query.
+ *
+ * @evidence contracts/common.md#principled-implementation The union is discriminated by `category`, with the fields each category needs, and a preconfigured form for what Nest's metadata alone gives.
+ * @evidence contracts/common.md#clear-and-simple-design A union of four records plus the preconfigured union.
+ * @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 IReflectHttpOperationParameter 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 IReflectHttpOperationParameter = IReflectHttpOperationParameter.IBody | IReflectHttpOperationParameter.IHeaders | IReflectHttpOperationParameter.IParam | IReflectHttpOperationParameter.IQuery;
 export declare namespace IReflectHttpOperationParameter {
+    /**
+     * The reflected parameter of a body, with its content type and whether it is
+     * encrypted.
+     *
+     * @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 IReflectHttpOperationParameter.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 reflected parameter of the headers, as an object or as one field.
+     *
+     * @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 IReflectHttpOperationParameter.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 reflected parameter of a path parameter with its field name.
+     *
+     * @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 IReflectHttpOperationParameter.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;
     }
+    /**
+     * The reflected parameter of the query, as an object or as one field.
+     *
+     * @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 IReflectHttpOperationParameter.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;
     }
@@ -23,9 +70,14 @@ export declare namespace IReflectHttpOperationParameter {
         type: IReflectType;
         metadata: IMetadataSchema;
         components: IMetadataComponents;
-        validate: MetadataFactory.Validator;
+        /**
+         * SDK policy checked over the metadata, for a JSON or text body. An HTTP
+         * input's wire rules are typia's instead, baked beside its metadata.
+         */
+        validate?: MetadataFactory.Validator;
         example?: any;
-        examples?: Record<string, any>;
+        /** Named examples, as OpenAPI Example Objects. */
+        examples?: Record<string, OpenApi.IExample>;
         description: string | null;
         jsDocTags: IJsDocTagInfo[];
     }

package/lib/structures/IReflectHttpOperationSuccess.d.ts

@@ -1,7 +1,18 @@
-import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
+import { IMetadataComponents, IMetadataSchema, OpenApi } from "@typia/interface";
 import { MetadataFactory } from "../internal/legacy";
 import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
 import { IReflectType } from "./IReflectType";
+/**
+ * The reflected success response of an operation: its type, status, content
+ * type, whether it is binary or encrypted, its schema, validator, and
+ * examples.
+ *
+ * @evidence contracts/common.md#principled-implementation The record holds what the SDK and the Swagger generators need to describe the response.
+ * @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 IReflectHttpOperationSuccess 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 IReflectHttpOperationSuccess {
     type: IReflectType;
     status: number;
@@ -10,7 +21,8 @@ export interface IReflectHttpOperationSuccess {
     encrypted: boolean;
     components: IMetadataComponents;
     metadata: IMetadataSchema;
-    validate: MetadataFactory.Validator;
+    validate?: MetadataFactory.Validator;
     example?: any;
-    examples?: Record<string, any>;
+    /** Named examples, as OpenAPI Example Objects. */
+    examples?: Record<string, OpenApi.IExample>;
 }

package/lib/structures/IReflectImport.d.ts

@@ -1,3 +1,13 @@
+/**
+ * An import of a source file: its file, its namespace import, its default
+ * import, its named elements, and their aliases.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is one import declaration in a form that can be merged by file.
+ * @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.
+ * @evidence contracts/portability.md#os-neutral-implementation file carries the source identity emitted by the native import analyzer; ImportDictionary owns converting it to a relative slash-separated module specifier. Binding names and aliases are language identifiers.
+ */
 export interface IReflectImport {
     file: string;
     asterisk: string | null;

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,10 +4,28 @@ 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;
     controller: IReflectController;
+    /**
+     * Property key of the controller method.
+     *
+     * {@link name} is the SDK function's name, which the accessor analysis
+     * renames: a reserved word such as `delete` becomes `_delete`. Metadata the
+     * method's decorators define, and what names the method, read this key.
+     */
+    key: string;
     name: string;
     method: string;
     path: string;

package/lib/structures/ITypedHttpRouteException.d.ts

@@ -1,10 +1,22 @@
+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;
     example: any;
-    examples: Record<string, any>;
+    /** Named examples, as OpenAPI Example Objects. */
+    examples: Record<string, OpenApi.IExample>;
     type: IReflectType;
     metadata: MetadataSchema;
 }

package/lib/structures/ITypedHttpRouteParameter.d.ts

@@ -1,18 +1,64 @@
+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;
     }
@@ -23,7 +69,8 @@ export declare namespace ITypedHttpRouteParameter {
         type: IReflectType;
         metadata: MetadataSchema;
         example?: any;
-        examples?: Record<string, any>;
+        /** Named examples, as OpenAPI Example Objects. */
+        examples?: Record<string, OpenApi.IExample>;
         description: string | null;
         jsDocTags: IJsDocTagInfo[];
     }

package/lib/structures/ITypedHttpRouteSuccess.d.ts

@@ -1,6 +1,17 @@
+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;
@@ -9,7 +20,8 @@ export interface ITypedHttpRouteSuccess {
     encrypted: boolean;
     metadata: MetadataSchema;
     example?: any;
-    examples?: Record<string, any>;
+    /** Named examples, as OpenAPI Example Objects. */
+    examples?: Record<string, OpenApi.IExample>;
     setHeaders: Array<{
         type: "setter";
         source: string;