@nestia/core 14.0.1 → 14.0.2

package/native/transform/node_transform.go

@@ -159,7 +159,7 @@ func nestiaCoreCollectParameterReplacements(
 		}
 		canonical := nestiaCoreCanonicalSegments(context, segments)
 		kind := nestiaCoreParameterKind(canonical)
-		if kind == "" || nestiaCoreDecoratorReference(state.prog, context, decorator, segments, canonical) == false {
+		if kind == "" || IsNestiaCoreCall(state.prog, nestiaCoreOriginalNode(state.ec, call.AsNode())) == false {
 			continue
 		}
 		candidates = append(candidates, candidate{call: call, segments: segments, kind: kind})
@@ -210,7 +210,7 @@ func nestiaCoreCollectMethodReplacements(
 			continue
 		}
 		canonical := nestiaCoreCanonicalSegments(context, segments)
-		if nestiaCoreDecoratorReference(state.prog, context, decorator, segments, canonical) == false {
+		if IsNestiaCoreCall(state.prog, nestiaCoreOriginalNode(state.ec, call.AsNode())) == false {
 			continue
 		}
 		// @WebSocketRoute carries no injected validator (it is not a method kind),
@@ -230,7 +230,7 @@ func nestiaCoreCollectMethodReplacements(
 			if nestiaCoreMcpRouteAlreadyTransformed(call) {
 				continue
 			}
-		} else if nestiaCoreShouldSkipMethodDecorator(state.prog, call) {
+		} else if nestiaCoreShouldSkipMethodDecorator(state.prog, nestiaCoreOriginalNode(state.ec, call.AsNode()).AsCallExpression()) {
 			continue
 		}
 		candidates = append(candidates, candidate{call: call, segments: segments, kind: kind})
@@ -264,13 +264,16 @@ func nestiaCoreCollectMethodReplacements(
 }
 
 // nestiaCoreOriginalNode returns the parse-tree node a (possibly synthetic) node
-// was rebuilt from, so checker queries that need binder symbols or types resolve
-// against the original. core runs after typia in the shared emit pass: when typia
+// was rebuilt from, so checker queries that need binder symbols, signatures or
+// types and source-text decisions resolve against the original. The rewritten
+// call remains the emission target so typia's generated arguments are retained.
+// core runs after typia in the shared emit pass: when typia
 // lowers a `typia.random<T>()` call that sits in a decorator argument or method
 // body, it rebuilds the enclosing method (and its parameters) into synthetic
-// nodes that carry no binder symbol. GetSignatureFromDeclaration /
-// GetTypeAtLocation then nil-panic on them, and GetTextOfNode on a synthetic
-// callee has no source span. ec.MostOriginal walks the original-link chain back
+// nodes that carry no binder symbol or checker parent context.
+// GetResolvedSignature / GetSignatureFromDeclaration / GetTypeAtLocation can
+// nil-panic on them, and source lookup on a synthetic call or callee has no
+// original source span. ec.MostOriginal walks the original-link chain back
 // to the parse node; it is a no-op for nodes core sees before typia touched them.
 func nestiaCoreOriginalNode(ec *shimprinter.EmitContext, node *shimast.Node) *shimast.Node {
 	if ec == nil || node == nil {

package/native/transform/package.go

@@ -0,0 +1,55 @@
+package transform
+
+import (
+	"encoding/json"
+	"path/filepath"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// SourceFilePackageName returns the nearest package-scope manifest's name for a
+// resolved declaration source. A node_modules boundary ends the scope before
+// its manifest is read. Missing, unreadable or malformed ownership
+// returns an empty name; a foreign or invalid nearest manifest never falls
+// through to an enclosing package.
+//
+// The loaded program filesystem owns path resolution, including its overlays
+// and dependency observations. This performs one ancestor walk without retaining
+// programs or caching an owner across unrelated compilation requests.
+//
+// @evidence contracts/common.md#principled-implementation Node's LOOKUP_PACKAGE_SCOPE ends at the node_modules path component before reading a manifest there. Within that scope the nearest manifest's decoded name decides declaration identity. A present unreadable or invalid manifest also stops resolution, so neither a manifestless dependency nor an invalid foreign owner inherits an enclosing core, rxjs, tgrid or typia owner.
+// @evidence contracts/common.md#clear-and-simple-design One ancestor loop returns one decoded name, with nil, package-scope boundary and filesystem-root termination. All declaration provenance consumers share this operation rather than duplicating ownership policies.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The literal node_modules component establishes Node's documented scope boundary, not package identity. No library-directory spelling, fixture name or type name substitutes for the actual scoped manifest name. Reads use the program filesystem.
+// @evidence contracts/common.md#meaningful-documentation The comment defines scoped nearest-manifest semantics, boundary-before-read termination, empty results, overlay ownership and the absence of cross-program retention. The rule follows Node's ESM resolution LOOKUP_PACKAGE_SCOPE specification.
+// @evidence contracts/portability.md#os-neutral-implementation filepath.Dir, Base and Join represent native path components, and the driver's filesystem performs reads/existence checks. Exact node_modules component comparison follows Node's scope algorithm; no shell path or slash-substring membership test is composed.
+// @evidence contracts/performance.md#efficient-algorithms One read per ancestor and an existence check only after a failed read cost O(directory depth plus the first manifest's bytes). No source graph or dependency tree is recursively searched.
+// @evidence contracts/performance.md#reuse-equivalent-work The program filesystem supplies its own coherent read/overlay observation model. This operation shares no result across programs because manifest inputs and overlays may differ between requests.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Only the current ancestor string and one manifest buffer/decoded name are retained; no program pointer, global owner map, descriptor or filesystem handle survives the call.
+func SourceFilePackageName(prog *driver.Program, source *shimast.SourceFile) string {
+	if prog == nil || prog.FS == nil || source == nil {
+		return ""
+	}
+	for directory := filepath.Dir(source.FileName()); ; {
+		if filepath.Base(directory) == "node_modules" {
+			return ""
+		}
+		manifest := filepath.Join(directory, "package.json")
+		if contents, ok := prog.FS.ReadFile(manifest); ok {
+			var pack struct {
+				Name string `json:"name"`
+			}
+			if json.Unmarshal([]byte(contents), &pack) != nil {
+				return ""
+			}
+			return pack.Name
+		} else if prog.FS.FileExists(manifest) {
+			return ""
+		}
+		parent := filepath.Dir(directory)
+		if parent == directory {
+			return ""
+		}
+		directory = parent
+	}
+}

package/native/transform/printer.go

@@ -4,8 +4,6 @@ import (
 	shimast "github.com/microsoft/typescript-go/shim/ast"
 )
 
-const nestiaKindColonToken = shimast.KindQuestionToken + 1
-
 func normalizeNestiaSyntheticTokens(node *shimast.Node) {
 	if node == nil {
 		return
@@ -17,7 +15,7 @@ func normalizeNestiaSyntheticTokens(node *shimast.Node) {
 			conditional.QuestionToken = factory.NewToken(shimast.KindQuestionToken)
 		}
 		if conditional.ColonToken == nil {
-			conditional.ColonToken = factory.NewToken(nestiaKindColonToken)
+			conditional.ColonToken = factory.NewToken(shimast.KindColonToken)
 		}
 	}
 	node.ForEachChild(func(child *shimast.Node) bool {

package/native/transform/run.go

@@ -25,6 +25,15 @@ var (
 // decorator rewrites, then runs any statically linked contributor rewrite
 // collectors such as the SDK metadata pass when the caller explicitly enables
 // them.
+//
+// @evidence contracts/common.md#principled-implementation The command runs inside a `recover`, so an unexpected panic becomes one diagnostic line with the same shape as every other diagnostic and exit code 3 instead of a raw Go stack, and the stack is printed only when `NESTIA_NATIVE_DEBUG_STACK` is set.
+// @evidence contracts/common.md#clear-and-simple-design One deferred handler around the private dispatcher.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The recovery reports the failure; it does not retry or hide it, and the exit code stays non-zero.
+// @evidence contracts/common.md#meaningful-documentation The comment explains the recovery envelope, the diagnostic shape, and the debug variable.
+// @evidence contracts/portability.md#os-neutral-implementation Argument vectors are passed as strings to Go flag parsing without shell composition. Native working directories and file outputs are handled by os/filepath and the loaded program filesystem in the dispatched commands.
+// @evidence contracts/performance.md#efficient-algorithms Dispatch itself is constant work; build/transform cost is owned by their program load, diagnostics and per-file emit passes, not by the recovery wrapper.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Commands defer program and publication cleanup; linked collectors remain process-owned. The debug stack is allocated only after a panic.
 func Run(args []string) (code int) {
 	defer func() {
 		if exp := recover(); exp != nil {
@@ -57,6 +66,15 @@ func Run(args []string) (code int) {
 // writers are package state, so concurrent calls would interleave; the host runs
 // one command per process and Go tests in one package run sequentially unless
 // they opt into t.Parallel.
+//
+// @evidence contracts/common.md#principled-implementation The two package writers are replaced for the duration of one call and restored by a `defer`, so a caller can observe the JSON envelope of the project-mode transform, which an exit code alone cannot show; a nil writer leaves its stream unchanged.
+// @evidence contracts/common.md#clear-and-simple-design One function that swaps the writers, calls `Run`, and restores them.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts This is a test seam kept as an exported function because the external test module cannot reach the private writers; it changes no behavior of the command, but it mutates package state and is therefore not safe for concurrent calls, as its comment says, and it is used only by the Go test modules.
+// @evidence contracts/common.md#meaningful-documentation The comment explains why the seam exists, its restore behavior, and the concurrency limit.
+// @evidence contracts/portability.md#os-neutral-implementation Streams use caller supplied io.Writer values, with native file and process boundaries handled by Run and its dispatcher.
+// @evidence contracts/performance.md#efficient-algorithms Swapping two stream references is constant work; the dispatched command determines compilation cost.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The call borrows writers and restores previous references on return or panic; it neither closes caller writers nor supports concurrent calls.
 func RunWithOutput(args []string, out io.Writer, errOut io.Writer) int {
 	previousOut, previousErr := stdout, stderr
 	defer func() {

package/native/transform/schemaprojection/project.go

@@ -0,0 +1,213 @@
+package schemaprojection
+
+import metadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+
+// Project gives the schema writer an isolated representation
+// of an absorbed metadata graph. Recursive tuples occupy named alias slots
+// so the writer registers their component before visiting its children. Arrays
+// retain their native recursive representation and every name remains the
+// identifier allocated by the original metadata collection.
+//
+// The returned graph shares read-only scalar annotations but no metadata or
+// component node whose traversal or name cache the writer can mutate. The raw
+// graph remains the source of reflected interop data. Callers must use the
+// returned root for both the main schema and decomposed property schemas.
+// This type-only metadata foundation lives in the stable core host module:
+// contributor packages are relocated by ttsc, while their host imports keep
+// this module identity. The SDK owns baking and calls this operation across
+// that production boundary; this package has no SDK module dependency.
+//
+// @evidence contracts/common.md#principled-implementation SDK analysis absorbs aliases, while the schema writer only breaks tuple cycles through named alias components. Replacing recursive tuple uses by aliases of the same collection-allocated semantic slot retains tuple elements and recursive edges without creating names or changing raw reflection. Memoized copies are registered before visiting edges, preserving shared and mutually recursive identities.
+// @evidence contracts/common.md#clear-and-simple-design One graph projection owns the writer representation; a private visitor copies metadata and component edges, and one tuple helper separates a named use from its inline component body.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping follows recursive tuple metadata and original collection names for every input. It does not mutate foreign implementations, change absorption options, recognize fixture names, or catch schema failures.
+// @evidence contracts/common.md#meaningful-documentation The comment explains absorbed input, recursive tuple representation, original name ownership, isolation and the requirement to share the returned root with property schema generation.
+// @evidence contracts/performance.md#efficient-algorithms Pointer maps visit each metadata and component once, and copy each outgoing edge once, for O(V+E+annotation payload) work and space. The projection adds no checker analysis, compiler or host operation.
+// @evidence contracts/performance.md#reuse-equivalent-work Pointer memoization reuses each original metadata and component's projection when several edges reach the same identity within this invocation. The immutable supplied graph establishes equivalence, and the caller reuses that one returned graph for root and property schema writes against shared components. Each different invocation owns fresh maps and does not reuse a projection across changed inputs.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Memo maps and copied nodes belong to one bake invocation and become reclaimable with its result; no global cache, handle or background work is retained.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The projection visits an in-memory typia metadata graph with no native file identity or subprocess boundary.
+func Project(input *metadata.MetadataSchema) *metadata.MetadataSchema {
+	projection := &projection{
+		metadatas:    map[*metadata.MetadataSchema]*metadata.MetadataSchema{},
+		arrays:       map[*metadata.MetadataArrayType]*metadata.MetadataArrayType{},
+		tuples:       map[*metadata.MetadataTupleType]*metadata.MetadataTupleType{},
+		objects:      map[*metadata.MetadataObjectType]*metadata.MetadataObjectType{},
+		aliases:      map[*metadata.MetadataAliasType]*metadata.MetadataAliasType{},
+		tupleAliases: map[*metadata.MetadataTupleType]*metadata.MetadataAliasType{},
+	}
+	return projection.visit(input)
+}
+
+// projection retains invocation-local graph identities, including
+// separate tuple component bodies and their named recursive use sites.
+type projection struct {
+	metadatas    map[*metadata.MetadataSchema]*metadata.MetadataSchema
+	arrays       map[*metadata.MetadataArrayType]*metadata.MetadataArrayType
+	tuples       map[*metadata.MetadataTupleType]*metadata.MetadataTupleType
+	objects      map[*metadata.MetadataObjectType]*metadata.MetadataObjectType
+	aliases      map[*metadata.MetadataAliasType]*metadata.MetadataAliasType
+	tupleAliases map[*metadata.MetadataTupleType]*metadata.MetadataAliasType
+}
+
+// visit copies every metadata edge before a writer can reach it. Shared scalar
+// tag and documentation payloads are read-only to the schema writer.
+func (p *projection) visit(input *metadata.MetadataSchema) *metadata.MetadataSchema {
+	if input == nil {
+		return nil
+	}
+	if output, ok := p.metadatas[input]; ok {
+		return output
+	}
+	output := input.ShallowClone()
+	p.metadatas[input] = output
+	output.Rest = p.visit(input.Rest)
+	if input.Escaped != nil {
+		copy := *input.Escaped
+		output.Escaped = &copy
+		copy.Original, copy.Returns = p.visit(input.Escaped.Original), p.visit(input.Escaped.Returns)
+	}
+	output.Atomics = copyLeaves(input.Atomics)
+	output.Constants = copyLeaves(input.Constants)
+	output.Natives = copyLeaves(input.Natives)
+	output.Templates = copyLeaves(input.Templates)
+	for i, entry := range input.Templates {
+		if entry == nil {
+			continue
+		}
+		output.Templates[i].Row = make([]*metadata.MetadataSchema, len(entry.Row))
+		for j, child := range entry.Row {
+			output.Templates[i].Row[j] = p.visit(child)
+		}
+	}
+	output.Functions = copyLeaves(input.Functions)
+	for i, entry := range input.Functions {
+		if entry == nil {
+			continue
+		}
+		copy := output.Functions[i]
+		copy.Output = p.visit(entry.Output)
+		copy.Parameters = copyLeaves(entry.Parameters)
+		for j, parameter := range entry.Parameters {
+			if parameter != nil {
+				copy.Parameters[j].Type = p.visit(parameter.Type)
+			}
+		}
+	}
+	output.Sets = copyLeaves(input.Sets)
+	for i, entry := range input.Sets {
+		if entry != nil {
+			output.Sets[i].Value = p.visit(entry.Value)
+		}
+	}
+	output.Maps = copyLeaves(input.Maps)
+	for i, entry := range input.Maps {
+		if entry != nil {
+			output.Maps[i].Key, output.Maps[i].Value = p.visit(entry.Key), p.visit(entry.Value)
+		}
+	}
+	output.Arrays = copyLeaves(input.Arrays)
+	for i, entry := range input.Arrays {
+		if entry == nil || entry.Type == nil {
+			continue
+		}
+		component, ok := p.arrays[entry.Type]
+		if !ok {
+			copy := *entry.Type
+			component = &copy
+			p.arrays[entry.Type] = component
+			component.Value = p.visit(entry.Type.Value)
+		}
+		output.Arrays[i].Type = component
+	}
+	output.Objects = copyLeaves(input.Objects)
+	for i, entry := range input.Objects {
+		if entry == nil || entry.Type == nil {
+			continue
+		}
+		component, ok := p.objects[entry.Type]
+		if !ok {
+			copy := *entry.Type
+			component = &copy
+			p.objects[entry.Type] = component
+			component.Properties = copyLeaves(entry.Type.Properties)
+			for j, property := range entry.Type.Properties {
+				if property != nil {
+					component.Properties[j].Key, component.Properties[j].Value = p.visit(property.Key), p.visit(property.Value)
+				}
+			}
+		}
+		output.Objects[i].Type = component
+	}
+	output.Aliases = copyLeaves(input.Aliases)
+	for i, entry := range input.Aliases {
+		if entry == nil || entry.Type == nil {
+			continue
+		}
+		component, ok := p.aliases[entry.Type]
+		if !ok {
+			copy := *entry.Type
+			component = &copy
+			p.aliases[entry.Type] = component
+			component.Value = p.visit(entry.Type.Value)
+		}
+		output.Aliases[i].Type = component
+	}
+	output.Tuples = make([]*metadata.MetadataTuple, 0, len(input.Tuples))
+	for _, entry := range input.Tuples {
+		if entry == nil || entry.Type == nil {
+			output.Tuples = append(output.Tuples, entry)
+			continue
+		}
+		if entry.Type.Recursive {
+			alias, ok := p.tupleAliases[entry.Type]
+			if !ok {
+				alias = metadata.MetadataAliasType_create(metadata.MetadataAliasType{
+					Name: entry.Type.Name, DisplayName: entry.Type.DisplayName, Recursive: true, Nullables: entry.Type.Nullables,
+				})
+				p.tupleAliases[entry.Type] = alias
+				body := metadata.MetadataSchema_initialize()
+				alias.Value = body
+				copy := *entry
+				copy.Type = p.tuple(entry.Type)
+				body.Tuples = []*metadata.MetadataTuple{&copy}
+			}
+			output.Aliases = append(output.Aliases, metadata.MetadataAlias_create(metadata.MetadataAlias{Type: alias, Tags: entry.Tags}))
+		} else {
+			copy := *entry
+			copy.Type = p.tuple(entry.Type)
+			output.Tuples = append(output.Tuples, &copy)
+		}
+	}
+	return output
+}
+
+// tuple copies a structural component after registering its identity, allowing
+// its child metadata to return through the already registered named alias.
+func (p *projection) tuple(input *metadata.MetadataTupleType) *metadata.MetadataTupleType {
+	if output, ok := p.tuples[input]; ok {
+		return output
+	}
+	copy := *input
+	output := &copy
+	p.tuples[input] = output
+	output.Elements = make([]*metadata.MetadataSchema, len(input.Elements))
+	for i, element := range input.Elements {
+		output.Elements[i] = p.visit(element)
+	}
+	return output
+}
+
+// copyLeaves isolates node-local name caches. Scalar annotation
+// slices remain shared because the public schema writer only reads them.
+func copyLeaves[T any](input []*T) []*T {
+	if input == nil {
+		return nil
+	}
+	output := make([]*T, len(input))
+	for i, item := range input {
+		if item != nil {
+			copy := *item
+			output[i] = &copy
+		}
+	}
+	return output
+}

package/native/transform/transform.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 
 	shimast "github.com/microsoft/typescript-go/shim/ast"
@@ -251,6 +252,19 @@ func writeSingleOutput(text, outPath string) int {
 	return 0
 }
 
+// SourceFileText returns the text supplied by a present Text() provider.
+// Missing values, including typed nil receivers, and values without Text()
+// return empty text and false without invoking a method. Errors from a present
+// provider's Text() method propagate to its caller.
+//
+// @evidence contracts/common.md#principled-implementation Structural Text() support establishes the provider operation, while a guarded reflect nil-identity check establishes that a receiver exists before dispatch. Every nil-capable kind follows the same absent-source rule; non-nil providers return their own text unchanged.
+// @evidence contracts/common.md#clear-and-simple-design One structural type assertion, one constant-time receiver-presence check restricted to the kinds for which Go permits IsNil, and one method dispatch separate absent sources from actual provider behavior.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The nil rule applies to all structural providers without compiler-type names or recovery. It does not invoke missing receivers, mutate foreign providers or conceal errors raised by present providers.
+// @evidence contracts/common.md#meaningful-documentation The comment states exact absent-value behavior, typed nil receiver treatment and propagation of present-provider errors.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The Text provider is an in-memory structural interface; the helper does not read a native source file.
+// @evidence contracts/performance.md#efficient-algorithms Type and nil checks are constant work; obtaining the string has the provider-defined cost.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The provider owns source text and the returned string may retain those bytes; no global provider reference is stored.
 func SourceFileText(target any) (string, bool) {
 	type sourceText interface {
 		Text() string
@@ -259,6 +273,13 @@ func SourceFileText(target any) (string, bool) {
 	if !ok {
 		return "", false
 	}
+	value := reflect.ValueOf(file)
+	switch value.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice, reflect.UnsafePointer:
+		if value.IsNil() {
+			return "", false
+		}
+	}
 	return file.Text(), true
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/core",
-  "version": "14.0.1",
+  "version": "14.0.2",
   "description": "Super-fast validation decorators of NestJS",
   "main": "lib/index.js",
   "exports": {
@@ -53,7 +53,7 @@
     "tgrid": "^1.1.0",
     "typia": "15.0.0",
     "ws": "^7.5.3",
-    "@nestia/fetcher": "^14.0.1"
+    "@nestia/fetcher": "^14.0.2"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.18.0",
@@ -63,7 +63,7 @@
     "rxjs": ">=7.1.0",
     "ttsc": ">=0.19.2",
     "typia": "15.0.0",
-    "@nestia/fetcher": "^14.0.1"
+    "@nestia/fetcher": "^14.0.2"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
@@ -107,7 +107,8 @@
   "scripts": {
     "build": "rimraf lib && ttsc",
     "dev": "ttsc --watch",
-    "test:go": "cd test && go test -count=1 ./..."
+    "test:go": "cd test && go test -count=1 ./...",
+    "evidence": "evidence"
   },
   "types": "lib/index.d.ts"
 }

package/src/adaptors/McpAdaptor.ts

@@ -11,6 +11,7 @@ import { InstanceWrapper } from "@nestjs/core/injector/instance-wrapper";
 import { Module } from "@nestjs/core/injector/module";
 
 import { IMcpRouteReflect } from "../decorators/internal/IMcpRouteReflect";
+import { resolve_request_body } from "../decorators/internal/validate_request_body";
 import {
   create_external_context_creator,
   get_request_context_id,
@@ -47,14 +48,12 @@ import {
  *
  * @author wildduck - https://github.com/wildduck2
  * @example
- *   ```typescript
  *   import core from "@nestia/core";
  *   import { NestFactory } from "@nestjs/core";
  *
  *   const app = await NestFactory.create(AppModule);
  *   await core.McpAdaptor.upgrade(app, { path: "/mcp" });
  *   await app.listen(3000);
- *   ```;
  */
 export class McpAdaptor {
   /**
@@ -71,6 +70,11 @@ export class McpAdaptor {
    *
    * @param app Running Nest application instance.
    * @param options Transport and identity overrides.
+   * @evidence contracts/common.md#principled-implementation Tools are collected once from the prototype chain of every controller instance by the `nestia/McpRoute` metadata, with the first definition of a property name winning and accessors skipped without execution, duplicates by tool name refused before serving, and each call runs through NestJS's `ExternalContextCreator` so guards, interceptors, pipes, and exception filters apply as for an HTTP route; every request gets a fresh MCP server and Streamable HTTP transport, which stateless mode requires, and both are closed in a `finally`.
+   * @evidence contracts/common.md#clear-and-simple-design One entry point does discovery and registration; the per-tool call (`createHandler`), the duplicate check, the SDK loader, and the per-request response facade are separate module-private functions.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Reading the module graph goes through the internal `app.container`, because `INestApplication` exposes no public accessor for it, `create_external_context_creator` constructs an owned subclass through the Nest constructor and overrides module selection on that type, because the default looks for provider classes while controllers belong to the controller collection, and `get_request_context_id` registers the request provider on the request object as NestJS's router does for an HTTP route, and a per-request response facade forwards native state, events and method receivers without replacing raw methods. After a tool or its exception filter has sent headers, only the facade suppresses subsequent transport writes and preserves callbacks and chaining. Native transport writes do not themselves activate takeover. The remaining foreign-internal reads are the application container and Nest request context registration; the MCP SDK uses its public Node response injection boundary.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the stateless mode, what is discovered, and that the SDK is an optional dependency; the options documentation states the path and server information.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation MCP tool discovery and HTTP transport callbacks carry protocol values; optional SDK imports use Node module resolution and no native file identity or child process is defined here.
    */
   public static async upgrade(
     app: INestApplication,
@@ -101,7 +105,8 @@ export class McpAdaptor {
           for (const key of Object.getOwnPropertyNames(proto)) {
             if (key === "constructor" || visited.has(key)) continue;
             visited.add(key);
-            const method = proto[key];
+            // Route discovery inspects data descriptors without invoking accessors.
+            const method = Object.getOwnPropertyDescriptor(proto, key)?.value;
             if (typeof method !== "function") continue;
 
             const meta: IMcpRouteReflect | undefined = Reflect.getMetadata(
@@ -154,6 +159,7 @@ export class McpAdaptor {
         capabilities: { tools: {} },
       });
       const server = mcp.server;
+      const relay = transportResponse(res.raw ?? res);
 
       server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: tools.map((t) => ({
@@ -181,7 +187,7 @@ export class McpAdaptor {
             response: res,
             args,
           });
-          if (tookOver(res)) return { content: [] };
+          if (relay.takeOver()) return { content: [] };
           if (result instanceof Error) throw result;
           if (result === undefined) return { content: [] };
           return {
@@ -194,7 +200,7 @@ export class McpAdaptor {
             ],
           };
         } catch (e) {
-          if (tookOver(res)) return { content: [] };
+          if (relay.takeOver()) return { content: [] };
           if (INVALID_ARGUMENTS.has(e as object)) {
             const body = (e as BadRequestException).getResponse() as any;
             throw new McpError(ErrorCode.InvalidParams, (e as Error).message, {
@@ -224,7 +230,7 @@ export class McpAdaptor {
       });
       try {
         await mcp.connect(transport);
-        await transport.handleRequest(req.raw ?? req, res.raw ?? res, req.body);
+        await transport.handleRequest(req.raw ?? req, relay.response, req.body);
       } finally {
         await transport.close().catch(() => {});
         await mcp.close().catch(() => {});
@@ -242,7 +248,9 @@ export class McpAdaptor {
  * The arguments reach the method through the pipes as its body would, validated
  * by typia at that stage: after the guards, as `@TypedBody()` is. An invalid
  * argument is thrown as the validator's `BadRequestException`, which an
- * exception filter may map; unmapped, it becomes JSON-RPC `-32602`.
+ * exception filter may map; unmapped, it becomes JSON-RPC `-32602`. Successful
+ * resolver data becomes the argument before pipes execute. Legacy error-only
+ * metadata callbacks retain raw input on null success.
  *
  * A controller that is request-scoped, itself or through an enhancer or a
  * dependency, is built per request with its enhancers, as NestJS builds it for
@@ -275,10 +283,11 @@ const createHandler = (props: {
       {
         // [request, response, next] as an HTTP route has, then the arguments
         exchangeKeyForValue: (_type, _data, [, , , args]) => {
-          const error: Error | null = validate ? validate(args) : null;
-          if (error === null) return args;
-          INVALID_ARGUMENTS.add(error);
-          throw error;
+          if (!validate) return args;
+          const result = resolve_request_body(validate, args);
+          if (result.success) return result.data;
+          INVALID_ARGUMENTS.add(result.error);
+          throw result.error;
         },
       },
       contextId,
@@ -307,22 +316,55 @@ const createHandler = (props: {
 };
 
 /**
- * Whether an exception filter already wrote the HTTP response itself. The
- * response it wrote stands, so the transport's own is dropped: writing again
- * would throw, and the transport would destroy the connection mid-response.
+ * The transport's response view. Native state, events and method receivers stay
+ * on the real response; only this view's writes stop after a tool's exception
+ * filter has already answered. Normal transport writes never activate
+ * takeover.
  */
-const tookOver = (response: any): boolean => {
-  const raw: any = response.raw ?? response;
-  if (raw.headersSent !== true) return false;
-  raw.writeHead = () => raw;
-  raw.flushHeaders = () => {};
-  raw.write = () => true;
-  raw.end = (...args: unknown[]) => {
-    const callback: unknown = args.find((a) => typeof a === "function");
-    if (typeof callback === "function") queueMicrotask(() => callback());
-    return raw;
+const transportResponse = (
+  raw: any,
+): { response: any; takeOver: () => boolean } => {
+  let takenOver = false;
+  const respond = (key: string, args: unknown[]): unknown => {
+    if (takenOver) {
+      const callback = args.find((arg) => typeof arg === "function");
+      if ((key === "write" || key === "end") && typeof callback === "function")
+        queueMicrotask(() => callback());
+      return key === "write"
+        ? true
+        : key === "flushHeaders"
+          ? undefined
+          : response;
+    }
+    const result = Reflect.apply(raw[key], raw, args);
+    return result === raw ? response : result;
+  };
+  const writes = new Map<PropertyKey, (...args: unknown[]) => unknown>(
+    ["writeHead", "flushHeaders", "write", "end"].map((key) => [
+      key,
+      (...args: unknown[]) => respond(key, args),
+    ]),
+  );
+  const response: any = new Proxy(raw, {
+    get: (target, key) => {
+      const write = writes.get(key);
+      if (write !== undefined) return write;
+      const value = Reflect.get(target, key, target);
+      if (typeof value !== "function") return value;
+      return (...args: unknown[]) => {
+        const result = Reflect.apply(value, target, args);
+        return result === target ? response : result;
+      };
+    },
+    set: (target, key, value) => Reflect.set(target, key, value, target),
+  });
+  return {
+    response,
+    takeOver: () => {
+      takenOver ||= raw.headersSent === true;
+      return takenOver;
+    },
   };
-  return true;
 };
 
 const PARAMS_METADATA = "nestia/McpRoute/ExternalParameters";
@@ -374,8 +416,26 @@ const loadMcpSdk = async () => {
   }
 };
 
+/**
+ * Types of {@link McpAdaptor}: the options of `upgrade` and the record of a
+ * registered tool.
+ *
+ * @evidence contracts/common.md#principled-implementation The class exposes one static entry point, so the adapter has no instance state: the tool list is closed over by the registered route handler.
+ * @evidence contracts/common.md#clear-and-simple-design One static method and two nested types.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It has no fixture or tool name, and the MCP SDK is loaded lazily so an application that never enables MCP does not need it.
+ * @evidence contracts/common.md#meaningful-documentation The class comment explains what an MCP route is and how to enable it.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation MCP tool discovery and HTTP transport callbacks carry protocol values; optional SDK imports use Node module resolution and no native file identity or child process is defined here.
+ */
 export namespace McpAdaptor {
-  /** Configuration options for {@link McpAdaptor.upgrade}. */
+  /**
+   * Configuration options for {@link McpAdaptor.upgrade}.
+   *
+   * @evidence contracts/common.md#principled-implementation The two options are the route path, with `/mcp` as the default, and the server information reported to clients, with a default name and version.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record of two optional values.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type; the defaults are stated in the code that reads them.
+   * @evidence contracts/common.md#meaningful-documentation Each option documents its meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation MCP tool discovery and HTTP transport callbacks carry protocol values; optional SDK imports use Node module resolution and no native file identity or child process is defined here.
+   */
   export interface IOptions {
     /**
      * HTTP path where the MCP endpoint will be mounted.