@nestia/sdk 14.0.1 → 14.0.2

package/src/generates/internal/SdkImportWizard.ts

@@ -1,9 +1,36 @@
 import { ImportDictionary } from "./ImportDictionary";
 
+/**
+ * The imports of the SDK's runtime dependencies.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace names each dependency once so every generator registers it the same way.
+ * @evidence contracts/common.md#clear-and-simple-design Six one-call helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Each helper registers one fixed import.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkImportWizard {
+  /**
+   * Returns the import of the fetcher: the encrypted one or the plain one.
+   *
+   * @evidence contracts/common.md#principled-implementation The choice follows the route.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It returns the registering function.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.Fetcher composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const Fetcher = (encrypted: boolean) =>
     encrypted ? EncryptedFetcher : PlainFetcher;
 
+  /**
+   * Registers `HttpError` of `@nestia/fetcher`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a type import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.HttpError composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const HttpError = (importer: ImportDictionary) =>
     importer.external({
       declaration: true,
@@ -12,6 +39,15 @@ export namespace SdkImportWizard {
       name: "HttpError",
     });
 
+  /**
+   * Registers `IConnection` of `@nestia/fetcher`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a type import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.IConnection composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const IConnection = (importer: ImportDictionary) =>
     importer.external({
       declaration: true,
@@ -20,6 +56,15 @@ export namespace SdkImportWizard {
       name: "IConnection",
     });
 
+  /**
+   * Registers `Primitive` of `typia`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a type import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.Primitive composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const Primitive = (importer: ImportDictionary) =>
     importer.external({
       declaration: true,
@@ -28,6 +73,15 @@ export namespace SdkImportWizard {
       name: "Primitive",
     });
 
+  /**
+   * Registers `Resolved` of `typia`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a type import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.Resolved composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const Resolved = (importer: ImportDictionary) =>
     importer.external({
       declaration: true,
@@ -36,6 +90,15 @@ export namespace SdkImportWizard {
       name: "Resolved",
     });
 
+  /**
+   * Registers the default import of `typia`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a value import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.typia composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const typia = (importer: ImportDictionary) =>
     importer.external({
       declaration: false,

package/src/generates/internal/SdkMcpRouteProgrammer.ts

@@ -15,16 +15,32 @@ import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
 import { StringUtil } from "../../utils/StringUtil";
 import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
+import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 
 /**
  * Emits a typed client wrapper for an MCP tool.
  *
- * Object output types are wrapped in `Primitive<T>` because MCP round-trips
- * values through JSON. Void MCP tools return `Promise<void>`.
+ * Cloned input and output declarations use the native JSON wire graph.
+ * Source-reference output types use `Primitive<T>` for the same JSON
+ * round-trip. Void MCP tools return `Promise<void>`.
  *
  * @author wildduck - https://github.com/wildduck2
+ * @evidence contracts/common.md#principled-implementation The namespace prints the wrapper that calls the tool and its metadata, and turns a tool error into an exception.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and the writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The function's identifiers yield to the tool's own name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkMcpRouteProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace SdkMcpRouteProgrammer {
+  /**
+   * Returns the function and the namespace of an MCP tool.
+   *
+   * @evidence contracts/common.md#principled-implementation The two nodes are composed together so they share names.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The shape follows the tool metadata.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkMcpRouteProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -67,7 +83,7 @@ export namespace SdkMcpRouteProgrammer {
         alias: "McpCallToolResult",
       });
       const isVoid = isVoidReturn(route);
-      if (!isVoid)
+      if (!isVoid && _project.config.clone !== true)
         importer.external({
           declaration: true,
           file: "typia",
@@ -315,7 +331,7 @@ export namespace SdkMcpRouteProgrammer {
     };
 
   const writeNamespace =
-    (_project: INestiaProject) =>
+    (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedMcpRoute): Node => {
       const statements: Statement[] = [];
@@ -326,25 +342,29 @@ export namespace SdkMcpRouteProgrammer {
             [factory.createModifier(SyntaxKind.ExportKeyword)],
             "Input",
             undefined,
-            factory.createTypeReferenceNode(route.input.type.name),
+            project.config.clone === true && route.inputMetadata
+              ? SdkTypeProgrammer.write(project)(importer)(route.inputMetadata)
+              : factory.createTypeReferenceNode(route.input.type.name),
           ),
         );
 
       const outputType: Node =
         !isVoidReturn(route) && route.returnType !== null
-          ? factory.createTypeReferenceNode(
-              importer.external({
-                declaration: true,
-                file: "typia",
-                type: "element",
-                name: "Primitive",
-              }),
-              [
-                factory.createTypeReferenceNode(
-                  unwrapPromise(route.returnType.name),
-                ),
-              ],
-            )
+          ? project.config.clone === true && route.outputMetadata
+            ? SdkTypeProgrammer.write(project)(importer)(route.outputMetadata)
+            : factory.createTypeReferenceNode(
+                importer.external({
+                  declaration: true,
+                  file: "typia",
+                  type: "element",
+                  name: "Primitive",
+                }),
+                [
+                  factory.createTypeReferenceNode(
+                    unwrapPromise(route.returnType.name),
+                  ),
+                ],
+              )
           : factory.createKeywordTypeNode(SyntaxKind.VoidKeyword);
       statements.push(
         factory.createTypeAliasDeclaration(

package/src/generates/internal/SdkPathTemplate.ts

@@ -4,6 +4,15 @@ import { PathAnalyzer } from "../../analyses/PathAnalyzer";
 import { IdentifierFactory } from "../../factories/IdentifierFactory";
 import { ImportDictionary } from "./ImportDictionary";
 
+/**
+ * The path expression of an SDK function.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace composes the route's path from its segments, filling the parameters through the fetcher's encoder.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The segments are those the router reads.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkPathTemplate composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkPathTemplate {
   /**
    * The expression an SDK function builds its route's path with: the literal
@@ -16,6 +25,12 @@ export namespace SdkPathTemplate {
    * router reads the path, so a parameter with literal text beside it in its
    * segment, such as `/files/:id.json` or `/range/:from-:to`, is filled in
    * where it stands.
+   *
+   * @evidence contracts/common.md#principled-implementation A path without a parameter is a literal, and otherwise a template holding each parameter's `PathParameter.encode` call between its literal texts.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The literal text follows the router's reading.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkPathTemplate.compose composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const compose = (props: {
     importer: ImportDictionary;

package/src/generates/internal/SdkRouteDirectory.ts

@@ -2,6 +2,16 @@ import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
 
+/**
+ * One directory of the functional tree: its parent, its name, its module path,
+ * its children, and its routes.
+ *
+ * @evidence contracts/common.md#principled-implementation The module path is the parent's path with the name, from `api.functional`.
+ * @evidence contracts/common.md#clear-and-simple-design Parent and segment name identify one node; its derived module name, children and routes organize the generated functional tree.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The members are set once and only the collections grow.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkRouteDirectory composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export class SdkRouteDirectory {
   public readonly module: string;
   public readonly children: Map<string, SdkRouteDirectory>;

package/src/generates/internal/SdkTypeProgrammer.ts

@@ -8,6 +8,7 @@ import { TypeFactory } from "../../factories/TypeFactory";
 import {
   MetadataAliasType,
   MetadataArray,
+  MetadataArrayType,
   MetadataAtomic,
   MetadataConstantValue,
   MetadataEscaped,
@@ -15,10 +16,10 @@ import {
   MetadataProperty,
   MetadataSchema,
   MetadataTuple,
+  MetadataTupleType,
   decodeMetadataValue,
   isRequiredOf,
   isSoleLiteralOf,
-  sizeOf,
 } from "../../internal/legacy";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { StringUtil } from "../../utils/StringUtil";
@@ -26,10 +27,30 @@ import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkTypeTagProgrammer } from "./SdkTypeTagProgrammer";
 
+/**
+ * Writes the TypeScript type of a metadata.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns each member of the metadata into a type node and joins them as a union.
+ * @evidence contracts/common.md#clear-and-simple-design The schema facade and object writer use one writer per form; collection-body operations distinguish a named recursive definition from its nested references.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A name that cannot be referenced is written inline.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkTypeProgrammer {
   /* -----------------------------------------------------------
     FACADE
   ----------------------------------------------------------- */
