ttsc 0.30.3 → 0.31.0

package/cmd/ttscgraph/serve_projects_an_artifact_no_source_owns_test.go

@@ -11,20 +11,19 @@ import (
 // TestServeProjectsAnArtifactNoSourceOwns verifies that a session carrying
 // published artifacts can produce a shard snapshot at all.
 //
-// The shard projection assigns every node to the source that owns it, and fails
-// closed when a node names a file the manifest does not carry — a guard that is
-// right for a declaration, whose file is always a program source. A published
-// artifact has no such file: it is a Markdown document, a Prisma schema, or, for
-// an operation named by method and path, nothing at all. So the guard rejected
-// it and the resident session failed to start for any project that publishes
-// one, which is the whole product surface.
+// A document-backed artifact and a fileless operation are not program source
+// nodes. Both must survive projection, while each source-bearing shard must
+// contain only nodes from its named source. This test observes node membership
+// and source ownership, not client validation or every artifact kind.
 //
-// The metadata shard is where facts no source owns belong, and the client
-// exempts it from the ownership check for that reason.
-//
-//  1. Build a session over a one-file project, carrying one artifact.
+//  1. Build a session over a one-file project, carrying two artifacts.
 //  2. Take a full shard snapshot.
 //  3. Assert it succeeded and that the artifact is in it.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies that a session carrying published artifacts can produce a shard snapshot at all.
+// @evidence contracts/testing.md#independent-expectations Literal supplied addresses docs/sale.md#pricing and POST:/orders must each appear in an upserted shard; the latter has no file. Any source-bearing shard must contain only nodes from its source file. The session must carry the artifactNodes capability and a nonnil artifact producer. These assertions detect rejection or source misassignment of these artifacts, without certifying producer metadata contents or a particular metadata-shard key.
+// @evidence contracts/testing.md#distinguishing-cases A document-backed artifact versus a fileless operation share one program fixture; full projection must include both, source-bearing shards must obey their ownership boundary, and the session must retain its capability and producer claim.
+// @evidence contracts/testing.md#execution-ownership TestServeProjectsAnArtifactNoSourceOwns is a Go source-unit entry. It builds a resident session with newGraphSessionWithArtifacts and projects a full shard snapshot through projectFullGraphShards with explicit empty ignore membership; the compiler session is real and in-process, with no installed consumer, native build or Git acquisition.
 func TestServeProjectsAnArtifactNoSourceOwns(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -57,7 +56,7 @@ export function priced(): void {}
   }
   defer func() { _ = session.Close() }()
 
-  snapshot, _, err := session.buildFullShardSnapshot()
+  snapshot, _, err := projectFullGraphShards(session)
   if err != nil {
     t.Fatalf("the shard projection rejected a published artifact: %v", err)
   }
@@ -77,10 +76,8 @@ export function priced(): void {}
     }
   }
 
-  // The session's own claim, which is what the envelope answers with. An
-  // `unchanged` response carries no dump, so the envelope is the only place a
-  // client can learn this server holds artifacts; a shared constant there made
-  // the envelope and the dump disagree on exactly that frame.
+  // Observe the session's claim directly. This test does not send an unchanged
+  // request or validate a client's handling of the response envelope.
   if !slices.Contains(session.capabilities(), graph.CapabilityArtifactNodes) {
     t.Fatalf("a session holding artifacts declares %v", session.capabilities())
   }

package/cmd/ttscgraph/serve_protocol_fails_the_stream_on_an_unaddressable_request_line_test.go

