ttsc 0.30.4 → 0.31.1

package/cmd/ttscgraph/serve_session_reloads_newly_resolved_reference_path_test.go

@@ -8,6 +8,15 @@ import (
 
 // TestServeSessionReloadsNewlyResolvedReferencePath verifies triple-slash path
 // directives participate in freshness even though they are not AST statements.
+//
+// 1. Load a triple-slash path reference to missing generated/types.d.ts.
+// 2. Create the referenced Generated interface.
+// 3. Require a changed reload dump.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating the file named by a triple-slash path reference reloads a resident session even though the reference is not an AST statement.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: src/index.ts references ../generated/types.d.ts, which is absent, and creating it must yield mode reload, changed, with a dump. The new interface node is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Load a triple-slash path reference to missing generated/types.d.ts. Create the referenced Generated interface. Require a changed reload dump.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedReferencePath 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 TestServeSessionReloadsNewlyResolvedReferencePath(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -21,7 +30,7 @@ func TestServeSessionReloadsNewlyResolvedReferencePath(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -32,7 +41,7 @@ func TestServeSessionReloadsNewlyResolvedReferencePath(t *testing.T) {
   if err := os.WriteFile(target, []byte("interface Generated { id: number }\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_root_dirs_target_test.go

@@ -8,6 +8,15 @@ import (
 
 // TestServeSessionReloadsNewlyResolvedRootDirsTarget verifies virtual relative
 // paths across rootDirs participate in module-resolution freshness.
+//
+// 1. Load a virtual ./template import under src/views with src and generated roots.
+// 2. Create generated/views/template.ts.
+// 3. Require a changed reload dump containing template.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating generated/views/template.ts, the rootDirs peer of an unresolved ./template import in src/views, reloads a resident session and the new dump contains template.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: with rootDirs [src, generated] the virtual path views/template resolves to generated/views/template.ts, so creating it must yield mode reload, changed, with a node named template.
+// @evidence contracts/testing.md#distinguishing-cases Load a virtual ./template import under src/views with src and generated roots. Create generated/views/template.ts. Require a changed reload dump containing template.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedRootDirsTarget 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 TestServeSessionReloadsNewlyResolvedRootDirsTarget(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -25,7 +34,7 @@ func TestServeSessionReloadsNewlyResolvedRootDirsTarget(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 TestServeSessionReloadsNewlyResolvedRootDirsTarget(t *testing.T) {
   if err := os.WriteFile(target, []byte("export function template(): 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_type_reference_test.go

@@ -8,6 +8,15 @@ import (
 
 // TestServeSessionReloadsNewlyResolvedTypeReference verifies triple-slash type
 // directives honor configured typeRoots when a missing package appears.
+//
+// 1. Load a triple-slash fixture-types reference with explicit ./types roots.
+// 2. Create types/fixture-types/index.d.ts declaring FixtureType.
+// 3. Require a changed reload dump.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating types/fixture-types/index.d.ts behind the source's triple-slash reference reports reload, changed and a nonnil dump. Initial diagnostic disappearance and the FixtureType node are not asserted.
+// @evidence contracts/testing.md#independent-expectations The literal directive names fixture-types and typeRoots is ./types. Creating the named package must report reload, changed and a dump. The pinned source-type-reference replay supplies this freshness path; the diagnostic contents and FixtureType node are not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Load the missing triple-slash fixture-types reference with ./types roots; create its index.d.ts declaring FixtureType; require a changed reload dump without an importer edit.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsNewlyResolvedTypeReference 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 TestServeSessionReloadsNewlyResolvedTypeReference(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -21,7 +30,7 @@ func TestServeSessionReloadsNewlyResolvedTypeReference(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -32,7 +41,7 @@ func TestServeSessionReloadsNewlyResolvedTypeReference(t *testing.T) {
   if err := os.WriteFile(target, []byte("interface FixtureType { id: number }\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_root_file_set_test.go

@@ -6,8 +6,9 @@ import (
   "testing"
 )
 
-// TestServeSessionReloadsRootFileSet verifies include-glob additions and
-// deletions replace the compiler session rather than leaving stale roots.
+// TestServeSessionReloadsRootFileSet checks reported reloads after include-glob
+// addition and deletion, with the added name present and deleted name absent.
+// Compiler-session identity and construction counts are not observed.
 //
 // A one-file UpdateProgram cannot add or remove config roots. The session must
 // re-evaluate the tsconfig file set before source hashing and reload whenever
@@ -16,6 +17,11 @@ import (
 // 1. Add `AddedRoot` under an included directory and assert reload plus presence.
 // 2. Delete the original `BeforeEdit` root.
 // 3. Assert another reload removes the deleted declaration.
+//
+// @evidence contracts/testing.md#behavioral-verification Adding src/added.ts reports reload with AddedRoot; deleting src/index.ts reports reload without BeforeEdit. The test owns these names and modes rather than compiler-session object identity, construction counts or the complete surviving node set.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over an include-based fixture: creating src/added.ts must give mode reload, changed, with a node named AddedRoot; deleting src/index.ts must give another mode reload, changed, whose dump no longer contains BeforeEdit. A session that kept stale roots would report incremental or unchanged.
+// @evidence contracts/testing.md#distinguishing-cases Add `AddedRoot` under an included directory and assert reload plus presence; Delete the original `BeforeEdit` root; Assert another reload removes the deleted declaration.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsRootFileSet 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 TestServeSessionReloadsRootFileSet(t *testing.T) {
   root := graphSessionFixture(t)
   session, err := newGraphSession(root, "tsconfig.json")
@@ -23,7 +29,7 @@ func TestServeSessionReloadsRootFileSet(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -31,7 +37,7 @@ func TestServeSessionReloadsRootFileSet(t *testing.T) {
   if err := os.WriteFile(added, []byte("export class AddedRoot {}\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)
   }
@@ -42,7 +48,7 @@ func TestServeSessionReloadsRootFileSet(t *testing.T) {
   if err := os.Remove(filepath.Join(root, "src", "index.ts")); 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_source_deleted_during_load_test.go

@@ -11,15 +11,19 @@ import (
 // TestServeSessionReloadsSourceDeletedDuringLoad verifies a program source
 // that vanishes between compiler load and state capture is still detected.
 //
-// captureState hashes only sources it can read back from disk, so silently
-// skipping a just-deleted file would drop it from every later freshness check:
-// no root change, no source hash, no resolution candidate. The session must
-// record the resident text instead so the next snapshot observes the deletion
-// and reloads rather than serving the vanished declarations forever.
+// The imported helper is not a configured root. When its native stat reports
+// missing, captureState retains a hash of its resident text so the next source
+// check can observe deletion. This fixture requires reload and helper's absence;
+// it does not establish every resolution input or all graph facts.
 //
 //  1. Load a session whose root imports `helper.ts`.
 //  2. Delete `helper.ts` before capturing the freshness state.
 //  3. Assert the next snapshot reloads and drops the deleted declaration.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a program source that vanishes between compiler load and state capture is still detected.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: a source deleted after the compiler session loaded but before state capture must make the next snapshot mode reload, changed, with a dump that no longer contains the helper node. The fixture deletes helper.ts between driver.NewSession and captureState to inject the race.
+// @evidence contracts/testing.md#distinguishing-cases Load a session whose root imports `helper.ts`; Delete `helper.ts` before capturing the freshness state; Assert the next snapshot reloads and drops the deleted declaration.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsSourceDeletedDuringLoad 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 TestServeSessionReloadsSourceDeletedDuringLoad(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -36,9 +40,6 @@ func TestServeSessionReloadsSourceDeletedDuringLoad(t *testing.T) {
   if compiler == nil {
     t.Fatalf("NewSession returned nil session (diagnostics: %v)", diags)
   }
-  if err := os.Remove(filepath.Join(root, "src", "helper.ts")); err != nil {
-    t.Fatal(err)
-  }
   session := &graphSession{
     cwd:         root,
     tsconfig:    "tsconfig.json",
@@ -46,11 +47,17 @@ func TestServeSessionReloadsSourceDeletedDuringLoad(t *testing.T) {
     initialized: true,
   }
   defer session.Close()
+  if compiler.Program().SourceFile(filepath.Join(root, "src", "helper.ts")) == nil {
+    t.Fatal("the initial resident program omitted helper.ts before deletion")
+  }
+  if err := os.Remove(filepath.Join(root, "src", "helper.ts")); err != nil {
+    t.Fatal(err)
+  }
   if err := session.captureState(); 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_superseding_module_candidates_test.go

@@ -8,18 +8,23 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/internal/graph"
 )
 
-// TestServeSessionReloadsSupersedingModuleCandidates verifies a resident
-// session reloads when an unchanged specifier gains a missing candidate that
-// outranks the file TypeScript-Go selected for the first snapshot.
+// TestServeSessionReloadsSupersedingModuleCandidates checks reported reloads
+// after preferred-target creation and automatic types-package discovery.
 //
 // A resident session cannot rely on a changed importer or tsconfig to notice a
-// resolution precedence change. Each case pins a distinct resolver family while
-// preserving both files between observations.
+// resolution precedence change. Eight table cases retain an existing fallback;
+// the ninth adds a discovered types package without an earlier selected package.
 //
-//  1. Load a project whose specifier resolves to the lower-priority target.
-//  2. Create only the absent target that precedes it in that resolver's search.
-//  3. Assert the resident snapshot reloads and the imported symbol resolves to
-//     the newly preferred file. Package internals remain external boundaries.
+//  1. Load each table fallback or the empty wildcard-types fixture.
+//  2. Add the preferred target or newly discovered types package.
+//  3. Require reload and the case's winner-name/file-suffix or diagnostic fragment;
+//     the automatic-types case requires a nonnil reload dump only. Imported
+//     binding edges, full path identity and node External flags are not asserted.
+//
+// @evidence contracts/testing.md#behavioral-verification Eight table cases require reload and a winner-name/file-suffix or diagnostic fragment after preferred-target creation. A ninth case requires reload when a package appears under automatic types [*]. Neither imported binding edges nor complete graph contents are asserted.
+// @evidence contracts/testing.md#independent-expectations Literal fixtures require reload and changed after relative .ts-over-.js, first paths substitution, direct rootDirs location, nearer-package .ts over farther .js, earlier exports-array target, active types exports/imports, direct file over index, or types [*] directory membership creation. Seven table cases require winner with the literal file suffix; the exports-array case requires a diagnostic containing first.js. The ninth requires only a nonnil reload dump. Suffix/fragment matching does not establish full path identity; the nearer-package case changes both location and extension, so it does not isolate equal-extension distance priority.
+// @evidence contracts/testing.md#distinguishing-cases Eight table subtests add an absent preferred target while retaining their initial fallback. automatic_type_directory_membership instead adds a package to types [*] discovery. Each retains its own fixture, assertion and failure name; lower-priority no-change cases belong to separate tests. The ninth does not assert the ambient node itself.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsSupersedingModuleCandidates is a Go source-unit entry; its subtests are registered by the table and by one extra t.Run in the same function. Each runs a real in-process graphSession over a temporary project through snapshotGraphState with explicit empty ignore membership, so no consumer is installed and no native binary is built or launched.
 func TestServeSessionReloadsSupersedingModuleCandidates(t *testing.T) {
   cases := []struct {
     name           string
@@ -204,12 +209,12 @@ func TestServeSessionReloadsSupersedingModuleCandidates(t *testing.T) {
         t.Fatal(err)
       }
       defer session.Close()
-      if _, _, _, err := session.Snapshot(); err != nil {
+      if _, _, _, err := snapshotGraphState(session); err != nil {
         t.Fatal(err)
       }
 
       test.add(t, root)
-      dump, mode, changed, err := session.Snapshot()
+      dump, mode, changed, err := snapshotGraphState(session)
       if err != nil {
         t.Fatal(err)
       }
@@ -233,12 +238,12 @@ func TestServeSessionReloadsSupersedingModuleCandidates(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", "@types", "generated", "index.d.ts"), "declare const generatedAmbient: string;\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_transitive_project_reference_test.go

@@ -6,9 +6,18 @@ import (
   "testing"
 )
 
-// TestServeSessionReloadsTransitiveProjectReference verifies config and root
-// freshness traverses the complete project-reference graph, not only the
-// root config's direct references.
+// TestServeSessionReloadsTransitiveProjectReference checks leaf config tracking
+// and root-file freshness across the fixture's root-to-middle-to-leaf chain.
+// Other reference topologies and the added file's node are not asserted.
+//
+// 1. Load the root-to-middle-to-leaf project reference chain and inspect captured config identities.
+// 2. Publish the initial snapshot, then add leaf/src/added.ts.
+// 3. Require the leaf config to be tracked and the transitive root addition to publish a changed reload dump.
+//
+// @evidence contracts/testing.md#behavioral-verification A leaf config reached only through root to middle to leaf project references is tracked in the session's config hashes, and adding a file under the leaf's include reloads the session with a changed dump.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: the slash-form path of leaf/tsconfig.json must be a key of the captured config hashes (transitive reference tracked), and creating leaf/src/added.ts must yield mode reload, changed, with a dump. The added file's node is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Load the root-to-middle-to-leaf project reference chain and inspect captured config identities. Publish the initial snapshot, then add leaf/src/added.ts. Require the leaf config to be tracked and the transitive root addition to publish a changed reload dump.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReloadsTransitiveProjectReference 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 TestServeSessionReloadsTransitiveProjectReference(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -37,7 +46,7 @@ func TestServeSessionReloadsTransitiveProjectReference(t *testing.T) {
   if _, ok := session.configHashes[leafConfig]; !ok {
     t.Fatalf("transitive project config was not tracked: %s; got %#v", leafConfig, session.configHashes)
   }
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -45,7 +54,7 @@ func TestServeSessionReloadsTransitiveProjectReference(t *testing.T) {
   if err := os.WriteFile(added, []byte("export const added = 1;\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_when_program_plugin_linked_test.go

@@ -14,17 +14,22 @@ func (serveProgramPluginProbe) ApplyProgram(*driver.Program, driver.PluginContex
   return nil
 }
 
-// TestServeSessionReloadsWhenProgramPluginLinked verifies a project with an
-// active linked ProgramPlugin never takes the incremental source path.
+// TestServeSessionReloadsWhenProgramPluginLinked checks that one content rename
+// reports reload when the manifest pairs with the registered no-op ProgramPlugin.
 //
-// ProgramPlugin hooks mutate parsed ASTs in place and run exactly once per
-// Program, so an incremental source replacement would leave the new AST
-// without the plugin's mutations while the rest of the graph still carries
-// them. A content-only edit must therefore rebuild through a full reload.
+// ProgramPlugin implementations may mutate parsed ASTs, so the resident policy
+// requires full reload for such a linked member. This no-op probe exercises
+// classification and reported mode; it does not assert mutations, hook counts,
+// AST identity or every possible edit.
 //
 //  1. Register a linked ProgramPlugin and open a graph session.
 //  2. Apply a content-only edit that would otherwise refresh incrementally.
 //  3. Assert the snapshot reports a full reload with the post-edit node.
+//
+// @evidence contracts/testing.md#behavioral-verification A registered no-op ProgramPlugin paired with the linked manifest makes the BeforeEdit-to-AfterEdit source rename report reload, changed and AfterEdit present. Mutation effects, hook invocation counts and compiler object identity are not asserted.
+// @evidence contracts/testing.md#independent-expectations The resident policy requires reload when a linked member implements ProgramPlugin, because that capability permits AST mutation. Literal expected outcomes for this no-op implementation are reload, changed and AfterEdit; without that capability the same rename is incremental in the separate edit case. This does not certify actual mutation or once-per-Program dispatch.
+// @evidence contracts/testing.md#distinguishing-cases Register a linked ProgramPlugin and open a graph session; Apply a content-only edit that would otherwise refresh incrementally; Assert the snapshot reports a full reload with the post-edit node.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit entry runs actual resident state/projection with explicit empty ignore membership. The manifest environment is restored by t.Setenv; RegisterPlugin retains its no-op registration for process lifetime, and the one-entry manifest selects registry index zero. No global registry reset is asserted. No consumer is installed or native artifact built or started. Real Git acquisition belongs to the separate worktree E2E.
 func TestServeSessionReloadsWhenProgramPluginLinked(t *testing.T) {
   t.Setenv(driver.LinkedPluginsEnv, `[{"name":"probe","stage":"transform"}]`)
   driver.RegisterPlugin(serveProgramPluginProbe{})
@@ -35,7 +40,7 @@ func TestServeSessionReloadsWhenProgramPluginLinked(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -43,7 +48,7 @@ func TestServeSessionReloadsWhenProgramPluginLinked(t *testing.T) {
   if err := os.WriteFile(file, []byte("export class AfterEdit {}\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_retries_a_pending_dump_before_unchanged_test.go

@@ -0,0 +1,62 @@
+package main
+
+import (
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestServeSessionRetriesAPendingDumpBeforeUnchanged pins the state boundary
+// introduced by dump-time path validation. A failed dump may occur after the
+// compiler generation and its hashes were captured; the next request must
+// retry that generation instead of confirming the older client graph as
+// unchanged.
+//
+// 1. Capture a loaded program with an explicit pending reload change.
+// 2. Request two snapshots without another disk edit.
+// 3. Require the first request to publish reload and clear pending state, then the second to return unchanged with no dump.
+//
+// @evidence contracts/testing.md#behavioral-verification A session holding a pending full reload change publishes that retry on the next snapshot, clears the pending state, and only then reports unchanged with no dump on a further snapshot with no disk edit.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal states: with pending set to a reload change and no disk change, the first snapshot must be mode reload, changed, with a dump and leave pending nil, and the second must be mode unchanged with no dump. A session that ignored pending would answer unchanged first.
+// @evidence contracts/testing.md#distinguishing-cases Capture a loaded program with an explicit pending reload change. Request two snapshots without another disk edit. Require the first request to publish reload and clear pending state, then the second to return unchanged with no dump.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionRetriesAPendingDumpBeforeUnchanged 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 TestServeSessionRetriesAPendingDumpBeforeUnchanged(t *testing.T) {
+  root := graphSessionFixture(t)
+  compiler, diags, err := driver.NewSession(root, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil {
+    t.Fatal(err)
+  }
+  if compiler == nil {
+    t.Fatalf("NewSession returned nil session (diagnostics: %v)", diags)
+  }
+  session := &graphSession{
+    cwd:         root,
+    tsconfig:    "tsconfig.json",
+    compiler:    compiler,
+    initialized: true,
+    pending:     &graphChange{mode: serveModeReload, full: true},
+  }
+  defer session.Close()
+  if err := session.captureState(); err != nil {
+    t.Fatal(err)
+  }
+
+  dump, mode, changed, err := snapshotGraphState(session)
+  if err != nil {
+    t.Fatal(err)
+  }
+  if dump == nil || mode != serveModeReload || !changed {
+    t.Fatalf("pending dump retry = dump:%v mode:%q changed:%v", dump != nil, mode, changed)
+  }
+  if session.pending != nil {
+    t.Fatalf("successful retry left pending change %#v", session.pending)
+  }
+
+  dump, mode, changed, err = snapshotGraphState(session)
+  if err != nil {
+    t.Fatal(err)
+  }
+  if dump != nil || mode != serveModeUnchanged || changed {
+    t.Fatalf("retry did not converge: dump:%v mode:%q changed:%v", dump != nil, mode, changed)
+  }
+}

package/cmd/ttscgraph/serve_session_reuses_unchanged_preamble_source_test.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+  "os"
   "path/filepath"
   "testing"
 
@@ -10,6 +11,15 @@ import (
 // TestServeSessionReusesUnchangedPreambleSource verifies injected compiler text
 // is compared against the corresponding raw disk source, not mistaken for an
 // edit on every snapshot.
+//
+// 1. Load index.ts with an injected SourcePreamble and capture its raw disk identity.
+// 2. Request a snapshot from initialized state without another disk edit.
+// 3. Require unchanged with no dump; injected resident text must not be mistaken for a disk edit.
+//
+// @evidence contracts/testing.md#behavioral-verification A session whose compiler was created with a SourcePreamble does not treat the injected resident text as a disk edit: a snapshot with no disk change returns unchanged with no dump.
+// @evidence contracts/testing.md#independent-expectations The expectation is literal: the resident source text includes an injected declaration the disk file lacks, yet with the disk untouched Snapshot must return mode unchanged, not changed, with no dump. A comparison of raw resident text against raw disk bytes would report an edit.
+// @evidence contracts/testing.md#distinguishing-cases Load index.ts with an injected SourcePreamble and capture its raw disk identity. Request a snapshot from initialized state without another disk edit. Require unchanged with no dump; injected resident text must not be mistaken for a disk edit.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReusesUnchangedPreambleSource is a Go source-unit entry. driver.NewSession, captureState and the actual Snapshot facade run directly; the initialized unchanged branch returns before graph preparation or Git acquisition. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary.
 func TestServeSessionReusesUnchangedPreambleSource(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{"compilerOptions":{"strict":true},"files":["index.ts"]}`)
@@ -31,6 +41,17 @@ func TestServeSessionReusesUnchangedPreambleSource(t *testing.T) {
     initialized: true,
   }
   defer session.Close()
+  resident, ok := compiler.SourceText(filepath.Join(root, "index.ts"))
+  if !ok || resident != "declare const injected: number;\nexport const value = 1;\n" {
+    t.Fatalf("resident source lacks the literal injected preamble: found=%v text=%q", ok, resident)
+  }
+  disk, err := os.ReadFile(filepath.Join(root, "index.ts"))
+  if err != nil {
+    t.Fatal(err)
+  }
+  if string(disk) != "export const value = 1;\n" {
+    t.Fatalf("disk source changed during preamble load: %q", disk)
+  }
   if err := session.captureState(); err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_reuses_unchanged_snapshot_test.go

@@ -5,16 +5,21 @@ import (
   "testing"
 )
 
-// TestServeSessionReusesUnchangedSnapshot verifies repeated graph requests do
-// no graph rebuild when every project input is byte-identical.
+// TestServeSessionReusesUnchangedSnapshot verifies that a second request over
+// an untouched one-file project reports unchanged and omits a replacement dump.
 //
-// This is the hot MCP path. The native session still checks its config, root
-// file set, and resident source hashes, but it must omit the dump so the Node
-// server can retain its indexed maps without parsing or synthesizing them again.
+// The owning snapshot operation checks native inputs before returning this
+// result. This unit observes its mode, changed flag, and dump presence; it does
+// not count graph constructions or execute the Node consumer's indexed-map path.
 //
 // 1. Open a one-file graph session and request its initial dump.
 // 2. Request another snapshot without touching the project.
 // 3. Assert the second response is unchanged and carries no replacement dump.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies initial dump publication followed by an unchanged response with no replacement dump over an untouched one-file project. Graph construction counts and downstream Node parsing or indexed-map reuse are not observed here.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal session states over a one-file fixture: the first snapshot must be mode initial, changed, with a dump, and a second snapshot with no disk change must be mode unchanged, not changed, with no dump.
+// @evidence contracts/testing.md#distinguishing-cases Open a one-file graph session and request its initial dump; Request another snapshot without touching the project; Assert the second response is unchanged and carries no replacement dump.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionReusesUnchangedSnapshot 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 TestServeSessionReusesUnchangedSnapshot(t *testing.T) {
   root := graphSessionFixture(t)
   session, err := newGraphSession(root, "tsconfig.json")
@@ -23,7 +28,7 @@ func TestServeSessionReusesUnchangedSnapshot(t *testing.T) {
   }
   defer session.Close()
 
-  first, mode, changed, err := session.Snapshot()
+  first, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -31,7 +36,7 @@ func TestServeSessionReusesUnchangedSnapshot(t *testing.T) {
     t.Fatalf("initial snapshot = dump:%v mode:%q changed:%v", first != nil, mode, changed)
   }
 
-  second, mode, changed, err := session.Snapshot()
+  second, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_session_revisits_source_edited_during_load_test.go

@@ -13,12 +13,18 @@ import (
 //
 // Hashing the raw disk bytes at capture time would bless content the resident
 // program never parsed: disk and graph would disagree until an unrelated
-// change. The capture must hash the resident text instead, so the next
-// snapshot sees the disk mismatch and applies the missed edit.
+// change. Capture compares decoded disk text with resident text and marks a
+// mismatch for revisiting, so the next snapshot applies the missed edit. This
+// unit observes the resulting declarations and convergence, not hash values.
 //
 //  1. Load a session, then rewrite the source before capturing state.
 //  2. Take a snapshot and assert it refreshes to the on-disk declaration.
 //  3. Take another snapshot and assert the session has converged (unchanged).
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a source edited between compiler load and state capture is refreshed on the next snapshot.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: a source rewritten after the compiler loaded but before state capture must give a first snapshot that is changed and whose dump contains EditedDuringLoad and not BeforeEdit, followed by a second snapshot that is mode unchanged with no dump (converged). The first snapshot's mode is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Load a session, then rewrite the source before capturing state; Take a snapshot and assert it refreshes to the on-disk declaration; Take another snapshot and assert the session has converged (unchanged).
+// @evidence contracts/testing.md#execution-ownership TestServeSessionRevisitsSourceEditedDuringLoad 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 TestServeSessionRevisitsSourceEditedDuringLoad(t *testing.T) {
   root := graphSessionFixture(t)
   compiler, diags, err := driver.NewSession(root, "tsconfig.json", driver.LoadProgramOptions{})
@@ -28,10 +34,6 @@ func TestServeSessionRevisitsSourceEditedDuringLoad(t *testing.T) {
   if compiler == nil {
     t.Fatalf("NewSession returned nil session (diagnostics: %v)", diags)
   }
-  file := filepath.Join(root, "src", "index.ts")
-  if err := os.WriteFile(file, []byte("export class EditedDuringLoad {}\n"), 0o644); err != nil {
-    t.Fatal(err)
-  }
   session := &graphSession{
     cwd:         root,
     tsconfig:    "tsconfig.json",
@@ -39,11 +41,19 @@ func TestServeSessionRevisitsSourceEditedDuringLoad(t *testing.T) {
     initialized: true,
   }
   defer session.Close()
+  file := filepath.Join(root, "src", "index.ts")
+  resident, ok := compiler.SourceText(file)
+  if !ok || resident != "export class BeforeEdit {}\n" {
+    t.Fatalf("resident source before disk edit = found:%v text:%q", ok, resident)
+  }
+  if err := os.WriteFile(file, []byte("export class EditedDuringLoad {}\n"), 0o644); err != nil {
+    t.Fatal(err)
+  }
   if err := session.captureState(); err != nil {
     t.Fatal(err)
   }
 
-  dump, _, changed, err := session.Snapshot()
+  dump, _, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -51,7 +61,7 @@ func TestServeSessionRevisitsSourceEditedDuringLoad(t *testing.T) {
     t.Fatalf("edited-during-load source was not refreshed: dump:%v changed:%v", dump != nil, changed)
   }
 
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }