@nestia/sdk 14.0.0 → 14.0.2

package/native/sdk/sdk_transform.go

@@ -1,18 +1,23 @@
 package sdk
 
 import (
+	"encoding"
 	"encoding/json"
 	"fmt"
+	"math"
 	"os"
 	"path/filepath"
-	"regexp"
+	"reflect"
 	"sort"
+	"strconv"
 	"strings"
 
 	shimast "github.com/microsoft/typescript-go/shim/ast"
 	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+	shimprinter "github.com/microsoft/typescript-go/shim/printer"
 	shimscanner "github.com/microsoft/typescript-go/shim/scanner"
 	"github.com/samchon/nestia/packages/core/native/transform"
+	"github.com/samchon/nestia/packages/core/native/transform/schemaprojection"
 	"github.com/samchon/ttsc/packages/ttsc/driver"
 	nativecontext "github.com/samchon/typia/packages/typia/native/core/context"
 	nativefactories "github.com/samchon/typia/packages/typia/native/core/factories"
@@ -40,9 +45,10 @@ type nestiaSDKContext struct {
 }
 
 type nestiaSDKSchemaCacheKey struct {
-	Type   *shimchecker.Type
-	Text   string
-	Escape bool
+	Type       *shimchecker.Type
+	Text       string
+	Escape     bool
+	Properties bool
 }
 
 func newNestiaSDKContext(prog *driver.Program) *nestiaSDKContext {
@@ -148,7 +154,16 @@ func nestiaSDKMetadataText(context *nestiaSDKContext, file *shimast.SourceFile,
 		for index, param := range methodDecl.Parameters.Nodes {
 			typ := prog.Checker.GetTypeAtLocation(param)
 			name := nestiaSDKParameterName(param)
-			response := nestiaSDKResponse(context, imports, typ, nestiaSDKParameterTypeNode(param))
+			response := nestiaSDKResponse(context, imports, typ, nestiaSDKParameterTypeNode(param), true)
+			if ref, refs, err := nestiaSDKWebSocketParameterType(context, param); err != nil {
+				return "", err
+			} else if ref != nil {
+				response["type"] = ref
+				response["imports"] = refs
+			}
+			if err := nestiaSDKWebSocketHeaderError(context.prog, param, typ); err != nil {
+				return "", err
+			}
 			parameters = append(parameters, map[string]any{
 				"name":        name,
 				"index":       index,
@@ -166,7 +181,7 @@ func nestiaSDKMetadataText(context *nestiaSDKContext, file *shimast.SourceFile,
 	exceptions := nestiaSDKExceptionResponses(context, imports, method)
 	metadata := map[string]any{
 		"parameters":  parameters,
-		"success":     nestiaSDKResponse(context, imports, returnType, returnTypeNode),
+		"success":     nestiaSDKResponse(context, imports, returnType, returnTypeNode, false),
 		"exceptions":  exceptions,
 		"description": nestiaSDKNullableString(doc.Description),
 		"jsDocTags":   doc.Tags,
@@ -174,16 +189,98 @@ func nestiaSDKMetadataText(context *nestiaSDKContext, file *shimast.SourceFile,
 	return nestiaSDKMetadataLiteralText(metadata)
 }
 
-const nestiaSDKLiteralNull = "__NESTIA_LITERAL_NULL__"
+// An explicit JSON null must have a distinct Go representation from authored
+// strings, including strings that happen to resemble an internal marker.
+var nestiaSDKLiteralNull = nativefactories.LiteralFactory_Null{}
 
 func nestiaSDKMetadataLiteralText(metadata map[string]any) (string, error) {
-	data, err := json.Marshal(metadata)
+	data, err := json.Marshal(nestiaSDKFiniteLiteral(metadata))
 	if err != nil {
 		return "", err
 	}
-	text := string(data)
-	text = strings.ReplaceAll(text, `"`+nestiaSDKLiteralNull+`"`, "null")
-	return text, nil
+	return string(data), nil
+}
+
+// nestiaSDKFiniteLiteral copies a metadata value for encoding/json, writing
+// every non-finite number as null, the way JavaScript's `JSON.stringify` does.
+//
+// typia hands over NaN and positive or negative Infinity wherever a type or a comment spells one: a
+// numeric literal type such as `1e999`, a type tag argument such as
+// `tags.Minimum<1e999>`, and a JSDoc `@x-` extension whose text parses as
+// a float, which `NaN`, `Infinity`, and `inf` all do. encoding/json
+// refuses those values, so one of them anywhere in the types a route reaches
+// used to abort the whole metadata pass. The metadata is marshaled only here,
+// so walking it here gives every value, baked schema and metadata literal
+// alike, the same rule.
+//
+// The walk rebuilds maps, slices, and typia's ordered objects, whose
+// MarshalJSON would otherwise marshal a non-finite member itself. A null is
+// written as typia's explicit `LiteralFactory_Null` marker rather than a Go
+// nil, because an ordered object drops a nil member instead of printing it,
+// while `JSON.stringify({ a: NaN })` keeps the key. Any other value that
+// marshals itself is left as it is.
+func nestiaSDKFiniteLiteral(input any) any {
+	switch value := input.(type) {
+	case nil:
+		return nil
+	case nativefactories.LiteralFactory_OrderedObject:
+		return nestiaSDKFiniteOrderedLiteral(value)
+	case *nativefactories.LiteralFactory_OrderedObject:
+		if value == nil {
+			return value
+		}
+		return nestiaSDKFiniteOrderedLiteral(*value)
+	case json.Marshaler, encoding.TextMarshaler:
+		return value
+	}
+	reflected := reflect.ValueOf(input)
+	switch reflected.Kind() {
+	case reflect.Float32, reflect.Float64:
+		// by kind, because the checker's numbers are typescript-go's named
+		// `jsnum.Number`, not a plain float64
+		if number := reflected.Float(); math.IsNaN(number) || math.IsInf(number, 0) {
+			return nativefactories.LiteralFactory_Null{}
+		}
+		return input
+	case reflect.Map:
+		if reflected.IsNil() || reflected.Type().Key().Kind() != reflect.String {
+			return input
+		}
+		output := make(map[string]any, reflected.Len())
+		iterator := reflected.MapRange()
+		for iterator.Next() {
+			output[iterator.Key().String()] = nestiaSDKFiniteLiteral(iterator.Value().Interface())
+		}
+		return output
+	case reflect.Slice, reflect.Array:
+		if (reflected.Kind() == reflect.Slice && reflected.IsNil()) || reflected.Type().Elem().Kind() == reflect.Uint8 {
+			return input
+		}
+		output := make([]any, reflected.Len())
+		for i := range output {
+			output[i] = nestiaSDKFiniteLiteral(reflected.Index(i).Interface())
+		}
+		return output
+	case reflect.Pointer, reflect.Interface:
+		if reflected.IsNil() {
+			return input
+		}
+		return nestiaSDKFiniteLiteral(reflected.Elem().Interface())
+	}
+	return input
+}
+
+func nestiaSDKFiniteOrderedLiteral(
+	input nativefactories.LiteralFactory_OrderedObject,
+) nativefactories.LiteralFactory_OrderedObject {
+	output := nativefactories.LiteralFactory_OrderedObject{
+		Keys:   input.Keys,
+		Values: make(map[string]any, len(input.Values)),
+	}
+	for key, value := range input.Values {
+		output.Values[key] = nestiaSDKFiniteLiteral(value)
+	}
+	return output
 }
 
 type nestiaSDKJSDoc struct {
@@ -205,34 +302,83 @@ func nestiaSDKMethodJSDoc(file *shimast.SourceFile, method *shimast.Node) nestia
 	if comment == "" {
 		return doc
 	}
+	// A tag runs until the next one, and each line loses the comment's margin
+	// as TypeScript takes it off: the `*`, then the indentation up to the
+	// column the text began at. That is the description's first line, the
+	// text after a tag's name, a `@param` description past the parameter's
+	// name, a `@returns` one past its type, or, when the tag's text starts on
+	// the next line, the tag itself, so an `@example` keeps its code's
+	// indentation while a wrapped `@param` description does not.
 	description := []string{}
-	inTags := false
+	descriptionMargin := -1
+	var tag *nestiaSDKPendingTag
+	flush := func() {
+		if tag == nil {
+			return
+		}
+		body := strings.TrimLeft(strings.Join(tag.lines, "\n"), "\n")
+		body = strings.TrimRight(body, " \t\n")
+		if tag.name == "param" {
+			param, desc := nestiaSDKParseParamTag(body)
+			doc.Tags = append(doc.Tags, nestiaSDKJSDocParamTag(param, desc))
+			if param != "" {
+				doc.Params[param] = desc
+			}
+		} else {
+			if nestiaSDKIsReturnTag(tag.name) {
+				// TypeScript's text leaves out a type the tag declares
+				body = strings.TrimLeft(body[nestiaSDKReturnTypeEnd(body):], "\n")
+			}
+			doc.Tags = append(doc.Tags, nestiaSDKJSDocTag(tag.name, body))
+		}
+		tag = nil
+	}
 	for _, line := range strings.Split(comment, "\n") {
-		text := strings.TrimSpace(line)
-		text = strings.TrimPrefix(text, "*")
-		text = strings.TrimSpace(text)
-		if text == "" {
-			if inTags == false && len(description) != 0 {
-				description = append(description, "")
+		rest := strings.TrimLeft(line, " \t")
+		rest = strings.TrimPrefix(rest, "*")
+		rest = strings.TrimRight(rest, " \t\r")
+		trimmed := strings.TrimSpace(rest)
+		if strings.HasPrefix(trimmed, "@") {
+			flush()
+			name, body := nestiaSDKParseJSDocTag(trimmed)
+			margin := nestiaSDKJSDocIndent(rest)
+			// where the text begins in the body: a `@param` description after
+			// the parameter's name, a `@returns` one after its type
+			text := 0
+			if name == "param" {
+				_, text = nestiaSDKParamTagName(body)
+			} else if nestiaSDKIsReturnTag(name) {
+				text = nestiaSDKReturnTypeEnd(body)
+			}
+			if text < len(body) {
+				after := trimmed[1+len(name):]
+				margin += 1 + len(name) + len(after) - len(strings.TrimLeft(after, " \t")) + text
 			}
+			tag = &nestiaSDKPendingTag{name: name, lines: []string{body}, margin: margin}
 			continue
 		}
-		if strings.HasPrefix(text, "@") {
-			inTags = true
-			name, body := nestiaSDKParseJSDocTag(text)
-			doc.Tags = append(doc.Tags, nestiaSDKJSDocTag(name, body))
-			if name == "param" {
-				param, desc := nestiaSDKParseParamTag(body)
-				if param != "" {
-					doc.Params[param] = desc
-				}
+		if tag != nil {
+			tag.lines = append(tag.lines, nestiaSDKJSDocOutdent(rest, tag.margin))
+			continue
+		}
+		if trimmed == "" {
+			if len(description) != 0 {
+				description = append(description, "")
 			}
 			continue
 		}
-		if inTags == false {
-			description = append(description, text)
+		if descriptionMargin == -1 {
+			// text on the opening `/**` line has no `*` to measure from, so the
+			// lines after it keep the usual `* ` margin
+			if strings.HasPrefix(strings.TrimLeft(line, " \t"), "*") {
+				descriptionMargin = nestiaSDKJSDocIndent(rest)
+			} else {
+				descriptionMargin = 1
+			}
 		}
+		description = append(description, nestiaSDKJSDocOutdent(rest, descriptionMargin))
 	}
+	flush()
 	doc.Description = strings.TrimSpace(strings.Join(description, "\n"))
 	return doc
 }
@@ -288,14 +434,108 @@ func nestiaSDKParseJSDocTag(text string) (string, string) {
 	return name, body
 }
 
+// nestiaSDKPendingTag is a JSDoc tag whose text may continue on the next
+// lines.
+type nestiaSDKPendingTag struct {
+	name   string
+	lines  []string
+	margin int
+}
+
+// nestiaSDKJSDocIndent counts the spaces and tabs a JSDoc line starts with.
+func nestiaSDKJSDocIndent(line string) int {
+	return len(line) - len(strings.TrimLeft(line, " \t"))
+}
+
+// nestiaSDKJSDocOutdent takes up to margin spaces and tabs off a JSDoc line.
+func nestiaSDKJSDocOutdent(line string, margin int) string {
+	indent := nestiaSDKJSDocIndent(line)
+	if indent > margin {
+		indent = margin
+	}
+	return line[indent:]
+}
+
+// nestiaSDKParseParamTag splits a `@param` body into the parameter's name and
+// its description, as TypeScript does. A description that starts on the next
+// line keeps the indentation its margin leaves it.
 func nestiaSDKParseParamTag(body string) (string, string) {
-	parts := strings.Fields(body)
-	if len(parts) == 0 {
-		return "", ""
+	param, text := nestiaSDKParamTagName(body)
+	return param, strings.TrimLeft(body[text:], "\n")
+}
+
+// nestiaSDKParamTagName reads the parameter a `@param` body names, as
+// TypeScript does: a leading `{Type}` is not the name, and an optional
+// parameter's brackets and default, `[name=value]`, are not part of it. It
+// also returns where the description begins, past the spaces after the name.
+func nestiaSDKParamTagName(body string) (string, int) {
+	offset := nestiaSDKSkipBlank(body, 0, true)
+	if end := nestiaSDKClosing(body, offset, '{', '}'); end != -1 {
+		offset = nestiaSDKSkipBlank(body, end+1, true)
 	}
-	param := parts[0]
-	desc := strings.TrimSpace(strings.TrimPrefix(body, param))
-	return param, desc
+	name := ""
+	if end := nestiaSDKClosing(body, offset, '[', ']'); end != -1 {
+		// the bracket that closes the first, past any in a default value
+		name = body[offset+1 : end]
+		if equal := strings.Index(name, "="); equal != -1 {
+			name = name[:equal]
+		}
+		name = strings.TrimSpace(name)
+		offset = end + 1
+	} else {
+		start := offset
+		for offset < len(body) && strings.IndexByte(" \t\n", body[offset]) == -1 {
+			offset++
+		}
+		name = body[start:offset]
+	}
+	return name, nestiaSDKSkipBlank(body, offset, false)
+}
+
+// nestiaSDKIsReturnTag tells a `@returns` tag, which TypeScript also reads as
+// `@return`.
+func nestiaSDKIsReturnTag(name string) bool {
+	return name == "returns" || name == "return"
+}
+
+// nestiaSDKReturnTypeEnd returns where a `@returns` body's text begins past a
+// leading `{Type}`, which TypeScript reads as the type rather than the text,
+// and the spaces after it; 0 without a type.
+func nestiaSDKReturnTypeEnd(body string) int {
+	if end := nestiaSDKClosing(body, nestiaSDKSkipBlank(body, 0, true), '{', '}'); end != -1 {
+		return nestiaSDKSkipBlank(body, end+1, false)
+	}
+	return 0
+}
+
+// nestiaSDKClosing finds the bracket closing the one text opens at start, or
+// -1 when text opens none there or never closes it.
+func nestiaSDKClosing(text string, start int, open byte, close byte) int {
+	if start >= len(text) || text[start] != open {
+		return -1
+	}
+	depth := 0
+	for i := start; i < len(text); i++ {
+		if text[i] == open {
+			depth++
+		} else if text[i] == close {
+			depth--
+			if depth == 0 {
+				return i
+			}
+		}
+	}
+	return -1
+}
+
+// nestiaSDKSkipBlank moves offset past spaces and tabs, and line breaks too
+// when newline is set.
+func nestiaSDKSkipBlank(text string, offset int, newline bool) int {
+	for offset < len(text) &&
+		(text[offset] == ' ' || text[offset] == '\t' || (newline && text[offset] == '\n')) {
+		offset++
+	}
+	return offset
 }
 
 func nestiaSDKJSDocTag(name string, text string) map[string]any {
@@ -315,6 +555,33 @@ func nestiaSDKJSDocTag(name string, text string) map[string]any {
 	}
 }
 
+// nestiaSDKJSDocParamTag writes a `@param` tag the way TypeScript's
+// `JSDocTagInfo` does, which the SDK generators read: the parameter's name
+// as its own `parameterName` part, then a space and the description. Written
+// as one text part, the name could not be matched, so a WebSocket route lost
+// every `@param` line and the generators' tag fallbacks never applied.
+func nestiaSDKJSDocParamTag(param string, desc string) map[string]any {
+	if param == "" {
+		return nestiaSDKJSDocTag("param", "")
+	}
+	text := []any{
+		map[string]any{
+			"text": param,
+			"kind": "parameterName",
+		},
+	}
+	if desc != "" {
+		text = append(text,
+			map[string]any{"text": " ", "kind": "space"},
+			map[string]any{"text": desc, "kind": "text"},
+		)
+	}
+	return map[string]any{
+		"name": "param",
+		"text": text,
+	}
+}
+
 func nestiaSDKNullableString(value string) any {
 	value = strings.TrimSpace(value)
 	if value == "" {
@@ -335,7 +602,7 @@ func nestiaSDKExceptionResponses(
 		if exception == nil {
 			continue
 		}
-		responses = append(responses, nestiaSDKResponse(context, imports, exception.Type, exception.Node))
+		responses = append(responses, nestiaSDKResponse(context, imports, exception.Type, exception.Node, false))
 	}
 	return responses
 }
@@ -354,7 +621,9 @@ func nestiaSDKTypedExceptionInfo(prog *driver.Program, decorator *shimast.Node)
 		return nil
 	}
 	call := expression.AsCallExpression()
-	segments := transform.NestiaCoreExpressionSegments(call.Expression)
+	// by the export the import binds, as the runtime registers an aliased
+	// `TypedException` too; a lexical name lost it, misaligning the exceptions
+	segments := transform.NestiaCoreCanonicalDecoratorSegments(decorator)
 	if len(segments) == 0 || segments[len(segments)-1] != "TypedException" {
 		return nil
 	}
@@ -449,43 +718,67 @@ func nestiaSDKNormalizeImportPath(fileName string, module string) string {
 	return filepath.ToSlash(filepath.Join("node_modules", module))
 }
 
-func nestiaSDKReflectImports(name string, imports []nestiaSDKImportInfo) []any {
-	prefixes := nestiaSDKTypePrefixes(name)
+// nestiaSDKReflectImports collects imports from actual type references and
+// typeof queries. Literal values, property names and template text do not bind
+// imports, and named library types are classified by declaration provenance.
+func nestiaSDKReflectImports(prog *driver.Program, node *shimast.Node, imports []nestiaSDKImportInfo) []any {
 	output := []any{}
-	seen := map[string]bool{}
-	for _, imp := range imports {
-		if nestiaSDKImportMatches(prefixes, imp) == false {
-			continue
-		}
-		item := nestiaSDKImportLiteral(imp, prefixes)
-		key := fmt.Sprintf("%v", item)
-		if seen[key] {
-			continue
+	add := func(entity *shimast.Node) {
+		if entity == nil {
+			return
+		}
+		root := entity
+		for root != nil && root.Kind == shimast.KindQualifiedName {
+			root = root.AsQualifiedName().Left
+		}
+		if root == nil || root.Kind != shimast.KindIdentifier {
+			return
+		}
+		prefix := root.Text()
+		if nestiaSDKIsTypeKeyword(prefix) {
+			return
+		}
+		if prog != nil && prog.Checker != nil {
+			symbol := prog.Checker.GetSymbolAtLocation(root)
+			if symbol != nil && symbol.Flags&shimast.SymbolFlagsAlias != 0 {
+				prefixes := map[string]bool{prefix: true}
+				for _, imp := range imports {
+					if nestiaSDKImportMatches(prefixes, imp) {
+						output = append(output, nestiaSDKImportLiteral(imp, prefixes))
+					}
+				}
+				return
+			}
 		}
-		seen[key] = true
-		output = append(output, item)
+		output = append(output, nestiaSDKReflectTypeReferenceSymbolImport(prog, entity, nestiaSDKEntityNameText(entity))...)
 	}
-	return output
-}
-
-func nestiaSDKTypePrefixes(name string) map[string]bool {
-	output := map[string]bool{}
-	re := regexp.MustCompile(`[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*`)
-	for _, match := range re.FindAllString(name, -1) {
-		prefix := strings.Split(match, ".")[0]
-		if nestiaSDKIsGlobalTypePrefix(prefix) == false {
-			output[prefix] = true
+	var walk func(*shimast.Node)
+	walk = func(current *shimast.Node) {
+		if current == nil {
+			return
 		}
+		switch current.Kind {
+		case shimast.KindTypeReference:
+			add(current.AsTypeReferenceNode().TypeName)
+		case shimast.KindTypeQuery:
+			add(current.AsTypeQueryNode().ExprName)
+		}
+		current.ForEachChild(func(child *shimast.Node) bool { walk(child); return false })
 	}
-	return output
+	if node != nil && (node.Kind == shimast.KindIdentifier || node.Kind == shimast.KindQualifiedName) {
+		add(node)
+	} else {
+		walk(node)
+	}
+	return nestiaSDKMergeImportLiterals(output)
 }
 
-func nestiaSDKIsGlobalTypePrefix(prefix string) bool {
+// nestiaSDKIsTypeKeyword reports type spellings that cannot name an imported
+// declaration. Library names such as Date and Array can be shadowed in a module.
+func nestiaSDKIsTypeKeyword(prefix string) bool {
 	switch prefix {
 	case "any", "unknown", "never", "void", "null", "undefined",
-		"string", "number", "boolean", "bigint", "symbol", "object",
-		"Array", "ReadonlyArray", "Promise", "Record", "Partial", "Pick", "Omit",
-		"Date", "File", "Blob", "Uint8Array", "ArrayBuffer", "Error":
+		"string", "number", "boolean", "bigint", "symbol", "object":
 		return true
 	default:
 		return false
@@ -538,11 +831,16 @@ func nestiaSDKImportLiteral(imp nestiaSDKImportInfo, prefixes map[string]bool) m
 	return output
 }
 
+// nestiaSDKResponse reflects one route input or output. `parameter` marks a
+// method parameter: the Swagger generator reads query and headers parameters
+// from the resolved schema and may decompose their object into one OpenAPI
+// parameter per property, so only that schema bakes the property schemas.
 func nestiaSDKResponse(
 	context *nestiaSDKContext,
 	imports []nestiaSDKImportInfo,
 	typ *shimchecker.Type,
 	typeNode *shimast.Node,
+	parameter bool,
 ) map[string]any {
 	prog := context.prog
 	refType, refImports := nestiaSDKReflectType(prog, imports, typ, typeNode)
@@ -552,17 +850,18 @@ func nestiaSDKResponse(
 	return map[string]any{
 		"type":      refType,
 		"imports":   refImports,
-		"primitive": nestiaSDKSchemaPipe(context, typ, typeNode, true),
-		"resolved":  nestiaSDKSchemaPipe(context, typ, typeNode, false),
+		"primitive": nestiaSDKSchemaPipe(context, typ, typeNode, true, false),
+		"resolved":  nestiaSDKSchemaPipe(context, typ, typeNode, false, parameter),
 	}
 }
 
-func nestiaSDKSchemaPipe(context *nestiaSDKContext, typ *shimchecker.Type, typeNode *shimast.Node, escape bool) any {
+func nestiaSDKSchemaPipe(context *nestiaSDKContext, typ *shimchecker.Type, typeNode *shimast.Node, escape bool, properties bool) any {
 	prog := context.prog
 	key := nestiaSDKSchemaCacheKey{
-		Type:   typ,
-		Text:   nestiaSDKTypeNodeText(typeNode),
-		Escape: escape,
+		Type:       typ,
+		Text:       nestiaSDKTypeNodeText(typeNode),
+		Escape:     escape,
+		Properties: properties,
 	}
 	if cached, ok := context.schemaCache[key]; ok {
 		context.schemaHits++
@@ -614,18 +913,23 @@ func nestiaSDKSchemaPipe(context *nestiaSDKContext, typ *shimchecker.Type, typeN
 	// JSON-schema representation (e.g. a `void` route return or a parameter
 	// whose only members are functions). The legacy reader on the JS side
 	// already treats a missing `jsonSchema` as "skip", so swallow the panic
-	// and omit the field — the sdk generator falls back to its own derived
+	// and omit the field; the SDK generator falls back to its own derived
 	// schema path. This must never mask a real bug, so re-raise anything we
 	// don't recognize as a transformer error from the typia runtime.
-	if baked := nestiaSDKTryBakeJsonSchema(prog, typeNode, result.Data); baked != nil {
+	if baked := nestiaSDKTryBakeJsonSchema(prog, typ, context.collection, result.Data, properties, escape); baked != nil {
 		metadataLiteral["jsonSchema"] = baked
 	}
+	data := map[string]any{
+		"components": nestiaSDKMetadataComponentsLiteral(nestiaSDKVisitedMetadataComponents(context.collection, result.Data)),
+		"metadata":   metadataLiteral,
+	}
+	if properties {
+		// a route parameter's HTTP rule verdicts, from its own analysis
+		data["http"] = nestiaSDKHttpRules(prog.Checker, typ)
+	}
 	value := map[string]any{
 		"success": true,
-		"data": map[string]any{
-			"components": nestiaSDKMetadataComponentsLiteral(nestiaSDKVisitedMetadataComponents(context.collection, result.Data)),
-			"metadata":   metadataLiteral,
-		},
+		"data":    data,
 	}
 	context.schemaCache[key] = value
 	return value
@@ -634,12 +938,19 @@ func nestiaSDKSchemaPipe(context *nestiaSDKContext, typ *shimchecker.Type, typeN
 // nestiaSDKTryBakeJsonSchema runs `JsonSchemasProgrammer.WriteSchemas` for a
 // single metadata and returns the OpenAPI 3.1 schema literal. Returns nil
 // when typia signals the metadata has no JSON-schema representation (e.g.
-// `void` returns, function-only types) — the JS-side reader handles missing
+// `void` returns, function-only types); the JS-side reader handles missing
 // `jsonSchema` fields. Any other panic is re-raised so real bugs surface.
+//
+// With `properties`, the literal also carries the schema of each property of
+// the metadata's first object type, for the Swagger generator to decompose into
+// individual parameters (see `nestiaSDKPropertySchemas`).
 func nestiaSDKTryBakeJsonSchema(
 	prog *driver.Program,
-	typeNode *shimast.Node,
+	typ *shimchecker.Type,
+	registry *schemametadata.MetadataCollection,
 	metadata *schemametadata.MetadataSchema,
+	properties bool,
+	escape bool,
 ) (baked map[string]any) {
 	defer func() {
 		if r := recover(); r != nil {
@@ -650,6 +961,7 @@ func nestiaSDKTryBakeJsonSchema(
 			panic(r)
 		}
 	}()
+	metadata = schemaprojection.Project(metadata)
 	collection := nativejson.JsonSchemasProgrammer.WriteSchemas(struct {
 		Version   string
 		Metadatas []*schemametadata.MetadataSchema
@@ -660,6 +972,12 @@ func nestiaSDKTryBakeJsonSchema(
 	if len(collection.Schemas) == 0 {
 		return nil
 	}
+	// Baked before the components are flattened: the property schemas share
+	// the parent's components, so any component they reach must be included.
+	var propertySchemas map[string]any
+	if properties && collection.Components != nil {
+		propertySchemas = nestiaSDKPropertySchemas(metadata, collection.Components)
+	}
 	// `iterate.OpenApi_IComponents` has no JSON tags on its Schemas field,
 	// so default Go marshaling would emit `"Schemas"` (capital). The JS
 	// side reads `components.schemas`, so flatten to a plain map here.
@@ -667,266 +985,412 @@ func nestiaSDKTryBakeJsonSchema(
 	if collection.Components != nil && collection.Components.Schemas != nil {
 		schemasLiteral := map[string]any{}
 		for key, val := range collection.Components.Schemas {
-			schemasLiteral[key] = map[string]any(val)
+			schemasLiteral[key] = nestiaSDKJsonSchemaLiteral(val)
 		}
 		componentsLiteral["schemas"] = schemasLiteral
 	}
 	baked = map[string]any{
 		"version":    collection.Version,
 		"components": componentsLiteral,
-		"schema":     map[string]any(collection.Schemas[0]),
+		"schema":     nestiaSDKJsonSchemaLiteral(collection.Schemas[0]),
 	}
-	nestiaSDKMarkReadonlyArrayJsonSchema(prog, typeNode, baked)
+	if propertySchemas != nil {
+		baked["properties"] = propertySchemas
+	}
+	nestiaSDKMarkReadonlyArrayJsonSchema(prog, typ, baked, registry, escape)
 	return baked
 }
 
-func nestiaSDKMarkReadonlyArrayJsonSchema(prog *driver.Program, typeNode *shimast.Node, baked map[string]any) {
-	components, _ := baked["components"].(map[string]any)
-	schemas, _ := components["schemas"].(map[string]any)
-	schema := nestiaSDKSchemaMap(baked["schema"])
-	nestiaSDKMarkReadonlyArraySchemaNode(
-		prog,
-		typeNode,
-		schema,
-		schemas,
-		map[*shimast.Node]bool{},
-	)
-}
-
-func nestiaSDKMarkReadonlyArraySchemaNode(
-	prog *driver.Program,
-	typeNode *shimast.Node,
-	schema map[string]any,
-	components map[string]any,
-	visiting map[*shimast.Node]bool,
-) {
-	if typeNode == nil || schema == nil {
-		return
+// nestiaSDKPropertySchemas bakes the schema of each property of the metadata's
+// first object type, keyed by property name, for a decomposed query or headers
+// parameter. It is the property schema typia's object writer produces, minus
+// the fields the OpenAPI parameter carries in its own members: typia merges the
+// property's title, description, and deprecation into that schema, plus
+// readOnly, which has no meaning for a request parameter. What remains is the
+// value schema, written by typia's `Json_schema_station` exactly as
+// `WriteSchemas` writes one metadata but against the parent's components, so a
+// named type the value reaches resolves to the component the parent already
+// carries, and the property's `x-` JSDoc extensions.
+//
+// Only properties typia's object schema describes are baked: a property must
+// have a literal key and no `@hidden`, `@ignore`, or `@internal` tag (the
+// filter `json_schema_object` applies), and a value with no JSON form
+// (function-only or `never`) yields no schema. Skipping them here also keeps
+// their types out of the shared components.
+func nestiaSDKPropertySchemas(
+	metadata *schemametadata.MetadataSchema,
+	components *nativeiterate.OpenApi_IComponents,
+) map[string]any {
+	if len(metadata.Objects) == 0 || metadata.Objects[0].Type == nil {
+		return nil
 	}
-	if visiting[typeNode] {
-		return
+	output := map[string]any{}
+	for _, property := range metadata.Objects[0].Type.Properties {
+		if property == nil || property.Key == nil || property.Value == nil {
+			continue
+		}
+		key := property.Key.GetSoleLiteral()
+		if key == nil || nestiaSDKHasJSDocTag(property.JsDocTags, "hidden", "ignore", "internal") {
+			continue
+		}
+		schema := nativeiterate.Json_schema_station(nativeiterate.Json_schema_station_props{
+			BlockNever: true,
+			Components: components,
+			Attribute:  nativeiterate.JsonSchema{},
+			Metadata:   property.Value,
+		})
+		if schema == nil {
+			continue
+		}
+		nestiaSDKJsDocExtensions(schema, property.JsDocTags)
+		output[*key] = nestiaSDKJsonSchemaLiteral(schema)
 	}
-	visiting[typeNode] = true
-	defer delete(visiting, typeNode)
+	return output
+}
 
-	switch typeNode.Kind {
-	case shimast.KindArrayType:
-		child := nestiaSDKSchemaMap(schema["items"])
-		nestiaSDKMarkReadonlyArraySchemaNode(
-			prog,
-			typeNode.AsArrayTypeNode().ElementType,
-			child,
-			components,
-			visiting,
-		)
-	case shimast.KindTupleType:
-		tuple := typeNode.AsTupleTypeNode()
-		items := nestiaSDKSchemaList(schema["prefixItems"])
-		if tuple.Elements != nil {
-			for i, elem := range tuple.Elements.Nodes {
-				if i >= len(items) {
-					break
-				}
-				child := nestiaSDKSchemaMap(items[i])
-				nestiaSDKMarkReadonlyArraySchemaNode(prog, elem, child, components, visiting)
+// nestiaSDKJsDocExtensions writes a property's `x-` JSDoc tags into its schema
+// the way typia's object writer does (`json_schema_jsDocTags`, unexported):
+// the first text part, trimmed, read as a boolean, a number, null, or else a
+// string.
+func nestiaSDKJsDocExtensions(schema nativeiterate.JsonSchema, tags []schemametadata.IJsDocTagInfo) {
+	for _, tag := range tags {
+		if strings.HasPrefix(tag.Name, "x-") == false {
+			continue
+		}
+		for _, text := range tag.Text {
+			if text.Kind != "text" {
+				continue
+			}
+			value := strings.ReplaceAll(strings.TrimSpace(text.Text), "\r\n", "\n")
+			if value == "true" || value == "false" {
+				schema[tag.Name] = value == "true"
+			} else if number, err := strconv.ParseFloat(value, 64); err == nil {
+				schema[tag.Name] = number
+			} else if value == "null" {
+				schema[tag.Name] = nil
+			} else {
+				schema[tag.Name] = value
 			}
+			break
 		}
-	case shimast.KindParenthesizedType:
-		nestiaSDKMarkReadonlyArraySchemaNode(
-			prog,
-			typeNode.AsParenthesizedTypeNode().Type,
-			schema,
-			components,
-			visiting,
-		)
-	case shimast.KindTypeOperator:
-		operator := typeNode.AsTypeOperatorNode()
-		if nestiaSDKTypeOperatorPrefix(typeNode, operator.Type) == "readonly" &&
-			nestiaSDKReadonlyArrayOperand(operator.Type) {
-			schema["x-readonly-array"] = true
-		}
-		nestiaSDKMarkReadonlyArraySchemaNode(
-			prog,
-			operator.Type,
-			schema,
-			components,
-			visiting,
-		)
-	case shimast.KindTypeReference:
-		nestiaSDKMarkReadonlyArrayTypeReference(
-			prog,
-			typeNode,
-			schema,
-			components,
-			visiting,
-		)
-	case shimast.KindTypeLiteral:
-		nestiaSDKMarkReadonlyArrayTypeElements(
-			prog,
-			typeNode.AsTypeLiteralNode().Members,
-			schema,
-			components,
-			visiting,
-		)
 	}
 }
 
-func nestiaSDKMarkReadonlyArrayTypeReference(
-	prog *driver.Program,
-	typeNode *shimast.Node,
-	schema map[string]any,
-	components map[string]any,
-	visiting map[*shimast.Node]bool,
-) {
-	ref := typeNode.AsTypeReferenceNode()
-	name := nestiaSDKEntityNameText(ref.TypeName)
-	if name == "ReadonlyArray" {
-		schema["x-readonly-array"] = true
-	}
-	if (name == "Array" || name == "ReadonlyArray") && ref.TypeArguments != nil &&
-		len(ref.TypeArguments.Nodes) != 0 {
-		child := nestiaSDKSchemaMap(schema["items"])
-		nestiaSDKMarkReadonlyArraySchemaNode(
-			prog,
-			ref.TypeArguments.Nodes[0],
-			child,
-			components,
-			visiting,
-		)
-	}
-	for _, decl := range nestiaSDKTypeReferenceDeclarations(prog, ref.TypeName) {
-		switch decl.Kind {
-		case shimast.KindInterfaceDeclaration:
-			target := nestiaSDKReferencedSchema(schema, components, name)
-			nestiaSDKMarkReadonlyArrayTypeElements(
-				prog,
-				decl.AsInterfaceDeclaration().Members,
-				target,
-				components,
-				visiting,
-			)
-		case shimast.KindTypeAliasDeclaration:
-			target := nestiaSDKReferencedSchema(schema, components, name)
-			nestiaSDKMarkReadonlyArraySchemaNode(
-				prog,
-				decl.AsTypeAliasDeclaration().Type,
-				target,
-				components,
-				visiting,
-			)
-		}
-	}
-}
-
-func nestiaSDKMarkReadonlyArrayTypeElements(
-	prog *driver.Program,
-	members *shimast.TypeElementList,
-	schema map[string]any,
-	components map[string]any,
-	visiting map[*shimast.Node]bool,
-) {
-	if members == nil || schema == nil {
-		return
-	}
-	properties := nestiaSDKSchemaMap(schema["properties"])
-	if properties == nil {
-		return
-	}
-	for _, member := range members.Nodes {
-		if member == nil || member.Kind != shimast.KindPropertySignature {
-			continue
+func nestiaSDKHasJSDocTag(tags []schemametadata.IJsDocTagInfo, names ...string) bool {
+	for _, tag := range tags {
+		for _, name := range names {
+			if tag.Name == name {
+				return true
+			}
 		}
-		property := member.AsPropertySignatureDeclaration()
-		name := nestiaSDKSchemaPropertyName(property.Name())
-		child := nestiaSDKSchemaMap(properties[name])
-		nestiaSDKMarkReadonlyArraySchemaNode(
-			prog,
-			property.Type,
-			child,
-			components,
-			visiting,
-		)
 	}
+	return false
 }
 
-func nestiaSDKTypeReferenceDeclarations(prog *driver.Program, node *shimast.Node) []*shimast.Node {
-	if prog == nil || prog.Checker == nil || node == nil {
-		return nil
-	}
-	symbol := prog.Checker.GetSymbolAtLocation(node)
-	if symbol == nil {
-		typ := prog.Checker.GetTypeFromTypeNode(node)
-		if typ != nil {
-			symbol = typ.Symbol()
+// nestiaSDKJsonSchemaLiteral prepares one typia JSON schema for the
+// encoding/json serialization of the SDK metadata, dropping the members typia
+// leaves absent.
+//
+// typia's schema writer stores a Go nil for an absent member: a constant with
+// no `@title` gets a nil *string title and description, and `any` gets a nil
+// type. typia's own literal printer skips nil object members, but encoding/json
+// prints them as null, which JSON Schema rejects for those keywords. A nil
+// cannot be dropped everywhere, though: in an instance-valued keyword (`const`,
+// `default`, `enum`, `example`, `examples`) or a vendor extension it can be a
+// real null. typia marks the nulls a type declares, such as
+// `tags.Example<null>`, with `LiteralFactory_Null`, which is no nil and
+// marshals as null, but a JSDoc `@x-foo null` still reaches the schema as a
+// bare nil, from typia's object writer and from nestiaSDKJsDocExtensions alike.
+//
+// So the walk follows JSON Schema structure: it drops a nil member of a schema
+// object, recurses through the applicator keywords into subschemas, and leaves
+// every other value, instance data included, as it is.
+func nestiaSDKJsonSchemaLiteral(input any) any {
+	reflected := reflect.ValueOf(input)
+	if reflected.Kind() != reflect.Map || reflected.Type().Key().Kind() != reflect.String {
+		return input // a boolean schema, or a value that is no schema object
+	}
+	output := make(map[string]any, reflected.Len())
+	iterator := reflected.MapRange()
+	for iterator.Next() {
+		key := iterator.Key().String()
+		member := iterator.Value().Interface()
+		if nestiaSDKJsonSchemaInstanceKeyword(key) {
+			output[key] = member
+		} else if nestiaSDKIsNilLike(member) == false {
+			output[key] = nestiaSDKJsonSchemaMember(key, member)
 		}
 	}
-	if symbol == nil {
-		return nil
-	}
-	return symbol.Declarations
+	return output
 }
 
-func nestiaSDKReferencedSchema(schema map[string]any, components map[string]any, name string) map[string]any {
-	ref, _ := schema["$ref"].(string)
-	if ref == "" {
-		return schema
-	}
-	const prefix = "#/components/schemas/"
-	if strings.HasPrefix(ref, prefix) {
-		name = strings.TrimPrefix(ref, prefix)
-	}
-	target := nestiaSDKSchemaMap(components[name])
-	if target != nil {
-		return target
+// nestiaSDKJsonSchemaMember recurses into the subschemas a JSON Schema 2020-12
+// applicator keyword holds, and returns any other keyword value unchanged.
+func nestiaSDKJsonSchemaMember(key string, member any) any {
+	switch key {
+	case "items", "additionalItems", "additionalProperties", "unevaluatedItems",
+		"unevaluatedProperties", "contains", "propertyNames", "not", "if", "then",
+		"else", "contentSchema":
+		return nestiaSDKJsonSchemaLiteral(member)
+	case "allOf", "anyOf", "oneOf", "prefixItems":
+		reflected := reflect.ValueOf(member)
+		if reflected.Kind() != reflect.Slice && reflected.Kind() != reflect.Array {
+			return member
+		}
+		output := make([]any, reflected.Len())
+		for i := range output {
+			output[i] = nestiaSDKJsonSchemaLiteral(reflected.Index(i).Interface())
+		}
+		return output
+	case "properties", "patternProperties", "dependentSchemas", "$defs", "definitions":
+		return nestiaSDKJsonSchemaNamedLiteral(member)
 	}
-	return schema
+	return member
 }
 
-func nestiaSDKSchemaMap(input any) map[string]any {
+// nestiaSDKJsonSchemaNamedLiteral normalizes each schema of a name-keyed schema
+// map, such as `properties`, keeping the order of typia's ordered objects.
+func nestiaSDKJsonSchemaNamedLiteral(input any) any {
 	switch value := input.(type) {
-	case map[string]any:
-		return value
-	case nativeiterate.JsonSchema:
-		return map[string]any(value)
-	default:
-		return nil
+	case nativefactories.LiteralFactory_OrderedObject:
+		return nestiaSDKJsonSchemaOrderedLiteral(value)
+	case *nativefactories.LiteralFactory_OrderedObject:
+		if value == nil {
+			return nil
+		}
+		return nestiaSDKJsonSchemaOrderedLiteral(*value)
+	}
+	reflected := reflect.ValueOf(input)
+	if reflected.Kind() != reflect.Map || reflected.Type().Key().Kind() != reflect.String {
+		return input
 	}
+	output := make(map[string]any, reflected.Len())
+	iterator := reflected.MapRange()
+	for iterator.Next() {
+		output[iterator.Key().String()] = nestiaSDKJsonSchemaLiteral(iterator.Value().Interface())
+	}
+	return output
 }
 
-func nestiaSDKSchemaList(input any) []any {
-	switch value := input.(type) {
-	case []any:
-		return value
-	case []nativeiterate.JsonSchema:
-		output := make([]any, len(value))
-		for i, elem := range value {
-			output[i] = elem
+func nestiaSDKJsonSchemaOrderedLiteral(
+	input nativefactories.LiteralFactory_OrderedObject,
+) nativefactories.LiteralFactory_OrderedObject {
+	output := nativefactories.LiteralFactory_OrderedObject{
+		Keys:   make([]string, 0, len(input.Keys)),
+		Values: make(map[string]any, len(input.Keys)),
+	}
+	for _, key := range input.Keys {
+		value, ok := input.Values[key]
+		if ok == false || nestiaSDKIsNilLike(value) {
+			continue
 		}
-		return output
-	default:
-		return nil
+		output.Keys = append(output.Keys, key)
+		output.Values[key] = nestiaSDKJsonSchemaLiteral(value)
 	}
+	return output
 }
 
-func nestiaSDKReadonlyArrayOperand(node *shimast.Node) bool {
-	if node == nil {
-		return false
+// nestiaSDKJsonSchemaInstanceKeyword reports a keyword whose value is JSON
+// instance data, where null is a legitimate value: the instance keywords of
+// JSON Schema and OpenAPI, and `x-` vendor extensions.
+func nestiaSDKJsonSchemaInstanceKeyword(key string) bool {
+	switch key {
+	case "const", "default", "enum", "example", "examples":
+		return true
 	}
-	switch node.Kind {
-	case shimast.KindArrayType, shimast.KindTupleType:
+	return strings.HasPrefix(key, "x-")
+}
+
+// nestiaSDKIsNilLike mirrors typia's `literalFactory_isNilLike`.
+func nestiaSDKIsNilLike(value any) bool {
+	if value == nil {
 		return true
-	case shimast.KindTypeReference:
-		return nestiaSDKEntityNameText(node.AsTypeReferenceNode().TypeName) == "Array"
-	case shimast.KindParenthesizedType:
-		return nestiaSDKReadonlyArrayOperand(node.AsParenthesizedTypeNode().Type)
+	}
+	reflected := reflect.ValueOf(value)
+	switch reflected.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return reflected.IsNil()
 	default:
 		return false
 	}
 }
 
-func nestiaSDKSchemaPropertyName(node *shimast.Node) string {
-	text := nestiaSDKTypeNodeText(node)
-	return strings.Trim(text, "\"'")
+// nestiaSDKMarkReadonlyArrayJsonSchema carries the producing checker's readonly
+// facts into the baked schema. Alias spelling is never an immutability test.
+func nestiaSDKMarkReadonlyArrayJsonSchema(prog *driver.Program, typ *shimchecker.Type, baked map[string]any, registry *schemametadata.MetadataCollection, escape bool) {
+ registry = registry.Clone()
+ components, _ := baked["components"].(map[string]any)
+ schemas, _ := components["schemas"].(map[string]any)
+ nestiaSDKMarkReadonlySchemaType(prog, typ, nestiaSDKSchemaMap(baked["schema"]), schemas, registry, escape, map[nestiaSDKReadonlyVisit]bool{}, false)
+ for key, schema := range nestiaSDKSchemaMap(baked["properties"]) {
+  nestiaSDKMarkReadonlySchemaType(prog, prog.Checker.GetTypeOfPropertyOfType(typ, key), nestiaSDKSchemaMap(schema), schemas, registry, escape, map[nestiaSDKReadonlyVisit]bool{}, false)
+ }
+}
+
+// nestiaSDKMarkReadonlySchemaType pairs actual substituted checker types with
+// the schema positions the writer emitted, including inferred types and cycles.
+func nestiaSDKMarkReadonlySchemaType(prog *driver.Program, typ *shimchecker.Type, schema map[string]any, components map[string]any, registry *schemametadata.MetadataCollection, escape bool, visiting map[nestiaSDKReadonlyVisit]bool, skipEscape bool) {
+ if prog == nil || prog.Checker == nil || typ == nil || schema == nil { return }
+ // The cloned registry preserves the producer's type-to-component identity.
+ // Public emplace lookups cannot mutate the analysis registry or its counters.
+ if escape && !skipEscape {
+  if method := prog.Checker.GetTypeOfPropertyOfType(typ, "toJSON"); method != nil {
+   for _, signature := range prog.Checker.GetSignaturesOfType(method, shimchecker.SignatureKindCall) {
+    if returned := prog.Checker.GetReturnTypeOfSignature(signature); returned != nil && returned != typ {
+     nestiaSDKMarkReadonlySchemaType(prog, returned, schema, components, registry, escape, visiting, true)
+     return
+    }
+   }
+  }
+ }
+ target := schema
+ if ref, ok := schema["$ref"].(string); ok && strings.HasPrefix(ref, "#/components/schemas/") {
+  name := strings.TrimPrefix(ref, "#/components/schemas/")
+  if component := nestiaSDKSchemaMap(components[name]); component != nil {
+   if component["type"] == "object" && typ.Flags() & shimchecker.TypeFlagsObject != 0 {
+    owner, fresh := registry.Emplace(prog.Checker, typ)
+    if fresh || owner.Name != name { return }
+   }
+   target = component
+  }
+ }
+ key := nestiaSDKReadonlyVisit{Type: typ, Schema: reflect.ValueOf(schema).Pointer()}
+ if visiting[key] { return }
+ visiting[key] = true
+ if typ.Flags() & (shimchecker.TypeFlagsUnion | shimchecker.TypeFlagsIntersection) != 0 {
+  for _, child := range typ.AsUnionOrIntersectionType().Types() {
+   matched := false
+   if typ.Flags() & shimchecker.TypeFlagsUnion != 0 {
+    for _, keyword := range []string{"oneOf", "anyOf"} {
+     if branches := nestiaSDKSchemaList(target[keyword]); len(branches) != 0 {
+      matched = true
+      analyzed := nativefactories.MetadataFactory.Analyze(nativefactories.MetadataFactory_IProps{
+       Checker: prog.Checker,
+       Options: nativefactories.MetadataFactory_IOptions{Escape: escape && !skipEscape, Constant: true, Absorb: true},
+       Components: registry.Clone(), Type: child,
+      })
+      if analyzed.Success {
+       // A union constituent can have no JSON value (undefined, void, never,
+       // or function-only). Unlike the top-level writer, this branch probe
+       // must return nil for those omissions without rejecting the parent.
+       produced := nativeiterate.Json_schema_station(nativeiterate.Json_schema_station_props{
+        BlockNever: false,
+        Components: &nativeiterate.OpenApi_IComponents{Schemas: map[string]nativeiterate.JsonSchema{}},
+        Attribute: nativeiterate.JsonSchema{}, Metadata: schemaprojection.Project(analyzed.Data),
+       })
+       if produced != nil {
+        expected := nestiaSDKJsonSchemaLiteral(produced)
+        for _, branch := range branches {
+         if nestiaSDKReadonlySchemaEquivalent(expected, branch) {
+          nestiaSDKMarkReadonlySchemaType(prog, child, nestiaSDKSchemaMap(branch), components, registry, escape, visiting, skipEscape)
+         }
+        }
+       }
+      }
+     }
+    }
+   }
+   if !matched { nestiaSDKMarkReadonlySchemaType(prog, child, schema, components, registry, escape, visiting, skipEscape) }
+  }
+  return
+ }
+ for _, keyword := range []string{"oneOf", "anyOf", "allOf"} {
+  if branches := nestiaSDKSchemaList(target[keyword]); len(branches) != 0 {
+   for _, branch := range branches {
+    nestiaSDKMarkReadonlySchemaType(prog, typ, nestiaSDKSchemaMap(branch), components, registry, escape, visiting, skipEscape)
+   }
+   return
+  }
+ }
+ if target["type"] == "array" {
+  readonly := false
+  var element *shimchecker.Type
+  if shimchecker.IsTupleType(typ) {
+   readonly = typ.TargetTupleType().IsReadonly()
+  } else {
+   for _, index := range prog.Checker.GetIndexInfosOfType(typ) {
+    if index.KeyType().Flags() & shimchecker.TypeFlagsNumber != 0 { element = index.ValueType(); readonly = index.IsReadonly() }
+   }
+  }
+  if !shimchecker.IsTupleType(typ) && element == nil { return }
+  mutableKey := nestiaSDKReadonlyVisit{Schema: reflect.ValueOf(target).Pointer()}
+  if !readonly {
+   visiting[mutableKey] = true
+   delete(schema, "x-readonly-array")
+   delete(target, "x-readonly-array")
+  } else if !visiting[mutableKey] { schema["x-readonly-array"] = true; target["x-readonly-array"] = true }
+  if shimchecker.IsTupleType(typ) {
+   arguments := prog.Checker.GetTypeArguments(typ)
+   for index, flag := range typ.TargetTupleType().ElementFlags() {
+    if flag == shimchecker.ElementFlagsRest && index < len(arguments) { nestiaSDKMarkReadonlySchemaType(prog, arguments[index], nestiaSDKSchemaMap(target["additionalItems"]), components, registry, escape, visiting, false) }
+   }
+   for index, child := range nestiaSDKSchemaList(target["prefixItems"]) {
+    if index < len(arguments) { nestiaSDKMarkReadonlySchemaType(prog, arguments[index], nestiaSDKSchemaMap(child), components, registry, escape, visiting, false) }
+   }
+  } else if element != nil {
+   nestiaSDKMarkReadonlySchemaType(prog, element, nestiaSDKSchemaMap(target["items"]), components, registry, escape, visiting, false)
+  }
+  return
+ }
+ for key, child := range nestiaSDKSchemaMap(target["properties"]) {
+  nestiaSDKMarkReadonlySchemaType(prog, prog.Checker.GetTypeOfPropertyOfType(typ, key), nestiaSDKSchemaMap(child), components, registry, escape, visiting, false)
+ }
+ for _, index := range prog.Checker.GetIndexInfosOfType(typ) {
+  nestiaSDKMarkReadonlySchemaType(prog, index.ValueType(), nestiaSDKSchemaMap(target["additionalProperties"]), components, registry, escape, visiting, false)
+ }
+}
+
+// nestiaSDKReadonlySchemaEquivalent compares the native writer's branch shape,
+// ignoring only the readonly facts this traversal has already attached.
+func nestiaSDKReadonlySchemaEquivalent(expected any, actual any) bool {
+ left, right := nestiaSDKSchemaMap(expected), nestiaSDKSchemaMap(actual)
+ if left != nil && right != nil {
+  count := 0
+  for key, value := range left {
+   if key == "x-readonly-array" { continue }
+   other, exists := right[key]
+   if !exists || !nestiaSDKReadonlySchemaEquivalent(value, other) { return false }
+   count++
+  }
+  for key := range right { if key != "x-readonly-array" { count-- } }
+  return count == 0
+ }
+ leftList, rightList := nestiaSDKSchemaList(expected), nestiaSDKSchemaList(actual)
+ if leftList != nil && rightList != nil {
+  if len(leftList) != len(rightList) { return false }
+  for i := range leftList { if !nestiaSDKReadonlySchemaEquivalent(leftList[i], rightList[i]) { return false } }
+  return true
+ }
+ return reflect.DeepEqual(expected, actual)
+}
+// nestiaSDKReadonlyVisit identifies one checker-type/schema-map pair per bake.
+type nestiaSDKReadonlyVisit struct {
+ Type *shimchecker.Type
+ Schema uintptr
+}
+
+// nestiaSDKSchemaMap exposes schema maps and the values of an ordered property
+// dictionary without copying or changing its key order.
+func nestiaSDKSchemaMap(input any) map[string]any {
+ switch value := input.(type) {
+ case map[string]any: return value
+ case nativeiterate.JsonSchema: return map[string]any(value)
+ case nativefactories.LiteralFactory_OrderedObject: return value.Values
+ case *nativefactories.LiteralFactory_OrderedObject:
+  if value != nil { return value.Values }
+ }
+ return nil
+}
+
+func nestiaSDKSchemaList(input any) []any {
+ switch value := input.(type) {
+ case []any: return value
+ case []nativeiterate.JsonSchema:
+  output := make([]any, len(value))
+  for i, elem := range value { output[i] = elem }
+  return output
+ default: return nil
+ }
 }
 
 func nestiaSDKRestoreUnionOrder(typeNode *shimast.Node, metadata *schemametadata.MetadataSchema) {
@@ -1115,27 +1579,11 @@ func nestiaSDKIsTypeGuardError(prog *driver.Program, typ *shimchecker.Type, type
 }
 
 func nestiaSDKIsTypiaSourceFile(prog *driver.Program, source *shimast.SourceFile) bool {
-	if prog == nil || prog.FS == nil || source == nil {
-		return false
-	}
-	for directory := filepath.Dir(source.FileName()); ; {
-		contents, ok := prog.FS.ReadFile(filepath.Join(directory, "package.json"))
-		if ok {
-			var pack struct {
-				Name string `json:"name"`
-			}
-			return json.Unmarshal([]byte(contents), &pack) == nil && pack.Name == "typia"
-		}
-		parent := filepath.Dir(directory)
-		if parent == directory {
-			return false
-		}
-		directory = parent
-	}
+	return transform.SourceFilePackageName(prog, source) == "typia"
 }
 
 func nestiaSDKTypeGuardErrorSchemaPipe() any {
-	// Synthetic metadata for `TypeGuardError` exception responses — does not
+	// Synthetic metadata for `TypeGuardError` exception responses; it does not
 	// flow through `nestiaSDKSchemaPipe`, so the pre-baked fields legacy.ts
 	// reads (size/name/empty/jsonSchema) have to be filled by hand.
 	metadata := nestiaSDKObjectReferenceSchema("TypeGuardErrorany")
@@ -1285,6 +1733,9 @@ func nestiaSDKReflectType(
 	if typeNode == nil {
 		return map[string]any{"name": "__type"}, []any{}
 	}
+	if ref, refs, ok := nestiaSDKReflectAsyncAlias(prog, imports, typ, typeNode); ok {
+		return ref, refs
+	}
 	if typeNode != nil {
 		if ref, refs, ok := nestiaSDKReflectTypeNode(prog, imports, typeNode); ok {
 			return ref, refs
@@ -1300,7 +1751,120 @@ func nestiaSDKReflectType(
 	if name == "any" && prog != nil && prog.Checker != nil && typ != nil {
 		name = prog.Checker.TypeToString(typ)
 	}
-	return map[string]any{"name": name}, nestiaSDKReflectImports(name, imports)
+	return map[string]any{"name": name}, nestiaSDKReflectImports(prog, typeNode, imports)
+}
+
+// nestiaSDKReflectAsyncAlias reflects the actual response payload when its
+// annotation aliases an asynchronous wrapper. The checker builds a concrete AST
+// in the annotation's scope, substituting generic arguments and defaults; its
+// identifier-symbol map preserves declaration identity without reparsing text.
+// Ordinary user wrappers keep their original annotation and imports.
+func nestiaSDKReflectAsyncAlias(
+	prog *driver.Program,
+	imports []nestiaSDKImportInfo,
+	typ *shimchecker.Type,
+	node *shimast.Node,
+) (map[string]any, []any, bool) {
+	if prog == nil || prog.Checker == nil || typ == nil || node == nil {
+		return nil, nil, false
+	}
+	reference := node
+	for reference.Kind == shimast.KindParenthesizedType {
+		reference = reference.AsParenthesizedTypeNode().Type
+	}
+	if reference.Kind != shimast.KindTypeReference || transform.NestiaCoreIsAsyncReturnWrapperReference(prog, reference.AsTypeReferenceNode().TypeName) {
+		return nil, nil, false
+	}
+	declared := prog.Checker.GetTypeFromTypeNode(node)
+	if declared == nil || declared == typ || declared.Symbol() == nil {
+		return nil, nil, false
+	}
+	isAsync := func(current *shimchecker.Type) bool {
+		if current == nil || current.Symbol() == nil {
+			return false
+		}
+		for _, declaration := range current.Symbol().Declarations {
+			if declaration != nil && declaration.Name() != nil && transform.NestiaCoreIsAsyncReturnWrapperReference(prog, declaration.Name()) {
+				return true
+			}
+		}
+		return false
+	}
+	if !isAsync(declared) {
+		return nil, nil, false
+	}
+	seen := map[*shimchecker.Type]bool{}
+	for isAsync(typ) && !seen[typ] {
+		seen[typ] = true
+		arguments := prog.Checker.GetTypeArguments(typ)
+		if len(arguments) != 1 {
+			break
+		}
+		typ = arguments[0]
+	}
+	symbols := map[*shimast.IdentifierNode]*shimast.Symbol{}
+	// TypeScript's nodebuilder.FlagsNoTruncation is the public flag bit 1 << 0.
+	// The shim exposes TypeToTypeNode but no alias for that internal enum; a
+	// response type is executable client syntax and cannot use display elision.
+	const noTruncation = 1 << 0
+	projected := prog.Checker.TypeToTypeNode(typ, node, noTruncation, symbols)
+	if projected == nil {
+		return nil, nil, false
+	}
+	ref, _, ok := nestiaSDKReflectTypeNode(nil, nil, projected)
+	if !ok {
+		return nil, nil, false
+	}
+	refs := []any{}
+	add := func(entity *shimast.Node) {
+		root := entity
+		for root != nil && root.Kind == shimast.KindQualifiedName {
+			root = root.AsQualifiedName().Left
+		}
+		if root == nil || root.Kind != shimast.KindIdentifier {
+			return
+		}
+		symbol := symbols[root]
+		if symbol == nil || symbol.Flags&shimast.SymbolFlagsTypeParameter != 0 {
+			return
+		}
+		prefixes := map[string]bool{root.Text(): true}
+		matched := false
+		for _, imp := range imports {
+			if nestiaSDKImportMatches(prefixes, imp) {
+				refs = append(refs, nestiaSDKImportLiteral(imp, prefixes))
+				matched = true
+			}
+		}
+		if matched {
+			return
+		}
+		for _, declaration := range symbol.Declarations {
+			source := shimast.GetSourceFileOfNode(declaration)
+			if source != nil && (prog.TSProgram == nil || !prog.TSProgram.IsLibFile(source)) {
+				refs = append(refs, map[string]any{
+					"file": filepath.ToSlash(source.FileName()), "asterisk": nestiaSDKLiteralNull,
+					"default": nestiaSDKLiteralNull, "elements": []string{root.Text()},
+				})
+				return
+			}
+		}
+	}
+	var walk func(*shimast.Node)
+	walk = func(current *shimast.Node) {
+		if current == nil {
+			return
+		}
+		switch current.Kind {
+		case shimast.KindTypeReference:
+			add(current.AsTypeReferenceNode().TypeName)
+		case shimast.KindTypeQuery:
+			add(current.AsTypeQueryNode().ExprName)
+		}
+		current.ForEachChild(func(child *shimast.Node) bool { walk(child); return false })
+	}
+	walk(projected)
+	return ref, nestiaSDKMergeImportLiterals(refs), true
 }
 
 func nestiaSDKReflectTypeNode(
@@ -1322,7 +1886,7 @@ func nestiaSDKReflectTypeNode(
 		element, refs, ok := nestiaSDKReflectTypeNode(prog, imports, node.AsArrayTypeNode().ElementType)
 		if ok == false {
 			element = map[string]any{"name": nestiaSDKTypeNodeText(node.AsArrayTypeNode().ElementType)}
-			refs = nestiaSDKReflectImports(element["name"].(string), imports)
+			refs = nestiaSDKReflectImports(prog, node.AsArrayTypeNode().ElementType, imports)
 		}
 		return map[string]any{
 			"name":          "Array",
@@ -1332,34 +1896,29 @@ func nestiaSDKReflectTypeNode(
 		child, refs, ok := nestiaSDKReflectTypeNode(prog, imports, node.AsParenthesizedTypeNode().Type)
 		if ok == false {
 			child = map[string]any{"name": nestiaSDKTypeNodeText(node.AsParenthesizedTypeNode().Type)}
-			refs = nestiaSDKReflectImports(child["name"].(string), imports)
+			refs = nestiaSDKReflectImports(prog, node.AsParenthesizedTypeNode().Type, imports)
 		}
-		name, _ := child["name"].(string)
-		return map[string]any{"name": "(" + name + ")"}, refs, true
+		return map[string]any{"name": "(" + nestiaSDKReflectTypeText(child) + ")"}, refs, true
 	case shimast.KindTypeOperator:
 		operator := node.AsTypeOperatorNode()
 		prefix := nestiaSDKTypeOperatorPrefix(node, operator.Type)
 		if prefix == "" {
 			return nil, nil, false
 		}
-		child, refs, ok := nestiaSDKReflectTypeNode(prog, imports, operator.Type)
-		if ok == false {
-			child = map[string]any{"name": nestiaSDKTypeNodeText(operator.Type)}
-			refs = nestiaSDKReflectImports(child["name"].(string), imports)
-		}
-		name, _ := child["name"].(string)
-		return map[string]any{"name": prefix + " " + name}, refs, true
+		// Operators retain their actual syntax: readonly requires an array or
+		// tuple operand, and rendering the reflected Array<T> form here would
+		// produce invalid TypeScript. Checker-projected nodes already contain
+		// concrete alias arguments and are printed by the same text operation.
+		return map[string]any{"name": nestiaSDKTypeNodeText(node)},
+			nestiaSDKReflectImports(prog, operator.Type, imports), true
 	case shimast.KindTypeQuery:
 		return nil, nil, false
 	case shimast.KindTypeReference:
 		ref := node.AsTypeReferenceNode()
 		name := nestiaSDKEntityNameText(ref.TypeName)
-		rootRefs := nestiaSDKReflectImports(name, imports)
-		if len(rootRefs) == 0 && nestiaSDKIsAsyncReturnWrapper(prog, ref.TypeName, name) == false {
-			rootRefs = nestiaSDKReflectTypeReferenceSymbolImport(prog, ref.TypeName, name)
-		}
+		rootRefs := nestiaSDKReflectImports(prog, ref.TypeName, imports)
 		if ref.TypeArguments != nil && len(ref.TypeArguments.Nodes) != 0 {
-			if nestiaSDKIsAsyncReturnWrapper(prog, ref.TypeName, name) && len(ref.TypeArguments.Nodes) == 1 {
+			if transform.NestiaCoreIsAsyncReturnWrapperReference(prog, ref.TypeName) && len(ref.TypeArguments.Nodes) == 1 {
 				return nestiaSDKReflectTypeNode(prog, imports, ref.TypeArguments.Nodes[0])
 			}
 			args := make([]any, 0, len(ref.TypeArguments.Nodes))
@@ -1369,7 +1928,7 @@ func nestiaSDKReflectTypeNode(
 				if ok == false {
 					text := nestiaSDKTypeNodeText(child)
 					arg = map[string]any{"name": text}
-					refs = nestiaSDKReflectImports(text, imports)
+					refs = nestiaSDKReflectImports(prog, child, imports)
 				}
 				args = append(args, arg)
 				groups = append(groups, refs)
@@ -1385,16 +1944,20 @@ func nestiaSDKReflectTypeNode(
 		if name == "" {
 			return nil, nil, false
 		}
-		return map[string]any{"name": name}, nestiaSDKReflectImports(name, imports), true
+		return map[string]any{"name": name}, nestiaSDKReflectImports(prog, node, imports), true
 	}
 }
 
+// nestiaSDKReflectTypeReferenceSymbolImport supplies a declaration import when
+// no authored import binding describes the referenced type. The actual program's
+// library-file identity keeps global library declarations out of client imports.
+// Locally bound type parameters have no importable module declaration.
 func nestiaSDKReflectTypeReferenceSymbolImport(prog *driver.Program, node *shimast.Node, name string) []any {
 	if prog == nil || prog.Checker == nil || node == nil {
 		return nil
 	}
 	prefix := strings.Split(name, ".")[0]
-	if nestiaSDKIsGlobalTypePrefix(prefix) {
+	if nestiaSDKIsTypeKeyword(prefix) {
 		return nil
 	}
 	symbol := prog.Checker.GetSymbolAtLocation(node)
@@ -1404,17 +1967,18 @@ func nestiaSDKReflectTypeReferenceSymbolImport(prog *driver.Program, node *shima
 			symbol = typ.Symbol()
 		}
 	}
-	if symbol == nil || len(symbol.Declarations) == 0 {
+	if symbol == nil || symbol.Flags&shimast.SymbolFlagsTypeParameter != 0 || len(symbol.Declarations) == 0 {
 		return nil
 	}
 	sourceFile := shimast.GetSourceFileOfNode(symbol.Declarations[0])
 	if sourceFile == nil {
 		return nil
 	}
-	file := filepath.ToSlash(sourceFile.FileName())
-	if strings.Contains(file, "/typescript/lib/") {
+	// a default library type, whichever folder or replacement package supplies it
+	if prog.TSProgram != nil && prog.TSProgram.IsLibFile(sourceFile) {
 		return nil
 	}
+	file := filepath.ToSlash(sourceFile.FileName())
 	return []any{
 		map[string]any{
 			"file":     file,
@@ -1441,7 +2005,7 @@ func nestiaSDKReflectJoinedTypeNode(
 		if ok == false {
 			text := nestiaSDKTypeNodeText(child)
 			names = append(names, text)
-			groups = append(groups, nestiaSDKReflectImports(text, imports))
+			groups = append(groups, nestiaSDKReflectImports(prog, child, imports))
 		} else {
 			names = append(names, nestiaSDKReflectTypeText(ref))
 			groups = append(groups, refs)
@@ -1505,18 +2069,261 @@ func nestiaSDKParentClassName(node *shimast.Node) string {
 	return ""
 }
 
+// nestiaSDKMethodName names a decorated method's site. The contributor visits
+// every decorated method of the program, controller or not, and a computed
+// name such as `[key]` has no identifier: it reads as its literal key when it
+// has one, and as its source otherwise. The metadata still reaches the method,
+// because a decorator attaches it under the key the runtime computes.
 func nestiaSDKMethodName(node *shimast.Node) string {
 	if node == nil || node.Name() == nil {
 		return ""
 	}
-	return strings.Trim(node.Name().Text(), "\"'")
+	name := node.Name()
+	if name.Kind == shimast.KindComputedPropertyName {
+		switch expression := name.AsComputedPropertyName().Expression; expression.Kind {
+		case shimast.KindStringLiteral, shimast.KindNumericLiteral, shimast.KindNoSubstitutionTemplateLiteral:
+			return expression.Text()
+		}
+	}
+	return strings.Trim(shimast.NodeText(name), "\"'")
+}
+
+// nestiaSDKWebSocketHeaderError reports a WebSocket route whose handshake
+// header the generated SDK cannot carry: the header type of an
+// @WebSocketRoute.Acceptor() (its first type argument) or the type of an
+// @WebSocketRoute.Header() parameter must be an object type or undefined,
+// because the SDK function sends it as connection.headers, which @nestia/fetcher
+// types `IConnection<Headers extends object | undefined>`. tgrid itself leaves
+// the header unconstrained, so a null or primitive header serves, yet its SDK
+// would not compile.
+func nestiaSDKWebSocketHeaderError(
+	prog *driver.Program,
+	param *shimast.Node,
+	typ *shimchecker.Type,
+) error {
+	category := transform.NestiaCoreWebSocketParameterCategory(prog, param)
+	var header *shimchecker.Type
+	switch category {
+	case "Acceptor":
+		// only tgrid's acceptor has a header; the transform already rejects any
+		// other type, and asking a non-reference type for its type arguments
+		// would fault the checker
+		if _, name := transform.NestiaCoreWebSocketTypeReference(prog, nestiaSDKParameterTypeNode(param)); name != "WebSocketAcceptor" {
+			return nil
+		}
+		if typ == nil || typ.Flags()&shimchecker.TypeFlagsObject == 0 || typ.ObjectFlags()&shimchecker.ObjectFlagsReference == 0 {
+			return nil
+		}
+		if args := shimchecker.Checker_getTypeArguments(prog.Checker, typ); len(args) != 0 {
+			header = args[0]
+		}
+	case "Header":
+		header = typ
+	default:
+		return nil
+	}
+	if header == nil || nestiaSDKIsConnectionHeader(header) {
+		return nil
+	}
+	return fmt.Errorf(
+		"@WebSocketRoute.%s() parameter %q has the header type %q, which the SDK cannot send: it carries the handshake header as connection.headers, which must be an object type or undefined. Use an object type, or undefined for no header.",
+		category,
+		nestiaSDKParameterName(param),
+		prog.Checker.TypeToString(header),
+	)
+}
+
+// nestiaSDKIsConnectionHeader reports whether typ is assignable to
+// `object | undefined`, the constraint of IConnection's Headers: any, never,
+// undefined, an object type, or a union of them; an intersection only when
+// every member is an object type, so `string & {}` stays a string.
+func nestiaSDKIsConnectionHeader(typ *shimchecker.Type) bool {
+	flags := typ.Flags()
+	if flags&(shimchecker.TypeFlagsAny|shimchecker.TypeFlagsNever|shimchecker.TypeFlagsUndefined|shimchecker.TypeFlagsObject|shimchecker.TypeFlagsNonPrimitive) != 0 {
+		return true
+	}
+	if flags&shimchecker.TypeFlagsUnion != 0 {
+		for _, elem := range typ.AsUnionOrIntersectionType().Types() {
+			if nestiaSDKIsConnectionHeader(elem) == false {
+				return false
+			}
+		}
+		return true
+	}
+	if flags&shimchecker.TypeFlagsIntersection != 0 {
+		for _, elem := range typ.AsUnionOrIntersectionType().Types() {
+			if elem.Flags()&(shimchecker.TypeFlagsObject|shimchecker.TypeFlagsNonPrimitive) == 0 {
+				return false
+			}
+		}
+		return true
+	}
+	return false
 }
 
+// nestiaSDKWebSocketParameterType reflects an @WebSocketRoute.Acceptor() or
+// .Driver() parameter annotated through a type alias or an import type as the
+// tgrid reference it spells, such as `WebSocketAcceptor<Header, Provider,
+// Listener>`, because the generated client needs those type arguments. Each
+// argument is reflected in the file that writes it, and one naming a type
+// parameter of a generic alias is replaced by what the annotation passes for
+// it. It returns nil for an annotation writing the tgrid reference itself as a
+// type reference, and an error for an alias using its type parameter inside an
+// argument, such as `IRoom<P>`, which no written node spells.
+func nestiaSDKWebSocketParameterType(
+	context *nestiaSDKContext,
+	param *shimast.Node,
+) (map[string]any, []any, error) {
+	category := transform.NestiaCoreWebSocketParameterCategory(context.prog, param)
+	switch category {
+	case "Acceptor", "Driver":
+	default:
+		return nil, nil, nil
+	}
+	chain, name := transform.NestiaCoreWebSocketTypeReference(context.prog, nestiaSDKParameterTypeNode(param))
+	// the annotation's own reflection serves a tgrid reference written as a
+	// plain type reference, but reflects an import type without its arguments
+	if len(chain) == 0 || (len(chain) == 1 && chain[0].Kind == shimast.KindTypeReference) {
+		return nil, nil, nil
+	}
+	args := []any{}
+	groups := [][]any{}
+	if target := chain[len(chain)-1].TypeArgumentList(); target != nil {
+		for _, node := range target.Nodes {
+			argument := nestiaSDKWebSocketTypeArgument(context.prog, chain, node)
+			if argument == nil {
+				return nil, nil, fmt.Errorf(
+					"@WebSocketRoute.%s() parameter %q is typed by a type alias whose %s type argument %q uses a type parameter of the alias inside it, which the SDK cannot write. Pass each type parameter as a whole type argument, or write the %s type directly.",
+					category,
+					nestiaSDKParameterName(param),
+					name,
+					nestiaSDKTypeNodeText(node),
+					name,
+				)
+			}
+			imports := context.imports(shimast.GetSourceFileOfNode(argument))
+			arg, refs, ok := nestiaSDKReflectTypeNode(context.prog, imports, argument)
+			if ok == false {
+				text := nestiaSDKTypeNodeText(argument)
+				arg = map[string]any{"name": text}
+				refs = nestiaSDKReflectImports(context.prog, argument, imports)
+			}
+			args = append(args, arg)
+			groups = append(groups, refs)
+		}
+	}
+	refs := nestiaSDKMergeImportLiterals(groups...)
+	if refs == nil {
+		refs = []any{}
+	}
+	return map[string]any{
+		"name":          name,
+		"typeArguments": args,
+	}, refs, nil
+}
+
+// nestiaSDKWebSocketTypeArgument follows a type argument of the last reference
+// in chain back through the aliases while it names a type parameter of the
+// alias it is written in, to what the reference before passes for it or else
+// to the parameter's default. It returns nil when the argument uses such a
+// type parameter any other way, which no written node spells.
+func nestiaSDKWebSocketTypeArgument(prog *driver.Program, chain []*shimast.Node, node *shimast.Node) *shimast.Node {
+	for level := len(chain) - 1; level > 0; {
+		alias := nestiaSDKEnclosingTypeAlias(chain[level])
+		if alias == nil {
+			return nil
+		}
+		parameters := alias.AsTypeAliasDeclaration().TypeParameters
+		index := nestiaSDKTypeParameterIndex(prog, parameters, node)
+		if index == -1 {
+			if nestiaSDKUsesAliasTypeParameter(prog, node) {
+				return nil
+			}
+			return node
+		}
+		// the reference naming the alias, a type reference or an import type
+		reference := chain[level-1].TypeArgumentList()
+		if reference != nil && index < len(reference.Nodes) {
+			node = reference.Nodes[index]
+			level--
+			continue
+		}
+		// a default may name an earlier parameter of the same alias
+		node = parameters.Nodes[index].AsTypeParameterDeclaration().DefaultType
+		if node == nil {
+			return nil
+		}
+	}
+	return node
+}
+
+func nestiaSDKEnclosingTypeAlias(node *shimast.Node) *shimast.Node {
+	for parent := node.Parent; parent != nil; parent = parent.Parent {
+		if parent.Kind == shimast.KindTypeAliasDeclaration {
+			return parent
+		}
+	}
+	return nil
+}
+
+// nestiaSDKTypeParameterIndex is the position of the type parameter node names
+// by itself, such as `P` or `(P)`, among parameters, or -1.
+func nestiaSDKTypeParameterIndex(prog *driver.Program, parameters *shimast.NodeList, node *shimast.Node) int {
+	for node != nil && node.Kind == shimast.KindParenthesizedType {
+		node = node.AsParenthesizedTypeNode().Type
+	}
+	if parameters == nil || node == nil || node.Kind != shimast.KindTypeReference {
+		return -1
+	}
+	if arguments := node.AsTypeReferenceNode().TypeArguments; arguments != nil && len(arguments.Nodes) != 0 {
+		return -1
+	}
+	symbol := prog.Checker.GetSymbolAtLocation(node.AsTypeReferenceNode().TypeName)
+	if symbol == nil || symbol.Flags&shimast.SymbolFlagsTypeParameter == 0 {
+		return -1
+	}
+	for index, parameter := range parameters.Nodes {
+		for _, declaration := range symbol.Declarations {
+			if declaration == parameter {
+				return index
+			}
+		}
+	}
+	return -1
+}
+
+// nestiaSDKUsesAliasTypeParameter reports whether node refers to a type
+// parameter a type alias declares anywhere inside it.
+func nestiaSDKUsesAliasTypeParameter(prog *driver.Program, node *shimast.Node) bool {
+	if node == nil {
+		return false
+	}
+	if node.Kind == shimast.KindTypeReference {
+		symbol := prog.Checker.GetSymbolAtLocation(node.AsTypeReferenceNode().TypeName)
+		if symbol != nil && symbol.Flags&shimast.SymbolFlagsTypeParameter != 0 {
+			for _, declaration := range symbol.Declarations {
+				if declaration != nil && declaration.Parent != nil && declaration.Parent.Kind == shimast.KindTypeAliasDeclaration {
+					return true
+				}
+			}
+		}
+	}
+	found := false
+	node.ForEachChild(func(child *shimast.Node) bool {
+		found = nestiaSDKUsesAliasTypeParameter(prog, child)
+		return found
+	})
+	return found
+}
+
+// nestiaSDKParameterName reads a parameter's identifier, or "" for a
+// destructuring pattern such as `{ organizationId }`, which declares no name
+// the SDK could reuse; the SDK names such a parameter after its role.
 func nestiaSDKParameterName(node *shimast.Node) string {
-	if node == nil || node.Name() == nil {
+	if node == nil || node.Name() == nil || node.Name().Kind != shimast.KindIdentifier {
 		return ""
 	}
-	return strings.Trim(node.Name().Text(), "\"'")
+	return node.Name().Text()
 }
 func nestiaSDKParameterTypeNode(node *shimast.Node) *shimast.Node {
 	if node != nil && node.AsParameterDeclaration() != nil {
@@ -1536,7 +2343,7 @@ func nestiaSDKMethodReturnTypeNode(prog *driver.Program, method *shimast.Node) *
 func nestiaSDKReturnTypeNode(prog *driver.Program, node *shimast.Node) *shimast.Node {
 	if node != nil && node.Kind == shimast.KindTypeReference {
 		ref := node.AsTypeReferenceNode()
-		if ref != nil && ref.TypeArguments != nil && len(ref.TypeArguments.Nodes) == 1 && nestiaSDKIsAsyncReturnWrapper(prog, ref.TypeName, nestiaSDKEntityNameText(ref.TypeName)) {
+		if ref != nil && ref.TypeArguments != nil && len(ref.TypeArguments.Nodes) == 1 && transform.NestiaCoreIsAsyncReturnWrapperReference(prog, ref.TypeName) {
 			return ref.TypeArguments.Nodes[0]
 		}
 	}
@@ -1546,84 +2353,18 @@ func nestiaSDKReturnTypeNode(prog *driver.Program, node *shimast.Node) *shimast.
 func nestiaSDKEntityNameText(node *shimast.Node) string {
 	return nestiaSDKTypeNodeText(node)
 }
-func nestiaSDKIsAsyncReturnWrapper(
-	prog *driver.Program,
-	node *shimast.Node,
-	name string,
-) bool {
-	if name == "Promise" {
-		return true
-	}
-	if name != "Observable" || prog == nil || prog.Checker == nil {
-		return false
-	}
-	symbol := prog.Checker.GetSymbolAtLocation(node)
-	return nestiaSDKIsRxjsObservableImport(node) ||
-		(symbol != nil && nestiaSDKIsRxjsDeclarations(symbol.Declarations))
-}
-
-func nestiaSDKIsRxjsDeclarations(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/") {
-			return true
-		}
-	}
-	return false
-}
-
-func nestiaSDKIsRxjsObservableImport(node *shimast.Node) bool {
-	source, ok := transform.SourceFileText(shimast.GetSourceFileOfNode(node))
-	return ok && nestiaSDKHasNamedImport(source, "rxjs", "Observable", "Observable")
-}
-
-func nestiaSDKHasNamedImport(
-	source string,
-	module string,
-	imported string,
-	local string,
-) bool {
-	for _, match := range nestiaSDKImportFromPattern.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 nestiaSDKImportFromPattern = regexp.MustCompile(
-	`(?s)import\s+(?:type\s+)?(.+?)\s+from\s+["']([^"']+)["']`,
-)
-
 func nestiaSDKTypeNodeText(node *shimast.Node) string {
 	if node == nil {
 		return ""
 	}
 	file := shimast.GetSourceFileOfNode(node)
-	source, ok := transform.SourceFileText(file)
+	source, ok := "", false
+	if file != nil {
+		source, ok = transform.SourceFileText(file)
+	}
 	if ok == false {
-		return ""
+		printer := shimprinter.NewPrinter(shimprinter.PrinterOptions{}, shimprinter.PrintHandlers{}, shimprinter.NewEmitContext())
+		return strings.TrimSpace(printer.Emit(node, file))
 	}
 	start, end := node.Pos(), node.End()
 	if start < 0 || end > len(source) || start >= end {
@@ -1640,7 +2381,9 @@ type sdkOperationMetadataInsertResult struct {
 func nestiaSDKDiagnostic(site nestiaSDKSite, message string) transform.Diagnostic {
 	line, column := 0, 0
 	if site.File != nil && site.Method != nil {
-		if pos := site.Method.Pos(); pos >= 0 {
+		// the first token's position: Pos() starts at the leading trivia, the
+		// previous line's end and any JSDoc
+		if pos := shimscanner.GetTokenPosOfNode(site.Method, site.File, false); pos >= 0 {
 			l, c := shimscanner.GetECMALineAndByteOffsetOfPosition(site.File, pos)
 			line, column = l+1, c+1
 		}