@@ -10,18 +10,19 @@ import (
 // malformed NDJSON line ends the stream with a diagnostic on stderr instead of
 // answering with a reply nobody can read.
 //
-// The server used to answer an unparseable line with an error carrying the zero
-// ID, because none could be parsed. That reply had no addressee: the launcher
-// matches a response to a pending request by id and drops anything else, and its
-// ids start at 1, so the frame was discarded and the caller's promise never
-// settled — a graph call hung forever on a line the client itself sent. There is
-// no recoverable reading of a line the protocol cannot address, so failing the
-// stream is the honest outcome: the exit carries this stderr to the client,
-// which rejects every pending request with it.
+// The malformed first line cannot supply an addressed request. This source
+// operation must return failure with a diagnostic and no response bytes, even
+// though a valid request follows it. Client promise settlement and OS process
+// exit propagation are not exercised here.
 //
 //  1. Send a non-JSON line, then a valid request that must never be served.
-//  2. Assert serveSnapshots exits non-zero and names the offending line.
+//  2. Assert serveSnapshots returns nonzero and the diagnostic names the failure category.
 //  3. Assert no response frame was written, since none could be addressed.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a malformed NDJSON line ends the stream with a diagnostic on stderr instead of answering with a reply nobody can read.
+// @evidence contracts/testing.md#independent-expectations The expectation is the protocol rule that a line with no parsable id cannot be answered: a non-JSON line followed by a valid request must produce a nonzero exit, the stderr text 'unaddressable serve request', and zero bytes on the output stream, so the later valid request is never served. A server that replied with a zero-id error frame fails the empty-output check.
+// @evidence contracts/testing.md#distinguishing-cases Send a non-JSON line followed by a valid request; require a nonzero returned status and the literal unaddressable serve request diagnostic category; require zero output bytes, including no response to the later valid request.
+// @evidence contracts/testing.md#execution-ownership TestServeProtocolFailsTheStreamOnAnUnaddressableRequestLine is a Go source-unit entry. It calls serveSnapshots in-process; the first line fails JSON decoding before any session or Git acquisition happens, so nothing is installed, built or launched.
 func TestServeProtocolFailsTheStreamOnAnUnaddressableRequestLine(t *testing.T) {
   root := graphSessionFixture(t)
   oldStderr := stderr

package/cmd/ttscgraph/serve_protocol_negotiates_incremental_shards_test.go

@@ -10,12 +10,23 @@ import (
 // TestServeProtocolNegotiatesIncrementalShards pins the opt-in boundary between
 // existing full-dump clients and the native shard protocol. A negotiated first
 // response carries one complete manifest and transaction, while the following
-// no-op carries neither a dump nor a shard payload.
+// no-op carries neither a dump nor a shard payload. Completeness here means
+// structural correspondence of manifest keys and upserts, not independent
+// authentication of the graph facts or digest bytes.
+//
+// 1. Submit protocol version one requests over a real resident source fixture.
+// 2. Read the initial shard envelope and then the unchanged response from the NDJSON operation.
+// 3. Require initial sequence one, base zero, a complete nonempty manifest and matching upserts with no deletes or legacy dump; require no unchanged payload.
+//
+// @evidence contracts/testing.md#behavioral-verification With graphSnapshotVersion 1 the real NDJSON serve loop answers the first request with a complete shard transaction (sequence 1, base 0, non-empty manifest, one upsert per manifest entry, no deletes, no legacy dump) and answers the second with an unchanged response carrying neither dump nor snapshot.
+// @evidence contracts/testing.md#independent-expectations The shard contract supplies literal sequence 1, base sequence 0, empty base generation and no deletes. Each nonempty unique manifest key must have exactly one upsert with the same digest, rather than merely an equal count. The unedited second request must be unchanged without payload. Digest bytes and completeness of semantic graph facts are not independently authenticated.
+// @evidence contracts/testing.md#distinguishing-cases Submit protocol version one requests over a real resident source fixture. Read the initial shard envelope and then the unchanged response from the NDJSON operation. Require initial sequence one, base zero, a complete nonempty manifest and matching upserts with no deletes or legacy dump; require no unchanged payload.
+// @evidence contracts/testing.md#execution-ownership TestServeProtocolNegotiatesIncrementalShards is a Go source-unit entry. serveSnapshotRequests performs actual NDJSON decoding and resident lifecycle through the source publisher; prepared projection consumes 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 TestServeProtocolNegotiatesIncrementalShards(t *testing.T) {
   root := graphSessionFixture(t)
   input := strings.NewReader("{\"id\":1,\"graphSnapshotVersion\":1}\n{\"id\":2,\"graphSnapshotVersion\":1}\n")
   var output bytes.Buffer
-  if code := serveSnapshots(input, &output, root, "tsconfig.json"); code != 0 {
+  if code := serveSourceSnapshots(input, &output, root, "tsconfig.json"); code != 0 {
     t.Fatalf("serveSnapshots exited %d", code)
   }
 
@@ -38,6 +49,30 @@ func TestServeProtocolNegotiatesIncrementalShards(t *testing.T) {
   if len(snapshot.Manifest) == 0 || len(snapshot.Upserts) != len(snapshot.Manifest) || len(snapshot.Deletes) != 0 {
     t.Fatalf("initial transaction is not complete: manifest=%d upserts=%d deletes=%d", len(snapshot.Manifest), len(snapshot.Upserts), len(snapshot.Deletes))
   }
+  manifest := map[string]string{}
+  for _, entry := range snapshot.Manifest {
+    if entry.Key == "" || entry.Digest == "" {
+      t.Fatalf("initial manifest has an empty key or digest: %#v", entry)
+    }
+    if _, exists := manifest[entry.Key]; exists {
+      t.Fatalf("initial manifest repeats key %q", entry.Key)
+    }
+    manifest[entry.Key] = entry.Digest
+  }
+  seen := map[string]bool{}
+  for _, upsert := range snapshot.Upserts {
+    key := upsert.Shard.Key
+    digest, exists := manifest[key]
+    if !exists || seen[key] || upsert.Digest != digest {
+      t.Fatalf("initial upsert does not uniquely match its manifest entry: %#v", upsert)
+    }
+    seen[key] = true
+  }
+  for key := range manifest {
+    if !seen[key] {
+      t.Fatalf("initial transaction omits manifest key %q", key)
+    }
+  }
   if unchanged.Error != "" || unchanged.Mode != serveModeUnchanged || unchanged.Changed || unchanged.Dump != nil || unchanged.Snapshot != nil {
     t.Fatalf("negotiated unchanged response: %#v", unchanged)
   }

package/cmd/ttscgraph/serve_protocol_retries_session_creation_test.go

@@ -35,12 +35,17 @@ func (r *stepReader) Read(p []byte) (int, error) {
 //
 // The MCP server starts the native process lazily, so the first request may
 // hit a broken tsconfig. Failing session creation must stay per-request: the
-// server keeps running, and once the config is fixed the same process builds
+// request loop keeps running, and once the config is fixed the same loop builds
 // the session and serves the initial dump.
 //
 //  1. Request a snapshot while tsconfig.json is invalid; assert an error.
 //  2. Fix the config between requests, request again.
 //  3. Assert the second response is a normal initial snapshot.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a project that is invalid at startup answers with an error and recovers on a later request.
+// @evidence contracts/testing.md#independent-expectations The expected outcome is literal: request 1 over an invalid tsconfig returns an error for id 1 with no dump and not changed, and after the test rewrites the config from a stepped reader between requests, request 2 returns mode initial, changed, with a dump containing the Recovered class from the fixture source. A loop that cached the failure or exited would fail.
+// @evidence contracts/testing.md#distinguishing-cases Request a snapshot while tsconfig.json is invalid; assert an error; Fix the config between requests, request again; Assert the second response is a normal initial snapshot.
+// @evidence contracts/testing.md#execution-ownership TestServeProtocolRetriesSessionCreation is a Go source-unit entry. serveSnapshotRequests performs actual NDJSON decoding and resident lifecycle through the source publisher; prepared projection consumes 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 TestServeProtocolRetriesSessionCreation(t *testing.T) {
   root := t.TempDir()
   config := filepath.Join(root, "tsconfig.json")
@@ -59,7 +64,7 @@ func TestServeProtocolRetriesSessionCreation(t *testing.T) {
   }}
   var output bytes.Buffer
 
-  if code := serveSnapshots(input, &output, root, "tsconfig.json"); code != 0 {
+  if code := serveSourceSnapshots(input, &output, root, "tsconfig.json"); code != 0 {
     t.Fatalf("serveSnapshots exited %d", code)
   }
   decoder := json.NewDecoder(&output)

package/cmd/ttscgraph/serve_protocol_reuses_session_test.go

@@ -7,14 +7,24 @@ import (
   "testing"
 )
 
-// TestServeProtocolReusesSession verifies multiple NDJSON requests share one
-// compiler session and unchanged responses omit the full dump.
+// TestServeProtocolReusesSession verifies initial then unchanged responses on
+// one NDJSON stream, with no dump on the unchanged response. It observes the
+// reported reuse behavior, not compiler-construction counts or object identity.
+//
+// 1. Load the resident fixture and submit requests with IDs one and two.
+// 2. Decode both responses from one NDJSON operation.
+// 3. Require an initial changed dump for ID one and unchanged with no dump for ID two.
+//
+// @evidence contracts/testing.md#behavioral-verification On one NDJSON stream, id 1 reports initial with a changed dump and id 2 over unedited sources reports unchanged, not changed and no dump. The assertions own these response distinctions; they do not observe compiler-construction counts or session object identity.
+// @evidence contracts/testing.md#independent-expectations Literal serve-contract modes initial then unchanged, IDs 1 and 2, and the second response's absent dump are independent expected outcomes for the unedited fixture. Repeating an initial response or returning a dump on unchanged fails. A hidden reconstruction that preserved all these responses would remain indistinguishable.
+// @evidence contracts/testing.md#distinguishing-cases Load the resident fixture and submit requests with IDs one and two. Decode both responses from one NDJSON operation. Require an initial changed dump for ID one and unchanged with no dump for ID two.
+// @evidence contracts/testing.md#execution-ownership TestServeProtocolReusesSession is a Go source-unit entry. serveSnapshotRequests performs actual NDJSON decoding and resident lifecycle through the source publisher; prepared projection consumes 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 TestServeProtocolReusesSession(t *testing.T) {
   root := graphSessionFixture(t)
   input := strings.NewReader("{\"id\":1}\n{\"id\":2}\n")
   var output bytes.Buffer
 
-  if code := serveSnapshots(input, &output, root, "tsconfig.json"); code != 0 {
+  if code := serveSourceSnapshots(input, &output, root, "tsconfig.json"); code != 0 {
     t.Fatalf("serveSnapshots exited %d", code)
   }
   decoder := json.NewDecoder(&output)

package/cmd/ttscgraph/serve_session_applies_source_edit_incrementally_test.go

@@ -11,13 +11,18 @@ import (
 // TestServeSessionAppliesSourceEditIncrementally verifies a content-only source
 // edit updates the graph through the resident tsgo Program.
 //
-// A declaration rename changes graph nodes but not imports, so UpdateProgram can
-// reuse every unchanged AST. The new dump must expose the replacement symbol
-// and remove the old one without reopening the project.
+// The same-file declaration rename must report incremental mode, expose the
+// replacement name and remove the old name. Those observations do not count
+// compiler constructions, establish unchanged AST identity, or cover every node.
 //
-// 1. Build the initial graph containing `BeforeEdit`.
+// 1. Request the initial graph for the fixture declaring `BeforeEdit`.
 // 2. Replace it with `AfterEdit` in the same source file.
-// 3. Assert incremental mode and an exact post-edit node set.
+// 3. Assert incremental mode, `AfterEdit` present and `BeforeEdit` absent.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a content-only source edit updates the graph through the resident tsgo Program.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: after the single source file's class is renamed from BeforeEdit to AfterEdit on disk, the second snapshot must report mode incremental and changed, contain a node named AfterEdit and no node named BeforeEdit. Only those two names are checked, not the whole node set.
+// @evidence contracts/testing.md#distinguishing-cases Build the initial graph, replace the class in the same source file, then assert incremental mode, the new node present and the old node absent. A reload or rebuild mode, or a stale old node, fails; edits to imports or declaration files are owned by other cases.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionAppliesSourceEditIncrementally 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 TestServeSessionAppliesSourceEditIncrementally(t *testing.T) {
   root := graphSessionFixture(t)
   session, err := newGraphSession(root, "tsconfig.json")
@@ -25,7 +30,7 @@ func TestServeSessionAppliesSourceEditIncrementally(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -33,7 +38,7 @@ func TestServeSessionAppliesSourceEditIncrementally(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_fails_closed_on_deleted_config_test.go

@@ -12,14 +12,19 @@ import (
 // The boundary twin of the invalid-config case: deletion takes the
 // hashesChanged ErrNotExist branch and its forced reload fails at session
 // construction rather than config parsing. A byte-identical restore must then
-// report unchanged — the resident graph still matches the disk exactly — and
-// the compiler session must keep serving incremental edits, proving the
-// failed reload episode left no partial state behind.
+// report unchanged, and a later source rename must report incremental with
+// AfterEdit present. These selected recovery outcomes do not certify every
+// internal state field or every graph fact after the failed reload.
 //
 //  1. Build a valid initial graph, then delete tsconfig.json.
 //  2. Assert the snapshot fails with no dump.
 //  3. Restore the identical config and assert the snapshot is unchanged.
 //  4. Edit the source and assert an incremental refresh still works.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies removing the project config fails the snapshot without poisoning the resident session.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal session outcomes over a fixture whose config is deleted and then restored byte-identical: the failing snapshot must return an error with no dump and changed false, the restored config must yield mode unchanged with no dump, and a following source rename must yield mode incremental with the AfterEdit node. A session that served the cached graph, or stayed broken after the failed reload, fails.
+// @evidence contracts/testing.md#distinguishing-cases Build a valid initial graph, delete tsconfig.json and require an error with no dump; restore the identical bytes and require unchanged; edit the source and require an incremental refresh. The deleted-config case is the ErrNotExist twin of the invalid-config case, which is owned by another test.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionFailsClosedOnDeletedConfig 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 TestServeSessionFailsClosedOnDeletedConfig(t *testing.T) {
   root := graphSessionFixture(t)
   session, err := newGraphSession(root, "tsconfig.json")
@@ -27,7 +32,7 @@ func TestServeSessionFailsClosedOnDeletedConfig(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -39,7 +44,7 @@ func TestServeSessionFailsClosedOnDeletedConfig(t *testing.T) {
   if err := os.Remove(config); err != nil {
     t.Fatal(err)
   }
-  dump, _, changed, err := session.Snapshot()
+  dump, _, changed, err := snapshotGraphState(session)
   if err == nil || dump != nil || changed {
     t.Fatalf("deleted config must fail closed: dump:%v changed:%v err:%v", dump != nil, changed, err)
   }
@@ -47,7 +52,7 @@ func TestServeSessionFailsClosedOnDeletedConfig(t *testing.T) {
   if err := os.WriteFile(config, saved, 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -58,7 +63,7 @@ func TestServeSessionFailsClosedOnDeletedConfig(t *testing.T) {
   if err := os.WriteFile(filepath.Join(root, "src", "index.ts"), []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_fails_closed_on_invalid_config_test.go

@@ -16,6 +16,11 @@ import (
 // 1. Build a valid initial graph, then replace tsconfig.json with invalid JSON.
 // 2. Assert snapshot fails with no dump instead of serving the cached graph.
 // 3. Restore a valid config and assert the next request reloads successfully.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a broken project config never falls back to the last valid graph and recovers after the config is fixed.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: with tsconfig.json replaced by invalid JSON the snapshot must return an error with no dump and changed false (no stale graph), and after the valid config is restored the next snapshot must be mode reload, changed, with a dump that still contains the BeforeEdit class from the fixture source.
+// @evidence contracts/testing.md#distinguishing-cases Build a valid initial graph, then replace tsconfig.json with invalid JSON; Assert snapshot fails with no dump instead of serving the cached graph; Restore a valid config and assert the next request reloads successfully.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionFailsClosedOnInvalidConfig 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 TestServeSessionFailsClosedOnInvalidConfig(t *testing.T) {
   root := graphSessionFixture(t)
   session, err := newGraphSession(root, "tsconfig.json")
@@ -23,7 +28,7 @@ func TestServeSessionFailsClosedOnInvalidConfig(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 +36,7 @@ func TestServeSessionFailsClosedOnInvalidConfig(t *testing.T) {
   if err := os.WriteFile(config, []byte("{ invalid"), 0o644); err != nil {
     t.Fatal(err)
   }
-  dump, _, changed, err := session.Snapshot()
+  dump, _, changed, err := snapshotGraphState(session)
   if err == nil || dump != nil || changed {
     t.Fatalf("invalid config must fail closed: dump:%v changed:%v err:%v", dump != nil, changed, err)
   }
@@ -40,7 +45,7 @@ func TestServeSessionFailsClosedOnInvalidConfig(t *testing.T) {
   if err := os.WriteFile(config, []byte(valid), 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_keeps_base_url_fallback_unchanged_test.go

@@ -16,6 +16,11 @@ import (
 //  1. Load a paths import whose configured fallback target exists.
 //  2. Create only the corresponding baseUrl-style file.
 //  3. Assert the session remains unchanged because the paths target still wins.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies an unmatched baseUrl-style file does not invalidate a paths resolution.
+// @evidence contracts/testing.md#independent-expectations The expected outcome follows from the pinned TypeScript-Go resolver behavior stated in the test: a matching paths substitution does not fall back to baseUrl, so creating @generated/value.ts at the project root cannot change the resolved module and the snapshot must be unchanged with no dump. A resident session that tracked a baseUrl probe would report a reload.
+// @evidence contracts/testing.md#distinguishing-cases Load a paths import whose configured fallback target exists; Create only the corresponding baseUrl-style file; Assert the session remains unchanged because the paths target still wins.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsBaseURLFallbackUnchanged 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 TestServeSessionKeepsBaseURLFallbackUnchanged(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -35,11 +40,11 @@ func TestServeSessionKeepsBaseURLFallbackUnchanged(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, "@generated", "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)
   }

package/cmd/ttscgraph/serve_session_keeps_change_detection_live_after_initial_dump_error_test.go

@@ -0,0 +1,66 @@
+package main
+
+import (
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestServeSessionKeepsChangeDetectionLiveAfterInitialDumpError verifies a
+// rejected first dump still advances the session into its change-detection
+// state. The invalid relative cwd is a deterministic path-mapper failure; once
+// corrected, the same captured generation is retried and can become the first
+// published snapshot.
+//
+// 1. Capture the initial program and use a relative project root to force projection failure.
+// 2. Repair the root and retry the same resident change.
+// 3. Require the first error to keep initialized change detection and an initial pending change, then publish the initial dump after repair.
+//
+// @evidence contracts/testing.md#behavioral-verification When the first dump fails (a relative project root is rejected as not absolute), the session still marks itself initialized and keeps an initial pending change, and after the root is repaired the same generation is published as an initial changed dump.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: the first snapshot must error with text containing 'project root', return no dump and changed false, leave initialized true and a pending change whose mode is initial, and after repairing the root return mode initial, changed, with a dump. The relative root is the deterministic failure injector.
+// @evidence contracts/testing.md#distinguishing-cases Capture the initial program and use a relative project root to force projection failure. Repair the root and retry the same resident change. Require the first error to keep initialized change detection and an initial pending change, then publish the initial dump after repair.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsChangeDetectionLiveAfterInitialDumpError 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 TestServeSessionKeepsChangeDetectionLiveAfterInitialDumpError(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,
+  }
+  defer session.Close()
+  if err := session.captureState(); err != nil {
+    t.Fatal(err)
+  }
+  session.cwd = "relative-project"
+
+  dump, _, changed, err := snapshotGraphState(session)
+  if err == nil || !strings.Contains(err.Error(), "project root") {
+    t.Fatalf("initial dump error = %v, want absolute-root rejection", err)
+  }
+  if dump != nil || changed || !session.initialized || session.pending == nil || session.pending.mode != serveModeInitial {
+    t.Fatalf(
+      "failed initial state = dump:%v changed:%v initialized:%v pending:%#v",
+      dump != nil,
+      changed,
+      session.initialized,
+      session.pending,
+    )
+  }
+
+  session.cwd = root
+  dump, mode, changed, err := snapshotGraphState(session)
+  if err != nil {
+    t.Fatal(err)
+  }
+  if dump == nil || mode != serveModeInitial || !changed {
+    t.Fatalf("repaired initial dump = dump:%v mode:%q changed:%v", dump != nil, mode, changed)
+  }
+}

package/cmd/ttscgraph/serve_session_keeps_esm_directory_candidate_unchanged_test.go

@@ -13,6 +13,15 @@ import (
 // it never performs the CommonJS value/package.json or value/index.* lookup in
 // ESM mode. Those directory members must therefore stay out of a resident
 // session's freshness inputs.
+//
+// 1. Load an ESM value.js import with a resolved JavaScript fallback.
+// 2. Create a directory package candidate, then the higher-priority value.ts candidate.
+// 3. Require the directory candidate to leave the session unchanged and value.ts to reload with typescriptWinner.
+//
+// @evidence contracts/testing.md#behavioral-verification In nodenext ESM mode, creating a value/ directory with package.json and index.ts does not change a resident session that resolves ./value.js to the JavaScript file, while creating the higher-priority value.ts reloads it and the new dump contains typescriptWinner.
+// @evidence contracts/testing.md#independent-expectations The expected outcomes come from the TypeScript resolution rule the test cites (ESM mode substitutes value.ts for value.js but never probes the CommonJS directory/index lookup): the directory creation must be unchanged with no dump, and creating value.ts must be mode reload with a node named typescriptWinner. A session that tracked directory probes would reload on the first step.
+// @evidence contracts/testing.md#distinguishing-cases Load an ESM value.js import with a resolved JavaScript fallback. Create a directory package candidate, then the higher-priority value.ts candidate. Require the directory candidate to leave the session unchanged and value.ts to reload with typescriptWinner.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsESMDirectoryCandidateUnchanged 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 TestServeSessionKeepsESMDirectoryCandidateUnchanged(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "package.json"), `{"type":"module"}`)
@@ -33,7 +42,7 @@ func TestServeSessionKeepsESMDirectoryCandidateUnchanged(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if _, _, _, err := session.Snapshot(); err != nil {
+  if _, _, _, err := snapshotGraphState(session); err != nil {
     t.Fatal(err)
   }
 
@@ -42,7 +51,7 @@ func TestServeSessionKeepsESMDirectoryCandidateUnchanged(t *testing.T) {
   }
   writeGraphFile(t, filepath.Join(root, "src", "value", "package.json"), `{"type":"module"}`)
   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)
   }
@@ -51,7 +60,7 @@ func TestServeSessionKeepsESMDirectoryCandidateUnchanged(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_exports_blocked_file_candidates_unchanged_test.go

@@ -18,6 +18,11 @@ import (
 //  2. Create an unlisted file at the bare subpath without changing package.json.
 //  3. Assert the session is unchanged, then create the export-map target that
 //     genuinely precedes the fallback and assert it reloads.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies a package export map prevents unlisted bare-file candidates from invalidating a resident session.
+// @evidence contracts/testing.md#independent-expectations The expected outcomes follow from package export-map semantics: with exports listing only ./dist/first.js and ./dist/fallback.js, creating the unlisted node_modules/fixture-package/feature.ts must leave the snapshot unchanged with no dump, whereas creating the listed, earlier dist/first.js must produce mode reload, changed, with a dump. The reload assertion does not check the new export's node.
+// @evidence contracts/testing.md#distinguishing-cases Load a package subpath resolved through its export-map fallback target; Create an unlisted file at the bare subpath without changing package.json; Assert the session is unchanged, then create the export-map target that genuinely precedes the fallback and assert it reloads.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsExportsBlockedFileCandidatesUnchanged 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 TestServeSessionKeepsExportsBlockedFileCandidatesUnchanged(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -41,11 +46,11 @@ func TestServeSessionKeepsExportsBlockedFileCandidatesUnchanged(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", "feature.ts"), "export function winner(): void {}\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -54,7 +59,7 @@ func TestServeSessionKeepsExportsBlockedFileCandidatesUnchanged(t *testing.T) {
   }
 
   writeGraphFile(t, filepath.Join(root, "node_modules", "fixture-package", "dist", "first.js"), "export function winner() {}\nexport function exportsWinner() {}\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_inactive_conditional_export_unchanged_test.go

@@ -12,6 +12,15 @@ import (
 // An inactive branch can be present ahead of the active `types` and `default`
 // branches in package.json, but creating that target must not reload a
 // resident ESM session. Creating the missing active `types` target still must.
+//
+// 1. Load a conditional export with browser, types and default branches and a JavaScript fallback.
+// 2. Create the inactive browser file, then the selected types declaration.
+// 3. Require no dump for the inactive branch and a reload for the selected types branch.
+//
+// @evidence contracts/testing.md#behavioral-verification Creating the file behind an export condition the active nodenext lookup cannot select (browser) leaves a resident session unchanged with no dump, while creating the selected types declaration reloads it.
+// @evidence contracts/testing.md#independent-expectations The expected outcomes follow from package exports condition semantics for the nodenext/types lookup: the browser branch is inactive so creating dist/browser.js must be unchanged with no dump, and creating dist/types.d.ts, which precedes the default fallback, must be mode reload and changed. The reload step asserts the mode and change flag, not the new declaration's node.
+// @evidence contracts/testing.md#distinguishing-cases Load a conditional export with browser, types and default branches and a JavaScript fallback. Create the inactive browser file, then the selected types declaration. Require no dump for the inactive branch and a reload for the selected types branch.
+// @evidence contracts/testing.md#execution-ownership TestServeSessionKeepsInactiveConditionalExportUnchanged 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 TestServeSessionKeepsInactiveConditionalExportUnchanged(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "package.json"), `{"type":"module"}`)
@@ -42,12 +51,12 @@ func TestServeSessionKeepsInactiveConditionalExportUnchanged(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", "browser.js"), "export function winner() {}\nexport function browserOnly() {}\n")
-  dump, mode, changed, err := session.Snapshot()
+  dump, mode, changed, err := snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -56,7 +65,7 @@ func TestServeSessionKeepsInactiveConditionalExportUnchanged(t *testing.T) {
   }
 
   writeGraphFile(t, filepath.Join(root, "node_modules", "fixture-package", "dist", "types.d.ts"), "export declare function winner(): void;\nexport declare function typesWinner(): void;\n")
-  dump, mode, changed, err = session.Snapshot()
+  dump, mode, changed, err = snapshotGraphState(session)
   if err != nil {
     t.Fatal(err)
   }