@nestia/sdk 14.0.1 → 14.0.2

package/src/structures/IOperationMetadata.ts

@@ -8,6 +8,16 @@ import { IJsDocTagInfo } from "typia";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * The compile-time metadata of an operation: its parameters, its success, its
+ * exceptions, its description, and its JSDoc tags.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is what the nestia transform serializes into the `OperationMetadata` decorator and the analyzers read back.
+ * @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 IOperationMetadata 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 IOperationMetadata {
   parameters: IOperationMetadata.IParameter[];
   success: IOperationMetadata.IResponse;
@@ -16,12 +26,32 @@ export interface IOperationMetadata {
   jsDocTags: IJsDocTagInfo[];
 }
 export namespace IOperationMetadata {
+  /**
+   * The metadata of a parameter: the response fields plus its name, position,
+   * description, and tags.
+   *
+   * @evidence contracts/common.md#principled-implementation A parameter has the type facts of a response and the identity facts of a declaration.
+   * @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 IOperationMetadata.IParameter 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 IParameter extends IResponse {
     name: string;
     index: number;
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
   }
+  /**
+   * The metadata of a value: its reflected type, its imports, and its schemas
+   * in the primitive and the resolved forms.
+   *
+   * @evidence contracts/common.md#principled-implementation Each form is either a schema or the list of errors that made it unavailable, so an unreadable type is reported instead of dropped.
+   * @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 IOperationMetadata.IResponse 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 IResponse {
     type: IReflectType | null;
     imports: IReflectImport[];
@@ -29,6 +59,16 @@ export namespace IOperationMetadata {
     resolved: ValidationPipe<ISchema, IError>;
   }
 
+  /**
+   * A schema: the components, the metadata, and the wire rule violations of the
+   * type.
+   *
+   * @evidence contracts/common.md#principled-implementation The components and the metadata describe the type and the HTTP rules record why it cannot travel as a query, a header, a path segment, or a form.
+   * @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 IOperationMetadata.ISchema 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 ISchema {
     components: IMetadataComponents;
     metadata: IMetadataSchema;
@@ -44,6 +84,12 @@ export namespace IOperationMetadata {
    * The violations of each HTTP input category's rules, which are typia's own
    * validators except the path parameter rule typia keeps unexported and the
    * one of a field-named `@Query("key")` or `@Headers("key")`.
+   *
+   * @evidence contracts/common.md#principled-implementation One list per input kind lets the parameter analysis pick the list that applies.
+   * @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 IOperationMetadata.IHttpRules 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 IHttpRules {
     /** A query object: `@TypedQuery()`, `@Query()`, `@TypedQuery.Body()`. */
@@ -61,6 +107,15 @@ export namespace IOperationMetadata {
     /** A multipart body: `@TypedFormData.Body()`. */
     formData: IError[];
   }
+  /**
+   * One analysis error: the name, the accessor of the member, and the messages.
+   *
+   * @evidence contracts/common.md#principled-implementation The three members identify where in a type the error is.
+   * @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 IOperationMetadata.IError 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 IError {
     name: string;
     accessor: string | null;

package/src/structures/IReflectController.ts

@@ -4,6 +4,16 @@ import { IReflectHttpOperation } from "./IReflectHttpOperation";
 import { IReflectMcpOperation } from "./IReflectMcpOperation";
 import { IReflectWebSocketOperation } from "./IReflectWebSocketOperation";
 
+/**
+ * A reflected controller: its class, its file, its paths, prefixes, versions,
+ * security, tags, and operations.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the reflection result that the typed analysis consumes.
+ * @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 controller source pathname supplied by ConfigAnalyzer; paths and prefixes retain Nest router spelling independently of native separators.
+ */
 export interface IReflectController {
   class: Function;
   prefixes: string[];

package/src/structures/IReflectHttpOperation.ts

@@ -6,6 +6,16 @@ import { IReflectHttpOperationParameter } from "./IReflectHttpOperationParameter
 import { IReflectHttpOperationSuccess } from "./IReflectHttpOperationSuccess";
 import { IReflectImport } from "./IReflectImport";
 
+/**
+ * A reflected HTTP operation: its function, name, method, paths, versions,
+ * parameters, success, exceptions, security, tags, imports, and description.
+ *
+ * @evidence contracts/common.md#principled-implementation The record joins Nest's runtime metadata with the compile-time metadata of 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 IReflectHttpOperation 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 IReflectHttpOperation {
   protocol: "http";
   function: Function;

package/src/structures/IReflectHttpOperationException.ts

@@ -7,6 +7,16 @@ import {
 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 {
   // BASIC PROPERTIES
   status: number | "2XX" | "3XX" | "4XX" | "5XX";

package/src/structures/IReflectHttpOperationParameter.ts

@@ -8,12 +8,32 @@ import {
 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 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"
@@ -22,12 +42,39 @@ export namespace IReflectHttpOperationParameter {
       | "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;
   }

package/src/structures/IReflectHttpOperationSuccess.ts

@@ -8,6 +8,17 @@ 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;

package/src/structures/IReflectImport.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/src/structures/IReflectMcpOperation.ts

@@ -1,5 +1,6 @@
 import { IJsDocTagInfo } from "typia";
 
+import { IOperationMetadata } from "./IOperationMetadata";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectMcpOperationParameter } from "./IReflectMcpOperationParameter";
 import { IReflectType } from "./IReflectType";
@@ -10,6 +11,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";
@@ -23,12 +30,24 @@ 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 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.
+   */
   export interface IAnnotations {
     readOnlyHint?: boolean;
     destructiveHint?: boolean;

package/src/structures/IReflectMcpOperationParameter.ts

@@ -1,5 +1,6 @@
 import { IJsDocTagInfo } from "typia";
 
+import { IOperationMetadata } from "./IOperationMetadata";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectType } from "./IReflectType";
 
@@ -7,12 +8,20 @@ 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/src/structures/IReflectOperationError.ts

@@ -2,6 +2,16 @@ 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;
@@ -10,16 +20,35 @@ export interface IReflectOperationError {
   contents: Array<string | IOperationMetadata.IError>;
 }
 export 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.
+   */
   export class Key implements Pick<IComparable<Key>, "less"> {
     public constructor(public readonly 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.
+     */
     public less(obj: Key): boolean {
       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 (this.error.function ?? "") < (obj.error.function ?? "");
+      const leftFunction = this.error.function ?? "";
+      const rightFunction = obj.error.function ?? "";
+      if (leftFunction !== rightFunction) return leftFunction < rightFunction;
       return (this.error.from ?? "") < (obj.error.from ?? "");
     }
   }

package/src/structures/IReflectType.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/src/structures/IReflectWebSocketOperation.ts

@@ -4,6 +4,16 @@ 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/src/structures/IReflectWebSocketOperationParameter.ts

@@ -3,6 +3,16 @@ 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
@@ -10,10 +20,55 @@ export type IReflectWebSocketOperationParameter =
   | IReflectWebSocketOperationParameter.IParam
   | IReflectWebSocketOperationParameter.IQuery;
 export 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/src/structures/ITypedApplication.ts

@@ -4,6 +4,16 @@ 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/src/structures/ITypedHttpRoute.ts

@@ -6,6 +6,16 @@ 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/src/structures/ITypedHttpRouteException.ts

@@ -3,6 +3,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 {
   // BASIC PROPERTIES
   status: number | "2XX" | "3XX" | "4XX" | "5XX";

package/src/structures/ITypedHttpRouteParameter.ts

@@ -4,12 +4,30 @@ 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 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"
@@ -18,12 +36,39 @@ export namespace ITypedHttpRouteParameter {
       | "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;
   }