@nestia/core 14.0.1 → 14.0.3

package/native/transform/buildoutput/output.go

@@ -0,0 +1,147 @@
+// Package buildoutput owns a build's buffered artifact publication and reporting.
+package buildoutput
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sync"
+)
+
+// Options fixes the command's reporting and publication policy for one build.
+//
+// @evidence contracts/common.md#principled-implementation Emit reflects the original compiler configuration, while Quiet and Manifest retain the requested output protocol; the three plugin flags and project paths describe the actual build summary.
+// @evidence contracts/common.md#clear-and-simple-design One value separates immutable command policy from buffered artifacts and the filesystem writer.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts These values come from resolved command inputs and compiler options, without fixture or caller-name decisions.
+// @evidence contracts/common.md#meaningful-documentation The declaration identifies the lifetime and meaning of publication policy.
+// @evidence contracts/performance.md#efficient-algorithms This fixed policy record performs no traversal or computation; session construction copies its scalar fields and string references once.
+// @evidence contracts/performance.md#reuse-equivalent-work One immutable resolved policy is shared by callbacks of the same build; a new build receives its own policy instead of a cached compiler configuration.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The record holds flags and path strings only, with no handles or independently growing collection; its lifetime belongs to one output session.
+// @evidence contracts/portability.md#os-neutral-implementation Paths remain caller-provided opaque strings until the manifest filesystem owner interprets them through native filepath operations; the policy introduces no separator or platform-name assumptions.
+type Options struct {
+	// TSConfig is the requested project path shown in the initial summary.
+	TSConfig string
+
+	// CWD is the resolved working directory shown in the initial summary.
+	CWD string
+
+	// Manifest is the explicitly requested output-list path; empty disables it.
+	Manifest string
+
+	// Core, SDK and Typia are the resolved composing-plugin flags.
+	Core, SDK, Typia bool
+
+	// Emit is the original compiler policy, before any private analysis traversal.
+	Emit bool
+
+	// Quiet suppresses both initial and successful-publication summaries.
+	Quiet bool
+}
+
+// Publisher buffers compiler artifacts until the caller reports successful completion.
+// Its write callback is the build's artifact filesystem boundary; manifest output
+// uses native filesystem operations. Finish follows completed producer callbacks
+// and terminates the session, releasing all buffered strings even on failure.
+//
+// @evidence contracts/common.md#principled-implementation Compiler callbacks append under a mutex only for an emitting configuration. The completion verdict gates all artifact and requested-manifest writes; artifacts precede the manifest, and any filesystem failure stops publication and the success summary.
+// @evidence contracts/common.md#clear-and-simple-design One command-scoped session owns the immutable policy, concurrent buffer and output dependencies; no compiler, transform or project loader is retained.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The caller supplies the existing production artifact writer, not a replaced foreign method. Completion comes from actual compiler and transform diagnostics; this layer does not invent their verdict.
+// @evidence contracts/common.md#meaningful-documentation The declaration states writer ownership, producer completion, session termination and failure release behavior.
+// @evidence contracts/performance.md#efficient-algorithms Buffering and publication each visit every emitted artifact once; manifest encoding costs the sum of path lengths.
+// @evidence contracts/performance.md#reuse-equivalent-work Immutable build policy is shared by all concurrent compiler callbacks of this session only, and a manifest uses the same ordered artifact paths.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Only one build's output strings are retained until Finish, which detaches the entire buffer before any filesystem call. No package state or file handle survives completion.
+// @evidence contracts/portability.md#os-neutral-implementation Artifact paths are delegated unchanged to the production writer, and the manifest uses native filesystem operations in Finish. Session state and mutex semantics do not depend on a host operating system.
+type Publisher struct {
+	options   Options
+	stdout    io.Writer
+	writeFile func(string, string) error
+	mutex     sync.Mutex
+	pending   []artifact
+}
+
+type artifact struct{ fileName, text string }
+
+// New begins one output session and writes its initial summary when requested.
+//
+// @evidence contracts/common.md#principled-implementation The initial summary reports the original Emit policy before transforms run, so a verbose analysis-only build reports emit=false even when its private transformer traversal emits into a discarded buffer.
+// @evidence contracts/common.md#clear-and-simple-design Construction stores policy and actual output boundaries, then writes one conditional summary.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The actual command supplies paths, plugin flags and writers; no expected diagnostic or artifact is fabricated.
+// @evidence contracts/common.md#meaningful-documentation The comment distinguishes the initial summary from successful publication reporting.
+// @evidence contracts/performance.md#efficient-algorithms Construction allocates one fixed session and formats at most one summary, costing the reported path lengths rather than loading or scanning a compiler project.
+// @evidence contracts/performance.md#reuse-equivalent-work The same options and writer references serve all callbacks in this one build, with no cross-build cache or compiler identity reuse.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The command owns the returned session; construction creates no file or process handles, and the command's terminal Finish releases buffered outputs.
+// @evidence contracts/portability.md#os-neutral-implementation The initial report prints caller-provided paths as text and does not join, normalize or infer an operating system from them.
+func New(options Options, stdout io.Writer, writeFile func(string, string) error) *Publisher {
+	p := &Publisher{options: options, stdout: stdout, writeFile: writeFile}
+	if !options.Quiet {
+		fmt.Fprintf(stdout, "// ttsc-nestia build: tsconfig=%s cwd=%s core=%v sdk=%v typia=%v emit=%v\n", options.TSConfig, options.CWD, options.Core, options.SDK, options.Typia, options.Emit)
+	}
+	return p
+}
+
+// Write buffers a completed artifact without publishing bytes; analysis-only output is discarded.
+//
+// @evidence contracts/common.md#principled-implementation Original non-emitting policy discards callback output. An emitting session serializes each filename/text pair under its mutex so parallel declaration callbacks cannot lose or misassociate artifacts.
+// @evidence contracts/common.md#clear-and-simple-design One policy check and one protected append implement the compiler callback boundary.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Every buffered filename and byte string comes from the actual compiler callback; this operation invokes no filesystem or compiler surrogate.
+// @evidence contracts/common.md#meaningful-documentation The comment states deferred publication and the analysis-only discard rule.
+// @evidence contracts/performance.md#efficient-algorithms Each callback performs one policy check and amortized constant-time append under a mutex; it retains the compiler strings without reparsing or copying their contents.
+// @evidence contracts/performance.md#reuse-equivalent-work Callbacks share only the immutable session policy and its protected buffer. No artifact is inferred from or substituted for another callback's bytes.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Each filename/text pair remains scoped to this build until Finish detaches the complete buffer, including rejected and analysis-only completion paths.
+// @evidence contracts/portability.md#os-neutral-implementation The callback preserves compiler-provided filename text and performs no path interpretation, filesystem call or platform-dependent concurrency branch.
+func (p *Publisher) Write(fileName, text string) {
+	if !p.options.Emit {
+		return
+	}
+	p.mutex.Lock()
+	defer p.mutex.Unlock()
+	p.pending = append(p.pending, artifact{fileName: fileName, text: text})
+}
+
+// Finish commits successful emitting output in artifact/manifest/summary order.
+// A rejected or analysis-only build writes no artifacts or manifest. The buffer
+// is released on every path; a filesystem failure can leave preceding artifacts
+// and is returned to the command for its nonzero diagnostic protocol.
+//
+// @evidence contracts/common.md#principled-implementation The actual completion verdict and Emit policy jointly gate publication. Each callback artifact is written unchanged; the explicitly requested manifest contains exactly those paths, and the success summary appears only after all writes succeed. Earlier writes are not claimed to be transactional on an IO failure.
+// @evidence contracts/common.md#clear-and-simple-design One terminal operation detaches the session buffer, applies two guards and executes ordered artifact, manifest and summary stages with immediate error returns.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The operation does not invoke a compiler or infer success from output presence. Its callback is the caller-owned filesystem boundary, and manifest creation uses standard native IO.
+// @evidence contracts/common.md#meaningful-documentation The comment states artifact ordering, no-output states, buffer release and the partial-write limit on IO failure.
+// @evidence contracts/portability.md#os-neutral-implementation The requested manifest uses filepath.Dir and native os.MkdirAll/os.WriteFile. Artifact paths are passed unchanged to the production writer; no platform-name predicate or path separator assumption is introduced.
+// @evidence contracts/performance.md#efficient-algorithms Completion traverses each retained artifact once and encodes the ordered path list once, costing artifact count plus emitted bytes and manifest path lengths; it starts no compiler or product host.
+// @evidence contracts/performance.md#reuse-equivalent-work The manifest derives from the exact successfully written ordered artifacts of this session, and no output list or success verdict is cached across builds.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The session buffer is detached before either guard or any filesystem write; local output references are released at return even on the first IO error, and native write operations close their own handles.
+func (p *Publisher) Finish(succeeded bool) error {
+	p.mutex.Lock()
+	pending := p.pending
+	p.pending = nil
+	p.mutex.Unlock()
+	if !succeeded || !p.options.Emit {
+		return nil
+	}
+	emitted := make([]string, 0, len(pending))
+	for _, output := range pending {
+		if err := p.writeFile(output.fileName, output.text); err != nil {
+			return fmt.Errorf("emit write failed: %w", err)
+		}
+		emitted = append(emitted, output.fileName)
+	}
+	if p.options.Manifest != "" {
+		data, err := json.Marshal(emitted)
+		if err != nil {
+			return fmt.Errorf("manifest marshal failed: %w", err)
+		}
+		if err := os.MkdirAll(filepath.Dir(p.options.Manifest), 0o755); err != nil {
+			return fmt.Errorf("manifest mkdir failed: %w", err)
+		}
+		if err := os.WriteFile(p.options.Manifest, data, 0o644); err != nil {
+			return fmt.Errorf("manifest write failed: %w", err)
+		}
+	}
+	if !p.options.Quiet {
+		fmt.Fprintf(p.stdout, "// ttsc-nestia build: emitted=%d files\n", len(emitted))
+	}
+	return nil
+}

