ttsc 0.30.3 → 0.31.0

package/internal/graph/line_model.go

@@ -4,12 +4,22 @@ import (
   "unicode/utf8"
 
   shimcore "github.com/microsoft/typescript-go/shim/core"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
 )
 
 // ECMALineStarts returns the byte offset of each logical source line. The
 // compiler is the authority for which bytes end a line, so graph evidence and
 // graph-backed LSP locations cannot drift from its LF, CRLF, CR, LS, and PS
 // coordinates.
+//
+// @evidence contracts/common.md#principled-implementation Compiler-produced ECMA line boundaries are copied into graph byte-offset coordinates without substituting a newline convention.
+// @evidence contracts/common.md#clear-and-simple-design This adapter centralizes the compiler-to-graph integer representation so consumers share the same line model.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts All supported source text uses the compiler API; no fixture-specific terminator table or foreign mutation is introduced.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains byte units and the compiler authority for line terminators, following the documentation skill's separated prose and tags.
+// @evidence contracts/performance.md#efficient-algorithms The compiler first counts LF bytes for initial capacity, then scans all ECMA terminators into its own line slice, which may grow for other terminators. This adapter allocates and copies a second integer slice; total work includes both source scans and line-count copying.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure adapter does not coordinate requests; source-snapshot owners retain its resulting line index.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Compiler and output line slices coexist during conversion and scale with the supplied line population without an adapter cap. The temporary compiler slice is call-local; the caller owns the returned index and its lifetime, with no separate retained source/cache or native handle.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation ECMALineStarts computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func ECMALineStarts(text string) []int {
   compilerStarts := shimcore.ComputeECMALineStarts(text)
   starts := make([]int, len(compilerStarts))