+  /**
+   * Returns the type of a metadata: the union of its any, null, undefined,
+   * escaped, constant, template, atomic, tuple, array, object, alias, and
+   * native and typed collection forms. An empty union emits never.
+   *
+   * @evidence contracts/common.md#principled-implementation Named objects, aliases and recursive collections use references; implicit objects and nonrecursive collections use inline bodies. A recursive declaration writes its collection body once, and nested uses return through references.
+   * @evidence contracts/common.md#clear-and-simple-design One function of ordered cases.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The member order is fixed, supported resolved natives retain their type references, and empty unions use the TypeScript bottom type rather than an empty printed node.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -70,15 +91,39 @@ export namespace SdkTypeProgrammer {
         union.push(
           writeAlias(project)(importer)(alias.type as MetadataAliasType),
         );
-      for (const native of meta.natives)
-        if (native.name === "Blob" || native.name === "File")
-          union.push(write_native(native.name));
+      for (const native of meta.natives) union.push(write_native(native.name));
+      for (const set of meta.sets)
+        union.push(
+          factory.createTypeReferenceNode("Set", [
+            write(project)(importer)(set.value),
+          ]),
+        );
+      for (const map of meta.maps)
+        union.push(
+          factory.createTypeReferenceNode("Map", [
+            write(project)(importer)(map.key),
+            write(project)(importer)(map.value),
+          ]),
+        );
 
-      return union.length === 1
-        ? union[0]!
-        : factory.createUnionTypeNode(union);
+      return union.length === 0
+        ? TypeFactory.keyword("never")
+        : union.length === 1
+          ? union[0]!
+          : factory.createUnionTypeNode(union);
     };
 
+  /**
+   * Returns the type of an object: the regular properties as one literal,
+   * intersected with each dynamic key's index signature. Both signature forms
+   * retain the metadata's readonly modifier.
+   *
+   * @evidence contracts/common.md#principled-implementation A key that is a sole literal is regular, and every other key is dynamic. Each property's mutability supplies the readonly modifier for its corresponding property or index signature.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The cases are exhaustive over the keys.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeProgrammer.write_object composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write_object =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -102,9 +147,22 @@ export namespace SdkTypeProgrammer {
     (importer: ImportDictionary) =>
     (meta: MetadataEscaped): TypeNode => {
       if (
-        sizeOf(meta.original) === 1 &&
         meta.original.natives.length === 1 &&
-        meta.original.natives[0]!.name === "Date"
+        meta.original.natives[0]!.name === "Date" &&
+        !meta.original.any &&
+        meta.original.escaped === null &&
+        [
+          meta.original.atomics,
+          meta.original.constants,
+          meta.original.templates,
+          meta.original.arrays,
+          meta.original.tuples,
+          meta.original.objects,
+          meta.original.aliases,
+          meta.original.sets,
+          meta.original.maps,
+          meta.original.functions,
+        ].every((members) => members.length === 0)
       )
         return factory.createIntersectionTypeNode([
           TypeFactory.keyword("string"),
@@ -209,7 +267,9 @@ export namespace SdkTypeProgrammer {
     (meta: MetadataArray): TypeNode =>
       write_type_tag_matrix(importer)(
         "array",
-        factory.createArrayTypeNode(write(project)(importer)(meta.type!.value)),
+        meta.type!.recursive
+          ? writeAlias(project)(importer)(meta.type!)
+          : write_array_type(project)(importer)(meta.type!),
         meta.tags,
       );
 
@@ -217,8 +277,42 @@ export namespace SdkTypeProgrammer {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (meta: MetadataTuple): TypeNode =>
+      meta.type!.recursive
+        ? writeAlias(project)(importer)(meta.type!)
+        : write_tuple_type(project)(importer)(meta.type!);
+
+  /**
+   * Writes an array definition's body, using named references for recursive
+   * collections reached through its element schema.
+   *
+   * @evidence contracts/common.md#principled-implementation A declaration needs one array body while its nested use sites use the ordinary writer's recursive references, so X=X[] is finite and retains its element meaning.
+   * @evidence contracts/common.md#clear-and-simple-design One array node delegates its element to write.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The declaration operation is distinct from reference emission and adds no test-only flags or names.
+   * @evidence contracts/common.md#meaningful-documentation The comment distinguishes a definition body from nested references.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeProgrammer.write_array_type composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  export const write_array_type =
+    (project: INestiaProject) =>
+    (importer: ImportDictionary) =>
+    (meta: MetadataArrayType): TypeNode =>
+      factory.createArrayTypeNode(write(project)(importer)(meta.value));
+
+  /**
+   * Writes a tuple definition's body, retaining optional and rest elements
+   * while nested recursive collections use named references.
+   *
+   * @evidence contracts/common.md#principled-implementation Each element retains its optional/rest form and schema; nested uses return through write, whose recursive reference branch terminates self and mutual collection cycles.
+   * @evidence contracts/common.md#clear-and-simple-design One element map creates the tuple body.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The same body operation serves ordinary inline tuples and recursive declarations without special-cased source names.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the definition body and modifier responsibilities.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeProgrammer.write_tuple_type composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  export const write_tuple_type =
+    (project: INestiaProject) =>
+    (importer: ImportDictionary) =>
+    (meta: MetadataTupleType): TypeNode =>
       factory.createTupleTypeNode(
-        meta.type!.elements.map((elem) =>
+        meta.elements.map((elem) =>
           elem.rest
             ? factory.createRestTypeNode(
                 factory.createArrayTypeNode(
@@ -243,7 +337,9 @@ export namespace SdkTypeProgrammer {
               p.jsDocTags,
             );
             const signature = factory.createPropertySignature(
-              undefined,
+              p.mutability === "readonly"
+                ? [factory.createModifier(SyntaxKind.ReadonlyKeyword)]
+                : undefined,
               NamingConvention.variable(
                 String(p.key.constants[0]!.values[0]!.value),
               )
@@ -275,7 +371,9 @@ export namespace SdkTypeProgrammer {
       factory.createTypeLiteralNode([
         FilePrinter.description(
           factory.createIndexSignature(
-            undefined,
+            property.mutability === "readonly"
+              ? [factory.createModifier(SyntaxKind.ReadonlyKeyword)]
+              : undefined,
             [
               factory.createParameterDeclaration(
                 undefined,
@@ -297,7 +395,13 @@ export namespace SdkTypeProgrammer {
   const writeAlias =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
-    (meta: MetadataAliasType | MetadataObjectType): TypeNode => {
+    (
+      meta:
+        | MetadataAliasType
+        | MetadataObjectType
+        | MetadataArrayType
+        | MetadataTupleType,
+    ): TypeNode => {
       importInternalFile(project)(importer)(meta.name);
       // The reference has to spell the accessor path the declaration was
       // written under, not the raw metadata name: a duplicated name carries

package/src/generates/internal/SdkTypeTagProgrammer.ts

@@ -5,7 +5,25 @@ import { LiteralFactory } from "../../factories/LiteralFactory";
 import { decodeTagValue } from "../../internal/legacy";
 import { ImportDictionary } from "./ImportDictionary";
 
+/**
+ * Writes the type tags of a cloned DTO.
+ *
+ * @evidence contracts/common.md#principled-implementation Supported predefined tags require matching arguments and encoded validation, exclusivity and schema expansions; other tags are emitted from the metadata fields as tags.TagBase.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions over a table of predefined tags.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The choice is decided by the expansion.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeTagProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkTypeTagProgrammer {
+  /**
+   * The kinds of type a tag can be attached to.
+   *
+   * @evidence contracts/common.md#principled-implementation The six kinds are those the tags declare.
+   * @evidence contracts/common.md#clear-and-simple-design One 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 declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeTagProgrammer.Target composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export type Target =
     | "object"
     | "array"
@@ -20,8 +38,9 @@ export namespace SdkTypeTagProgrammer {
    * A tag prints as the predefined typia tag it matches, `tags.Minimum<3>`,
    * only when that tag accepts the argument and, given it, expands to exactly
    * the tag the metadata carries; then the two are the same type. Anything else
-   * prints in the generic `tags.TagBase<{ ... }>` form, which is always the
-   * same type.
+   * prints in the generic `tags.TagBase<{ ... }>` form using the native
+   * metadata's reported fields. This cannot recover source details absent from
+   * that metadata or composite values changed by JSON encoding.
    *
    * The tag's name cannot decide it. The SDK names a tag after its object type
    * with the brackets and quotes a component name drops, `Minimum3` or
@@ -29,6 +48,12 @@ export namespace SdkTypeTagProgrammer {
    * tag named alike (#1662). The expansion can: it is typia's declaration of
    * each predefined tag, and should typia change one, the tag only falls back
    * to the `TagBase` form.
+   *
+   * @evidence contracts/common.md#principled-implementation A tag prints as the predefined tag it matches only when that tag expands to exactly the tag the metadata carries.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Generic tags retain the reported value, validation, exclusivity and schema fields; NaN has no literal type and is represented as null. Source details absent from native metadata are not claimed to be reconstructed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeTagProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const write = (
     importer: ImportDictionary,
@@ -60,7 +85,15 @@ export namespace SdkTypeTagProgrammer {
     );
   };
 
-  /** Writes the predefined typia tag `tags.<name><argument>`. */
+  /**
+   * Writes the predefined typia tag `tags.<name><argument>`.
+   *
+   * @evidence contracts/common.md#principled-implementation The name and argument were decided by the matching.
+   * @evidence contracts/common.md#clear-and-simple-design One node.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The argument is written as a literal.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkTypeTagProgrammer.writePredefined composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const writePredefined = (
     importer: ImportDictionary,
     name: string,
@@ -289,10 +322,7 @@ const serialize = (value: string): string =>
       })[char]!,
   );
 
-/**
- * Every predefined typia tag, keyed by its kind, as `@typia/interface` declares
- * it.
- */
+/** Supported predefined typia tag expansions, keyed by their metadata kind. */
 const DEFINITIONS: Record<string, IDefinition> = {
   minimum: {
     name: "Minimum",