package/native/transform/contributor.go

@@ -14,6 +14,15 @@ var emitTransformCollectors []emitTransformCollector
 // inside the shared EmitContext alongside the typia and core node transforms, so
 // a linked contributor (e.g. @nestia/sdk) participates in the same emit pass
 // rather than patching its output afterwards.
+//
+// @evidence contracts/common.md#principled-implementation A statically linked contributor registers a collector once at package initialization, and the host runs all collectors in registration order inside the shared emit pass, so contributors take part in the same emit rather than rewriting its output afterwards; a nil collector is ignored.
+// @evidence contracts/common.md#clear-and-simple-design One append to a package-level list, read by one private function.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It is the documented registration point for linked contributors, not a hook into foreign code; the list is written only during initialization, which is single-threaded.
+// @evidence contracts/common.md#meaningful-documentation The comment states who calls it, when the collectors run, and why.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation A collector is an in-process function registered by linked Go packages, with no native path or subprocess representation.
+// @evidence contracts/performance.md#efficient-algorithms A non-nil registration appends once with amortized constant work; executing all registered collectors later is linear in their count plus their own work.
+// @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 process owns the collector slice for its lifetime. Registration is intended for package initialization; repeated later registrations would grow it without a bound.
 func RegisterEmitTransformCollector(collector emitTransformCollector) {
 	if collector != nil {
 		emitTransformCollectors = append(emitTransformCollectors, collector)

package/native/transform/core_querify.go

@@ -66,9 +66,7 @@ func nestiaCoreHttpQuerifyProgrammer(prog *driver.Program, ec *shimprinter.EmitC
 			if ok == false || property == nil || property.Value == nil {
 				continue
 			}
-			statements = append(statements, nestiaCoreFactory.NewExpressionStatement(
-				nestiaCoreHttpQuerifyDecode(key, property.Value, ec),
-			))
+			statements = append(statements, nestiaCoreHttpQuerifyDecode(key, property.Value, ec))
 		}
 	}
 	statements = append(statements, nestiaCoreFactory.NewReturnStatement(nestiaCoreFactory.NewIdentifier("output")))
@@ -194,7 +192,43 @@ func nestiaCoreQueryWrapperArrow(statements []*shimast.Node) *shimast.Node {
 	)
 }
 
+// nestiaCoreHttpQuerifyDecode writes one property into the URLSearchParams.
+//
+// An omitted optional property and a null array both write nothing, which the
+// request decoder reads back as undefined and null; a nullable scalar still
+// writes its "null" marker.
 func nestiaCoreHttpQuerifyDecode(key string, value *schemametadata.MetadataSchema, ec *shimprinter.EmitContext) *shimast.Node {
+	statement := nestiaCoreFactory.NewExpressionStatement(nestiaCoreHttpQuerifyWrite(key, value, ec))
+	absent := []shimast.Kind{}
+	if value.IsRequired() == false {
+		absent = append(absent, shimast.KindUndefinedKeyword)
+	}
+	if len(value.Arrays) != 0 && value.Nullable {
+		absent = append(absent, shimast.KindNullKeyword)
+	}
+	for i := len(absent) - 1; i >= 0; i-- {
+		var marker *shimast.Node
+		if absent[i] == shimast.KindUndefinedKeyword {
+			marker = nestiaCoreFactory.NewIdentifier("undefined")
+		} else {
+			marker = nestiaCoreFactory.NewKeywordExpression(absent[i])
+		}
+		statement = nestiaCoreFactory.NewIfStatement(
+			nestiaCoreFactory.NewBinaryExpression(
+				nil,
+				nativefactories.IdentifierFactory.Access(ec, nestiaCoreFactory.NewIdentifier("input"), key),
+				nil,
+				nestiaCoreFactory.NewToken(shimast.KindExclamationEqualsEqualsToken),
+				marker,
+			),
+			statement,
+			nil,
+		)
+	}
+	return statement
+}
+
+func nestiaCoreHttpQuerifyWrite(key string, value *schemametadata.MetadataSchema, ec *shimprinter.EmitContext) *shimast.Node {
 	if len(value.Arrays) != 0 {
 		return nestiaCoreFactory.NewCallExpression(
 			nativefactories.IdentifierFactory.Access(

package/native/transform/core_transform.go

@@ -3,7 +3,6 @@ package transform
 import (
 	"fmt"
 	"os"
-	"path/filepath"
 	"regexp"
 	"runtime/debug"
 	"strings"
@@ -128,7 +127,7 @@ func nestiaCoreOptionErrors(plan plugin.Plan) []string {
 		errors = append(errors, fmt.Sprintf("invalid %q option %s: it must be one of %s.", name, nestiaCoreOptionText(value), accepted))
 	}
 	for _, entry := range plan.Entries {
-		if entry.Name != "@nestia/core" && !strings.Contains(entry.Transform, "@nestia/core") {
+		if entry.Kind() != "core" {
 			continue
 		}
 		if value, ok := entry.Config["validate"]; ok {
@@ -151,7 +150,7 @@ func nestiaCoreOptionText(value any) string {
 func readNestiaCoreOptions(plan plugin.Plan) nestiaCoreOptions {
 	options := nestiaCoreOptions{}
 	for _, entry := range plan.Entries {
-		if entry.Name != "@nestia/core" && !strings.Contains(entry.Transform, "@nestia/core") {
+		if entry.Kind() != "core" {
 			continue
 		}
 		if value, ok := entry.Config["validate"].(string); ok {
@@ -222,7 +221,7 @@ func nestiaCoreDecoratorCall(prog *driver.Program, decorator *shimast.Node) (*sh
 	}
 	context := newNestiaCoreFileContext(shimast.GetSourceFileOfNode(decorator))
 	canonical := nestiaCoreCanonicalSegments(context, segments)
-	if nestiaCoreDecoratorReference(prog, context, decorator, segments, canonical) == false {
+	if IsNestiaCoreCall(prog, call.AsNode()) == false {
 		return nil, nil, false
 	}
 	return call, canonical, true
@@ -232,6 +231,18 @@ func nestiaCoreDecoratorCall(prog *driver.Program, decorator *shimast.Node) (*sh
 // @nestia/core export its import binds, so `import { TypedException as TE }`
 // reads `TE<T>()` as `TypedException`. It returns nil for a decorator that is
 // no call.
+//
+// This mapping names the imported syntax. IsNestiaCoreCall separately verifies
+// that the resolved declaration belongs to core, including re-export facades.
+//
+// @evidence contracts/common.md#principled-implementation The decorator's callee is split into identifier segments, and the leading identifier is replaced by the `@nestia/core` export that its import binds, so an aliased import reads as the canonical name; a decorator that is not a call reads as nil.
+// @evidence contracts/common.md#clear-and-simple-design A thin exported wrapper that builds the file's import context and delegates the mapping to a private function.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The names come from the import declarations of the file, and no alias or file name is special-cased.
+// @evidence contracts/common.md#meaningful-documentation The comment gives the aliasing example and the nil result.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The import mapping reads TypeScript AST module specifiers and names rather than native paths.
+// @evidence contracts/performance.md#efficient-algorithms The helper scans file statements and named imports to build its mapping on each call, then walks the callee segments. Repeated decorator calls in one file rebuild that mapping.
+// @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 file context map and returned segment slice are call-local; no program is retained globally by this helper.
 func NestiaCoreCanonicalDecoratorSegments(decorator *shimast.Node) []string {
 	_, segments, ok := nestiaCoreRawDecoratorCall(decorator)
 	if !ok {
@@ -308,32 +319,24 @@ func nestiaCoreCanonicalSegments(context nestiaCoreFileContext, segments []strin
 	return canonical
 }
 
-func nestiaCoreDecoratorReference(
-	prog *driver.Program,
-	context nestiaCoreFileContext,
-	decorator *shimast.Node,
-	segments []string,
-	canonical []string,
-) bool {
-	if len(segments) == 0 {
-		return false
-	}
-	if _, ok := context.coreImports[segments[0]]; ok {
-		return true
-	}
-	if nestiaCorePotentialDecoratorSegments(canonical) == false {
+// IsNestiaCoreCall reports whether the call resolves to a declaration in `@nestia/core`.
+//
+// The resolved signature's declaration belongs to core only when its nearest
+// package manifest names @nestia/core, including relocated or re-exported core
+// declarations and excluding foreign nested packages.
+//
+// @evidence contracts/common.md#principled-implementation The resolved signature identifies the actual declaration source, and SourceFilePackageName establishes its nearest owner; unresolved calls or non-core ownership return false without relying on lexical aliases or directory spelling.
+// @evidence contracts/common.md#clear-and-simple-design Signature/source nil guards precede one shared package-ownership operation and an exact name comparison.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Foreign workspace lookalikes and nested packages cannot inherit core identity from their path, while a relocated or transparently re-exported core declaration keeps its actual manifest owner.
+// @evidence contracts/common.md#meaningful-documentation The comment defines resolved declaration ownership and describes relocation, re-export and nested-package behavior.
+// @evidence contracts/portability.md#os-neutral-implementation Declaration package ownership delegates to SourceFilePackageName, which walks native ancestors through filepath and the loaded program filesystem rather than source-path substrings.
+// @evidence contracts/performance.md#efficient-algorithms Resolved signature lookup is followed by one nearest-manifest ancestor walk, proportional to directory depth and manifest bytes.
+// @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 No separate cache is retained by this predicate; the compiler program owns resolved signatures and filesystem observations.
+func IsNestiaCoreCall(prog *driver.Program, node *shimast.Node) bool {
+	if prog == nil || prog.Checker == nil || node == nil {
 		return false
 	}
-	return IsNestiaCoreCall(prog, decorator.AsDecorator().Expression)
-}
-
-func nestiaCorePotentialDecoratorSegments(segments []string) bool {
-	return nestiaCoreParameterKind(segments) != "" ||
-		nestiaCoreMethodKind(segments) != "" ||
-		(len(segments) != 0 && segments[len(segments)-1] == "WebSocketRoute")
-}
-
-func IsNestiaCoreCall(prog *driver.Program, node *shimast.Node) bool {
 	signature := prog.Checker.GetResolvedSignature(node)
 	if signature == nil || signature.Declaration() == nil {
 		return false
@@ -342,11 +345,7 @@ func IsNestiaCoreCall(prog *driver.Program, node *shimast.Node) bool {
 	if source == nil {
 		return false
 	}
-	location := filepath.ToSlash(source.FileName())
-	return strings.Contains(location, "@nestia/core/lib/") ||
-		strings.Contains(location, "packages/core/lib/") ||
-		strings.Contains(location, "@nestia/core/src/decorators/") ||
-		strings.Contains(location, "packages/core/src/decorators/")
+	return SourceFilePackageName(prog, source) == "@nestia/core"
 }
 func nestiaCoreParameterKind(segments []string) string {
 	suffixes := map[string]string{
@@ -461,6 +460,12 @@ func nestiaCoreParameterArgumentNodes(
 	return output, true, nil
 }
 
+// nestiaCoreGenerateTypedBody preserves the selected helper's validation,
+// equality, clone or prune operation within the public three-tag validator ABI.
+// The shared runtime resolver retains assert returns and validation.data for
+// decorated arguments, so clone helpers supply copies while is retains the
+// input. Prune helpers mutate and return that same input. Explicit success tags
+// distinguish valid Error, null or undefined data from validation failures.
 func nestiaCoreGenerateTypedBody(
 	prog *driver.Program,
 	importer *nativecontext.ImportProgrammer, ec *shimprinter.EmitContext,
@@ -522,13 +527,12 @@ func nestiaCoreGenerateTypedBody(
 	}
 }
 
-// nestiaCoreGenerateTypedHeaders intentionally collapses the 10-mode validate
-// option down to {assert, is, validate}. Header values are strings keyed by
-// name; deep-clone and prune semantics that @TypedBody honors (assertClone,
-// assertPrune, validateClone, validatePrune, etc.) have no meaningful effect
-// on a flat string→string map. Pass-through to the base programmer is the
-// intended behavior, not a fallthrough — matches v6 parity. See also
-// nestiaCoreGenerateTypedQuery and nestiaCoreGenerateTypedFormDataBody.
+// nestiaCoreGenerateTypedHeaders maps all ten validate options onto the HTTP
+// header decoder's three base validator families: assert, is and validate.
+// Equality, clone and prune options select their corresponding base family;
+// this operation generates decoded header values rather than a plain body helper.
+// Body helper return semantics and the decorator's returned body are distinct:
+// see nestiaCoreGenerateTypedBody for clone results and in-place pruning.
 func nestiaCoreGenerateTypedHeaders(prog *driver.Program, importer *nativecontext.ImportProgrammer, ec *shimprinter.EmitContext, options nestiaCoreOptions, modulo *shimast.Node, typ *shimchecker.Type) *shimast.Node {
 	context := nestiaCoreTypiaContext(prog, importer, ec, false, false, false)
 	name := nestiaCoreTypeName(prog, typ)
@@ -1085,6 +1089,18 @@ func safeNestiaCoreGenerateNode(generator func() (*shimast.Node, error)) (node *
 
 var nestiaCoreSingleParameterArrowPattern = regexp.MustCompile(`(^|[\s(=,:?])([A-Za-z_$][A-Za-z0-9_$]*) =>`)
 
+// NestiaCoreMethodReturnType returns the type of a route method's response body.
+//
+// The declared return type is used when it is `Promise<T>` or an rxjs `Observable<T>`, and `T` is returned, so an asynchronous method is typed by what it resolves to. A missing signature returns nil.
+//
+// @evidence contracts/common.md#principled-implementation An explicit annotation is unwrapped only when its resolved symbol declares the TypeScript library Promise or an rxjs-owned Observable. Otherwise the checker's resolved return type uses the same provenance rule, preserving user wrappers and allowing aliases to the library type. Global Promise augmentations retain the library declaration in their merged symbol.
+// @evidence contracts/common.md#clear-and-simple-design One function with two unwrapping paths, sharing the private wrapper predicates.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The wrappers are the two types NestJS handlers return; no method or controller name is special-cased.
+// @evidence contracts/common.md#meaningful-documentation The comment states the unwrapped wrappers and the nil result.
+// @evidence contracts/portability.md#os-neutral-implementation Promise provenance comes from compiler library identity; Observable package ownership uses SourceFilePackageName and the program filesystem with native filepath ancestors.
+// @evidence contracts/performance.md#efficient-algorithms The function inspects one annotation/signature and its wrapper declarations; Observable ownership may perform one native ancestor walk per candidate declaration.
+// @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 Returned types are owned by the caller program; this helper retains no type or program cache.
 func NestiaCoreMethodReturnType(prog *driver.Program, node *shimast.Node) *shimchecker.Type {
 	if typ := nestiaCoreExplicitAsyncReturnType(prog, node); typ != nil {
 		return typ
@@ -1099,7 +1115,7 @@ func NestiaCoreMethodReturnType(prog *driver.Program, node *shimast.Node) *shimc
 	}
 	symbol := typ.Symbol()
 	if symbol != nil &&
-		nestiaCoreIsAsyncReturnWrapperSymbol(symbol.Name, symbol.Declarations) {
+		nestiaCoreIsAsyncReturnWrapperSymbol(prog, symbol.Name, symbol.Declarations) {
 		args := prog.Checker.GetTypeArguments(typ)
 		if len(args) == 1 {
 			return args[0]
@@ -1120,92 +1136,72 @@ func nestiaCoreExplicitAsyncReturnType(prog *driver.Program, node *shimast.Node)
 	if ref == nil || ref.TypeArguments == nil || len(ref.TypeArguments.Nodes) != 1 {
 		return nil
 	}
-	if nestiaCoreIsAsyncReturnWrapperReference(prog, ref.TypeName) == false {
+	if NestiaCoreIsAsyncReturnWrapperReference(prog, ref.TypeName) == false {
 		return nil
 	}
 	return prog.Checker.GetTypeFromTypeNode(ref.TypeArguments.Nodes[0])
 }
 
-func nestiaCoreIsAsyncReturnWrapperReference(
+// NestiaCoreIsAsyncReturnWrapperReference reports whether a type reference names
+// a wrapper a route method's return type is unwrapped from: `Promise`, or the
+// rxjs `Observable` however it is imported, aliased or re-exported.
+//
+// Promise must have a resolved declaration in the program's TypeScript library.
+// Observable must have a resolved declaration owned by rxjs. A same-spelled
+// user wrapper remains an ordinary response type.
+//
+// @evidence contracts/common.md#principled-implementation The checker resolves the reference and import aliases to their declarations. Promise requires a declaration in the compiler-identified library; Observable requires a nearest manifest naming rxjs. Namespace user types and missing library declarations cannot become asynchronous wrappers merely by spelling.
+// @evidence contracts/common.md#clear-and-simple-design One function that resolves the symbol and delegates the name and ownership test to the shared symbol predicate, so the syntactic annotation path and the checker path of the return type use one rule; the SDK reads the same function rather than keeping a second copy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No source spelling, fixture identity, filename fragment or folder name substitutes for declaration provenance. The TypeScript program identifies its actual library files and the program filesystem supplies nearest package ownership.
+// @evidence contracts/common.md#meaningful-documentation The comment identifies both supported wrappers and their declaration provenance requirements, including preservation of user lookalikes.
+// @evidence contracts/portability.md#os-neutral-implementation Library identity uses the compiler; rxjs ownership uses program filesystem reads and filepath ancestor traversal through SourceFilePackageName.
+// @evidence contracts/performance.md#efficient-algorithms Symbol/alias resolution is followed by a declaration scan and at most one ancestor walk per Observable declaration.
+// @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 No result cache or handle is owned here; returned truth is independent of any retained storage.
+func NestiaCoreIsAsyncReturnWrapperReference(
 	prog *driver.Program,
 	node *shimast.Node,
 ) bool {
-	name := nestiaCoreTypeNodeText(node)
-	if name == "Promise" {
-		return true
+	if node == nil {
+		return false
 	}
-	if name != "Observable" || prog == nil || prog.Checker == nil {
+	if prog == nil || prog.Checker == nil {
 		return false
 	}
 	symbol := prog.Checker.GetSymbolAtLocation(node)
-	return nestiaCoreIsRxjsObservableImport(node) ||
-		(symbol != nil && nestiaCoreIsRxjsDeclarations(symbol.Declarations))
+	if symbol != nil && symbol.Flags&shimast.SymbolFlagsAlias != 0 {
+		if aliased := shimchecker.Checker_getAliasedSymbol(prog.Checker, symbol); aliased != nil {
+			symbol = aliased
+		}
+	}
+	return symbol != nil && nestiaCoreIsAsyncReturnWrapperSymbol(prog, symbol.Name, symbol.Declarations)
 }
 
 func nestiaCoreIsAsyncReturnWrapperSymbol(
+	prog *driver.Program,
 	name string,
 	declarations []*shimast.Node,
 ) bool {
-	if name == "Promise" {
-		return true
+	if name == "Promise" && prog != nil && prog.TSProgram != nil {
+		for _, decl := range declarations {
+			if source := shimast.GetSourceFileOfNode(decl); source != nil && prog.TSProgram.IsLibFile(source) {
+				return true
+			}
+		}
 	}
-	return name == "Observable" && nestiaCoreIsRxjsDeclarations(declarations)
+	return name == "Observable" && nestiaCoreIsRxjsDeclarations(prog, declarations)
 }
 
-func nestiaCoreIsRxjsDeclarations(declarations []*shimast.Node) bool {
+func nestiaCoreIsRxjsDeclarations(prog *driver.Program, declarations []*shimast.Node) bool {
 	for _, decl := range declarations {
 		sourceFile := shimast.GetSourceFileOfNode(decl)
-		if sourceFile == nil {
-			continue
-		}
-		file := filepath.ToSlash(sourceFile.FileName())
-		if strings.Contains(file, "/node_modules/rxjs/") {
+		if sourceFile != nil && SourceFilePackageName(prog, sourceFile) == "rxjs" {
 			return true
 		}
 	}
 	return false
 }
 
-func nestiaCoreIsRxjsObservableImport(node *shimast.Node) bool {
-	source, ok := SourceFileText(shimast.GetSourceFileOfNode(node))
-	return ok && nestiaCoreHasNamedImport(source, "rxjs", "Observable", "Observable")
-}
-
-func nestiaCoreHasNamedImport(
-	source string,
-	module string,
-	imported string,
-	local string,
-) bool {
-	for _, match := range nestiaCoreImportFromPattern.FindAllStringSubmatch(source, -1) {
-		if len(match) < 3 || match[2] != module {
-			continue
-		}
-		open := strings.Index(match[1], "{")
-		close := strings.LastIndex(match[1], "}")
-		if open < 0 || close <= open {
-			continue
-		}
-		for _, part := range strings.Split(match[1][open+1:close], ",") {
-			fields := strings.Fields(strings.TrimPrefix(strings.TrimSpace(part), "type "))
-			if len(fields) == 1 && fields[0] == local && imported == local {
-				return true
-			}
-			if len(fields) == 3 &&
-				fields[0] == imported &&
-				fields[1] == "as" &&
-				fields[2] == local {
-				return true
-			}
-		}
-	}
-	return false
-}
-
-var nestiaCoreImportFromPattern = regexp.MustCompile(
-	`(?s)import\s+(?:type\s+)?(.+?)\s+from\s+["']([^"']+)["']`,
-)
-
 func nestiaCoreTypeNodeText(node *shimast.Node) string {
 	if node == nil {
 		return ""
@@ -1316,6 +1312,17 @@ func matchClosingParen(text string, pos int) (int, bool) {
 	}
 	return 0, false
 }
+
+// NestiaCoreExpressionSegments returns the identifier segments of an identifier or a property-access chain, such as `core.TypedRoute.Get` as `core`, `TypedRoute`, `Get`, and nil for any other expression.
+//
+// @evidence contracts/common.md#principled-implementation The recursion follows the left side of each property access to its root identifier and appends the property names, and any other node kind makes the whole chain not a name, so a call, an element access, or a computed name is never read as a path.
+// @evidence contracts/common.md#clear-and-simple-design One recursive function over two node kinds.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the syntax only.
+// @evidence contracts/common.md#meaningful-documentation The comment gives the example and the nil result.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Identifier segments describe source syntax rather than native file paths.
+// @evidence contracts/performance.md#efficient-algorithms The recursion visits each property access once; append amortizes slice growth, with space proportional to chain depth.
+// @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 returned slice is caller-owned and recursion state ends at return.
 func NestiaCoreExpressionSegments(node *shimast.Node) []string {
 	if node == nil {
 		return nil

package/native/transform/core_websocket.go

@@ -2,8 +2,6 @@ package transform
 
 import (
 	"fmt"
-	"path/filepath"
-	"strings"
 
 	shimast "github.com/microsoft/typescript-go/shim/ast"
 	shimchecker "github.com/microsoft/typescript-go/shim/checker"
@@ -70,6 +68,15 @@ func validateNestiaCoreWebSocketRoute(
 
 // NestiaCoreWebSocketParameterCategory names the WebSocketRoute parameter
 // decorator on a parameter, such as "Acceptor" or "Driver", or "" for none.
+//
+// @evidence contracts/common.md#principled-implementation A parameter that has exactly one decorator, a call whose callee ends in `WebSocketRoute.<Category>`, reports that category name, and any other parameter reports the empty string.
+// @evidence contracts/common.md#clear-and-simple-design An exported wrapper over the private classifier so that the SDK contributor and the core transform share one definition.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is structural, and no parameter name is special-cased.
+// @evidence contracts/common.md#meaningful-documentation The comment gives examples of the categories and the empty result.
+// @evidence contracts/portability.md#os-neutral-implementation Resolved decorator ownership delegates native package paths to SourceFilePackageName; returned category names are protocol metadata.
+// @evidence contracts/performance.md#efficient-algorithms Exactly-one-decorator checks are constant; classification also builds a file import context and resolves declaration ownership.
+// @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 Context maps are local and returned category text refers to compiler data; no cross-program storage is created.
 func NestiaCoreWebSocketParameterCategory(prog *driver.Program, param *shimast.Node) string {
 	return nestiaCoreWebSocketParameterCategory(prog, param)
 }
@@ -103,6 +110,15 @@ func nestiaCoreWebSocketParameterTypeNode(param *shimast.Node) *shimast.Node {
 // reference, each after the first written in the type alias the one before it
 // names, and the name tgrid declares the type by; or nil and "" when the
 // annotation leads to no tgrid type.
+//
+// @evidence contracts/common.md#principled-implementation The annotation is followed through parentheses, import aliases, and type aliases, with each step recorded, until a declaration of the `tgrid` package is reached, and the walk is capped at 32 steps so a cyclic alias cannot loop; the chain and the name tgrid declares are returned, so every spelling of the same type is accepted and a type of the same name from another package is rejected.
+// @evidence contracts/common.md#clear-and-simple-design One loop with a depth guard, built on private helpers for the reference name and the tgrid declaration test.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The type is identified by its resolved declaration, not by its spelling, which is the point of the function.
+// @evidence contracts/common.md#meaningful-documentation The comment states the spellings followed, what the chain contains, and the nil result.
+// @evidence contracts/portability.md#os-neutral-implementation tgrid provenance delegates nearest-manifest reads to SourceFilePackageName and the program filesystem instead of deriving package identity from directory spelling.
+// @evidence contracts/performance.md#efficient-algorithms The alias walk is capped at 32 steps; each step resolves a symbol and scans declarations, including package ancestor walks for ownership.
+// @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 chain holds at most 32 node references and is returned to the caller; no global alias graph is retained.
 func NestiaCoreWebSocketTypeReference(prog *driver.Program, node *shimast.Node) ([]*shimast.Node, string) {
 	chain := []*shimast.Node{}
 	for depth := 0; node != nil && depth < 32; depth++ {
@@ -124,7 +140,7 @@ func NestiaCoreWebSocketTypeReference(prog *driver.Program, node *shimast.Node)
 		if symbol == nil {
 			return nil, ""
 		}
-		if nestiaCoreIsTgridDeclarations(symbol.Declarations) {
+		if nestiaCoreIsTgridDeclarations(prog, symbol.Declarations) {
 			return chain, symbol.Name
 		}
 		if symbol.Flags&shimast.SymbolFlagsTypeAlias == 0 {
@@ -162,10 +178,10 @@ func nestiaCoreTypeReferenceName(node *shimast.Node) *shimast.Node {
 	return nil
 }
 
-func nestiaCoreIsTgridDeclarations(declarations []*shimast.Node) bool {
+func nestiaCoreIsTgridDeclarations(prog *driver.Program, declarations []*shimast.Node) bool {
 	for _, declaration := range declarations {
 		source := shimast.GetSourceFileOfNode(declaration)
-		if source != nil && strings.Contains(filepath.ToSlash(source.FileName()), "/tgrid/") {
+		if source != nil && SourceFilePackageName(prog, source) == "tgrid" {
 			return true
 		}
 	}