@nestia/core 14.0.0 → 14.0.2

package/native/plugin/plan.go

@@ -14,6 +14,16 @@ const (
 	TypiaTransform      = "typia/lib/transform"
 )
 
+// Entry is one plugin of the ordered list that ttsc hands to the host: its name, stage, the `transform` specifier of its configuration, and the whole configuration.
+//
+// @evidence contracts/common.md#principled-implementation The fields are the parts of the payload that classification and option reading need, with the transform specifier lifted out of the configuration map once so every later comparison reads a string.
+// @evidence contracts/common.md#clear-and-simple-design A plain record with no behavior; the two methods answer questions about it.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It carries the payload as given, and no plugin name or option is special-cased here.
+// @evidence contracts/common.md#meaningful-documentation The comment names the fields and where the value comes from.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Plugin specifiers are module identifiers and configuration is decoded data, not native file identity.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This record defines data rather than choosing a processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This record does not coordinate computations across consumers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The parsed entry stores configuration but does not own its consumers lifetimes.
 type Entry struct {
 	Name      string
 	Stage     string
@@ -21,6 +31,16 @@ type Entry struct {
 	Config    map[string]any
 }
 
+// Plan is the parsed plugin list: the entries in order and one flag for each plugin family present.
+//
+// @evidence contracts/common.md#principled-implementation The three flags are computed once by `ParsePlan` from the classification of every entry, so the callers ask a boolean instead of rescanning the list.
+// @evidence contracts/common.md#clear-and-simple-design A record of three flags and the ordered entries, with one derived accessor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It holds parsed data only, and the flags follow from the entries.
+// @evidence contracts/common.md#meaningful-documentation The comment states what each part of the plan means.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The ordered plugin list and family flags contain no native paths or process handles.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This record defines data rather than choosing a processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This record does not coordinate computations across consumers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The plan stores parsed entries; the command owns their lifetime.
 type Plan struct {
 	Core    bool
 	SDK     bool
@@ -28,12 +48,31 @@ type Plan struct {
 	Entries []Entry
 }
 
+// UsesNestia reports whether the plan contains a `@nestia/core` or a `@nestia/sdk` entry, that is, whether any nestia rewrite is wanted.
+//
+// @evidence contracts/common.md#principled-implementation The result is the disjunction of the two family flags, which is exactly the condition under which the nestia passes run.
+// @evidence contracts/common.md#clear-and-simple-design A one-line accessor over two fields, so the condition has one definition.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the flags and nothing else.
+// @evidence contracts/common.md#meaningful-documentation The comment states the condition.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The family-flag predicate reads only booleans.
+// @evidence contracts/performance.md#efficient-algorithms Reading two family flags takes constant work and allocates no collection.
+// @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 state survives the boolean result.
 func (p Plan) UsesNestia() bool {
 	return p.Core || p.SDK
 }
 
 // Kind reports which plugin family an entry belongs to: "core", "sdk", "typia",
 // or "" when it is none of them.
+//
+// @evidence contracts/common.md#principled-implementation The family is decided by the entry name or by the `transform` specifier compared with the known published specifiers, so an entry written under either spelling of the plugin is recognized, and any other entry is not a family member.
+// @evidence contracts/common.md#clear-and-simple-design A one-line method over the private classifier, so one function owns the naming rules.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The names are the published package specifiers, which are contract constants, and no consumer or path is special-cased.
+// @evidence contracts/common.md#meaningful-documentation The comment lists the four possible results.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Classification compares published module specifiers, not native paths.
+// @evidence contracts/performance.md#efficient-algorithms Classification trims and compares the name and transform strings, linear in their 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 Only temporary trimmed strings are used; no registry entry is retained.
 func (e Entry) Kind() string {
 	return classify(e)
 }
@@ -41,6 +80,15 @@ func (e Entry) Kind() string {
 // BoolConfig reads a boolean option from an entry's resolved plugin config. The
 // second result distinguishes an option explicitly set to false from one that is
 // absent, which the tri-state options depend on.
+//
+// @evidence contracts/common.md#principled-implementation A boolean read from the configuration returns its value and a presence flag, so an option explicitly set to false is distinct from an absent one, which the tri-state options need; a non-boolean value reads as absent.
+// @evidence contracts/common.md#clear-and-simple-design One map lookup and one type assertion.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It reads only the configuration of the entry it is called on.
+// @evidence contracts/common.md#meaningful-documentation The comment states why the second result exists.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The lookup reads an in-memory JSON option map.
+// @evidence contracts/performance.md#efficient-algorithms One map lookup and type assertion use expected constant 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 lookup retains no state or handle.
 func (e Entry) BoolConfig(key string) (bool, bool) {
 	if e.Config == nil {
 		return false, false
@@ -49,13 +97,25 @@ func (e Entry) BoolConfig(key string) (bool, bool) {
 	return value, ok
 }
 
+// ParsePlan parses the ordered plugin payload that ttsc passes as `--plugins-json`.
+//
+// An empty payload is an empty plan. A payload that is not a JSON list of plugin objects is an error naming the flag. JSON null is not an empty list, and a null list entry is not a plugin object. An entry without a stage is a `transform` stage entry.
+//
+// @evidence contracts/common.md#principled-implementation The standard JSON decoder checks the list and object field types. A nil decoded list identifies JSON null rather than an empty array; pointer elements retain null entries for explicit rejection. Each object keeps its order, defaults its stage, supplies its transform string and contributes its classified family flag. A rejected list returns a zero plan even when a prior element was valid.
+// @evidence contracts/common.md#clear-and-simple-design One function that decodes, normalizes, and classifies; the string reading and the classification are private helpers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The defaults are the ttsc protocol's, and the function trusts the payload only as far as decoding it.
+// @evidence contracts/common.md#meaningful-documentation The comment states the accepted payloads, the error, and the stage default.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The command payload is a JSON string; plugin transform specifiers remain module identifiers rather than native paths.
+// @evidence contracts/performance.md#efficient-algorithms Decoding is linear in payload bytes and one classification is performed per entry; the output holds one entry per plugin.
+// @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 Decoded maps and the result list belong to the returned plan and become reclaimable with its caller.
 func ParsePlan(payload string) (Plan, error) {
 	payload = strings.TrimSpace(payload)
 	if payload == "" {
 		return Plan{}, nil
 	}
 
-	var raws []struct {
+	var raws []*struct {
 		Name   string         `json:"name"`
 		Stage  string         `json:"stage"`
 		Config map[string]any `json:"config"`
@@ -63,11 +123,17 @@ func ParsePlan(payload string) (Plan, error) {
 	if err := json.Unmarshal([]byte(payload), &raws); err != nil {
 		return Plan{}, fmt.Errorf("parse plugins-json: %w", err)
 	}
+	if raws == nil {
+		return Plan{}, fmt.Errorf("parse plugins-json: expected a JSON list of plugin objects")
+	}
 
 	plan := Plan{
 		Entries: make([]Entry, 0, len(raws)),
 	}
-	for _, raw := range raws {
+	for index, raw := range raws {
+		if raw == nil {
+			return Plan{}, fmt.Errorf("parse plugins-json: entry %d must be a JSON object", index)
+		}
 		stage := raw.Stage
 		if stage == "" {
 			stage = "transform"

package/native/transform/ast.go

@@ -7,15 +7,35 @@ import (
 )
 
 // NodeName returns the trimmed identifier text of a named AST node
-// (method, parameter, ...). Empty when the node has no name.
+// (method, parameter, ...). Empty when the node has no name. A name that is no
+// identifier, a destructured parameter's `{ a }` or a computed method name's
+// `[key]`, reads as its source, since typescript-go's `Text()` panics on it.
+//
+// @evidence contracts/common.md#principled-implementation The identifier text is read through the shim's `NodeText` so that a destructured parameter or a computed method name, whose `Text()` panics in the compiler port, reads as its source, and the quotes of a string-literal name are trimmed.
+// @evidence contracts/common.md#clear-and-simple-design One function with a nil check, one call, and one trim.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It handles the node kinds the compiler API defines, with no fixture names.
+// @evidence contracts/common.md#meaningful-documentation The comment states the empty result, the source fallback for non-identifiers, and the reason.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The compiler node name is source text, not a filesystem path.
+// @evidence contracts/performance.md#efficient-algorithms Reading NodeText and trimming quote characters cost at most the name text length.
+// @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 string borrows or contains source text; the helper retains no node globally.
 func NodeName(node *shimast.Node) string {
 	if node == nil || node.Name() == nil {
 		return ""
 	}
-	return strings.Trim(node.Name().Text(), "\"'")
+	return strings.Trim(shimast.NodeText(node.Name()), "\"'")
 }
 
-// NodeText returns the verbatim source slice spanned by a node.
+// NodeText returns the source slice spanned by a node with surrounding whitespace removed.
+//
+// @evidence contracts/common.md#principled-implementation The node's position range is applied to the source text of its file after a bounds check, and the slice is trimmed, so a synthesized node or a range outside the source returns an empty string instead of panicking.
+// @evidence contracts/common.md#clear-and-simple-design One function over the source text accessor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the text of the file the node belongs to and adds nothing to it.
+// @evidence contracts/common.md#meaningful-documentation The comment identifies the source range and whitespace trimming.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Source text and node byte offsets are compiler data rather than native filesystem access.
+// @evidence contracts/performance.md#efficient-algorithms Bounds checks are constant work and TrimSpace scans at most the selected source range.
+// @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 source substring can keep its source string alive until the caller releases it; no global state or handle is acquired.
 func NodeText(node *shimast.Node) string {
 	if node == nil {
 		return ""

package/native/transform/build.go

@@ -2,17 +2,16 @@ package transform
 
 import (
 	"context"
-	"encoding/json"
 	"flag"
 	"fmt"
 	"io"
 	"os"
 	"path/filepath"
-	"sync"
 	"time"
 
 	shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
 	"github.com/samchon/nestia/packages/core/native/plugin"
+	"github.com/samchon/nestia/packages/core/native/transform/buildoutput"
 	"github.com/samchon/ttsc/packages/ttsc/driver"
 	typiaadapter "github.com/samchon/typia/packages/typia/native/adapter"
 )
@@ -117,18 +116,14 @@ func runBuild(args []string) int {
 	defer prog.Close()
 	releaseTypiaRegistries := registerTypiaDefaultLibraryClassifier(prog)
 	defer releaseTypiaRegistries()
-	if !*quiet {
-		fmt.Fprintf(
-			stdout,
-			"// ttsc-nestia build: tsconfig=%s cwd=%s core=%v sdk=%v typia=%v emit=%v\n",
-			*tsconfigPath,
-			cwd,
-			plan.Core,
-			plan.SDK,
-			plan.Typia,
-			shouldEmit,
-		)
-	}
+	publication := buildoutput.New(buildoutput.Options{
+		TSConfig: *tsconfigPath, CWD: cwd, Manifest: *manifestPath,
+		Core: plan.Core, SDK: plan.SDK, Typia: plan.Typia,
+		Emit: shouldEmit, Quiet: *quiet,
+	}, stdout, driver.DefaultWriteFile)
+	// Publication owns all generated bytes until actual diagnostics accept them.
+	// Every earlier return terminates this session without committing its buffer.
+	defer publication.Finish(false)
 
 	// AST-integration emit: typia's per-file transformer and @nestia/core's own
 	// per-file transformer both run inside tsgo's emit pipeline (sharing the
@@ -141,7 +136,13 @@ func runBuild(args []string) int {
 	if profile {
 		started = time.Now()
 	}
-	newPathsRewriter(prog).applyAll(prog.SourceFiles())
+	// Path remapping serves published output, not type analysis. The private
+	// ForceEmit program used by noEmit has not run semantic diagnostics, so its
+	// checker still resolves imports lazily. Changing those imports to output
+	// paths would make it look for JavaScript files that do not exist.
+	if shouldEmit {
+		newPathsRewriter(prog).applyAll(prog.SourceFiles())
+	}
 	profileBuildStep(profile, "paths-rewrite", started)
 
 	typiaTransform := nestiaTypiaNodeTransform(prog, readTypiaPluginOptions(plan), addDiagnostic)
@@ -160,20 +161,9 @@ func runBuild(args []string) int {
 	}
 	transforms := append([]driver.PluginTransform{typiaTransform, coreTransform}, contributorTransforms...)
 
-	emitted := []string{}
-	pending := []buildPendingOutput{}
-	var writeMu sync.Mutex
 	writeFile := shimcompiler.WriteFile(func(fileName, text string, data *shimcompiler.WriteFileData) error {
 		_ = data
-		if shouldEmit {
-			// TypeScript-Go emits declarations in parallel. Serialize the shared
-			// slices so buffering cannot lose an artifact or race while the
-			// declaration workers call this callback concurrently.
-			writeMu.Lock()
-			defer writeMu.Unlock()
-			emitted = append(emitted, fileName)
-			pending = append(pending, buildPendingOutput{FileName: fileName, Text: text})
-		}
+		publication.Write(fileName, text)
 		return nil
 	})
 
@@ -215,41 +205,15 @@ func runBuild(args []string) int {
 	if emitHasError {
 		return 3
 	}
-	if shouldEmit {
-		for _, output := range pending {
-			if err := driver.DefaultWriteFile(output.FileName, output.Text); err != nil {
-				fmt.Fprintf(stderr, "ttsc-nestia build: emit write failed: %v\n", err)
-				return 3
-			}
-		}
-		if *manifestPath != "" {
-			data, err := json.Marshal(emitted)
-			if err != nil {
-				fmt.Fprintf(stderr, "ttsc-nestia build: manifest marshal failed: %v\n", err)
-				return 3
-			}
-			if err := os.MkdirAll(filepath.Dir(*manifestPath), 0o755); err != nil {
-				fmt.Fprintf(stderr, "ttsc-nestia build: manifest mkdir failed: %v\n", err)
-				return 3
-			}
-			if err := os.WriteFile(*manifestPath, data, 0o644); err != nil {
-				fmt.Fprintf(stderr, "ttsc-nestia build: manifest write failed: %v\n", err)
-				return 3
-			}
-		}
-		if !*quiet {
-			fmt.Fprintf(stdout, "// ttsc-nestia build: emitted=%d files\n", len(emitted))
-		}
+	if err := publication.Finish(true); err != nil {
+		fmt.Fprintf(stderr, "ttsc-nestia build: %v\n", err)
+		return 3
 	}
+
 	profileBuildStep(profile, "total", totalStarted)
 	return 0
 }
 
-type buildPendingOutput struct {
-	FileName string
-	Text     string
-}
-
 // emitDeclarations runs tsgo's standard declaration emitter for the program.
 // tsgo's MarkLinkedReferences pass can nil-panic on some cross-module reference
 // shapes (e.g. a nestia.config.ts that calls NestFactory.create, compiled by the
@@ -275,6 +239,16 @@ func runCheck(args []string) int {
 	return runBuild(append([]string{"--noEmit"}, args...))
 }
 
+// Diagnostic is one transform error: its file, line and column when known, its code, and its message.
+//
+// @evidence contracts/common.md#principled-implementation The record carries what the diagnostic line and the compiler envelope need, and a zero line marks a diagnostic without a position.
+// @evidence contracts/common.md#clear-and-simple-design A five-field record with one formatting method.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The values come from the transforms that report them.
+// @evidence contracts/common.md#meaningful-documentation The comment names the fields and the meaning of an absent position.
+// @evidence contracts/portability.md#os-neutral-implementation File holds the compiler supplied native source path; formatting delegates native relative-path conversion to filepath.Rel instead of treating it as a URL.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This record defines data rather than choosing a processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This record does not coordinate computations across consumers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A diagnostic record stores a path and message; the reporting command owns the collection lifetime.
 type Diagnostic struct {
 	File    string
 	Line    int
@@ -283,6 +257,16 @@ type Diagnostic struct {
 	Message string
 }
 
+// String formats the diagnostic as `file:line:column - error TS(code): message`, with the file made relative to `cwd` when possible, and without the position when the line is unknown.
+//
+// @evidence contracts/common.md#principled-implementation The path is made relative with `filepath.Rel` and the position part is printed only for a positive line, which is the same shape as every other nestia and typia diagnostic.
+// @evidence contracts/common.md#clear-and-simple-design One function with two format strings.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The shape is the protocol that ttsc reads from stderr, not a test-specific format.
+// @evidence contracts/common.md#meaningful-documentation The comment states the two formats and the relative path rule.
+// @evidence contracts/portability.md#os-neutral-implementation filepath.Rel represents native path differences, including cross-volume failure which keeps the original path. The position format is diagnostic protocol text.
+// @evidence contracts/performance.md#efficient-algorithms Relative path calculation and formatting are linear in path and message 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 Only the formatted string is returned; no file or writer is opened.
 func (d Diagnostic) String(cwd string) string {
 	file := d.File
 	if rel, err := filepath.Rel(cwd, file); err == nil {
@@ -294,6 +278,16 @@ func (d Diagnostic) String(cwd string) string {
 	return fmt.Sprintf("%s - error TS(%s): %s", file, d.Code, d.Message)
 }
 
+// WriteTypiaTransformDiagnostics writes each diagnostic on its own line to the writer, with files relative to `cwd`.
+//
+// @evidence contracts/common.md#principled-implementation Each diagnostic is written by its own `String`, one per line in the given order, so the output is the concatenation of the formatted diagnostics.
+// @evidence contracts/common.md#clear-and-simple-design One loop over one formatter.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It writes what it is given, without filtering or reordering.
+// @evidence contracts/common.md#meaningful-documentation The comment states the format and the ordering.
+// @evidence contracts/portability.md#os-neutral-implementation Each diagnostic uses filepath.Rel for native paths and writes through io.Writer; no shell or executable spelling is assembled.
+// @evidence contracts/performance.md#efficient-algorithms Each diagnostic is formatted and written once; work is linear in diagnostic count and total text 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 The writer is caller-owned and remains open; the function retains no diagnostic collection after returning.
 func WriteTypiaTransformDiagnostics(out io.Writer, diagnostics []Diagnostic, cwd string) {
 	for _, diag := range diagnostics {
 		fmt.Fprintln(out, diag.String(cwd))

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

@@ -1,8 +1,6 @@
 package transform
 
 import (
-	"fmt"
-
 	shimast "github.com/microsoft/typescript-go/shim/ast"
 	shimchecker "github.com/microsoft/typescript-go/shim/checker"
 	shimprinter "github.com/microsoft/typescript-go/shim/printer"
@@ -44,7 +42,13 @@ func nestiaCoreHttpQuerifyProgrammer(prog *driver.Program, ec *shimprinter.EmitC
 		Type:       typ,
 	})
 	if result.Success == false {
-		panic(fmt.Errorf("failed to analyze query-string metadata: %d error(s)", len(result.Errors)))
+		panic(nativecontext.TransformerError_from(struct {
+			Code   string
+			Errors []nativecontext.TransformerError_MetadataFactory_IError
+		}{
+			Code:   "nestia.core.TypedQueryRoute",
+			Errors: nestiaCoreMetadataErrors(result.Errors),
+		}))
 	}
 	statements := []*shimast.Node{
 		nativefactories.StatementFactory.Constant(nativefactories.StatementFactory_ConstantProps{
@@ -62,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")))
@@ -149,12 +151,28 @@ func nestiaCoreHttpValidateQuerifyProgrammer(prog *driver.Program, importer *nat
 			Name:  "query",
 			Value: nestiaCoreHttpQuerifyProgrammer(prog, ec, typ),
 		}),
+		// the object is validated, then querified: validating the
+		// URLSearchParams against the object type found every property absent
 		nativefactories.StatementFactory.Constant(nativefactories.StatementFactory_ConstantProps{
-			Name:  "output",
-			Value: nestiaCoreCall("query", nestiaCoreFactory.NewIdentifier("input")),
+			Name:  "result",
+			Value: nestiaCoreCall("validate", nestiaCoreFactory.NewIdentifier("input")),
 		}),
 		nestiaCoreFactory.NewReturnStatement(nestiaCoreFactory.NewAsExpression(
-			nestiaCoreCall("validate", nestiaCoreFactory.NewIdentifier("output")),
+			nestiaCoreFactory.NewConditionalExpression(
+				nestiaCoreFactory.NewPropertyAccessExpression(
+					nestiaCoreFactory.NewIdentifier("result"),
+					nil,
+					nestiaCoreFactory.NewIdentifier("success"),
+					shimast.NodeFlagsNone,
+				),
+				nil,
+				nestiaCoreFactory.NewObjectLiteralExpression(nestiaCoreFactory.NewNodeList([]*shimast.Node{
+					nestiaCoreProperty("success", nestiaCoreFactory.NewKeywordExpression(shimast.KindTrueKeyword), ec),
+					nestiaCoreProperty("data", nestiaCoreCall("query", nestiaCoreFactory.NewIdentifier("input")), ec),
+				}), false),
+				nil,
+				nestiaCoreFactory.NewIdentifier("result"),
+			),
 			nativefactories.TypeFactory.Keyword("any"),
 		)),
 	})
@@ -174,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(