@@ -22,6 +32,15 @@ func ECMALineStarts(text string) []int {
 // LineEnd returns the byte offset immediately before line's terminator, or the
 // end of text for its final logical line. starts must come from ECMALineStarts
 // for the same text.
+//
+// @evidence contracts/common.md#principled-implementation The supplied index bounds one logical line and ECMA terminator widths identify its exclusive content end.
+// @evidence contracts/common.md#clear-and-simple-design One bounded scan handles all compiler terminators without allocating a substring or rebuilding the line index.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid line indices return the documented text boundary rather than manufacturing fixture-specific spans.
+// @evidence contracts/common.md#meaningful-documentation The native comment identifies byte units, final-line behavior and the same-text index precondition under the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms Index lookup is constant time and scanning costs only the selected line's byte length, with constant temporary space.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This calculation consumes a caller-owned reusable line index and creates no cross-request computation owner.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No retained state or native resource is acquired.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation LineEnd computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func LineEnd(text string, starts []int, line int) int {
   if line < 0 || line >= len(starts) {
     return len(text)
@@ -44,40 +63,40 @@ func LineEnd(text string, starts []int, line int) int {
 
 // FirstCodeOffset advances over leading whitespace and comments so a graph
 // span begins at its declaration rather than its leading trivia.
+//
+// The compiler scanner also recognizes Unicode whitespace, shebangs and
+// conflict-marker trivia. Negative offsets return zero; offsets at or past EOF
+// are returned unchanged without entering the scanner.
+//
+// @evidence contracts/common.md#principled-implementation Compiler SkipTrivia supplies the actual ECMA whitespace, comment, shebang and conflict-marker boundaries for the declaration's byte coordinate.
+// @evidence contracts/common.md#clear-and-simple-design One guarded adapter delegates lexical policy to the compiler instead of maintaining a partial parallel scanner.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The supported scanner API handles all source trivia without a declaration-banner exception or foreign parser mutation.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains the leading-trivia adjustment; tags remain separated as required by the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms The delegated scanner advances through trivia with UTF-8 decoding and bounded conflict-marker lookahead; boundary bytes may be inspected again. Work follows the scanned range without copying intermediate source text, rather than guaranteeing exactly one inspection per byte.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This span calculation does not own a request cache; its text and starting offset determine a single result.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function retains no text, indices or tasks after returning.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation FirstCodeOffset computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func FirstCodeOffset(text string, pos int) int {
   if pos < 0 {
     return 0
   }
-  for pos < len(text) {
-    width := sourceWhitespaceWidth(text, pos)
-    switch {
-    case width > 0:
-      pos += width
-    case text[pos] == '/' && pos+1 < len(text) && text[pos+1] == '/':
-      pos = LineCommentEnd(text, pos)
-    case text[pos] == '/' && pos+1 < len(text) && text[pos+1] == '*':
-      pos += 2
-      for pos+1 < len(text) && !(text[pos] == '*' && text[pos+1] == '/') {
-        _, size := utf8.DecodeRuneInString(text[pos:])
-        if size == 0 {
-          return len(text)
-        }
-        pos += size
-      }
-      if pos+1 < len(text) {
-        pos += 2
-      } else {
-        return len(text)
-      }
-    default:
-      return pos
-    }
+  if pos >= len(text) {
+    return pos
   }
-  return len(text)
+  return shimscanner.SkipTrivia(text, pos)
 }
 
 // LineCommentEnd returns the byte offset immediately after a // comment and
 // its line terminator, or len(text) when the comment reaches EOF.
+//
+// @evidence contracts/common.md#principled-implementation A forward UTF-8 scan recognizes the same ECMA terminator widths as source indexing and includes the complete terminator in its result.
+// @evidence contracts/common.md#clear-and-simple-design One shared helper gives trivia and signature compaction a common line-comment boundary.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts EOF and terminators follow source syntax without a hardcoded comment shape or parser patch.
+// @evidence contracts/common.md#meaningful-documentation The native comment defines the exclusive byte offset and EOF behavior, with documentation-skill spacing before tags.
+// @evidence contracts/performance.md#efficient-algorithms Cost is linear in this comment's bytes and temporary space is constant.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The helper computes one comment boundary and does not coordinate repeated requests.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No resources or source snapshots are retained by this calculation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation LineCommentEnd computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func LineCommentEnd(text string, start int) int {
   for i := start + 2; i < len(text); {
     if width := lineTerminatorWidth(text, i); width > 0 {

package/internal/graph/literals.go

@@ -77,17 +77,16 @@ func (g *Graph) putLiterals(checker *shimchecker.Checker, path string, statement
 //
 // The names are the half a caller writes. `literals` answers which values the
 // enum admits, the question a serializer asks, but the code says `Colors.Red`
-// and never `"red"` — so an enum whose node the graph already held still sent a
-// caller to the file to learn what to type (#738).
+// and never `"red"` — so a caller who already holds the enum's node would still
+// open the file to learn what to type.
 //
 // The list comes from the declaration, not from the declared type's
 // constituents, and that is not a detail. A type is a set, so the checker folds
 // two members carrying one value into one constituent: `enum Dup { A = 'x', B =
 // 'x' }` resolves to a single type, and reading names off it reports `A` and
-// loses `B` — the same silent under-report as #732, out of the same instinct to
-// take a declaration fact from a type. The value set really is one value, which
-// is why `literals` is right to say `"x"` once; the member list is two members,
-// and only the declaration says so.
+// loses `B`, a silent under-report from taking a declaration fact from a type.
+// The value set really is one value, which is why `literals` is right to say
+// `"x"` once; the member list is two members, and only the declaration says so.
 //
 // Each member's value still comes from the checker, per member, so an implicit
 // `First` reports 0 with nothing reading the source. A member the checker
@@ -101,7 +100,7 @@ func enumMembers(checker *shimchecker.Checker, statement *shimast.Node) []EnumMe
   out := make([]EnumMember, 0, len(declaration.Members.Nodes))
   for _, node := range declaration.Members.Nodes {
     symbol := node.Symbol()
-    if symbol == nil || symbol.Name == "" {
+    if symbol == nil {
       continue
     }
     member := EnumMember{Name: symbol.Name}

package/internal/graph/literals_are_absent_when_the_type_admits_more_than_it_can_name_test.go

@@ -8,8 +8,8 @@ import (
 )
 
 // TestLiteralsAreAbsentWhenTheTypeAdmitsMoreThanItCanName verifies the negative
-// twin of every literal case: a type whose members cannot all be named reports
-// none of them rather than the subset that can.
+// counterparts for four authored non-enumerable shapes: each reports no
+// literals, while a four-member control union has a four-entry result.
 //
 // This is what lets a present `literals` mean the whole type. `Widened` admits
 // four literals and every other string besides, and a caller cannot tell a
@@ -22,7 +22,13 @@ import (
 //  1. Compile a fixture holding each non-enumerable shape.
 //  2. Build the graph.
 //  3. Assert none of them recorded a value set.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual Build nodes for Widened, Generic, Primitive and Computed must have zero literals; the Narrow control must have four entries. The helper requires each queried node to exist. Other type shapes and control literal contents are not asserted here.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: the control union Narrow must report four values, and Widened (union with string), Generic (type parameter), Primitive (string alias) and Computed (enum with a computed member) must each report no values at all rather than a subset.
+// @evidence contracts/testing.md#distinguishing-cases Compile a fixture holding each non-enumerable shape; Build the graph; Assert none of them recorded a value set.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes a driver Program in-process and directly calls Build. Actual Program filename/shared ID formatting and literalsOf select existing nodes and their reported arrays; a restored empty linked-plugin manifest excludes ambient hooks. No compute() execution, emit, installed consumer or product process runs.
 func TestLiteralsAreAbsentWhenTheTypeAdmitsMoreThanItCanName(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"), `declare const compute: () => number;
@@ -50,9 +56,8 @@ export enum Computed {
   graph := Build(prog)
   path := sourceFile(t, prog, "main.ts").FileName()
 
-  // The control: the shapes below differ from this one by exactly the property
-  // that makes them unnameable, so an empty result there is the rule acting and
-  // not the pass failing to run on this fixture at all.
+  // A nonempty control detects omission of the entire literal pass; this count
+  // does not independently check the control's four values.
   if got := literalsOf(t, graph, nodeID(path, "Narrow", NodeTypeAlias)); len(got) != 4 {
     t.Fatalf("control union did not report its four members: got %v", got)
   }

package/internal/graph/literals_cover_enum_members_the_graph_has_no_nodes_for_test.go

@@ -10,23 +10,21 @@ import (
 
 // TestLiteralsCoverEnumMembersTheGraphHasNoNodesFor verifies that an enum
 // reports its member values, string-valued, numeric, and implicitly numbered
-// alike, however the declaration is laid out.
-//
-// An enum needed this more than a union did (#732). Its members are not nodes —
-// the build pass records member nodes for classes and interfaces only — so
-// nothing else in a details result carries them, and the old source-text scrape
-// stopped at the line holding `{`, which is the first line of every enum written
-// the ordinary way. A multi-line enum therefore reported no members at all,
-// through `literals` or otherwise, and only a single-line one answered. The
-// implicit fixture pins that the values come from the checker rather than the
-// text: nothing in `Implicit`'s source spells out 0 and 1.
+// alike, in the authored multiline, single-line and implicit fixtures.
+// The negative node check is limited to Wrapped.A with kind method; it neither
+// proves all member nodes absent nor makes literals the only enum detail field.
 //
 //  1. Compile a fixture with a multi-line string enum, a single-line one, and an
 //     enum whose members are implicitly numbered.
 //  2. Build the graph.
-//  3. Assert each reports its resolved member values, and that the enum still
-//     has no member nodes so `literals` is genuinely the only carrier.
+//  3. Assert the literal value arrays and reject one Wrapped.A method-node ID.
+//
+// @evidence contracts/testing.md#behavioral-verification Build must report ordered a/b/c string values for Wrapped, identical values for Flat, ordered 0/1 for Implicit, and no method node at Wrapped.A. This does not authenticate the acquisition algorithm or absence of all possible enum-member nodes.
+// @evidence contracts/testing.md#independent-expectations Wrapped and Implicit use literal expected arrays for authored string and implicit numeric enums. Flat equality reuses Wrapped only after its exact literal check. The single Wrapped.A method-ID negative does not cover other member names or node kinds, and implicit values are expected semantics rather than proof that only a checker could produce them.
+// @evidence contracts/testing.md#distinguishing-cases Multiline and single-line equal declarations contrast layout, while implicit numbering supplies 0/1 without explicit numeric initializers. One method-node-ID absence is the bounded negative counterpart; other enum detail fields remain permitted.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program in-process and directly calls Build and the existing-node literalsOf helper. Actual filenames/shared ID formatting select endpoints; a restored empty linked-plugin manifest excludes ambient hooks. No emit, enum execution, installed consumer or product process runs.
 func TestLiteralsCoverEnumMembersTheGraphHasNoNodesFor(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 enum Wrapped {
@@ -55,7 +53,7 @@ export enum Implicit {
   graph := Build(prog)
   path := sourceFile(t, prog, "main.ts").FileName()
 
-  // The declaration whose members the old scrape could never reach.
+  // Multiline declaration with independent literal expected values.
   wrapped := literalsOf(t, graph, nodeID(path, "Wrapped", NodeEnum))
   if want := []string{`"a"`, `"b"`, `"c"`}; !slices.Equal(wrapped, want) {
     t.Fatalf("multi-line enum under-reported its members: got %v, want %v", wrapped, want)
@@ -65,14 +63,14 @@ export enum Implicit {
   if !slices.Equal(flat, wrapped) {
     t.Fatalf("enum layout changed the value set: wrapped %v, flat %v", wrapped, flat)
   }
-  // Implicitly numbered members: the values exist only in the checker, never in
-  // the source text, so a scrape of any kind cannot produce this list.
+  // Implicitly numbered members have literal semantic expectations; no numeric
+  // initializers are written, but this does not certify the acquisition method.
   implicit := literalsOf(t, graph, nodeID(path, "Implicit", NodeEnum))
   if want := []string{"0", "1"}; !slices.Equal(implicit, want) {
     t.Fatalf("implicitly numbered enum did not report its resolved values: got %v, want %v", implicit, want)
   }
-  // The premise: no member node exists to carry these instead, so dropping
-  // `literals` for an enum would take its members out of the graph entirely.
+  // Reject this particular method-node identity; other enum detail fields and
+  // member-node spellings are not examined.
   if node, ok := graph.Nodes[nodeID(path, "Wrapped.A", NodeMethod)]; ok {
     t.Fatalf("enum member unexpectedly modeled as a node (%v); literals may no longer be the only carrier", node.ID)
   }

package/internal/graph/literals_do_not_depend_on_declaration_line_wrapping_test.go

@@ -9,25 +9,26 @@ import (
 )
 
 // TestLiteralsDoNotDependOnDeclarationLineWrapping verifies that collectLiterals
-// answers with the union's members whatever the declaration's layout: the same
+// answers with the union's members for two authored layouts: the same
 // eight-member type written one member per line and written on one line both
 // report all eight.
 //
-// This is the #732 regression. The value set used to be scraped out of the
-// declaration's first four lines of source text and cut to six, so completeness
-// was a function of line wrapping and of member count rather than of the type:
-// the wrapped form reported the three members that fit in the snippet, and the
-// flat form reported six of eight. Both cuts were silent. Eight members is the
-// boundary that pins both at once — it is past the old six-member cap, so a
-// reintroduced cap fails here on the flat twin instead of hiding behind a small
-// fixture.
+// Exact eight-value expectations reject a six-value truncation in either form;
+// output equality alone would not. Other layouts and population limits are not
+// asserted by this entry.
 //
 //  1. Compile a fixture with a wrapped union and a flat union of the same eight
 //     string literals.
 //  2. Build the graph.
 //  3. Assert both nodes carry all eight values, in source form, and that the two
 //     lists are identical.
+//
+// @evidence contracts/testing.md#behavioral-verification Build must report the exact ordered eight-value array for both authored Wrapped and Flat aliases, then their arrays must agree. The check covers these two layouts, not all declaration formatting or type populations.
+// @evidence contracts/testing.md#independent-expectations Both aliases have independent literal quoted a-through-h expected arrays; exact checks precede pair equality so two equally truncated results cannot pass. The wrapped form includes one authored trailing comment. No expected list is generated by the literal renderer.
+// @evidence contracts/testing.md#distinguishing-cases Compile a fixture with a wrapped union and a flat union of the same eight string literals; Build the graph; Assert both nodes carry all eight values, in source form, and that the two lists are identical.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program in-process and directly calls Build and the existing-node literalsOf helper. Actual filename/shared nodeID formatting select aliases, not an independent ID-grammar oracle. A restored empty linked-plugin manifest excludes ambient hooks; no emit, consumer installation or product process runs.
 func TestLiteralsDoNotDependOnDeclarationLineWrapping(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 type Wrapped =

package/internal/graph/literals_render_every_value_in_typescript_source_form_test.go

@@ -8,22 +8,22 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// TestLiteralsRenderEveryValueInTypescriptSourceForm verifies that each kind of
-// literal a union can hold reaches the wire as the way it is written, and that
-// the rendering is the checker's own rather than this package's.
-//
-// Source form is what makes the list readable as the type: it is the only
-// rendering that tells `1` from `"1"` and `true` from `"true"`, which bare
-// contents cannot, and the old string-only scrape could not report a numeric
-// union at all. The escaping fixture is why the checker's `ValueToString` is
-// used instead of a local formatter — a quote inside a value has to come back
-// escaped the way TypeScript escapes it, and Go's own quoting is not that.
+// TestLiteralsRenderEveryValueInTypescriptSourceForm checks the reported source
+// renderings of eight authored alias shapes, including selected escaped strings
+// and mixed kinds. It inspects graph facts rather than serialized wire bytes;
+// output matching does not authenticate the renderer's acquisition method.
 //
 //  1. Compile a fixture with a string, numeric, boolean, bigint, nullable, and
 //     escaped-string union.
 //  2. Build the graph.
 //  3. Assert each value set renders in TypeScript source form.
+//
+// @evidence contracts/testing.md#behavioral-verification Build's recorded literal arrays for eight authored aliases must exactly match the selected string, numeric, boolean, bigint, nullable, undefined, escaping and mixed-kind source-form expectations. Other literal values, escaping forms and wire encoding are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expectations are the literal TypeScript source renderings in the table (quoted strings, 1, true/false, 1n, null, undefined, escaped quotes and tab, and a mixed union), asserted against the node's recorded values for eight alias declarations. They are written independently of the renderer, which is the checker's ValueToString.
+// @evidence contracts/testing.md#distinguishing-cases Compile a fixture with a string, numeric, boolean, bigint, nullable, and escaped-string union; Build the graph; Assert each value set renders in TypeScript source form.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program in-process and directly calls Build and existing-node literalsOf. Actual filename/shared ID formatting select aliases; a restored empty linked-plugin manifest excludes ambient hooks. No dump serialization, TypeScript value execution, installed consumer or product process runs.
 func TestLiteralsRenderEveryValueInTypescriptSourceForm(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 type Strings = 'a' | 'b';
@@ -54,7 +54,7 @@ export type Mixed = 'a' | 1 | true;
   }{
     // A string keeps its quotes, so the list reads as the type does.
     {"Strings", []string{`"a"`, `"b"`}},
-    // Numbers were absent entirely under the string-only scrape.
+    // Numeric values remain unquoted.
     {"Numbers", []string{"1", "2", "3"}},
     {"Bools", []string{"false", "true"}},
     {"Bigints", []string{"1n", "2n"}},

package/internal/graph/literals_resolve_through_alias_indirection_test.go

@@ -9,22 +9,22 @@ import (
 )
 
 // TestLiteralsResolveThroughAliasIndirection verifies that a union assembled out
-// of other unions reports every member it admits, including the ones no token of
-// its own declaration names.
-//
-// This is the half of #732 that was not truncation but a wrong answer of the
-// right shape. Reading `type Wide = Narrow | 'd'` off the source text finds one
-// quoted token and reports `'d'`, a complete-looking three-member type reduced
-// to one, with nothing marking the loss. Only the checker has followed Narrow.
-// The nested case (`Wider = Wide | 'e'`) pins that the resolution is not one hop
-// deep, and the checker also flattens and dedups, so `Duplicated` must report
-// `'a'` once rather than twice.
+// of other unions reports the literal values of the three authored aliases.
+// One- and two-hop forms include inherited members; re-listing a requires one
+// occurrence. This does not authenticate the acquisition algorithm, deeper
+// alias handling or its cost.
 //
 //  1. Compile a fixture whose aliases build on each other, one of them
 //     re-listing a member an aliased union already has.
 //  2. Build the graph.
 //  3. Assert each alias reports the full set it admits, deduplicated.
+//
+// @evidence contracts/testing.md#behavioral-verification Build must report exact ordered literal arrays for Wide, Wider and Duplicated, retaining inherited values across the tested one/two-hop aliases and one a in the duplicate form. Other alias structures and resolution work are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: Wide (Narrow | 'd') must report a, b, c, d; Wider (Wide | 'e') must report a through e; and Duplicated (Narrow | 'a') must report a, b, c with a once, all in source-quoted form.
+// @evidence contracts/testing.md#distinguishing-cases Compile a fixture whose aliases build on each other, one of them re-listing a member an aliased union already has; Build the graph; Assert each alias reports the full set it admits, deduplicated.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program in-process and directly calls Build and existing-node literalsOf. Actual filename/shared ID formatting select the aliases; a restored empty linked-plugin manifest excludes ambient hooks. No emit, installed consumer or product process runs.
 func TestLiteralsResolveThroughAliasIndirection(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 type Narrow = 'a' | 'b' | 'c';
@@ -50,7 +50,7 @@ export type Duplicated = Narrow | 'a';
   if want := []string{`"a"`, `"b"`, `"c"`, `"d"`}; !slices.Equal(wide, want) {
     t.Fatalf("alias indirection lost members: got %v, want %v", wide, want)
   }
-  // Two hops: resolution is the type's, so depth costs nothing.
+  // Two authored hops; this result check does not measure resolution cost.
   wider := literalsOf(t, graph, nodeID(path, "Wider", NodeTypeAlias))
   if want := []string{`"a"`, `"b"`, `"c"`, `"d"`, `"e"`}; !slices.Equal(wider, want) {
     t.Fatalf("nested alias indirection lost members: got %v, want %v", wider, want)

package/internal/graph/member_relation_edges_follow_checker_validity_test.go

@@ -19,9 +19,15 @@ import (
 //  1. Compile a class implementing an interface through ordinary methods plus
 //     the two valid cross-kind shapes, and a class overriding an abstract base.
 //  2. Build the native graph.
-//  3. Assert every directly declared checker-valid pair has the correct member
-//     relation while constructors never become override edges.
+//  3. Assert the five selected member pairs have the correct relation, while
+//     the two resident constructor nodes have no tested override edge.
+//
+// @evidence contracts/testing.md#behavioral-verification The fixture must have zero actual Program diagnostics, and Build must report five literal implements/overrides pairs, including two cross-kind implementations. Both constructor nodes must exist without a member-relation edge between them. Other valid shapes, exact relation counts and spans are not asserted.
+// @evidence contracts/testing.md#independent-expectations The oracle is the TypeScript checker: the fixture is first required to have no diagnostics, then the literal pairs Implementation.run/name/callback to Contract.run/name/callback must carry origin implements (including the getter-for-readonly-property and method-for-function-property shapes) and Derived.act/property to Base.act/property must carry origin overrides, while Derived's constructor must have no member-relation edge to Base's.
+// @evidence contracts/testing.md#distinguishing-cases Ordinary methods and property overrides contrast the selected getter-for-property and method-for-function-property accepted shapes. Resident constructor nodes supply a bounded negative relation counterpart; invalid pairs are not exercised by this valid fixture.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program, queries actual diagnostics and directly calls Build in-process. Actual filename/shared ID formatting select literal pairs; edgeOrigin reads a first matching edge rather than proving uniqueness. A restored empty linked-plugin manifest excludes ambient hooks; no emit, installed consumer or product process runs.
 func TestMemberRelationEdgesFollowCheckerValidity(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 interface Contract {
@@ -79,6 +85,9 @@ export class Derived extends Base {
 
   derivedConstructor := nodeID(path, "Derived.__constructor", NodeMethod)
   baseConstructor := nodeID(path, "Base.__constructor", NodeMethod)
+  if built.Nodes[derivedConstructor] == nil || built.Nodes[baseConstructor] == nil {
+    t.Fatalf("missing fixture constructor nodes; nodes: %v", nodeIDSet(built))
+  }
   if hasEdge(built, derivedConstructor, baseConstructor, EdgeMemberRelation) {
     t.Fatalf("constructors are not member overrides; edges: %v", built.Edges)
   }

package/internal/graph/member_relation_edges_preserve_checker_boundaries_test.go

@@ -19,8 +19,15 @@ import (
 //  1. Build generic, overloaded, optional, merged, property/method, and
 //     accessor cases.
 //  2. Require checker diagnostics for the deliberately rejected declarations.
-//  3. Assert accepted pairs produce one member relation and rejected pairs none.
+//  3. Assert accepted pairs have their expected relation origin and rejected
+//     pairs have resident endpoint nodes but no member relation.
+//
+// @evidence contracts/testing.md#behavioral-verification Build's eleven authored accepted pairs must have their literal first-matching relation origin, while six rejected pairs must have resident endpoints and no member-relation edge. One erroneous Program also contains accepted siblings; all generic/override rules or exact edge multiplicities are not certified.
+// @evidence contracts/testing.md#independent-expectations The oracle is the TypeScript checker's accept/reject decisions encoded in the fixture: eleven accepted pairs (generic instantiation, overload set, optional-to-required, property for method, abstract accessor, split and merged declarations, protected override) must carry the literal origin implements or overrides, and six rejected pairs (wrong generic method, optional for required, method for property, property over concrete accessor, mixed-flag symbol, protected pretender) must have no member-relation edge. The only diagnostic requirement is that the program has at least one diagnostic, so the rejection of each specific pair is shown by the absent edge, not by a named diagnostic.
+// @evidence contracts/testing.md#distinguishing-cases Accepted pairs and rejected pairs sit side by side in one erroneous program, so a rejected sibling must not suppress an accepted one and an accepted one must not admit a rejected one; each pair's edge presence or absence is asserted by node id, and presence is checked by origin equality rather than by a count of exactly one.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program, requires at least one actual diagnostic and directly calls Build in-process. Actual filename/shared ID formatting select literal pairs, with first-match edgeOrigin and presence-only hasEdge helpers. A restored empty linked-plugin manifest excludes ambient hooks; no emit, installed consumer or product process runs.
 func TestMemberRelationEdgesPreserveCheckerBoundaries(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 interface Generic<T> {
@@ -184,6 +191,9 @@ export class ProtectedPretender implements ProtectedBase {
     {nodeID(path, "ProtectedPretender.token", NodeVariable), nodeID(path, "ProtectedBase.token", NodeVariable)},
   }
   for _, pair := range rejected {
+    if built.Nodes[pair.from] == nil || built.Nodes[pair.to] == nil {
+      t.Fatalf("rejected pair endpoints missing %s -> %s; nodes: %v", pair.from, pair.to, nodeIDSet(built))
+    }
     if hasEdge(built, pair.from, pair.to, EdgeMemberRelation) {
       t.Fatalf("checker-rejected boundary gained a member edge %s -> %s; edges: %v", pair.from, pair.to, built.Edges)
     }

package/internal/graph/member_relation_edges_reject_checker_invalid_pairs_test.go

@@ -8,20 +8,22 @@ import (
 )
 
 // TestMemberRelationEdgesRejectCheckerInvalidPairs verifies that an invalid
-// heritage relation cannot still manufacture authoritative member edges.
-//
-// The former TypeScript-memory synthesis compared only names and the broad
-// method/property set, so TS2416 and TS2425 diagnostics coexisted with
-// `implements`/`overrides` edges and those edges could become runtime dispatch
-// hops. A valid class in the same erroneous Program is the negative twin: an
-// unrelated diagnostic must not globally disable checker-owned relations.
+// member pair has no relation edge in the authored erroneous Program. Valid
+// members in the same classes and an unrelated valid class retain their edges.
+// No runtime dispatch follows these graph facts in this entry.
 //
 //  1. Compile invalid method/property, same-kind signature, and static/instance
 //     implementations plus an invalid class override and one valid class.
 //  2. Require the checker diagnostics that prove the fixture is rejected.
 //  3. Assert invalid pairs have no member edges while the valid class still
 //     carries its checker-backed implementation edges.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual Program diagnostics must include TS2416 and TS2425; Build must retain six rejected pair endpoints without their member edges, three literal implements pairs and one overrides sibling. Exact relation multiplicity, each pair's own diagnostic and runtime dispatch are not asserted.
+// @evidence contracts/testing.md#independent-expectations Literal authored member shapes define the six absent pairs and the four accepted origin expectations. Actual TS2416/TS2425 presence independently requires an erroneous fixture, but the codes are not correlated to each rejected pair. Resident endpoint checks distinguish relation rejection from dropped declarations; first matching origin checks do not prove uniqueness.
+// @evidence contracts/testing.md#distinguishing-cases Compile invalid method/property, same-kind signature, and static/instance implementations plus an invalid class override and one valid class; Require the checker diagnostics that prove the fixture is rejected; Assert invalid pairs have no member edges while the valid class still carries its checker-backed implementation edges.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program, queries actual diagnostics and directly calls Build in-process. Actual filename/shared ID formatting select literal pairs, using presence-only hasEdge and first-match edgeOrigin helpers. A restored empty linked-plugin manifest excludes ambient hooks; no emit, installed consumer or product process runs.
 func TestMemberRelationEdgesRejectCheckerInvalidPairs(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 interface Contract {
@@ -90,6 +92,9 @@ export class InvalidDerived extends Base {
     {nodeID(path, "InvalidDerived.run", NodeMethod), nodeID(path, "Base.run", NodeMethod)},
   }
   for _, pair := range absent {
+    if built.Nodes[pair.from] == nil || built.Nodes[pair.to] == nil {
+      t.Fatalf("rejected pair endpoints missing %s -> %s; nodes: %v", pair.from, pair.to, nodeIDSet(built))
+    }
     if hasEdge(built, pair.from, pair.to, EdgeMemberRelation) {
       t.Fatalf("checker-invalid pair gained an authoritative member edge %s -> %s; edges: %v", pair.from, pair.to, built.Edges)
     }

package/internal/graph/namespace_dotted_form_qualifies_deeply_test.go

@@ -11,10 +11,19 @@ import (
 // single-level namespace test does not: `namespace A.B.C { … }` is parsed as a
 // ModuleDeclaration whose body is another ModuleDeclaration, so moduleStatements
 // must descend through the chain and qualifiedName must build the full dotted
-// prefix. A regression in either would silently drop every declaration in a
-// dotted (or deeply nested) namespace — the idiom of .d.ts-heavy and
-// proto-generated codebases.
+// prefix. This entry asserts one authored three-level dotted function ID and
+// incoming call, not every nested namespace form or declaration payload.
+//
+// 1. Load dotted namespace A.B.C with deep and a caller.
+// 2. Build qualified namespace declarations and calls.
+// 3. Require A.B.C.deep and the caller value-call edge to that qualified declaration.
+//
+// @evidence contracts/testing.md#behavioral-verification Require A.B.C.deep and the caller value-call edge to that qualified declaration.
+// @evidence contracts/testing.md#independent-expectations Literal A.B.C.deep and caller names select a present function-keyed node and a caller-to-deep value-call triple in the authored fixture. Expected ID selection shares nodeID and the actual Program filename; node Name payload, exact edge count and an independent ID grammar are not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Load dotted namespace A.B.C with deep and a caller. Build qualified namespace declarations and calls. Require A.B.C.deep and the caller value-call edge to that qualified declaration.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program in-process and directly calls Build and presence-only hasEdge. A restored empty linked-plugin manifest excludes ambient hooks; no namespace code execution, dump serialization, installed consumer or product process runs.
 func TestNamespaceDottedFormQualifiesDeeply(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), `{
   "compilerOptions": {

package/internal/graph/namespace_members_become_qualified_nodes_and_edges_test.go

@@ -10,8 +10,8 @@ import (
 // TestNamespaceMembersBecomeQualifiedNodesAndEdges verifies that declarations
 // inside a `namespace` are first-class graph nodes, keyed by their
 // namespace-qualified name, and that edges cross the namespace boundary in both
-// directions. A top-level-statements-only walk recorded none of this: every
-// namespaced declaration and every edge touching one was silently dropped.
+// directions in the authored Service fixture. Four selected node keys and
+// four relationship triples are checked, not all namespace facts or payloads.
 //
 // The fixture exercises four relationships:
 //
@@ -19,7 +19,17 @@ import (
 //   - top-level into a namespace:  bootstrap     -> Service.run
 //   - namespaced method type-ref:  Service.Worker.process -> Payload
 //   - namespaced type referenced:  WorkerRef     -> Service.Worker
+//
+// 1. Load Service.helper, Service.run, Service.Worker and Service.Worker.process with Payload and WorkerRef.
+// 2. Build namespace declarations, value calls and type references.
+// 3. Require all four qualified nodes, run-to-helper and bootstrap-to-run calls, and process-to-Payload and WorkerRef-to-Worker type references.
+//
+// @evidence contracts/testing.md#behavioral-verification Require all four qualified nodes, run-to-helper and bootstrap-to-run calls, and process-to-Payload and WorkerRef-to-Worker type references.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: Service.helper, Service.run, Service.Worker and Service.Worker.process must be nodes; and value-call edges Service.run to Service.helper and bootstrap to Service.run, and type-ref edges Service.Worker.process to Payload and WorkerRef to Service.Worker, must exist.
+// @evidence contracts/testing.md#distinguishing-cases Load Service.helper, Service.run, Service.Worker and Service.Worker.process with Payload and WorkerRef. Build namespace declarations, value calls and type references. Require all four qualified nodes, run-to-helper and bootstrap-to-run calls, and process-to-Payload and WorkerRef-to-Worker type references.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes a native project, constructs/closes its driver Program in-process and directly calls Build and presence-only hasEdge. Actual Program filename and shared nodeID formatting select the literal qualified endpoints, not an independent ID grammar. A restored empty linked-plugin manifest excludes ambient hooks; no namespace execution, dump serialization, installed consumer or product process runs.
 func TestNamespaceMembersBecomeQualifiedNodesAndEdges(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), `{
   "compilerOptions": {

package/internal/graph/node_identity_is_position_invariant_test.go

@@ -9,8 +9,8 @@ import (
 
 // TestNodeIdentityIsPositionInvariant verifies that a declaration keeps the same
 // node id after lines are inserted above it. A byte-offset or line-number key
-// would re-key every declaration below an edit, forcing a future incremental
-// layer to churn the whole graph; the realpath + name + kind key does not.
+// would change the reported ID set for this fixture. The test does not exercise
+// an incremental host or independently authenticate physical path identity.
 //
 // The probe rewrites the same file with a comment and blank lines prepended,
 // shifting every offset below, and asserts (a) the reload actually changed the
@@ -20,7 +20,13 @@ import (
 //  1. Compile a fixture, capture its node ids and source text.
 //  2. Rewrite the same file with leading lines that shift every offset.
 //  3. Assert the text changed but the node-id set did not.
+//
+// @evidence contracts/testing.md#behavioral-verification Two fresh native Program loads around the authored comment/blank-line edit must report changed source text and equal graph ID sets, with three IDs initially. Exact source text, specific ID spellings, evidence-span movement and incremental host churn are not asserted.
+// @evidence contracts/testing.md#independent-expectations Three initial IDs, differing source text and unchanged reported ID membership are the expected effects of this nonsemantic edit. The ID baseline comes from the first Build, so equality cannot authenticate structural completeness or the identities' exact spellings. The source-change check rejects an identical stale read but does not compare the complete edited text to a literal.
+// @evidence contracts/testing.md#distinguishing-cases Compile a fixture, capture its node ids and source text; Rewrite the same file with leading lines that shift every offset; Assert the text changed but the node-id set did not.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit writes and edits one native file, constructs/closes two fresh driver Programs through buildSnapshot, and directly calls Build with a local key-set comparison. A restored empty linked-plugin manifest excludes ambient hooks; no resident update protocol, installed consumer or product process runs.
 func TestNodeIdentityIsPositionInvariant(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
   main := filepath.Join(root, "src", "main.ts")

package/internal/graph/node_ids_preserve_hash_bearing_components_test.go

@@ -9,13 +9,18 @@ import (
 // path and symbol hashes remain structured facts through dump relativization.
 //
 // A source path and an authored private member may both contain '#'. Splitting
-// the display id at either raw occurrence made the dump lose its project
-// relative path and made consumers read the member as an id separator. The
+// the display id at either raw occurrence would lose the intended path/symbol
+// boundary. The
 // codec must escape those components while keeping ordinary ids byte-identical.
 //
 //  1. Build ordinary and hash-bearing ids from their raw structured facts.
 //  2. Relativize the hash-bearing id as the dump does.
 //  3. Recover its raw file component and assert the escaped wire spelling.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies graph identity: quoted path and symbol hashes remain structured facts through dump relativization.
+// @evidence contracts/testing.md#independent-expectations The body supplies exact literal ordinary and escaped IDs: ordinary src/main.ts#main:function, doubled Windows backslashes with escaped path hash and an unchanged colon-bearing symbol name, and escaped relative path/private-member hashes. Parsing must recover the authored raw path/name, and nodeFile must return literal src#generated/main#file.ts. These string expectations are not generated by the codec; real compiler private-member binding and physical source identity are not authenticated.
+// @evidence contracts/testing.md#distinguishing-cases Build ordinary and hash-bearing ids from their raw structured facts; Relativize the hash-bearing id as the dump does; Recover its raw file component and assert the escaped wire spelling.
+// @evidence contracts/testing.md#execution-ownership This same-package Go unit directly calls nodeID, parseNodeID, newDumpContext, relID and nodeFile on authored strings. Only the temporary parent directory is created; the hash-bearing project/source paths are absent and can use native existing-ancestor canonicalization. No source files, compiler Program, dump serialization, installed consumer or product process are created.
 func TestNodeIDsPreserveHashBearingComponents(t *testing.T) {
   if got, want := nodeID("src/main.ts", "main", NodeFunction), "src/main.ts#main:function"; got != want {
     t.Fatalf("ordinary id = %q, want %q", got, want)
@@ -38,4 +43,7 @@ func TestNodeIDsPreserveHashBearingComponents(t *testing.T) {
   if file := nodeFile(got); file != "src#generated/main#file.ts" {
     t.Fatalf("decoded file = %q, want raw hash-bearing relative path", file)
   }
+  if err := context.pathError(); err != nil {
+    t.Fatalf("relativizing the authored ID failed: %v", err)
+  }
 }