ttsc 0.30.4 → 0.31.0

package/internal/graph/dump.go

@@ -9,7 +9,7 @@ import (
 )
 
 // dump.go projects a built graph onto the JSON wire contract `ttscgraph dump`
-// prints: the IGraphDump shape the @ttsc/graph engine loads (and the 3D viewer
+// prints: the ITtscGraphDump shape the @ttsc/graph engine loads (and the 3D viewer
 // reduces). The internal Node/Edge model stays narrow (so the resident MCP path
 // is untouched); the richer schema is produced here:
 //
@@ -24,18 +24,28 @@ import (
 //
 // Structural derivations the schema also defines (file nodes, contains/exports
 // edges) are left to the TypeScript loader, which has the node set in hand and
-// is where the redesign keeps that logic.
+// is where that logic lives.
 
 // DumpEvidence is a 1-based source span grounding a node declaration or an edge
-// expression. It is display/expansion only, never identity.
+// expression. Columns count UTF-8 bytes from the ECMA line start, not UTF-16
+// code units or display cells. It is display/expansion only, never identity.
 //
 // File is omitted when the reader reconstructs it exactly: a node's span is in
 // the node's file, and an ordinary edge's span is in the file its `from` id
 // names. Cross-file assigned implementations keep the actual evidence file. The
-// path is long, it rode the wire once per node and once per edge, and on VS Code
-// those two copies are 55 MB of a 323 MB document that then has to be encoded,
-// piped, parsed and validated. An `implementation` span keeps its file — that one
+// path is long and would otherwise ride the wire once per node and once per
+// edge, on a document that then has to be encoded, piped, parsed and validated.
+// An `implementation` span keeps its file — that one
 // can genuinely live in another file from the declaration that owns it.
+//
+// @evidence contracts/common.md#principled-implementation One-based line/column spans ground displayed facts while optional File preserves the owner-reconstructible versus cross-file distinction.
+// @evidence contracts/common.md#clear-and-simple-design The wire record carries location evidence independently from node identity.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Optional file omission is a reconstructible schema rule rather than a project-specific payload shortcut.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state one-based ECMA lines, UTF-8 byte columns, optional file reconstruction and implementation spans under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation File is a portable dump coordinate, never an OS-wide case-folded identity inferred by this record.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This span container selects no coordinate algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The dump context owns reusable line indices.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The enclosing payload owns this span's lifetime.
 type DumpEvidence struct {
   File      string `json:"file,omitempty"`
   StartLine int    `json:"startLine"`
@@ -46,12 +56,30 @@ type DumpEvidence struct {
 
 // DumpDecoratorArgument is one decorator argument; Literal is set only for a
 // statically-resolved string or boolean literal.
+//
+// @evidence contracts/common.md#principled-implementation Optional Literal preserves only the statically supported decorator argument facts without asserting runtime evaluation.
+// @evidence contracts/common.md#clear-and-simple-design One wire field mirrors the internal argument boundary.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The record encodes no framework-specific argument inference.
+// @evidence contracts/common.md#meaningful-documentation Native prose defines literal availability and supported value kinds under the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation A JSON decorator value has no native path or process boundary.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Projection owns computation, not this payload record.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This value coordinates no repeated computation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Its enclosing dump owns storage lifetime.
 type DumpDecoratorArgument struct {
   Literal any `json:"literal,omitempty"`
 }
 
 // DumpDecorator is a decorator as written on a declaration, carried on its
 // target node for a consumer to interpret.
+//
+// @evidence contracts/common.md#principled-implementation The written name and ordered literal arguments preserve convention facts without selecting a framework meaning.
+// @evidence contracts/common.md#clear-and-simple-design Target association is supplied by the enclosing node instead of repeated in this nested record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No convention-specific expected endpoint is fabricated.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains written syntax and consumer interpretation, with documentation-skill tag spacing.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Decorator syntax data has no filesystem or process identity.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This nested payload does not choose collection or projection algorithms.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing generation owns shared fact reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The enclosing node payload owns these values' lifetime.
 type DumpDecorator struct {
   Name      string                  `json:"name"`
   Arguments []DumpDecoratorArgument `json:"arguments"`
@@ -61,6 +89,15 @@ type DumpDecorator struct {
 // the declaration it was written on. `name` is the tag without its `@` and
 // `text` is everything after it, joined into one line. Neither is interpreted:
 // which part of a text names a thing belongs to whichever convention wrote it.
+//
+// @evidence contracts/common.md#principled-implementation Name and normalized text preserve unknown-tag facts without assigning citation meaning to the text.
+// @evidence contracts/common.md#clear-and-simple-design Node nesting supplies ownership while this record carries only the convention's written data.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No handpicked evidence or reference convention changes this general tag record.
+// @evidence contracts/common.md#meaningful-documentation Native prose defines the absent @ prefix, joined text and uninterpreted semantics under the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Tag text is convention data, not a native path interpreted here.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This wire container selects no parsing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The snapshot owns reused tag facts.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record owns no acquisition or release lifecycle.
 type DumpDocTag struct {
   Name string `json:"name"`
   Text string `json:"text,omitempty"`
@@ -70,14 +107,33 @@ type DumpDocTag struct {
 // and the value it carries. `value` is omitted for a member the checker could
 // not fold to a constant — the name still stands, and the name is what a caller
 // asking about the enum came for.
+//
+// @evidence contracts/common.md#principled-implementation Required Name preserves even the empty-string enum name; optional Value means the checker could not establish a constant value.
+// @evidence contracts/common.md#clear-and-simple-design The ordered member record supplies enum outlines without additional graph identities.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No initializer text guessing or expected enum value is encoded.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains caller-visible name and optional constant value, with documentation-skill tag separation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Enum names and values carry no native boundary.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The record selects no folding or rendering algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Snapshot owners control fact reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The enclosing node owns storage lifetime.
 type DumpEnumMember struct {
   Name  string `json:"name"`
   Value string `json:"value,omitempty"`
 }
 
 // DumpObjectMember is one direct object-literal member carried on its variable
-// node. Line and Signature are rendered from the same Program-owned source text
-// as the node evidence, so the outline cannot race a later disk write.
+// node. Line and Signature use the caller-supplied text map shared with node
+// evidence, without reopening disk. The caller must bind that map to the AST
+// generation and keep both stable; this record does not authenticate that bind.
+//
+// @evidence contracts/common.md#principled-implementation Static member identity is separate from snapshot-rendered line/signature data that may be unavailable without source text.
+// @evidence contracts/common.md#clear-and-simple-design A direct-member outline remains nested on its owning variable rather than duplicating declaration nodes.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No dynamic spread member or source-derived expected name is manufactured.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains direct membership, shared supplied text and caller-owned generation binding under the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This source-syntax outline has no native filesystem identity.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Rendering and traversal belong to the dump context.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The container coordinates no computation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Its parent node payload owns retention.
 type DumpObjectMember struct {
   Name      string `json:"name"`
   Kind      string `json:"kind"`
@@ -87,18 +143,28 @@ type DumpObjectMember struct {
 
 // DumpNode is the wire shape of a graph node. Lowercase json keys are the
 // contract; the Go field names are not.
+//
+// @evidence contracts/common.md#principled-implementation Required simple Name, optional qualified identity, source evidence and distinct artifact containment express the existing wire schema without inlining function bodies.
+// @evidence contracts/common.md#clear-and-simple-design Display facts remain separate from identity and implementation evidence; the TypeScript loader owns synthesized declaration containment.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No MCP response cap, consumer fixture or guessed body boundary is represented as a graph fact.
+// @evidence contracts/common.md#meaningful-documentation Native member comments explain signature boundaries, artifact-only Parent and lowercase JSON ownership, using documentation-skill spacing.
+// @evidence contracts/portability.md#os-neutral-implementation File and span paths use the shared portable mapper while symbol names and artifact addresses keep their own protocol identity.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This wire container selects no projection algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing snapshot owns reuse of these facts.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The payload contains no independent handle or cache lifecycle.
 type DumpNode struct {
   ID            string `json:"id"`
   Kind          string `json:"kind"`
   Name          string `json:"name"`
   QualifiedName string `json:"qualifiedName,omitempty"`
-  // Signature is the declaration head, cut where the compiler says the body
-  // opens. A consumer that reconstructed it by scanning physical lines both
-  // leaked implementation text when a declaration shared its line with its body
-  // and stopped early when the head itself contained a brace — a type-literal
-  // parameter, an object return type, a destructured parameter. Neither is a
-  // guess the consumer can win, so the producer renders it here.
-  Signature     string             `json:"signature,omitempty"`
+
+  // Signature is an optional outline rendered from the supplied text using a
+  // bounded AST-selected cut. The helper finds the earliest modeled arrow,
+  // block, object/array literal or class-expression boundary; it does not prove
+  // that every cut is the declaration's own body opening or its complete head.
+  // Missing text or an unusable boundary leaves this field empty.
+  Signature string `json:"signature,omitempty"`
+
   File          string             `json:"file"`
   External      bool               `json:"external"`
   Ignored       bool               `json:"ignored,omitempty"`
@@ -108,11 +174,13 @@ type DumpNode struct {
   Literals      []string           `json:"literals,omitempty"`
   EnumMembers   []DumpEnumMember   `json:"enumMembers,omitempty"`
   ObjectMembers []DumpObjectMember `json:"objectMembers,omitempty"`
+
   // Parent is the artifact containing this one, and is empty for every
   // declaration: a declaration's containment is synthesized by the TypeScript
   // memory layer, and two producers of one relation would put two answers in
   // the graph.
-  Parent         string          `json:"parent,omitempty"`
+  Parent string `json:"parent,omitempty"`
+
   Evidence       *DumpEvidence   `json:"evidence,omitempty"`
   Implementation *DumpEvidence   `json:"implementation,omitempty"`
   Decorators     []DumpDecorator `json:"decorators,omitempty"`
@@ -121,6 +189,15 @@ type DumpNode struct {
 
 // DumpEdge is the wire shape of a graph edge. Lowercase json keys are the
 // contract; the Go field names are not.
+//
+// @evidence contracts/common.md#principled-implementation Directed wire endpoints and refined relationship kind remain distinct from optional source evidence.
+// @evidence contracts/common.md#clear-and-simple-design One relationship record carries only facts needed by the receiving graph loader.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No synthetic ranking relationship or expected path is encoded.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies the wire shape and JSON-key contract, with documentation-skill tag separation.
+// @evidence contracts/portability.md#os-neutral-implementation Parsed symbol IDs use shared path projection, including path-valued module names; opaque or unparsed IDs remain reported strings. This container neither resolves native aliases nor authenticates physical endpoints.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Projection owns ordering and mapping algorithms.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The graph generation owns relationship reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The enclosing dump owns retained storage.
 type DumpEdge struct {
   From     string        `json:"from"`
   To       string        `json:"to"`
@@ -128,44 +205,74 @@ type DumpEdge struct {
   Evidence *DumpEvidence `json:"evidence,omitempty"`
 }
 
-// Dump is the IGraphDump envelope: the project it was built for, the evidence
+// Dump is the ITtscGraphDump envelope: the project it was built for, the evidence
 // about the program that produced it, and the full node and edge sets with none
 // of the MCP response caps.
+//
+// @evidence contracts/common.md#principled-implementation Supplied facts, provenance and diagnostics carry the producer's generation claims; the container does not authenticate their common acquisition or completeness. Capabilities distinguish claimed collection from absent evidence.
+// @evidence contracts/common.md#clear-and-simple-design The envelope groups snapshot proof and uncapped facts without mixing serve-protocol controls into the body schema.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Complete facts are not replaced by sample nodes or MCP response limits.
+// @evidence contracts/common.md#meaningful-documentation Native member paragraphs explain generation provenance and empty diagnostic semantics, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Project reports the shared projection base and native paths use its protocol coordinates, subject to best-effort alias and supplied case-policy limits; opaque artifact addresses retain separate identity.
+// @evidenceExclude contracts/performance.md#efficient-algorithms NewDump owns projection cost rather than this envelope type.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Session owners establish whether this snapshot may be reused.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns the completed payload's lifetime.
 type Dump struct {
   Project  string `json:"project"`
   Tsconfig string `json:"tsconfig"`
-  // Provenance proves the rest of this dump came from one Program. It rides the
-  // body rather than the serve envelope so a dump written to a file by the
-  // one-shot command keeps its evidence, and so a consumer holding only the
-  // parsed dump never has to ask where it came from.
+
+  // Provenance carries the producer's capture claims in the body so file output
+  // retains them. Consumers must validate those claims; this field does not by
+  // itself prove a common Program or artifact acquisition.
   Provenance Provenance `json:"provenance"`
-  // Diagnostics are the compiler's findings for the same program generation
-  // that produced Nodes and Edges. Empty means the program had none, not that
-  // they were not collected; the producer states that in its capabilities.
+
+  // Diagnostics contains reported driver findings, including fileless failures.
+  // Empty is meaningful as collected-empty only under a valid producer capture
+  // and declared diagnostic capability, not merely because this slice is empty.
   Diagnostics []Diagnostic `json:"diagnostics"`
-  Nodes       []DumpNode   `json:"nodes"`
-  Edges       []DumpEdge   `json:"edges"`
+
+  Nodes []DumpNode `json:"nodes"`
+  Edges []DumpEdge `json:"edges"`
 }
 
 // DumpFacts is the path-normalized fact payload of one graph shard. It omits
 // project-wide provenance and diagnostics so an incremental producer can
 // project one invalidated closure without reconstructing a complete Dump.
+//
+// @evidence contracts/common.md#principled-implementation One shard's nodes and outgoing edges are separated from project-wide provenance and diagnostics that require a generation owner.
+// @evidence contracts/common.md#clear-and-simple-design The smaller payload supports actual partial graph replacement without rebuilding a full envelope.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The intended shard producer uses BuildFiles selection rather than response caps; this payload does not enforce how its supplied graph population was obtained.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains intentionally omitted project-wide fields and incremental responsibility, with documentation-skill tag spacing.
+// @evidence contracts/portability.md#os-neutral-implementation Shard facts share the complete dump's portable path and evidence representation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The projection operation chooses the algorithm, not this container.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The resident shard store owns unchanged-shard reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns retention and replacement of this payload.
 type DumpFacts struct {
   Nodes []DumpNode `json:"nodes"`
   Edges []DumpEdge `json:"edges"`
 }
 
 // DumpOrigin is the snapshot evidence a caller attaches to a dump: who built it
-// and what the same program generation had to say about the code. It is a
-// separate struct because only the commands that own a compiler session can
-// produce it, while the graph projection below is pure.
+// and reported driver findings. Compiler-session owners must bind these inputs
+// to one acquisition, but arbitrary callers can construct this record too.
+// Projection does not reacquire compiler findings; its native path mapping is
+// separate from that acquisition and does not authenticate the origin.
+//
+// @evidence contracts/common.md#principled-implementation Caller-supplied provenance and diagnostics require a common capture established by the producer; this input record and subsequent projection do not independently certify it.
+// @evidence contracts/common.md#clear-and-simple-design Origin facts are explicit inputs; projection does not query live compiler state, although its shared path mapper can perform native resolution.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts NewDump stamps the schema version; this input does not authorize guessed capabilities or reconstructed disk provenance.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes caller-owned acquisition from projection/native path resolution and explains supplied diagnostics under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Captured physical paths are deliberately retained until the shared dump mapper projects them together.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This input record chooses no snapshot acquisition algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The session owner establishes reuse validity.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The input container owns no independent retention or handle lifecycle.
 type DumpOrigin struct {
-  // Provenance identifies the producing program. NewDump always stamps the
-  // schema version itself, so a caller cannot publish a wrong one.
+  // Provenance reports the producing program. NewDump stamps its schema version
+  // regardless of this input, but does not authenticate the other fields.
   Provenance Provenance
 
-  // Diagnostics are the compiler findings for the producing generation, or nil
-  // when the caller did not collect them.
+  // Diagnostics are supplied driver findings. Nil carries no findings and does
+  // not itself prove whether collection occurred.
   Diagnostics []Diagnostic
 }
 
@@ -173,9 +280,20 @@ type DumpOrigin struct {
 // root of the portable path coordinate; ignored is the git-ignored source set
 // (nil for a non-git project); sources maps a source file's physical path to its
 // text so byte spans become line/col evidence (nil omits evidence); origin is
-// the snapshot evidence that proves where the facts came from. It returns an
-// error before serialization when a path is on another filesystem root or two
-// physical sources would collide at one wire identity.
+// caller-supplied provenance and diagnostics, not independently authenticated by
+// this projector. A non-nil graph and stable supplied data are required. It
+// returns an error before serialization for detected cross-root or identity
+// collisions under the mapper's case policy and best-effort native path answers;
+// successful projection is not a physical snapshot or filesystem freeze.
+//
+// @evidence contracts/common.md#principled-implementation Facts and supplied provenance/diagnostics pass through one mapper's collision checks; source spans use supplied text, while this projector neither authenticates origin nor freezes native identity or graph payloads.
+// @evidence contracts/common.md#clear-and-simple-design Shared newDumpFacts performs projection; this envelope adapter stamps producer schema and normalizes mandatory arrays before publication.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Collision and cross-root failures stop publication instead of emitting guessed coordinates or quietly dropping inconvenient nodes.
+// @evidence contracts/common.md#meaningful-documentation Native prose states supplied-data ownership, project base, optional inputs and the mapper's pre-serialization checks and identity limits, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Virtual and native paths share the mapper's compiler-reported case policy, with exact spelling for standalone graphs. Native alias resolution is best-effort, may inspect ancestors and may retain lexical spelling; the mapper does not certify per-directory case behavior or observation-time identity.
+// @evidence contracts/performance.md#efficient-algorithms Projection includes node/edge and provenance/diagnostic text-key sorts, all member/tag/decorator payloads, source-line construction, repeated trivia/signature scans and span lookups. Cached path mapping still includes path bytes and native ancestor resolution on misses; population-only sorting and coordinate lookup bounds are not the full cost.
+// @evidence contracts/performance.md#reuse-equivalent-work One dump context shares raw path mapping, physical aliases and per-source line indices across facts, diagnostics and provenance for this immutable snapshot.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Mapping, line indices, grouping and output arrays scale without a payload cap. Local caches become unreachable after the call, but returned fields may borrow original literal/member payloads; the caller owns their shared lifetimes and immutability. Projection failure returns no partial Dump, without reclaiming caller inputs or publishing bytes.
 func NewDump(g *Graph, project, tsconfig string, ignored map[string]bool, sources map[string]string, origin DumpOrigin) (Dump, error) {
   facts, ctx, err := newDumpFacts(g, project, ignored, sources)
   if err != nil {
@@ -226,13 +344,25 @@ func NewDump(g *Graph, project, tsconfig string, ignored map[string]bool, source
 // dump path/evidence codec. The caller may pass a partial graph produced by
 // BuildFiles; no project-wide provenance, diagnostic walk or full Dump is
 // constructed.
+// The graph must be non-nil and supplied facts/text remain stable during the
+// call. Returned literal payloads may share the graph's original values; this
+// projection does not freeze native identity or deep-copy every fact.
+//
+// @evidence contracts/common.md#principled-implementation A partial graph uses the same identity and evidence codec as a full graph without pretending it carries project-wide origin facts.
+// @evidence contracts/common.md#clear-and-simple-design One shared projection function supplies the actual shard payload rather than constructing and trimming a full Dump.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No response cap or guessed diagnostic omission changes shard fact identity.
+// @evidence contracts/common.md#meaningful-documentation Native prose describes partial-build input and absent project-wide work, with documentation-skill tag spacing.
+// @evidence contracts/portability.md#os-neutral-implementation Shard coordinates retain the graph's reported case policy; shared best-effort native alias mapping may retain lexical spelling and rejects detected cross-root or identity-collision failures without certifying observation-time physical identity.
+// @evidence contracts/performance.md#efficient-algorithms Shared projection includes node/edge text-key sorting, member/tag/decorator payloads, path-byte hashing and native ancestor resolution on cache misses, source line construction and repeated trivia/signature scans for emitted spans; it omits project-wide provenance and diagnostic work.
+// @evidence contracts/performance.md#reuse-equivalent-work The shard-local context shares path and line-index results among all emitted facts; unchanged shard reuse belongs to its resident caller.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Uncapped mapping, grouping, line-index and output arrays scale with the supplied graph. Local caches become unreachable after return; the caller owns returned arrays and shared original literal payload lifetimes and keeps those borrowed values stable.
 func NewDumpFacts(g *Graph, project string, ignored map[string]bool, sources map[string]string) (DumpFacts, error) {
   facts, _, err := newDumpFacts(g, project, ignored, sources)
   return facts, err
 }
 
 func newDumpFacts(g *Graph, project string, ignored map[string]bool, sources map[string]string) (DumpFacts, *dumpContext, error) {
-  ctx := newDumpContext(project, sources)
+  ctx := newDumpContext(project, sources, !g.pathCaseInsensitive)
 
   // Decorators ride on their target node; group by the internal node id before
   // ids are relativized for output.
@@ -381,6 +511,18 @@ func objectMemberWireKind(kind NodeKind) string {
 
 // MarshalDump serializes a built graph to the export JSON, indented when pretty.
 // See NewDump for the parameters.
+// Native JSON marshaling buffers the full value and copies the returned bytes;
+// pretty marshaling additionally builds indented bytes. This byte-returning
+// adapter appends no protocol newline and acquires no output writer.
+//
+// @evidence contracts/common.md#principled-implementation NewDump's identity projection checks precede JSON encoding; formatting preserves the supplied facts without authenticating snapshot origin or adding a protocol newline.
+// @evidence contracts/common.md#clear-and-simple-design One byte-returning adapter delegates graph semantics to NewDump and encoding to encoding/json.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Encoding failures propagate rather than substituting expected JSON or suppressing invalid paths.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies byte serialization and indentation; the referenced input contract remains documented by NewDump under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation This adapter preserves NewDump's portable coordinate rules and propagates its native-boundary errors.
+// @evidence contracts/performance.md#efficient-algorithms Projection includes NewDump's native/text/payload costs. JSON encoding includes map-key text sorting, full-value buffering and returned-byte copying; pretty output additionally scans and allocates indented bytes.
+// @evidence contracts/performance.md#reuse-equivalent-work Graph projection shares its per-snapshot indices; this adapter does not retain encoded results across changed generations.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Projection and encoded/copy/optional indentation buffers scale without a payload cap; the standard encoder pool may retain capacity. Returned bytes belong to the caller, and this adapter retains no own result cache or native handle.
 func MarshalDump(g *Graph, project, tsconfig string, ignored map[string]bool, sources map[string]string, origin DumpOrigin, pretty bool) ([]byte, error) {
   d, err := NewDump(g, project, tsconfig, ignored, sources, origin)
   if err != nil {
@@ -392,14 +534,24 @@ func MarshalDump(g *Graph, project, tsconfig string, ignored map[string]bool, so
   return json.Marshal(d)
 }
 
-// EncodeDump writes the export JSON straight to w, one buffered pass, ending it
+// EncodeDump projects and JSON-encodes the graph to w, ending the encoded value
 // with the newline the one-shot protocol expects.
 //
-// The alternative is what the dump command used to do: marshal the whole
-// document into a byte slice, convert that slice into a string, and print the
-// string. On VS Code the document is 323 MB, so the conversion was a second full
-// copy of it held live beside the first — half a gigabyte of peak heap that
-// bought nothing, because the bytes were already exactly what stdout wanted.
+// The standard JSON encoder builds the complete encoded value in memory before
+// writing it; pretty output also uses an indentation buffer. The 1 MiB bufio
+// writer batches I/O rather than bounding payload memory, and may reuse an
+// already larger supplied bufio.Writer. This avoids an additional caller-created
+// string conversion but is not incremental JSON serialization. Write failures
+// may leave partial output; the caller owns the writer and its close lifecycle.
+//
+// @evidence contracts/common.md#principled-implementation NewDump's checked identity projection is encoded to the supplied writer with a trailing newline; encoding, write and final-flush errors propagate without certifying complete publication after failure.
+// @evidence contracts/common.md#clear-and-simple-design Projection stays in NewDump and standard buffered JSON encoding avoids an additional caller string-output pipeline without promising incremental serialization.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Buffer size is an I/O batching constant, not a fact cap; no expected payload or foreign writer behavior is patched.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain full-value/indentation buffering, the I/O buffer's distinct role and writer ownership, with documentation-skill tag separation.
+// @evidence contracts/portability.md#os-neutral-implementation The caller supplies the writer; portable graph identities and native mapping errors are preserved from NewDump without shell output quoting.
+// @evidence contracts/performance.md#efficient-algorithms NewDump owns projection, mapping and sorting costs. JSON encoding includes map-key text sorting and the full value's bytes; pretty output additionally scans and buffers indented bytes before native writer/flush work.
+// @evidence contracts/performance.md#reuse-equivalent-work The projection context shares equivalent path and source-index work; streamed bytes are effectful output and are not replayed from a cross-request cache.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Projection, full encoded value and optional indentation bytes coexist without a payload cap. The standard encoder returns its state to a pool that may retain buffer capacity; bufio may reuse caller storage. Successful encoding is flushed, while writer close, partial-output handling and retained caller buffers remain caller-owned.
 func EncodeDump(w io.Writer, g *Graph, project, tsconfig string, ignored map[string]bool, sources map[string]string, origin DumpOrigin, pretty bool) error {
   dump, err := NewDump(g, project, tsconfig, ignored, sources, origin)
   if err != nil {
@@ -465,7 +617,7 @@ func wireEdgeKind(kind EdgeKind, origin string) string {
 // A node without a recorded simple name (a future virtual node) falls back to
 // the last dot-separated segment.
 func nodeNames(n *Node) (simple, qualified string) {
-  if n.Simple == "" {
+  if n.Simple == "" && !n.HasSimple {
     if dot := strings.LastIndex(n.Name, "."); dot >= 0 {
       return n.Name[dot+1:], n.Name
     }
@@ -486,9 +638,9 @@ type dumpContext struct {
   lines   map[string]lineStarts
 }
 
-func newDumpContext(project string, sources map[string]string) *dumpContext {
+func newDumpContext(project string, sources map[string]string, caseSensitive ...bool) *dumpContext {
   return &dumpContext{
-    paths:   newDumpPathMapper(project),
+    paths:   newDumpPathMapper(project, caseSensitive...),
     sources: sources,
     lines:   map[string]lineStarts{},
   }
@@ -577,8 +729,8 @@ func (c *dumpContext) declarationSignature(n *Node) string {
   return strings.TrimSpace(text[pos:end])
 }
 
-// objectMemberSignature reproduces the compact outline details has historically
-// returned, but slices it from Program-owned text while the dump is built
+// objectMemberSignature reproduces the compact outline `details` returns, but
+// slices it from Program-owned text while the dump is built
 // instead of reopening the live file later.
 func (c *dumpContext) objectMemberSignature(file string, member ObjectMember) string {
   pos, end := member.Pos, member.SignatureEnd
@@ -600,9 +752,6 @@ func (c *dumpContext) objectMemberSignature(file string, member ObjectMember) st
   if pos >= end {
     return ""
   }
-  if pos >= end {
-    return ""
-  }
   signature := strings.TrimSuffix(compactObjectMemberSignature(text[pos:end]), ",")
   const maxObjectMemberSignatureRunes = 160
   runes := []rune(signature)

package/internal/graph/dump_checkout_paths_are_stable_test.go

@@ -20,15 +20,22 @@ const portableDumpTSConfig = `{
 }
 `
 
-// TestDumpCheckoutPathsAreStable verifies the whole dump-identity consequence
-// surface, not only the path helper.
+// TestDumpCheckoutPathsAreStable compares complete serialized dumps for two
+// authored checkout roots after clearing only Project, with selected literal
+// path assertions. It does not cover every path spelling or platform boundary.
 //
 //  1. Build the same project plus sibling .ts/.d.ts under two checkout roots.
 //  2. Remove only the producer-local Project locator and require byte identity.
 //  3. Assert nodes, module names, endpoints, implementation evidence,
 //     diagnostics, manifests, and universe inputs all use one `../shared`
 //     coordinate, with the .ts internal and the .d.ts an external leaf.
+//
+// @evidence contracts/testing.md#behavioral-verification Two independently loaded checkout fixtures serialize identically after clearing only Project. Literal assertions cover sibling source and declaration nodes, module naming, edge endpoint membership, injected implementation evidence, diagnostic location, provenance source and universe config/root coordinates.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: the same project built under two different checkout roots must marshal to identical JSON once only the producer-local Project field is cleared, no checkout path may appear in the JSON, and the dump must use the literal coordinate ../shared/value.ts (internal function, module node and a provenance source), ../shared/types.d.ts (external leaf) and tsconfig.json/src/main.ts roots, a TS2322 diagnostic on ../shared/value.ts, and an implementation span in ../shared/value.ts. The implementation file on the main node is injected by the test to exercise that optional path.
+// @evidence contracts/testing.md#distinguishing-cases Build the same project plus sibling .ts/.d.ts under two checkout roots; Remove only the producer-local Project locator and require byte identity; Assert nodes, module names, endpoints, implementation evidence, diagnostics, manifests, and universe inputs all use one `../shared` coordinate, with the .ts internal and the .d.ts an external leaf.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes two native project/sibling trees, constructs and closes their driver compiler Programs in-process, and directly calls Build and dump/provenance operations. A restored empty linked-plugin manifest excludes ambient hooks. Implementation coordinates are explicitly injected into the test-owned graph, not produced by an assignment transform; no consumer installation or native product command runs.
 func TestDumpCheckoutPathsAreStable(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   firstCheckout := filepath.Join(t.TempDir(), "checkout-one")
   secondCheckout := filepath.Join(t.TempDir(), "checkout-two")
   first := portableFixtureDump(t, firstCheckout)

package/internal/graph/dump_diagnostics_ride_the_generation_that_built_it_test.go

@@ -8,23 +8,22 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// TestDumpDiagnosticsRideTheGenerationThatBuiltIt verifies the dump carries the
-// compiler's findings for the same program that produced its nodes and edges,
-// relativized like every other path on the wire.
-//
-// FileDiagnostics was written, tested, and then called by nothing: its own
-// comment said "the dump and MCP results carry no diagnostics", so a consumer
-// that wanted to know whether the code it was reading even compiles had to run a
-// second compile to find out — against a program that, by then, was not this one.
-// The value of riding along is precisely that the answer belongs to this
-// snapshot; a diagnostics list assembled separately would be a different
-// program's opinion.
+// TestDumpDiagnosticsRideTheGenerationThatBuiltIt supplies findings from the
+// same compiler Program used for Build and checks one diagnostic's dump fields.
+// Omitting that supplied origin produces a non-nil empty diagnostics list.
+// This does not compare different generations or exercise a consumer request.
 //
 //  1. Build a fixture whose only file assigns a string to a number binding.
 //  2. Dump it.
 //  3. Assert the TS2322 sits in the dump, at the location tsgo reports, against
 //     a project-relative path.
+//
+// @evidence contracts/testing.md#behavioral-verification Build and NewDiagnostics use the same authored compiler Program; NewDump must retain a TS2322 with the selected location, message, severity and relative file. A second dump without supplied diagnostics must contain a non-nil empty list. Cross-generation rejection and consumer queries are not exercised.
+// @evidence contracts/testing.md#independent-expectations The string-to-number assignment has literal TS2322, line 1, column 14, error category, not assignable message fragment and src/main.ts expectations. Omitted diagnostics have literal empty-list expectations. These are supplied expectations rather than results generated from NewDump, but they do not independently authenticate the compiler's complete diagnostic output or origin.
+// @evidence contracts/testing.md#distinguishing-cases Build a fixture whose only file assigns a string to a number binding; Dump it; Assert the TS2322 sits in the dump, at the location tsgo reports, against a project-relative path.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes a native project, constructs and closes its driver compiler Program in-process, and directly calls Build, NewDump, SourceTexts and NewDiagnostics. A restored empty linked-plugin manifest excludes ambient hooks. No consumer installation or native product command runs.
 func TestDumpDiagnosticsRideTheGenerationThatBuiltIt(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 const broken: number = "nope";

package/internal/graph/dump_evidence_skips_leading_trivia_test.go

@@ -16,15 +16,21 @@ import (
 // A declaration preceded by a doc comment and a call indented under its function
 // are the two shapes that break a naive Pos->line/col: the node would land on the
 // comment line and the edge column on the indentation. The dump skips leading
-// whitespace and `//` / `/* */` comments first, so this pins both to the real
-// token start.
+// whitespace and comments first. This fixture checks one block comment and
+// one indented call; it does not cover every trivia form or evidence endpoint.
 //
 //  1. Compile a fixture where `main` carries a block doc comment and calls
 //     `helper()` indented two spaces.
 //  2. Build and marshal the dump.
 //  3. Assert the `main` node's evidence starts on the `export function main`
 //     line, and the calls edge's evidence is the indented call's line and column.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual Build and MarshalDump results must place the main declaration after its block doc comment at line 5 and the selected calls edge after indentation at line 6 column 3. Other trivia forms, node columns and end coordinates are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal source coordinates in the fixture: the main function node's evidence must start on line 5 (past its three-line doc comment), and the calls edge from src/main.ts#main:function must have evidence at line 6, column 3 (the indented helper() call).
+// @evidence contracts/testing.md#distinguishing-cases Compile a fixture where `main` carries a block doc comment and calls `helper()` indented two spaces; Build and marshal the dump; Assert the `main` node's evidence starts on the `export function main` line, and the calls edge's evidence is the indented call's line and column.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes a native project, constructs and closes its driver Program in-process, calls Build, MarshalDump and SourceTexts, and decodes actual JSON. A restored empty linked-plugin manifest excludes ambient hooks. No consumer installation or native product command runs.
 func TestDumpEvidenceSkipsLeadingTrivia(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 helper(): void {}

package/internal/graph/dump_is_a_function_of_the_source_test.go

@@ -7,22 +7,21 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// TestDumpIsAFunctionOfTheSource pins the graph to the code it describes: two
-// builds of one unedited snapshot must produce one byte-identical document.
+// TestDumpIsAFunctionOfTheSource compares the serialized results of two
+// independent loads of one unedited native project. Its two classes each have
+// a private #count, but output equality alone does not prove either private
+// member is present, collision-free or stable across a process restart.
 //
-// It did not. A private class member — `#count` — is bound under a mangled name
-// carrying a counter that advances as the program is bound: `__#41@#count` in one
-// run, `__#38@#count` 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 source*: a handle the model was given could name nothing
-// after a restart, and no dump could be compared with another to prove that a
-// change had left the facts alone — the byte test every graph optimisation is
-// supposed to answer to was itself meaningless.
+// 1. Load the same Counter private-member and Other private-member source in two independent programs.
+// 2. Build and serialize each graph without sharing a builder.
+// 3. Require byte-identical dumps for these two loads; structural facts are not asserted here.
 //
-// Two classes each declare a `#count`, so the mangling counter is exercised more
-// than once and a per-class collision would surface here rather than in a
-// three-million-line repository.
+// @evidence contracts/testing.md#behavioral-verification Two independent compiler Programs and graph builders serialize the same authored declarations to identical dump bytes.
+// @evidence contracts/testing.md#independent-expectations One unchanged fixture supplies both independent loads, so their literal equality requirement is not generated by the serializer. This oracle detects differing bytes but cannot prove structural completeness, private-member collision freedom or stability under other allocation histories.
+// @evidence contracts/testing.md#distinguishing-cases Two independently constructed Programs and builders over the same private-member fixture must agree. No edited-source, empty-output or process-restart counterpart is asserted by this entry.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes one native project and loads and closes two actual driver Programs in-process, calling Build, SourceTexts and MarshalDump directly. A restored empty linked-plugin manifest excludes ambient hooks; no consumer installation or native product command runs.
 func TestDumpIsAFunctionOfTheSource(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 class Counter {

package/internal/graph/dump_never_serializes_a_list_as_null_test.go

@@ -9,19 +9,19 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// TestDumpNeverSerializesAListAsNull verifies every list the provenance contract
-// declares reaches the wire as a list, even when the producer filled none of it.
-//
-// A nil Go slice encodes as `null`, and the TypeScript mirror types these as
-// `string[]` / `T[]`, so a nil would fail validation at the consumer rather than
-// here — and a consumer that did not validate would have to guess whether `null`
-// meant "empty" or "absent". The distinction the contract actually uses for
-// absence is `capabilities`, not the difference between `null` and `[]`, so the
-// wire must never offer the second question.
+// TestDumpNeverSerializesAListAsNull checks that the five origin list fields
+// decode as non-nil slices when the supplied origin is empty. It also rejects
+// any :null token in this fixture's compact JSON; no consumer validator runs.
 //
 //  1. Build a dump whose origin declares nothing at all.
 //  2. Assert it still parses into lists, not nulls.
+//
+// @evidence contracts/testing.md#behavioral-verification MarshalDump with empty DumpOrigin must emit no :null substring and decode non-nil capabilities, sources, universe configs, universe roots and diagnostics. This entry does not assert their lengths or validate other origin populations through a consumer.
+// @evidence contracts/testing.md#independent-expectations The expectation is the wire rule that lists are never null: marshaling a dump built with an empty DumpOrigin must contain no ':null' substring and must decode with non-nil provenance.capabilities, sources, universe.configs, universe.roots and diagnostics. A nil Go slice encoding as null fails both checks.
+// @evidence contracts/testing.md#distinguishing-cases Build a dump whose origin declares nothing at all; Assert it still parses into lists, not nulls.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes a native project, constructs and closes its compiler Program in-process, invokes Build, MarshalDump and SourceTexts, and decodes actual JSON with the standard library. A restored empty linked-plugin manifest excludes ambient hooks; no consumer installation or native product command runs.
 func TestDumpNeverSerializesAListAsNull(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 const value = 1;\n")