ttsc 0.30.4 → 0.31.0

package/internal/graph/build.go

@@ -8,11 +8,23 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// Build walks the program's workspace source files and records a node for
-// each top-level declaration. The checker can load a dependency's raw `.ts`
+// Build walks the program's workspace source files and records modeled
+// declarations, members and nested closures. The checker can load a dependency's raw `.ts`
 // entry, so IsWorkspaceSourceFile owns the declaration boundary instead of
 // assuming every non-declaration source is authored here. External boundary
 // leaves enter the graph only as the resolved target of an edge (see Resolve).
+// A loaded non-nil Program is required and its generation must remain stable
+// during the build. SourceFiles may first apply pending linked hooks; their
+// latched failure remains in Program diagnostics rather than this return value.
+//
+// @evidence contracts/common.md#principled-implementation Declarations are indexed before checker-resolved relations, so every workspace endpoint uses one Program's symbols and identities.
+// @evidence contracts/common.md#clear-and-simple-design The complete build delegates to BuildFiles with nil selection and releases scratch state at one completion boundary.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler APIs determine declarations and relationships; no model-specific source pattern or expected graph answer is substituted.
+// @evidence contracts/common.md#meaningful-documentation The native comment identifies the producing Program and complete-build responsibility; separated tags follow the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms Work scales with resident source ASTs, emitted facts and repeated enclosing-container traversals; memoized resolution avoids repeating checker lookups.
+// @evidence contracts/performance.md#reuse-equivalent-work Per-build AST resolution, doc-host and edge identity maps share equivalent work only within this immutable Program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned graph retains emitted facts without a population cap; releaseBuildState drops the explicitly build-only AST-keyed and endpoint scratch fields, while the caller owns the graph and Program lifetimes and other aliases.
+// @evidence contracts/portability.md#os-neutral-implementation Build delegates native source-name classification and the compiler-reported case policy to BuildFiles. Program.SourceFiles may execute pending linked hooks, whose native effects belong to that owner; this wrapper does not prove per-directory physical identity.
 func Build(prog *driver.Program) *Graph {
   return BuildFiles(prog, nil, nil)
 }
@@ -26,6 +38,20 @@ func Build(prog *driver.Program) *Graph {
 // asks the new checker only about its invalidated closure instead of walking
 // every declaration again, while cross-file targets retain the exact stable IDs
 // established by the preceding committed generation.
+// The caller supplies a loaded non-nil Program and serializes mutation of its
+// generation and the borrowed base index during the build. Selection uses exact
+// compiler FileName strings, not native alias discovery or case-normalization of
+// the supplied selection. Even a partial build enumerates all resident source
+// files in both passes before limiting declaration and relation work.
+//
+// @evidence contracts/common.md#principled-implementation Selected workspace files supply replacement facts while committed base nodes resolve unchanged cross-file endpoints without mutating the previous generation.
+// @evidence contracts/common.md#clear-and-simple-design Selection and base-node context extend the same build pipeline instead of a second graph implementation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The invalidation owner supplies selected paths; no heuristic file quota, cooldown or fixture exception weakens the replacement set.
+// @evidence contracts/common.md#meaningful-documentation The native comment states partial ownership and committed endpoint reuse, applying documentation-skill spacing to these acknowledgments.
+// @evidence contracts/performance.md#efficient-algorithms Selection indexing and both resident-file enumerations include filename hashing and text classification. Selected files receive declaration and multiple relation traversals, checker resolution and enclosing-container work; endpoint lookup includes key bytes rather than population-only constant cost.
+// @evidence contracts/performance.md#reuse-equivalent-work The supplied committed map reuses unchanged endpoints and build-local memoization reuses checker answers within the replacement Program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Source-list copies, selection and build maps scale with resident/selected populations without a cap. releaseBuildState drops borrowed base-node and explicit scratch fields; emitted facts, ExportedTargets and ImplementationSources remain caller-owned in the returned graph.
+// @evidence contracts/portability.md#os-neutral-implementation Native filename classification and the compiler's reported UseCaseSensitiveFileNames policy are retained, without certifying physical per-directory equivalence. Exact FileName selection is caller-supplied; pending linked-hook native effects remain with Program.SourceFiles.
 func BuildFiles(prog *driver.Program, selected []string, baseNodes map[string]*Node) *Graph {
   selectedFiles := map[string]bool{}
   if selected != nil {
@@ -34,6 +60,7 @@ func BuildFiles(prog *driver.Program, selected []string, baseNodes map[string]*N
     }
   }
   g := &Graph{
+    pathCaseInsensitive:   !prog.TSProgram.UseCaseSensitiveFileNames(),
     Nodes:                 map[string]*Node{},
     bodyNodes:             map[string]bool{},
     seen:                  map[edgeKey]struct{}{},
@@ -63,13 +90,13 @@ func BuildFiles(prog *driver.Program, selected []string, baseNodes map[string]*N
 // finished with it.
 //
 // Every map cleared here is documented build-only, and each holds pointers into
-// the compiler AST or into the preceding generation”'s nodes: resolved is keyed
+// the compiler AST or into the preceding generation's nodes: resolved is keyed
 // by *shimast.Node, docHosts holds one per documented declaration, and baseNodes
 // is the whole prior endpoint index. A consumer that retains the returned Graph
-// therefore pinned all of it for as long as it held the graph — and
+// would otherwise pin all of it for as long as it held the graph —
 // internal/graphsymbols retains one for the lifetime of an editor session
 // between invalidations, closing the Program while the maps that reference its
-// AST live on. Clearing them here rather than at that consumer is what keeps the
+// AST live on. Clearing them here rather than at that consumer keeps the
 // decision with the producer, which is the only side that knows which fields are
 // scratch.
 //
@@ -90,7 +117,16 @@ func (g *Graph) releaseBuildState() {
 
 // SourceTexts maps every program source to the resident checker text.
 // Declaration and virtual bundled files are included because external graph
-// leaves still carry facts and spans the source manifest must attest to.
+// leaves still carry facts and spans. A pending linked-plugin dispatch runs first; its error is latched by Program and not returned through this text-only API.
+//
+// @evidence contracts/common.md#principled-implementation Text comes from resident SourceFiles, including dependencies needed to ground external evidence, rather than a later disk snapshot.
+// @evidence contracts/common.md#clear-and-simple-design One map exposes Program-owned text without reimplementing file loading.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Text extraction does not reread disk or substitute fixture sources. Pending linked hooks can run first and change the Program; returned text alone does not certify their success or a concurrently stable generation.
+// @evidence contracts/common.md#meaningful-documentation Native prose describes resident-source completeness and ownership, separated from tags under the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms After any first linked-hook dispatch and its callback/context costs, one loaded-file pass builds a map with filename hashing. Source text strings are shared, not recopied by content; delegated hook work is not bounded by file count.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This extraction does not coordinate repeated requests; its Program owner decides when a generation's text map can be reused.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The uncapped returned map and shared source/filename strings transfer to the caller; no Program pointer is stored in the map. Program owns linked state and callbacks, whose independently retained references are not released by this extraction.
+// @evidence contracts/portability.md#os-neutral-implementation Reported compiler filenames are preserved without native alias resolution. Pending linked callbacks can perform native work; this adapter does not certify path identity or hook effects.
 func SourceTexts(prog *driver.Program) map[string]string {
   if prog == nil || prog.TSProgram == nil {
     return map[string]string{}
@@ -113,6 +149,15 @@ func SourceTexts(prog *driver.Program) map[string]string {
 // files. It is the partial-build counterpart of SourceTexts: selected graph
 // shards still receive exact evidence and signatures, without walking or
 // retaining every unchanged source body again.
+//
+// @evidence contracts/common.md#principled-implementation Exact selected filename strings filter resident compiler text after pending linked-hook dispatch. No disk reread occurs in extraction, but callbacks and concurrent caller mutation are not certified by the returned map.
+// @evidence contracts/common.md#clear-and-simple-design A selection map adapts SourceTexts' ownership rule for shard producers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Caller-selected paths determine inclusion; no source content heuristic or diagnostic expectation affects the text.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains selected-source coverage and snapshot ownership with documentation-skill paragraph and tag spacing.
+// @evidence contracts/performance.md#efficient-algorithms A selection set and one whole resident-file pass include filename hashing/comparison bytes and output growth, plus any first linked-hook callback/context work. Selection does not bound delegated work or avoid enumeration of unchanged sources.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This function extracts a caller-owned generation view and does not own reuse across requests.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The uncapped selection set is call-local and output map/shared strings transfer to the caller. Program owns linked state and independently retained callbacks; output selection is not their reclamation policy.
+// @evidence contracts/portability.md#os-neutral-implementation Selection uses exact reported filename spelling, not physical alias or per-directory case equivalence. Pending linked callbacks retain their own native boundary responsibilities.
 func SourceTextsForFiles(prog *driver.Program, files []string) map[string]string {
   if prog == nil || prog.TSProgram == nil {
     return map[string]string{}
@@ -154,20 +199,11 @@ func collectStatements(g *Graph, path string, statements []*shimast.Node) {
     case shimast.KindFunctionDeclaration:
       addNode(g, path, statement, NodeFunction)
       // A function declared inside a function is still a name the runtime calls.
-      // This was off for a while on the theory that a closure is implementation,
-      // and implementation is read from the file — but Vue's renderer chain lives
-      // inside `baseCreateRenderer`, so `patch`, `mountElement` and
-      // `setupRenderEffect` were not implementation detail the index could skip;
-      // they were the flow the index exists to describe, and the graph had a blank
-      // where they belong. Asked how a state change reaches the DOM, a model spent
-      // three calls hunting for a name the graph did not hold.
-      //
-      // The cost is small and the answer is not bigger: the graph grows 3% in
-      // nodes on Vue and 5% on VS Code, and the tour payload does not change by a
-      // byte, because a closure ranks below the surface it hangs under and never
-      // takes a seed. It answers when asked for by name. Measured on the
-      // specific-flow lane: 59% of baseline tokens saved to 82%, and the calls
-      // halve — TypeORM 5 to 1, VS Code 8 to 2, Vue 6 to 2.
+      // Much of the ecosystem writes its engine as closures inside a factory
+      // (Vue's renderer chain lives inside `baseCreateRenderer`), so skipping
+      // them would leave a blank where the flow the index exists to describe
+      // sits. A closure ranks below the surface it hangs under and never takes a
+      // tour seed; it answers when asked for by name.
       //
       // The bodies stay out. A closure is a node with edges, not source text.
       collectClosures(g, path, statement)
@@ -218,9 +254,8 @@ func collectVariables(g *Graph, path string, statement *shimast.Node) {
 // the ecosystem writes its engine: Vue's `patch`, `mountElement`, and
 // `setupRenderEffect` are locals of `baseCreateRenderer`; a curried validator's
 // real parse is a local of the function that binds its error class. Recording only
-// what a file declares at its top level left that code out of the graph entirely —
-// a model asking how a state change reaches the DOM found the factory, nothing
-// under it, and went to read the files.
+// what a file declares at its top level would leave that code out of the graph
+// entirely.
 //
 // Only functions are recorded. A local `const i = 0` is a value, not a place code
 // runs, and the graph would drown in them.
@@ -249,8 +284,18 @@ func collectClosures(g *Graph, path string, declaration *shimast.Node) {
 // It reports false when any enclosing function is anonymous. An `inner` declared
 // inside two different callbacks of one file would otherwise key the same id and
 // merge into a node that is neither, fabricating edges between unrelated scopes.
-// Such a closure stays out of the graph, exactly as every body-scoped declaration
-// did before.
+// Such a closure stays out of the graph.
+// The supplied closure must be non-nil and belong to a stable compiler AST;
+// this helper does not validate or freeze its symbols and parent links.
+//
+// @evidence contracts/common.md#principled-implementation Lexical binding and enclosing callable identity distinguish local closures without source offsets or unstable counters.
+// @evidence contracts/common.md#clear-and-simple-design Owner and binding helpers compose one declaration identity, returning presence separately from the resulting string.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler AST binding determines supported closures; unnamed callbacks are not fabricated from fixture text.
+// @evidence contracts/common.md#meaningful-documentation Native prose states named-local scope and positional stability, following the documentation skill's prose/tag separation.
+// @evidence contracts/performance.md#efficient-algorithms Cost includes AST ancestor and binding-wrapper walks, qualified symbol-container recursion and text checks. Each enclosing owner prefixes the accumulated string again, so allocation/copy work includes intermediate names rather than only the final length.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This identity helper does not coordinate consumers; callers reuse indexed closure nodes within the graph generation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only a result string is returned; no AST or cache is retained.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation ClosureName computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func ClosureName(closure *shimast.Node) (string, bool) {
   symbol := closure.Symbol()
   if symbol == nil {
@@ -322,7 +367,7 @@ func ownerName(declaration *shimast.Node) (string, bool) {
 func bindingOf(fn *shimast.Node) *shimast.Node {
   for parent := fn.Parent; parent != nil; parent = parent.Parent {
     switch parent.Kind {
-    case shimast.KindVariableDeclaration:
+    case shimast.KindVariableDeclaration, shimast.KindPropertyAssignment:
       return parent
     case shimast.KindAsExpression,
       shimast.KindSatisfiesExpression,
@@ -342,6 +387,19 @@ func bindingOf(fn *shimast.Node) *shimast.Node {
 //
 // A binding that holds no function is not one. A local `const i = 0` is a value,
 // not a place code runs.
+// This returns syntactic candidates; ClosureName separately admits their symbol
+// and enclosing-owner names. Unrecognized anonymous callable nodes do not stop
+// this walk. The caller supplies a non-nil declaration and stable AST and owns
+// the returned slice and its borrowed AST references.
+//
+// @evidence contracts/common.md#principled-implementation The AST walk selects supported closure syntax inside the owning body and stops at each selected candidate; symbol and enclosing-name admission remain with ClosureName.
+// @evidence contracts/common.md#clear-and-simple-design One local collector supplies both declaration indexing and relation attribution with the same closure membership.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Native AST kinds and binding syntax determine selection without parsed-text approximations.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains body scope and nested-closure ownership, with tags separated under the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms The recursive child walk stops at selected closure candidates; callable-variable classification additionally unwraps initializer expressions. Work and stack/slice allocation include visited AST depth, wrapper checks and selected population, not a constant traversal bound.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This collection does not own cross-phase caching; Build's immutable AST and indexed nodes establish generation-level reuse.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Recursion depth and the returned candidate slice have no explicit cap. The caller owns the slice and borrowed AST references, keeps their generation valid while using them and releases them when no longer needed; this helper retains no separate cache or native handle.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation ClosuresIn computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func ClosuresIn(declaration *shimast.Node) []*shimast.Node {
   body := functionBody(declaration)
   if body == nil {
@@ -365,6 +423,15 @@ func ClosuresIn(declaration *shimast.Node) []*shimast.Node {
 
 // IsClosure reports whether a node inside a function body is a function the graph
 // records: a nested function declaration, or a binding that holds a function.
+//
+// @evidence contracts/common.md#principled-implementation Within the caller's function-body walk, function declarations and variables with callable bodies are the constructs eligible for closure indexing.
+// @evidence contracts/common.md#clear-and-simple-design Kind selection and the shared functionBody helper classify one AST node; lexical ownership remains with ClosuresIn.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Closure classification follows AST ownership, not fixture naming or graph ranking requirements.
+// @evidence contracts/common.md#meaningful-documentation Native prose defines the nested callable distinction and its use in boundary handling, with documentation-skill spacing.
+// @evidence contracts/performance.md#efficient-algorithms Kind dispatch is constant time; a variable's initializer unwrap follows only its local wrapper depth with constant temporary space.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate does not coordinate repeated operations or retain a classification cache.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No state or native resource is acquired.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IsClosure computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func IsClosure(node *shimast.Node) bool {
   switch node.Kind {
   case shimast.KindFunctionDeclaration:
@@ -412,6 +479,10 @@ func functionBody(declaration *shimast.Node) *shimast.Node {
     if binding := declaration.AsVariableDeclaration(); binding != nil {
       return functionBodyOfInitializer(binding.Initializer)
     }
+  case shimast.KindPropertyAssignment:
+    if binding := declaration.AsPropertyAssignment(); binding != nil {
+      return functionBodyOfInitializer(binding.Initializer)
+    }
   }
   return nil
 }
@@ -499,6 +570,7 @@ func putDeclaredNode(g *Graph, path, name string, kind NodeKind, declaration *sh
     ID:           id,
     Name:         name,
     Simple:       simpleName(declaration.Symbol()),
+    HasSimple:    declaration.Symbol() != nil,
     Kind:         kind,
     File:         path,
     Pos:          declaration.Pos(),
@@ -622,20 +694,27 @@ func isPropertyMember(kind shimast.Kind) bool {
 // symbol.Parent is the class/interface symbol, set by the binder for every
 // member.
 func methodName(symbol *shimast.Symbol) string {
-  if symbol == nil || symbol.Name == "" || symbol.Parent == nil || symbol.Parent.Name == "" {
+  if symbol == nil || symbol.Parent == nil || symbol.Parent.Name == "" {
     return ""
   }
   return qualifiedName(symbol)
 }
 
 // simpleName is the unqualified declared name of a symbol with no owner prefix,
-// the same form qualifiedName uses for the trailing member. A constructor's
-// internal-name prefix (\xFE) is escaped to "__" so the two agree.
+// the same form qualifiedName uses for the trailing member. Only an actual
+// private declaration loses its binder counter; public literal names can contain
+// the same text. A constructor's internal-name prefix (\xFE) becomes "__".
 func simpleName(symbol *shimast.Symbol) string {
   if symbol == nil || symbol.Name == "" {
     return ""
   }
-  return stripPrivateMangling(strings.ReplaceAll(symbol.Name, "\xFE", "__"))
+  name := strings.ReplaceAll(symbol.Name, "\xFE", "__")
+  for _, declaration := range symbol.Declarations {
+    if declared := declaration.Name(); declared != nil && declared.Kind == shimast.KindPrivateIdentifier {
+      return stripPrivateMangling(name)
+    }
+  }
+  return name
 }
 
 // stripPrivateMangling removes the checker's per-run counter from the name of a
@@ -643,15 +722,15 @@ func simpleName(symbol *shimast.Symbol) string {
 //
 // A `#field` is bound under a mangled name — `__#41@#field` — whose number comes
 // from a counter that advances as the program is bound, so the same field is
-// `__#41@#field` in one run and `__#38@#field` in the next. That counter reached
-// the node id, and with it the wire: on VS Code, 661 nodes and 661 edges changed
-// identity between two dumps of the *same unedited source*. A handle the model
-// was given could name nothing after a restart, and no dump could be compared to
-// another to prove a change had left the facts alone.
+// `__#41@#field` in one run and `__#38@#field` in the next. Left in the node id
+// that counter would reach the wire: the same unedited source would produce
+// different identities in two dumps, a handle given out in one session would
+// name nothing after a restart, and no two dumps could be compared to prove a
+// change had left the facts alone.
 //
 // The number identifies nothing a reader can use — the class already
 // distinguishes the field, and `#field` is what the source calls it. Dropping it
-// makes the id a function of the code again.
+// keeps the id a function of the code.
 func stripPrivateMangling(name string) string {
   const prefix = "__#"
   start := strings.Index(name, prefix)
@@ -677,10 +756,15 @@ func stripPrivateMangling(name string) string {
 // returned unchanged, which keeps every existing top-level node id stable. A
 // constructor's internal-name prefix (\xFE) is escaped to "__".
 func qualifiedName(symbol *shimast.Symbol) string {
-  name := simpleName(symbol)
-  if name == "" {
+  if symbol == nil {
     return ""
   }
+  for _, declaration := range symbol.Declarations {
+    if name, ok := objectDeclarationName(declaration); ok {
+      return name
+    }
+  }
+  name := simpleName(symbol)
   if prefix := containerPrefix(symbol); prefix != "" {
     return prefix + "." + name
   }

package/internal/graph/build_files_reuses_committed_cross_file_endpoints_test.go

@@ -9,21 +9,27 @@ import (
 
 // TestBuildFilesReusesCommittedCrossFileEndpoints verifies partial extraction
 // resolves selected-file facts against, but does not re-emit, the preceding
-// generation's unchanged declaration index.
+// full build's declaration index from the same unchanged Program.
 //
 // A member implementation edge is the boundary case: resolving the base class
 // alone is insufficient because the edge targets the base member node. If a
 // partial builder sees only its replacement file, that member disappears unless
 // the committed endpoint index participates in checker resolution. Conversely,
-// emitting the base and unrelated nodes again would turn a file edit back into
-// a whole-project graph replacement.
+// emitting the base and unrelated nodes again would violate this selected-file
+// extraction's output boundary. No edit or committed shard replacement runs.
 //
 //  1. Compile a base interface, one implementation and an unrelated source.
 //  2. Build the complete generation, then rebuild only the implementation file
 //     against its node index.
 //  3. Require the implementation/member facts and cross-file edge while
 //     rejecting re-emission of the base and unrelated nodes.
+//
+// @evidence contracts/testing.md#behavioral-verification BuildFiles selects impl.ts using the same Program's full-build nodes as its base index, emits Impl.run and its implements member relation to Base.run, and emits no node from base.ts or unrelated.ts.
+// @evidence contracts/testing.md#independent-expectations The method names, implements relation and forbidden file membership are authored expectations. File paths come from the loaded Program, and method IDs use the owning nodeID formatter, so ID grammar and filename reporting are not independently certified.
+// @evidence contracts/testing.md#distinguishing-cases Compile a base interface, one implementation and an unrelated source; Build the complete generation, then rebuild only the implementation file against its node index; Require the implementation/member facts and cross-file edge while rejecting re-emission of the base and unrelated nodes.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native temporary project, constructs and closes a driver compiler Program in-process, then calls Build and BuildFiles directly. A restored empty linked-plugin manifest excludes ambient hooks; no consumer installation or native product command is used.
 func TestBuildFilesReusesCommittedCrossFileEndpoints(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), `{
   "compilerOptions": {

package/internal/graph/build_keeps_source_distributed_dependencies_at_the_external_boundary_test.go

@@ -16,7 +16,13 @@ import (
 // 1. Load one workspace source that imports a raw TypeScript package entry.
 // 2. Assert only the referenced dependency symbol becomes an external leaf.
 // 3. Assert provenance retains the dependency source text without its facts.
+//
+// @evidence contracts/testing.md#behavioral-verification TestBuildKeepsSourceDistributedDependenciesAtTheExternalBoundary proves a package whose public entry is raw TypeScript remains a referenced leaf rather than becoming authored graph content. The resident source text is retained as provenance evidence even though its declarations are not walked.
+// @evidence contracts/testing.md#independent-expectations The authored dep-src fixture expects an external dependencyValue, no dependencyInternal node, a non-external workspaceValue with a value-call to dependencyValue, and the exact two-function source text in SourceTexts. Node IDs are taken from the returned named nodes, so their grammar is not independently certified.
+// @evidence contracts/testing.md#distinguishing-cases Load one workspace source that imports a raw TypeScript package entry; Assert only the referenced dependency symbol becomes an external leaf; Assert provenance retains the dependency source text without its facts.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native project/package fixture, constructs and closes a driver compiler Program in-process, then directly calls Build and SourceTexts. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer or native product command is used.
 func TestBuildKeepsSourceDistributedDependenciesAtTheExternalBoundary(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), `{
   "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },
@@ -62,8 +68,11 @@ export function workspaceValue(): number { return dependencyValue() + 1; }
   }
 
   dependencyTextRetained := false
-  for file := range SourceTexts(program) {
+  for file, text := range SourceTexts(program) {
     if strings.Contains(filepath.ToSlash(file), "/node_modules/dep-src/") {
+      if text != "export function dependencyValue(): number { return 1; }\nexport function dependencyInternal(): number { return dependencyValue(); }\n" {
+        t.Fatalf("resident dependency text differs from the authored fixture: %q", text)
+      }
       dependencyTextRetained = true
       break
     }

package/internal/graph/build_records_a_node_per_top_level_declaration_test.go

@@ -23,19 +23,25 @@ const fixtureTSConfig = `{
 `
 
 // TestBuildRecordsANodePerTopLevelDeclaration verifies that Build records one
-// graph node for each kind of top-level declaration, keyed by its
-// position-invariant id, and classifies workspace source as non-external.
+// graph node for each of six authored top-level declaration kinds and
+// classifies those workspace nodes as non-external.
 //
 // It pins the declaration-to-node mapping the rest of the graph is laid over: a
-// missing kind here is an edge with no endpoint later. driver.SourceFiles drops
-// declaration files, so every node must report External=false.
+// missing kind here would leave an expected endpoint absent. Build filters
+// declaration files before collecting these authored source declarations.
 //
 //  1. Compile a fixture with a function, class, interface, type alias, enum, and
 //     const declaration.
 //  2. Build the graph.
 //  3. Assert exactly those six nodes exist with the right kind and name, none
 //     marked external.
+//
+// @evidence contracts/testing.md#behavioral-verification Build returns exactly six non-module nodes for the authored declaration names and kinds, each non-external. No source-position change is performed.
+// @evidence contracts/testing.md#independent-expectations The six literal pairs fn/function, Cls/class, Iface/interface, Alias/type-alias, En/enum and value/variable must match the non-module population and non-external classification. IDs use the owning nodeID formatter and the Program-reported path, so ID grammar and position invariance are not independently certified.
+// @evidence contracts/testing.md#distinguishing-cases Compile a fixture with a function, class, interface, type alias, enum, and const declaration; Build the graph; Assert exactly those six nodes exist with the right kind and name, none marked external.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native temporary project, constructs and closes a driver compiler Program in-process, and calls Build directly. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer or native product command is used.
 func TestBuildRecordsANodePerTopLevelDeclaration(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
   writeFile(t, filepath.Join(root, "src", "main.ts"), `export function fn(): void {}

package/internal/graph/build_releases_the_scratch_it_no_longer_reads_test.go

@@ -9,17 +9,13 @@ import (
 )
 
 // TestBuildReleasesTheScratchItNoLongerReads verifies that a returned Graph
-// carries only what a consumer reads, and still carries what the shard path
-// reads after the call.
+// releases its unexported reference fields after full and partial construction,
+// while retaining the asserted public graph collections and expansion maps.
 //
-// Every field asserted nil below is documented build-only and holds pointers
-// into the compiler AST or into the preceding generation's nodes. They used to
-// survive the build, so a consumer retaining the Graph pinned all of it —
-// internal/graphsymbols keeps one for the lifetime of an editor session between
-// invalidations, closing the Program while the maps referencing its AST live on.
-// Measured on this repository's own packages, holding the Graph after closing
-// the Program retained 38.1 MB for @ttsc/lint, 52.5 MB for ttsc, and 58.2 MB for
-// @ttsc/graph; releasing the scratch brings those to 3.7, 5.0, and 4.0 MB.
+// Build-only reference fields can retain AST pointers, borrowed endpoint nodes,
+// or text/index scratch. Reflection checks that this returned Graph no longer
+// holds those field references; it does not measure collection, other owners,
+// editor lifetimes, or retained public graph content.
 //
 // The assertion is structural rather than a heap measurement on purpose: a
 // megabyte threshold is a flaky test, while "the producer stopped holding it" is
@@ -29,7 +25,13 @@ import (
 //  2. Assert every build-only field is released.
 //  3. Assert the two fields the shard expansion reads after the call, and the
 //     graph itself, are not.
+//
+// @evidence contracts/testing.md#behavioral-verification Full Build and selected-file BuildFiles return graphs with every unexported map, slice or pointer field nil, while the asserted public graph collections and expansion maps remain populated or allocated.
+// @evidence contracts/testing.md#independent-expectations The expectation is structural and exact rather than a heap measurement: found by reflection, every unexported map, slice or pointer field of the returned Graph must be nil after both a complete Build and a partial BuildFiles, ExportedTargets and ImplementationSources must remain non-nil, and Nodes, Edges and DocTags must be non-empty. The test cannot tell whether a released field was truly unreferenced elsewhere.
+// @evidence contracts/testing.md#distinguishing-cases Full and partial construction contrast, with the partial call borrowing a non-nil base index. Both must release private reference fields and retain public output; empty private fields alone cannot let an empty partial result pass.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native temporary project, constructs and closes a driver compiler Program in-process, and directly calls Build and BuildFiles. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer, native product command, heap measurement, or forced garbage collection is used.
 func TestBuildReleasesTheScratchItNoLongerReads(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), `{
   "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },
@@ -55,10 +57,8 @@ export function run(store: Store): void { store.save() }
   g := Build(prog)
   assertScratchReleased(t, g, "complete build")
 
-  // The partial build is not a second case of the same thing: `baseNodes` and
-  // `selectedFiles` are nil on arrival in a complete build, so a complete build
-  // alone cannot fail on them. `baseNodes` is the largest of the nine and the
-  // one #1243 flagged as the caution, because it is passed in rather than built.
+  // The partial call borrows a non-nil baseNodes index, unlike the full call.
+  // Both calls also allocate their own selected-file map.
   var mainFile string
   for _, node := range g.Nodes {
     mainFile = node.File
@@ -69,6 +69,13 @@ export function run(store: Store): void { store.save() }
   }
   partial := BuildFiles(prog, []string{mainFile}, g.Nodes)
   assertScratchReleased(t, partial, "partial build")
+  if partial.ExportedTargets == nil || partial.ImplementationSources == nil {
+    t.Error("partial build released its public expansion maps")
+  }
+  if len(partial.Nodes) == 0 || len(partial.Edges) == 0 || len(partial.DocTags) == 0 {
+    t.Fatalf("partial graph is empty: %d nodes, %d edges, %d tags",
+      len(partial.Nodes), len(partial.Edges), len(partial.DocTags))
+  }
 
   // The negative twin. Clearing scratch must not clear what the shard expansion
   // in cmd/ttscgraph/serve_shards.go reads after BuildFiles returns.
@@ -109,7 +116,7 @@ func assertScratchReleased(t *testing.T, g *Graph, label string) {
     }
     if !value.Field(index).IsNil() {
       t.Errorf(
-        "%s: %s survived; it pins the AST for as long as a consumer holds the graph",
+        "%s: %s survived as a private reference field in the returned graph",
         label,
         field.Name,
       )

package/internal/graph/decorators.go

@@ -7,6 +7,15 @@ import (
 // DecoratorArgument is one argument written on a decorator. Literal holds the
 // statically-resolved value when the argument is a string or boolean literal
 // and is nil otherwise.
+//
+// @evidence contracts/common.md#principled-implementation An optional literal distinguishes statically read string/boolean values from arguments whose runtime meaning the graph does not evaluate.
+// @evidence contracts/common.md#clear-and-simple-design A single payload keeps convention interpretation with the consumer instead of introducing an evaluator in the graph.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The representation contains no convention-specific decorator dispatch or foreign mutation.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the supported literal kinds and nil meaning, with documentation-skill spacing before tags.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This argument record chooses no computation strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The record does not coordinate computation across consumers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The consumer owns this data record's lifetime; it owns no resource acquisition or release.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type DecoratorArgument struct {
   Literal any
 }
@@ -15,6 +24,15 @@ type DecoratorArgument struct {
 // consumer can interpret a decorator convention (`@Controller('users')`,
 // `@Get(':id')`) without re-parsing source. Target is the id of the graph node
 // the decorator is applied to; Pos/End bound the decorator for evidence.
+//
+// @evidence contracts/common.md#principled-implementation Written decorator identity, ordered arguments and byte spans preserve syntax facts independently of convention semantics.
+// @evidence contracts/common.md#clear-and-simple-design One target-associated record separates source facts from the consumer's decorator interpretation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No particular framework or expected decorator answer is encoded in this shape.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains target identity, literal interpretation boundaries and source spans under the documentation skill.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This declaration represents collected facts rather than selecting a traversal algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Reuse is owned by the graph generation that contains these facts.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record has no independent cache or handle lifecycle.
+// @evidence contracts/portability.md#os-neutral-implementation File and the path-bearing Target preserve reported compiler spelling until dump projection; this record does not resolve native aliases or authenticate physical source identity.
 type Decorator struct {
   Target    string
   Name      string

package/internal/graph/decorators_capture_name_and_literal_arguments_test.go

@@ -8,10 +8,9 @@ import (
 )
 
 // TestDecoratorsCaptureNameAndLiteralArguments verifies that collectDecorators
-// records each decorator on a class and on its methods with the convention name
-// and the statically-resolved literal arguments, attributed to the decorated
-// node — the facts a consumer reads to interpret a decorator convention without
-// re-parsing source.
+// records the two authored class/method decorator names and string arguments
+// on their expected target nodes, while an undecorated method has no fact.
+// It does not execute decorators or a consumer's convention interpretation.
 //
 // A convention's value lives in the decorator's literal argument, so the test
 // pins both axes a consumer depends on: the decorator name (`Controller`,
@@ -26,7 +25,13 @@ import (
 //  3. Assert a Decorator targets the class with name "Controller" / literal
 //     "users", one targets the method with name "Get" / literal ":id", and the
 //     undecorated method has no fact.
+//
+// @evidence contracts/testing.md#behavioral-verification Build exposes matching Controller and Get facts on the expected class/method targets with one string argument each, and no decorator fact targets the plain method.
+// @evidence contracts/testing.md#independent-expectations The decorator names and string values users and :id are authored literals. The first matching fact is checked, not duplicate-fact absence; target IDs use nodeID and the Program-reported path, so their grammar is not independently certified.
+// @evidence contracts/testing.md#distinguishing-cases Compile a controller-shaped fixture with @Controller("users") on the class and @Get(":id") on one method, plus an undecorated method, using local decorator factories so the program type-checks with no dependency; Build the graph; Assert a Decorator targets the class with name "Controller" / literal "users", one targets the method with name "Get" / literal ":id", and the undecorated method has no fact.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native temporary project, constructs and closes a driver compiler Program in-process, and calls Build without emitting or executing the decorators. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer or native product command is used.
 func TestDecoratorsCaptureNameAndLiteralArguments(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
   writeFile(t, filepath.Join(root, "src", "main.ts"), `function Controller(prefix: string): any {

package/internal/graph/diagnostics.go

@@ -2,19 +2,32 @@ package graph
 
 import "github.com/samchon/ttsc/packages/ttsc/driver"
 
-// FileDiagnostics returns the resident program's compiler diagnostics for the
-// source file at path, with the code tsgo reports and the location the driver
+// FileDiagnostics filters the resident Program's driver diagnostics by exact
+// reported File spelling, with a compiler code where supplied and the location the driver
 // resolves (see Diagnostic: authored-relative under a source preamble). Because
 // the graph rides the already-open Program, this is one Program.Diagnostics()
-// call over the warm checker, not a second compile.
+// call, not a second Program construction. Native diagnostic stages can still
+// perform previously uncomputed checker work before this filter runs.
 //
-// This is the compiler-only slice: it carries the TypeScript semantic
-// diagnostics, not @ttsc/lint or transform-plugin findings.
+// This does not execute @ttsc/lint or collect transform findings independently.
+// Program.Diagnostics includes staged compiler findings and any latched linked
+// hook failure; an empty path selects fileless findings, including nil-Program
+// errors. The filter neither canonicalizes paths nor proves physical alias identity.
 //
 // This is the per-file view. The dump publishes the whole-program view through
-// NewDiagnostics, which groups and relativizes the same driver.Diagnostic values
-// in one pass; prefer it when every file is wanted, because filtering per file
-// here rescans the program's diagnostics once per call.
+// NewDiagnostics, which projects the same driver.Diagnostic values before the
+// shared dump mapper relativizes their paths. Prefer one whole-program acquisition
+// when every file is wanted; this filter reacquires the complete diagnostic result
+// once per call.
+//
+// @evidence contracts/common.md#principled-implementation Exact reported File equality filters the current Program.Diagnostics result, preserving matching fileless and latched-failure entries rather than authenticating physical alias equivalence or compiler-only origin.
+// @evidence contracts/common.md#clear-and-simple-design This per-file adapter leaves diagnostic acquisition to Program and whole-generation projection to NewDiagnostics.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No separate lint/transform execution or expected diagnostic is injected; matching driver failures keep their existing origin and meaning.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain reported spelling, fileless scope, staged acquisition and repeated per-file work under the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms Each call includes Program's native staged queries, conversion/sort work and full result allocation before filename-byte comparison and matching-slice growth; filtering population alone is not the total cost.
+// @evidence contracts/performance.md#reuse-equivalent-work Program owns any reusable native diagnostic state; this adapter constructs no second Program but neither caches the complete converted result nor guarantees every native query is already warm.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Complete delegated diagnostics and matching output coexist without a result cap. Returned records may reference resident AST/source objects; the caller owns their lifetime and the Program, while this filter retains no separate cache or checker lease.
+// @evidence contracts/portability.md#os-neutral-implementation The filter preserves and compares driver-reported native File spelling without separator rewriting, cwd anchoring or symlink/case alias discovery; diagnostic coordinate conversion remains with Program.
 func FileDiagnostics(prog *driver.Program, path string) []driver.Diagnostic {
   out := make([]driver.Diagnostic, 0)
   for _, diagnostic := range prog.Diagnostics() {