ttsc 0.30.3 → 0.31.0

package/cmd/ttscgraph/serve_session_keeps_lower_priority_module_candidate_unchanged_test.go

@@ -10,14 +10,20 @@ import (
 // resident session does not reload when a candidate after its selected target
 // appears.
 //
-// Directory index probes are lower priority than every direct-file probe. An
-// interleaved candidate list would turn the creation of an irrelevant index
-// file into a full program reload and erase the bounded-freshness guarantee.
+// Directory index probes follow the selected direct JavaScript file, while
+// value.mts is outside the automatic extension candidates for this import.
+// Creating either must leave this snapshot unchanged; value.ts precedes the
+// selected JavaScript file and must trigger the observed reload.
 //
 //  1. Load an extensionless commonjs import that resolves directly to value.js.
-//  2. Create only lower-priority value/index.ts and value.mts candidates.
+//  2. Create lower-priority value/index.ts and unselected-extension value.mts.
 //  3. Assert the resident session remains unchanged, then create value.ts and
 //     assert the strictly higher-priority candidate does reload it.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a resident session does not reload when a candidate after its selected target appears.
+// @evidence contracts/testing.md#independent-expectations For this extensionless commonjs import, the pinned resolver's direct-file list tries .ts before .js, reaches directory index probes only after direct-file failure, and does not add .mts to that extension list. Literal outcomes are unchanged with no dump after either index.ts or value.mts creation, then reload with typescriptWinner after value.ts creation. They distinguish these candidates, not every extension or resolution mode.
+// @evidence contracts/testing.md#distinguishing-cases Resolve ./value to value.js; create the later directory index and the ineligible automatic .mts extension separately and require unchanged; create earlier value.ts and require reload with typescriptWinner.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsLowerPriorityModuleCandidateUnchanged is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionKeepsLowerPriorityModuleCandidateUnchanged(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -32,14 +38,14 @@ func TestServeSessionKeepsLowerPriorityModuleCandidateUnchanged(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
   if err := os.MkdirAll(filepath.Join(root, "src", "value"), 0o755); err != nil {
     t.Fatal(err)
   }
   writeGraphFile(t, filepath.Join(root, "src", "value", "index.ts"), "export function winner(): void {}\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -48,7 +54,7 @@ func TestServeSessionKeepsLowerPriorityModuleCandidateUnchanged(t *testing.T) {
   }
 
   writeGraphFile(t, filepath.Join(root, "src", "value.mts"), "export function winner(): void {}\n")
-  dump, mode, changed, err = session.Snapshot()
+  dump, mode, changed, err = snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -57,7 +63,7 @@ func TestServeSessionKeepsLowerPriorityModuleCandidateUnchanged(t *testing.T) {
   }
 
   writeGraphFile(t, filepath.Join(root, "src", "value.ts"), "export function winner(): void {}\nexport function typescriptWinner(): void {}\n")
-  dump, mode, changed, err = session.Snapshot()
+  dump, mode, changed, err = snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_keeps_lower_priority_paths_pattern_unchanged_test.go

@@ -11,6 +11,15 @@ import (
 // `@/special/*` outranks `@/*`; a file under the broad substitution never
 // participates in this lookup, while a missing .ts sibling of the selected
 // specific substitution does.
+//
+// 1. Load overlapping broad and specific paths patterns for a special import.
+// 2. Create the broad candidate, then the selected specific candidate.
+// 3. Require the broad candidate to remain unchanged and the specific candidate to reload with specificPathsWinner.
+//
+// @evidence contracts/testing.md#behavioral-verification With overlapping paths patterns where @/special/* outranks @/*, creating the broad-pattern candidate leaves a resident session unchanged, while creating the missing .ts sibling of the selected specific substitution reloads it with the new specificPathsWinner node.
+// @evidence contracts/testing.md#independent-expectations The pinned wildcard matcher chooses the matching pattern with the longest prefix before the star. Here @/special/* outranks @/*, and only its substitutions are tried. Literal expectations are unchanged with no dump after broad/special/value.ts creation, then reload, changed and specificPathsWinner after specific/value.ts creation. Exact-key precedence, equal-prefix ties and other patterns are not covered.
+// @evidence contracts/testing.md#distinguishing-cases Load overlapping broad and specific paths patterns for a special import. Create the broad candidate, then the selected specific candidate. Require the broad candidate to remain unchanged and the specific candidate to reload with specificPathsWinner.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsLowerPriorityPathsPatternUnchanged is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionKeepsLowerPriorityPathsPatternUnchanged(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -34,12 +43,12 @@ func TestServeSessionKeepsLowerPriorityPathsPatternUnchanged(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
   writeGraphFile(t, filepath.Join(root, "broad", "special", "value.ts"), "export function winner(): void {}\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -48,7 +57,7 @@ func TestServeSessionKeepsLowerPriorityPathsPatternUnchanged(t *testing.T) {
   }
 
   writeGraphFile(t, filepath.Join(root, "specific", "value.ts"), "export function winner(): void {}\nexport function specificPathsWinner(): void {}\n")
-  dump, mode, changed, err = session.Snapshot()
+  dump, mode, changed, err = snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_keeps_missing_literal_root_unchanged_test.go

@@ -17,6 +17,11 @@ import (
 //  1. Open a session whose tsconfig lists absent `src/generated.ts` in files.
 //  2. Take repeated snapshots without touching the project.
 //  3. Assert each one reports unchanged with no replacement dump.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a permanently absent `files` entry does not churn the session.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: a files entry (src/generated.ts) that never exists must not flap, so two further snapshots after the initial one must each be mode unchanged with no dump and changed false. A session whose stored root set disagreed with its reloaded one would report reload.
+// @evidence contracts/testing.md#distinguishing-cases Open a session whose tsconfig lists absent `src/generated.ts` in files; Take repeated snapshots without touching the project; Assert each one reports unchanged with no replacement dump.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsMissingLiteralRootUnchanged is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionKeepsMissingLiteralRootUnchanged(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -30,12 +35,12 @@ func TestServeSessionKeepsMissingLiteralRootUnchanged(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
   for i := 0; i < 2; i++ {
-    dump, mode, changed, err := session.Snapshot()
+    dump, mode, changed, err := snapshotGraphState(session)
     if err != nil {
       t.Fatal(err)
     }

package/cmd/ttscgraph/serve_session_keeps_nonlongest_root_dirs_candidate_unchanged_test.go

@@ -11,6 +11,15 @@ import (
 // The containing source lies under both src and src/generated. Only the
 // longest root makes out/views/template a peer candidate; out/generated/views
 // comes from the shorter root and is never tried by this resolution.
+//
+// 1. Load a source under overlapping src and src/generated roots with out as a peer root.
+// 2. Create the shorter-root candidate, then the valid peer-root candidate.
+// 3. Require no change for the nonselected root and a reload containing rootDirsWinner for the selected peer.
+//
+// @evidence contracts/testing.md#behavioral-verification With rootDirs src, src/generated and out, creating a candidate reachable only from the shorter src root leaves a resident session unchanged, while creating the candidate under the peer of the longest matching root reloads it with the new rootDirsWinner node.
+// @evidence contracts/testing.md#independent-expectations The expected outcomes follow from TypeScript-Go's rule that rootDirs resolution starts from the longest matching root (src/generated): creating out/generated/views/template.ts must be unchanged with no dump, and creating src/views/template.ts, the higher-priority peer of out/views/template.js, must be mode reload with a node named rootDirsWinner.
+// @evidence contracts/testing.md#distinguishing-cases Load a source under overlapping src and src/generated roots with out as a peer root. Create the shorter-root candidate, then the valid peer-root candidate. Require no change for the nonselected root and a reload containing rootDirsWinner for the selected peer.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsNonLongestRootDirsCandidateUnchanged is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionKeepsNonLongestRootDirsCandidateUnchanged(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -30,12 +39,12 @@ func TestServeSessionKeepsNonLongestRootDirsCandidateUnchanged(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
   writeGraphFile(t, filepath.Join(root, "out", "generated", "views", "template.ts"), "export function winner(): void {}\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -44,7 +53,7 @@ func TestServeSessionKeepsNonLongestRootDirsCandidateUnchanged(t *testing.T) {
   }
 
   writeGraphFile(t, filepath.Join(root, "src", "views", "template.ts"), "export function winner(): void {}\nexport function rootDirsWinner(): void {}\n")
-  dump, mode, changed, err = session.Snapshot()
+  dump, mode, changed, err = snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_rebuilds_import_graph_change_test.go

@@ -6,16 +6,22 @@ import (
   "testing"
 )
 
-// TestServeSessionRebuildsImportGraphChange verifies an edited import set uses
-// tsgo's safe rebuild path instead of claiming structural reuse.
+// TestServeSessionRebuildsImportGraphChange verifies an added import reports
+// rebuild mode and exposes the authored main-to-helper call edge.
 //
-// UpdateProgram can replace one AST only while its module references are
-// unchanged. Adding an import must rebuild the Program, refresh the Checker, and
-// emit the newly-resolved call edge in the same resident native process.
+// The fixture initially declares BeforeEdit and a separate helper function.
+// Replacing the class with main's import and call must yield the new relation.
+// The test observes the reported mode and graph edge, not compiler-construction
+// counts, AST identity or checker-pool lifecycle.
 //
-// 1. Start with two exported functions and no edge between them.
+// 1. Start with BeforeEdit and a separate exported helper function.
 // 2. Edit the first file to import and call the second.
 // 3. Assert rebuild mode and a calls edge from `main` to `helper`.
+//
+// @evidence contracts/testing.md#behavioral-verification Replacing the fixture class with a main function importing and calling helper reports rebuild and publishes their calls edge. It does not count native constructions or assert AST/checker identity.
+// @evidence contracts/testing.md#independent-expectations The authored import and call require literal rebuild mode, changed, distinct nonempty node IDs for main and helper, and a calls edge joining those IDs. Node names and edge kind come from the fixture's semantics, not the edge builder's bookkeeping. Initial edge absence and the entire node set are not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Start with BeforeEdit and a separate helper; replace the class file with an import and main calling helper; require reported rebuild and the literal main-to-helper calls relation.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionRebuildsImportGraphChange is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionRebuildsImportGraphChange(t *testing.T) {
   root := graphSessionFixture(t)
   helper := filepath.Join(root, "src", "helper.ts")
@@ -27,7 +33,7 @@ func TestServeSessionRebuildsImportGraphChange(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -36,7 +42,7 @@ func TestServeSessionRebuildsImportGraphChange(t *testing.T) {
   if err := os.WriteFile(index, []byte(content), 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -51,6 +57,9 @@ func TestServeSessionRebuildsImportGraphChange(t *testing.T) {
       helperID = node.ID
     }
   }
+  if mainID == "" || helperID == "" || mainID == helperID {
+    t.Fatalf("rebuilt graph lacks distinct main and helper nodes: main=%q helper=%q", mainID, helperID)
+  }
   for _, edge := range dump.Edges {
     if edge.From == mainID && edge.To == helperID && edge.Kind == "calls" {
       return

package/cmd/ttscgraph/serve_session_reloads_commonjs_package_entry_for_esm_test.go

@@ -11,6 +11,15 @@ import (
 // The importing source is ESM, but TypeScript-Go temporarily uses CommonJS
 // lookup for a package without `type: module`. A missing main.ts therefore
 // precedes main.js and must invalidate the resident session when it appears.
+//
+// 1. Load an ESM importer of a CommonJS package with extensionless main and a JavaScript fallback.
+// 2. Create node_modules package main.ts ahead of its fallback.
+// 3. Require a reload containing winner with the literal package main.ts file suffix.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating dist/main.ts for the package main './dist/main' imported from an ESM project reports reload and changed; a winner node's slash-normalized file ends with node_modules/fixture-package/dist/main.ts.
+// @evidence contracts/testing.md#independent-expectations The pinned resolver temporarily uses CommonJS lookup for this package without type: module, so main.ts precedes main.js. Literal expected outcomes are reload, changed and winner with the supplied package file suffix. The helper uses suffix matching; it does not assert full path equality or physical file identity.
+// @evidence contracts/testing.md#distinguishing-cases Load an ESM importer of a CommonJS package with extensionless main and a JavaScript fallback; create main.ts ahead of that fallback; require reload with winner matching the literal package main.ts file suffix.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsCommonJSPackageEntryForESM is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsCommonJSPackageEntryForESM(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "package.json"), `{"type":"module"}`)
@@ -35,12 +44,12 @@ func TestServeSessionReloadsCommonJSPackageEntryForESM(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
   writeGraphFile(t, filepath.Join(root, "node_modules", "fixture-package", "dist", "main.ts"), "export function winner(): void {}\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reloads_created_literal_root_test.go

@@ -16,6 +16,11 @@ import (
 //  1. Open a session whose tsconfig lists absent `src/generated.ts` in files.
 //  2. Create that file without touching any other project input.
 //  3. Assert the next snapshot reloads and exposes the new declaration.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a `files`-listed root that does not exist yet joins the graph once it is created.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: after creating the previously absent files entry src/generated.ts and touching nothing else, the next snapshot must be mode reload, changed, with a dump containing the Generated class from that file.
+// @evidence contracts/testing.md#distinguishing-cases Open a session whose tsconfig lists absent `src/generated.ts` in files; Create that file without touching any other project input; Assert the next snapshot reloads and exposes the new declaration.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsCreatedLiteralRoot is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsCreatedLiteralRoot(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -29,12 +34,12 @@ func TestServeSessionReloadsCreatedLiteralRoot(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
   writeGraphFile(t, filepath.Join(root, "src", "generated.ts"), "export class Generated {}\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reloads_extended_config_change_test.go

@@ -6,8 +6,8 @@ import (
   "testing"
 )
 
-// TestServeSessionReloadsExtendedConfigChange verifies every config in an
-// extends chain participates in snapshot freshness.
+// TestServeSessionReloadsExtendedConfigChange verifies changing the one inherited
+// base config in this fixture reports reload with a replacement dump.
 //
 // Watching only the requested tsconfig misses compiler-option changes inherited
 // from a base file. The session records all parsed extended source files and
@@ -16,6 +16,11 @@ import (
 // 1. Create a project whose tsconfig extends `base.json`.
 // 2. Build once, then change a compiler option only in the base config.
 // 3. Assert the next snapshot reports a full reload.
+//
+// @evidence contracts/testing.md#behavioral-verification Changing strict from true to false in the fixture's single base.json reports reload, changed and a nonnil dump. The test does not assert effective strict semantics or every level of a multi-file extends chain.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: after only base.json (reached through extends) changes strict from true to false, the next snapshot must be mode reload, changed, with a dump. A session that watched only the requested tsconfig would answer unchanged.
+// @evidence contracts/testing.md#distinguishing-cases Create a project whose tsconfig extends `base.json`; Build once, then change a compiler option only in the base config; Assert the next snapshot reports a full reload.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsExtendedConfigChange is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsExtendedConfigChange(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "base.json"), `{"compilerOptions":{"strict":true,"target":"ES2022"}}`)
@@ -27,7 +32,7 @@ func TestServeSessionReloadsExtendedConfigChange(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -35,7 +40,7 @@ func TestServeSessionReloadsExtendedConfigChange(t *testing.T) {
   if err := os.WriteFile(base, []byte(`{"compilerOptions":{"strict":false,"target":"ES2022"}}`), 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reloads_module_suffix_candidate_test.go

@@ -5,8 +5,17 @@ import (
   "testing"
 )
 
-// TestServeSessionReloadsModuleSuffixCandidate verifies a configured module
-// suffix is considered before the unsuffixed extension candidate.
+// TestServeSessionReloadsModuleSuffixCandidate verifies the configured .native
+// TypeScript candidate replaces the selected unsuffixed JavaScript fallback.
+//
+// 1. Load a value.js fallback with moduleSuffixes selecting .native before the empty suffix.
+// 2. Create value.native.ts.
+// 3. Require a reload containing nativeWinner.
+//
+// @evidence contracts/testing.md#behavioral-verification With moduleSuffixes [.native, ”], creating value.native.ts beside the resolved value.js reloads a resident session and the new dump contains nativeWinner.
+// @evidence contracts/testing.md#independent-expectations moduleSuffixes includes .native, and TypeScript file candidates precede JavaScript fallback candidates. Literal outcomes after src/value.native.ts creation are reload, changed and nativeWinner. This fixture has no competing value.ts, so it does not distinguish reversal of the two suffixes within the same extension.
+// @evidence contracts/testing.md#distinguishing-cases Load a value.js fallback with moduleSuffixes selecting .native before the empty suffix. Create value.native.ts. Require a reload containing nativeWinner.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsModuleSuffixCandidate is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsModuleSuffixCandidate(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -26,12 +35,12 @@ func TestServeSessionReloadsModuleSuffixCandidate(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
   writeGraphFile(t, filepath.Join(root, "src", "value.native.ts"), "export function winner(): void {}\nexport function nativeWinner(): void {}\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reloads_newly_resolved_conditional_export_test.go

@@ -6,17 +6,22 @@ import (
   "testing"
 )
 
-// TestServeSessionReloadsNewlyResolvedConditionalExport verifies conditional
-// exports objects and array fallbacks contribute resolution candidates.
+// TestServeSessionReloadsNewlyResolvedConditionalExport verifies creating the
+// missing types target in this conditional export reports a reload.
 //
-// Real packages rarely map a subpath straight to one string: `exports`
-// commonly nests condition objects (`types`, `default`) and array fallbacks.
-// Every leaf target must be tracked, or a package shipping its compiled
-// output later stays invisible to the resident graph.
+// Both types and default targets begin absent. The default is a one-element
+// array, but only the types file is created. Array fallback selection, inactive
+// branches, the initial unresolved diagnostic and the new declaration's node
+// are not asserted by this case.
 //
 //  1. Import a package subpath whose exports leaf targets do not exist yet.
 //  2. Create the `types` condition's declaration target.
 //  3. Assert the next snapshot reports a full reload.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating the types target dist/feature.d.ts in this nested export object reports reload, changed and a nonnil dump. The default's one-element array remains absent, so this does not certify array fallback selection or every leaf's freshness.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: a package subpath whose exports condition object (types, default array) has no existing targets starts unresolved, and creating the types target dist/feature.d.ts must yield mode reload, changed, with a dump. The new declaration's node is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Import a package subpath whose exports leaf targets do not exist yet; Create the `types` condition's declaration target; Assert the next snapshot reports a full reload.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedConditionalExport is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsNewlyResolvedConditionalExport(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -39,7 +44,7 @@ func TestServeSessionReloadsNewlyResolvedConditionalExport(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -50,7 +55,7 @@ func TestServeSessionReloadsNewlyResolvedConditionalExport(t *testing.T) {
   if err := os.WriteFile(target, []byte("export declare function feature(): void;\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reloads_newly_resolved_config_types_test.go

@@ -16,6 +16,11 @@ import (
 //  1. Open a session whose config lists absent types package `fixture-types`.
 //  2. Create the package under the configured typeRoots directory.
 //  3. Assert the next snapshot reports a full reload.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies compilerOptions `types` entries participate in freshness without any source-level syntax.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: with compilerOptions.types naming an absent package fixture-types under typeRoots and no source-level reference, creating types/fixture-types/index.d.ts must yield mode reload, changed, with a dump.
+// @evidence contracts/testing.md#distinguishing-cases Open a session whose config lists absent types package `fixture-types`; Create the package under the configured typeRoots directory; Assert the next snapshot reports a full reload.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedConfigTypes is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsNewlyResolvedConfigTypes(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -29,12 +34,12 @@ func TestServeSessionReloadsNewlyResolvedConfigTypes(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
   writeGraphFile(t, filepath.Join(root, "types", "fixture-types", "index.d.ts"), "interface FixtureType { id: number }\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reloads_newly_resolved_excluded_import_test.go

@@ -14,9 +14,14 @@ import (
 // unchanged while module resolution changes from unresolved to resolved. The
 // session snapshots concrete resolution candidates and reloads when one appears.
 //
-// 1. Compile one root that imports missing, excluded `generated.ts`.
+// 1. Compile one root that imports missing `generated.ts`, which is not listed in files.
 // 2. Create that module without changing the importer or tsconfig roots.
 // 3. Assert reload mode and the newly-resolved declaration and call edge.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a previously missing relative import becomes visible even when the new file is not a tsconfig root.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: after generated.ts is created next to an importer whose files list is unchanged, the snapshot must be mode reload, changed, with nodes named main and generated and a calls edge from main to generated, found by node name and edge kind in the dump.
+// @evidence contracts/testing.md#distinguishing-cases Compile one root that imports missing generated.ts, absent from the files list; create that module without changing the importer or root list; require reload, distinct nonempty main/generated node IDs and their calls edge. No exclude pattern is configured by this fixture.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedExcludedImport is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsNewlyResolvedExcludedImport(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -30,7 +35,7 @@ func TestServeSessionReloadsNewlyResolvedExcludedImport(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -38,7 +43,7 @@ func TestServeSessionReloadsNewlyResolvedExcludedImport(t *testing.T) {
   if err := os.WriteFile(generated, []byte("export function generated(): void {}\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -53,6 +58,9 @@ func TestServeSessionReloadsNewlyResolvedExcludedImport(t *testing.T) {
       generatedID = node.ID
     }
   }
+  if mainID == "" || generatedID == "" || mainID == generatedID {
+    t.Fatalf("reloaded graph lacks distinct main and generated nodes: main=%q generated=%q", mainID, generatedID)
+  }
   for _, edge := range dump.Edges {
     if edge.From == mainID && edge.To == generatedID && edge.Kind == "calls" {
       return

package/cmd/ttscgraph/serve_session_reloads_newly_resolved_package_export_test.go

@@ -8,6 +8,15 @@ import (
 
 // TestServeSessionReloadsNewlyResolvedPackageExport verifies an exports target
 // appearing under an existing package triggers module-resolution reload.
+//
+// 1. Load fixture-package/feature with an existing exports map and missing target.
+// 2. Create the mapped dist/feature.ts declaration.
+// 3. Require a changed reload dump.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating dist/feature.ts behind the existing exports target ./dist/feature.js reports reload, changed and a nonnil dump. The pinned resolver permits that .js-to-.ts substitution; this test does not assert the initial unresolved diagnostic, its disappearance or the new declaration node.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: the exports map targets ./dist/feature.js, which does not exist, and creating dist/feature.ts must yield mode reload, changed, with a dump. The new declaration's node is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Load fixture-package/feature with an existing exports map and missing target. Create the mapped dist/feature.ts declaration. Require a changed reload dump.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedPackageExport is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsNewlyResolvedPackageExport(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -25,7 +34,7 @@ func TestServeSessionReloadsNewlyResolvedPackageExport(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -36,7 +45,7 @@ func TestServeSessionReloadsNewlyResolvedPackageExport(t *testing.T) {
   if err := os.WriteFile(target, []byte("export function feature(): void {}\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reloads_newly_resolved_package_import_test.go

@@ -8,6 +8,15 @@ import (
 
 // TestServeSessionReloadsNewlyResolvedPackageImport verifies wildcard imports
 // targets are tracked with the wildcard text matched from the package key.
+//
+// 1. Load the #generated/value import with a wildcard package imports mapping.
+// 2. Create the substituted generated/value.ts declaration.
+// 3. Require a changed reload dump.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating generated/value.ts, the substitution of the wildcard #generated/* package imports mapping for #generated/value, reloads a resident session.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: the imports map #generated/* to ./generated/*.js, so creating generated/value.ts for the specifier #generated/value must yield mode reload, changed, with a dump. The new declaration's node is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Load the #generated/value import with a wildcard package imports mapping. Create the substituted generated/value.ts declaration. Require a changed reload dump.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedPackageImport is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsNewlyResolvedPackageImport(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "package.json"), `{
@@ -25,7 +34,7 @@ func TestServeSessionReloadsNewlyResolvedPackageImport(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -36,7 +45,7 @@ func TestServeSessionReloadsNewlyResolvedPackageImport(t *testing.T) {
   if err := os.WriteFile(target, []byte("export function generated(): void {}\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reloads_newly_resolved_path_alias_test.go

@@ -8,6 +8,15 @@ import (
 
 // TestServeSessionReloadsNewlyResolvedPathAlias verifies a missing paths target
 // is tracked even when it is excluded from the tsconfig root set.
+//
+// 1. Load @generated/value through paths while only src/index.ts is a configured root.
+// 2. Create the excluded generated/value.ts target.
+// 3. Require a changed reload dump containing generated.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating the generated/value.ts target of a paths alias that is outside the configured root set reloads a resident session and the new dump contains generated.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: the @generated/* paths alias maps to generated/*, only src/index.ts is a root, and creating generated/value.ts must yield mode reload, changed, with a node named generated.
+// @evidence contracts/testing.md#distinguishing-cases Load @generated/value through paths while only src/index.ts is a configured root. Create the excluded generated/value.ts target. Require a changed reload dump containing generated.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedPathAlias is a Go source-unit entry. snapshotGraphState calls the actual prepareDumpSnapshot state operation and completes its graph projection with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary. The separate worktree E2E owns real Git acquisition.
 func TestServeSessionReloadsNewlyResolvedPathAlias(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -26,7 +35,7 @@ func TestServeSessionReloadsNewlyResolvedPathAlias(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -37,7 +46,7 @@ func TestServeSessionReloadsNewlyResolvedPathAlias(t *testing.T) {
   if err := os.WriteFile(target, []byte("export function generated(): void {}\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }