ttsc 0.30.4 → 0.31.0

package/cmd/ttscgraph/serve_shards_abandoned_generation_converges_on_retry_test.go

@@ -6,21 +6,20 @@ import (
   "testing"
 )
 
-// TestServeShardsAbandonedGenerationConvergesOnRetry verifies a consumer that
-// abandons a request mid-flight can still converge, and that the facts it
-// eventually commits match the ones it discarded.
+// TestServeShardsAbandonedGenerationConvergesOnRetry verifies discarding a returned snapshot does not prevent later convergence.
 //
-// The producer has no abort path: it commits after the projection succeeds, so
-// a client that walks away leaves the producer's committed generation ahead of
-// the consumer's. Cancellation is therefore discharged by base negotiation
-// rather than by cancellation handling, which is sound only if the abandoned
-// generation is not the sole carrier of its facts. A consumer replaying from
-// its own stale base has to receive those same facts again.
+// Publication commits the producer generation before a client consumes its
+// response. A later edit must advance that state again and publish the latest
+// source, rather than replaying the snapshot the client discarded.
 //
-//  1. Commit one generation, then edit and take a generation the client discards.
-//  2. Edit again and take the generation a recovered client would actually read.
-//  3. Require the store to have advanced once per accepted call and the final
-//     shard for the edited source to carry the latest text, not the abandoned one.
+// 1. Commit a generation, edit the source and discard its returned snapshot.
+// 2. Edit again and request the snapshot a recovering client would consume.
+// 3. Require one advance per publication and the latest Converged source facts.
+//
+// @evidence contracts/testing.md#behavioral-verification The source state commits each requested publication even when this caller discards a returned snapshot; a later edit converges on the latest source rather than the abandoned text.
+// @evidence contracts/testing.md#independent-expectations The literal successive source edits distinguish Abandoned from Converged. The committed sequence must advance once per accepted publication, and the final shard must carry Converged; equality with the discarded facts is not expected.
+// @evidence contracts/testing.md#distinguishing-cases Initial publication, a discarded changed response and another source edit distinguish producer commit from client consumption. This direct state case does not simulate a transport cancellation.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsAbandonedGenerationConvergesOnRetry is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsAbandonedGenerationConvergesOnRetry(t *testing.T) {
   root := graphSessionFixture(t)
   session, err := newGraphSession(root, "tsconfig.json")
@@ -28,10 +27,13 @@ func TestServeShardsAbandonedGenerationConvergesOnRetry(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  committed, _, _, err := session.SnapshotShards()
+  committed, _, _, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
+  if committed == nil || committed.Sequence != 1 || committed.Generation == "" {
+    t.Fatalf("initial committed generation = %#v", committed)
+  }
   file := filepath.Join(root, "src", "index.ts")
   indexSource := session.compiler.Program().SourceFile(file)
   if indexSource == nil {
@@ -43,14 +45,20 @@ func TestServeShardsAbandonedGenerationConvergesOnRetry(t *testing.T) {
   if err := os.WriteFile(file, []byte("export class Abandoned {}\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  abandoned, _, changed, err := session.SnapshotShards()
+  abandoned, _, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
   if abandoned == nil || !changed || abandoned.BaseGeneration != committed.Generation {
     t.Fatalf("abandoned generation = snapshot:%#v changed:%v", abandoned, changed)
   }
+  if abandoned.Sequence != committed.Sequence+1 {
+    t.Fatalf("abandoned sequence = %d, want %d", abandoned.Sequence, committed.Sequence+1)
+  }
   abandonedKey := session.graphStore.sourceKeys[indexKeyFile]
+  if abandonedKey == "" {
+    t.Fatal("abandoned source has no committed shard key")
+  }
 
   // The producer moved on regardless. A later edit plus the client's retry has
   // to publish a generation that supersedes the abandoned one rather than
@@ -58,7 +66,7 @@ func TestServeShardsAbandonedGenerationConvergesOnRetry(t *testing.T) {
   if err := os.WriteFile(file, []byte("export class Converged {}\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  converged, _, changed, err := session.SnapshotShards()
+  converged, _, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -82,6 +90,23 @@ func TestServeShardsAbandonedGenerationConvergesOnRetry(t *testing.T) {
   if !containsUpsertedShardKey(converged, convergedKey) {
     t.Fatalf("converged generation did not publish the latest shard %q", convergedKey)
   }
+  foundConverged := false
+  for _, upsert := range converged.Upserts {
+    if upsert.Shard.Key != convergedKey {
+      continue
+    }
+    for _, node := range upsert.Shard.Nodes {
+      if node.Name == "Abandoned" {
+        t.Error("latest source shard retained the abandoned declaration")
+      }
+      if node.Name == "Converged" {
+        foundConverged = true
+      }
+    }
+  }
+  if !foundConverged {
+    t.Error("latest source shard omitted the literal Converged declaration")
+  }
   if !containsString(converged.Deletes, abandonedKey) {
     t.Fatalf(
       "converged generation did not supersede the abandoned shard %q: %v",

package/cmd/ttscgraph/serve_shards_delete_removed_source_test.go

@@ -7,8 +7,18 @@ import (
 )
 
 // TestServeShardsDeleteRemovedSource verifies a root-set reload names the
-// superseded source shard explicitly while publishing a complete replacement
-// generation. A consumer never has to infer deletion from a missing payload.
+// removed source shard explicitly in Deletes and retains a committed key for
+// the other source. Complete replacement payloads and consumer application are
+// not observed here.
+//
+// 1. Publish index.ts and keep.ts as the initial source shards.
+// 2. Delete index.ts and publish the resulting source change.
+// 3. Require a reload delta based on the initial generation, deletion of the removed key and retention of the keep key.
+//
+// @evidence contracts/testing.md#behavioral-verification Deleting a root source makes the next shard snapshot a reload delta based on the initial generation that names the removed source's shard key in Deletes while the remaining source has a nonempty key in the committed store. Equality with its old key, complete payload membership, and consumer application are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over a two-source fixture: after src/index.ts is removed the snapshot must be mode reload and changed with BaseGeneration equal to the initial generation, its Deletes must contain the shard key the store held for index.ts, and the committed store must drop index.ts and keep a key for keep.ts.
+// @evidence contracts/testing.md#distinguishing-cases Publish index.ts and keep.ts as the initial source shards. Delete index.ts and publish the resulting source change. Require a reload delta based on the initial generation, deletion of the removed key and retention of the keep key.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsDeleteRemovedSource is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsDeleteRemovedSource(t *testing.T) {
   root := graphSessionFixture(t)
   keep := filepath.Join(root, "src", "keep.ts")
@@ -18,7 +28,7 @@ func TestServeShardsDeleteRemovedSource(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  initial, _, _, err := session.SnapshotShards()
+  initial, _, _, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -38,7 +48,7 @@ func TestServeShardsDeleteRemovedSource(t *testing.T) {
     t.Fatal(err)
   }
 
-  replacement, mode, changed, err := session.SnapshotShards()
+  replacement, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_shards_external_endpoints_test.go

@@ -6,6 +6,22 @@ import (
   "testing"
 )
 
+// TestServeShardsKeepReferencedExternalEndpointsOnIncrementalLane verifies an incremental local edit retains its referenced external endpoint.
+//
+// A partial projection must not prune an ambient callable still named by a local
+// edge. The full projection comparison checks another publication lane, while
+// both lanes continue to share the compiler and extraction helpers. This unit
+// independently checks the cached endpoint name and External flag, not the
+// local call edge or its endpoints.
+//
+// 1. Load an ambient external declaration and a local call to it.
+// 2. Publish the base, then change only the local implementation body.
+// 3. Require incremental publication, endpoint retention and full-lane agreement.
+//
+// @evidence contracts/testing.md#behavioral-verification An incremental private-body edit whose authored source continues to call external retains a cached node named external with External true. The local call edge and its endpoints are not independently asserted.
+// @evidence contracts/testing.md#independent-expectations The literal local body continues to call external, so that endpoint must remain in the committed node cache. Canonical facts are also compared with the full projection lane over the same compiler; the shared compiler and extraction helpers mean that comparison is not an independent checker oracle.
+// @evidence contracts/testing.md#distinguishing-cases Initial publication, a local body-only edit, the incremental mode and the still-referenced external endpoint contrast a retained dependency with the separate last-reference removal case.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit entry calls newGraphSession and snapshotGraphShardState, which complete the actual prepared state transaction with explicit empty ignore membership; real Git acquisition remains in the worktree E2E.
 func TestServeShardsKeepReferencedExternalEndpointsOnIncrementalLane(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -21,13 +37,13 @@ func TestServeShardsKeepReferencedExternalEndpointsOnIncrementalLane(t *testing.
     t.Fatal(err)
   }
   defer session.Close()
-  if snapshot, _, _, err := session.SnapshotShards(); err != nil || snapshot == nil {
+  if snapshot, _, _, err := snapshotGraphShardState(session); err != nil || snapshot == nil {
     t.Fatalf("initial shard snapshot = snapshot:%v error:%v", snapshot != nil, err)
   }
   if err := os.WriteFile(index, []byte("import { external } from './api';\nexport function local(): number { return external() + 2; }\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  snapshot, mode, changed, err := session.SnapshotShards()
+  snapshot, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_shards_keep_source_distributed_dependencies_at_the_boundary_test.go

@@ -6,14 +6,19 @@ import (
   "testing"
 )
 
-// TestServeShardsKeepSourceDistributedDependenciesAtTheBoundary proves the
-// incremental store owns only workspace declarations while provenance still
-// attests to every source the resident checker loaded.
+// TestServeShardsKeepSourceDistributedDependenciesAtTheBoundary verifies the
+// authored raw dependency has provenance without owning extracted graph facts,
+// while its referenced callable is represented by an external boundary node.
 //
 // 1. Snapshot one workspace source that imports a raw TypeScript package.
 // 2. Assert the dependency owns provenance but no authored graph facts.
 // 3. Edit the dependency and assert the store publishes a complete replacement.
 // 4. Compare the replacement store with the full-dump oracle.
+//
+// @evidence contracts/testing.md#behavioral-verification The authored dep-src dependency has provenance, is absent from extracted files, and owns no shard nodes or edges; its cached boundary nodes are external and named dependencyValue. Its edit reports rebuild, publishes each manifest key with its matching digest, and changes its checker digest. Other loaded sources and dependency packages are not certified.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over a fixture where src/main.ts imports the raw-TypeScript package dep-src: the dependency must appear in provenance sources, must not be in the store's extracted files, its shard must hold no nodes or edges, and all dependency nodes found in the store must be external and named dependencyValue, with at least one found; after editing the dependency the snapshot must be mode rebuild, changed, with one upsert per manifest entry and a changed checker digest for the dependency. The full-projection comparison runs another lane over the same compiler and extraction helpers, so it cannot independently detect a shared checker or extraction defect.
+// @evidence contracts/testing.md#distinguishing-cases Snapshot one workspace source that imports a raw TypeScript package; Assert the dependency owns provenance but no authored graph facts; Edit the dependency and assert the store publishes a complete replacement. 4. Compare the replacement store with the full-dump oracle.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsKeepSourceDistributedDependenciesAtTheBoundary is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsKeepSourceDistributedDependenciesAtTheBoundary(t *testing.T) {
   root := t.TempDir()
   dependencyPath := filepath.Join(root, "node_modules", "dep-src", "src", "index.ts")
@@ -34,7 +39,7 @@ func TestServeShardsKeepSourceDistributedDependenciesAtTheBoundary(t *testing.T)
     t.Fatal(err)
   }
   defer session.Close()
-  if snapshot, _, _, err := session.SnapshotShards(); err != nil || snapshot == nil {
+  if snapshot, _, _, err := snapshotGraphShardState(session); err != nil || snapshot == nil {
     t.Fatalf("initial shard snapshot = snapshot:%v error:%v", snapshot != nil, err)
   }
 
@@ -78,7 +83,7 @@ func TestServeShardsKeepSourceDistributedDependenciesAtTheBoundary(t *testing.T)
   }
 
   writeGraphFile(t, dependencyPath, "export function dependencyValue(): number { return 2; }\nexport function dependencyInternal(): number { return dependencyValue(); }\n")
-  replacement, mode, changed, err := session.SnapshotShards()
+  replacement, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -95,6 +100,32 @@ func TestServeShardsKeepSourceDistributedDependenciesAtTheBoundary(t *testing.T)
     )
   }
   dependencyDigestChanged := false
+  manifestDigests := make(map[string]string, len(replacement.Manifest))
+  if len(replacement.Manifest) == 0 {
+    t.Fatal("replacement manifest is empty")
+  }
+  for _, reference := range replacement.Manifest {
+    if reference.Key == "" || reference.Digest == "" {
+      t.Fatalf("replacement manifest has an empty identity: %#v", reference)
+    }
+    if _, exists := manifestDigests[reference.Key]; exists {
+      t.Fatalf("replacement manifest repeats key %q", reference.Key)
+    }
+    manifestDigests[reference.Key] = reference.Digest
+  }
+  seenUpserts := make(map[string]bool, len(replacement.Upserts))
+  for _, upsert := range replacement.Upserts {
+    digest, exists := manifestDigests[upsert.Shard.Key]
+    if !exists || digest != upsert.Digest || seenUpserts[upsert.Shard.Key] {
+      t.Fatalf("replacement upsert does not match a unique manifest entry: %#v", upsert)
+    }
+    seenUpserts[upsert.Shard.Key] = true
+  }
+  for key := range manifestDigests {
+    if !seenUpserts[key] {
+      t.Fatalf("replacement omitted manifest key %q", key)
+    }
+  }
   for _, source := range session.graphStore.provenance.Sources {
     if source.File == dependencyFile && source.Checker != dependencyDigest {
       dependencyDigestChanged = true

package/cmd/ttscgraph/serve_shards_match_full_dump_oracle_test.go

@@ -15,6 +15,15 @@ import (
 // accepted edit reconstruct exactly the facts the complete builder produces.
 // This keeps shard ownership and base-node reuse as an optimization boundary,
 // never a second semantic contract.
+//
+// 1. Load Base, Impl and a consumer, then publish an initial shard generation.
+// 2. Change a private implementation body and publish incrementally.
+// 3. Require canonical node, edge and diagnostic rows to equal a fresh full projection over the same compiler state; the two projection algorithms share the compiler.
+//
+// @evidence contracts/testing.md#behavioral-verification Require canonical node, edge and diagnostic rows to equal a fresh full projection over the same compiler state; the two projection algorithms share the compiler.
+// @evidence contracts/testing.md#independent-expectations The oracle is differential: after the initial publication and after a private-body edit (mode incremental), the committed shards' node, edge and diagnostic rows, canonicalized by sorted JSON, must equal a fresh complete projection of the same session. The fixture's Base/Impl/consumer sources are literal. The full-projection comparison runs another lane over the same compiler and extraction helpers, so it cannot independently detect a shared checker or extraction defect.
+// @evidence contracts/testing.md#distinguishing-cases Load Base, Impl and a consumer, then publish an initial shard generation. Change a private implementation body and publish incrementally. Require canonical node, edge and diagnostic rows to equal a fresh full projection over the same compiler state; the two projection algorithms share the compiler.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsMatchFullDumpOracle is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsMatchFullDumpOracle(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -30,7 +39,7 @@ func TestServeShardsMatchFullDumpOracle(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if snapshot, _, _, err := session.SnapshotShards(); err != nil || snapshot == nil {
+  if snapshot, _, _, err := snapshotGraphShardState(session); err != nil || snapshot == nil {
     t.Fatalf("initial shard snapshot = snapshot:%v error:%v", snapshot != nil, err)
   }
   assertServeShardFactsMatchFullDump(t, session)
@@ -39,7 +48,7 @@ func TestServeShardsMatchFullDumpOracle(t *testing.T) {
   if err := os.WriteFile(impl, []byte("import { Base } from './base';\nexport class Impl implements Base { run(): void { const touched = true; void touched; } }\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  snapshot, mode, changed, err := session.SnapshotShards()
+  snapshot, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -51,7 +60,7 @@ func TestServeShardsMatchFullDumpOracle(t *testing.T) {
 
 func assertServeShardFactsMatchFullDump(t *testing.T, session *graphSession) {
   t.Helper()
-  complete, err := session.buildDump()
+  complete, err := projectGraphDump(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_shards_merge_pending_and_new_edits_test.go

@@ -10,6 +10,15 @@ import (
 // replace the invalidation closure of an earlier uncommitted generation. Both
 // changed sources must enter the retry transaction before it can advance the
 // shard-store base.
+//
+// 1. Publish index.ts and OtherBefore in a committed shard generation.
+// 2. Change the first file, force a relative-root projection error, repair the root and change the second file.
+// 3. Require the pending first change and new second change to commit together on the incremental lane, clear pending state and match a full projection.
+//
+// @evidence contracts/testing.md#behavioral-verification Require the pending first change and new second change to commit together on the incremental lane, clear pending state and match a full projection.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal states over index.ts and other.ts: a first edit that fails projection with a relative root must leave pending set and the committed generation/sequence unchanged. Recovery after the second edit must be incremental and changed, clear pending, advance the original base once, and contain FirstAfter and OtherAfter without BeforeEdit or OtherBefore. Committed shards also equal a full projection over the same compiler and extraction helpers; that differential comparison cannot independently detect a shared checker or extraction defect.
+// @evidence contracts/testing.md#distinguishing-cases Publish index.ts and OtherBefore in a committed shard generation. Change the first file, force a relative-root projection error, repair the root and change the second file. Require the pending first change and new second change to commit together on the incremental lane, clear pending state and match a full projection.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsMergePendingAndNewEdits is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsMergePendingAndNewEdits(t *testing.T) {
   root := graphSessionFixture(t)
   other := filepath.Join(root, "src", "other.ts")
@@ -19,32 +28,56 @@ func TestServeShardsMergePendingAndNewEdits(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if snapshot, _, _, err := session.SnapshotShards(); err != nil || snapshot == nil {
+  if snapshot, _, _, err := snapshotGraphShardState(session); err != nil || snapshot == nil {
     t.Fatalf("initial snapshot = snapshot:%v error:%v", snapshot != nil, err)
   }
+  initialGeneration := session.graphStore.generation
+  initialSequence := session.graphStore.sequence
 
   first := filepath.Join(root, "src", "index.ts")
   if err := os.WriteFile(first, []byte("export class FirstAfter {}\n"), 0o644); err != nil {
     t.Fatal(err)
   }
   session.cwd = "relative-project"
-  if _, _, _, err := session.SnapshotShards(); err == nil {
+  if _, _, _, err := snapshotGraphShardState(session); err == nil {
     t.Fatal("first edit unexpectedly committed through invalid project root")
   }
   if session.pending == nil {
     t.Fatal("failed first edit left no pending invalidation")
   }
+  if session.graphStore.generation != initialGeneration || session.graphStore.sequence != initialSequence {
+    t.Fatal("failed first edit advanced the committed shard-store base")
+  }
 
   session.cwd = root
   if err := os.WriteFile(other, []byte("export class OtherAfter {}\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  recovered, mode, changed, err := session.SnapshotShards()
+  recovered, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
   if recovered == nil || mode != serveModeIncremental || !changed || session.pending != nil {
     t.Fatalf("merged recovery = snapshot:%v mode:%q changed:%v pending:%v", recovered != nil, mode, changed, session.pending != nil)
   }
+  if recovered.BaseGeneration != initialGeneration || recovered.Sequence != initialSequence+1 {
+    t.Fatalf("recovery did not advance the original base once: %#v", recovered)
+  }
+  foundFirst, foundOther := false, false
+  for _, committed := range session.graphStore.shards {
+    for _, node := range committed.shard.Nodes {
+      switch node.Name {
+      case "FirstAfter":
+        foundFirst = true
+      case "OtherAfter":
+        foundOther = true
+      case "BeforeEdit", "OtherBefore":
+        t.Errorf("recovered store retained old declaration %q", node.Name)
+      }
+    }
+  }
+  if !foundFirst || !foundOther {
+    t.Errorf("recovered store missed literal edits: FirstAfter=%v OtherAfter=%v", foundFirst, foundOther)
+  }
   assertServeShardFactsMatchFullDump(t, session)
 }

package/cmd/ttscgraph/serve_shards_prune_unreferenced_external_endpoints_test.go

@@ -8,6 +8,15 @@ import (
 
 // TestServeShardsPruneUnreferencedExternalEndpoints verifies an external leaf
 // leaves both resident endpoint indexes when its last owning edge disappears.
+//
+// 1. Publish a local call to an ambient external declaration and record its endpoint identity.
+// 2. Remove the last owning call while retaining the ambient import.
+// 3. Require zero retained references and no external endpoint in either cache, then match a full projection.
+//
+// @evidence contracts/testing.md#behavioral-verification Require zero retained references and no external endpoint in either cache, then match a full projection.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: after the only call to the ambient external function is removed (the import stays), the snapshot must be mode incremental, changed, the recorded external endpoint id must have zero references and be absent from both the wire endpoint cache and the internal node cache, and the committed shards must equal a full projection. The full-projection comparison runs another lane over the same compiler and extraction helpers, so it cannot independently detect a shared checker or extraction defect.
+// @evidence contracts/testing.md#distinguishing-cases Publish a local call to an ambient external declaration and record its endpoint identity. Remove the last owning call while retaining the ambient import. Require zero retained references and no external endpoint in either cache, then match a full projection.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsPruneUnreferencedExternalEndpoints is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsPruneUnreferencedExternalEndpoints(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -23,7 +32,7 @@ func TestServeShardsPruneUnreferencedExternalEndpoints(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if snapshot, _, _, err := session.SnapshotShards(); err != nil || snapshot == nil {
+  if snapshot, _, _, err := snapshotGraphShardState(session); err != nil || snapshot == nil {
     t.Fatalf("initial shard snapshot = snapshot:%v error:%v", snapshot != nil, err)
   }
   source := session.compiler.Program().SourceFile(index)
@@ -31,6 +40,9 @@ func TestServeShardsPruneUnreferencedExternalEndpoints(t *testing.T) {
     t.Fatal("fixture source was absent from resident program")
   }
   sourceKey := session.graphStore.sourceKeys[source.FileName()]
+  if sourceKey == "" || len(session.graphStore.sourceExternal[sourceKey]) != 1 {
+    t.Fatalf("fixture source must own one external endpoint: key=%q targets=%v", sourceKey, session.graphStore.sourceExternal[sourceKey])
+  }
   var externalID string
   for id := range session.graphStore.sourceExternal[sourceKey] {
     externalID = id
@@ -39,11 +51,15 @@ func TestServeShardsPruneUnreferencedExternalEndpoints(t *testing.T) {
   if externalID == "" {
     t.Fatal("fixture did not produce an external endpoint")
   }
+  endpoint, exists := session.graphStore.externalNodes[externalID]
+  if !exists || !endpoint.External || endpoint.Name != "external" || session.graphStore.externalReferences[externalID] != 1 {
+    t.Fatalf("fixture endpoint is not the singly referenced external callable: id=%q node=%#v references=%d", externalID, endpoint, session.graphStore.externalReferences[externalID])
+  }
 
   if err := os.WriteFile(index, []byte("import { external } from './api';\nexport function run(): number { return 1; }\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  snapshot, mode, changed, err := session.SnapshotShards()
+  snapshot, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_shards_publish_created_source_test.go

@@ -6,18 +6,22 @@ import (
 )
 
 // TestServeShardsPublishCreatedSource verifies a source that appears while the
-// session is resident enters the generation as its own shard and unblocks the
-// dependents that could not resolve it before.
+// session is resident enters the generation as its own shard and the authored
+// consumer acquires a changed shard key that is also upserted.
 //
-// Deletion is proven explicitly, but its mirror is the case where a wrong
-// closure is invisible: the consumer holds a graph that simply lacks a file,
-// and an agent asking about it is told the symbol does not exist rather than
-// receiving an error. The dependent must also refresh, because the import that
-// previously failed to resolve now produces real cross-file facts.
+// This is the source-creation counterpart to deletion: freshness must publish
+// the new source and refresh its consumer. This unit observes resident source
+// membership and shard identities, not resolution diagnostics, cross-file call
+// edges, or downstream consumer queries.
 //
 //  1. Commit a project whose consumer imports a module that does not exist yet.
 //  2. Create that module and request another shard snapshot.
 //  3. Require a shard for the new source and a replaced shard for its dependent.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies the authored new source enters the resident program and acquires an upserted shard key, while the consumer's nonempty key changes and is upserted. Actual call edges, diagnostic disappearance, and downstream consumer queries are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over a consumer that imports a not-yet-existing ./later: after src/later.ts is created, the snapshot must be changed with BaseGeneration equal to the initial generation, the new source must hold a committed shard key that is upserted, and the consumer's shard key must differ from its initial key and be upserted, because its import newly resolved. The snapshot mode is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Commit a project whose consumer imports a module that does not exist yet; Create that module and request another shard snapshot; Require a shard for the new source and a replaced shard for its dependent.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsPublishCreatedSource is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsPublishCreatedSource(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -32,7 +36,7 @@ func TestServeShardsPublishCreatedSource(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  initial, mode, changed, err := session.SnapshotShards()
+  initial, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -52,7 +56,7 @@ func TestServeShardsPublishCreatedSource(t *testing.T) {
   createdFile := filepath.Join(root, "src", "later.ts")
   writeGraphFile(t, createdFile, "export function later(): number { return 7; }\n")
 
-  next, mode, changed, err := session.SnapshotShards()
+  next, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -70,11 +74,10 @@ func TestServeShardsPublishCreatedSource(t *testing.T) {
   if !containsUpsertedShardKey(next, createdKey) {
     t.Fatalf("generation did not publish the created source shard %q", createdKey)
   }
-  // The dependent's import resolved for the first time, so its cross-file facts
-  // changed even though its own text did not. Reusing its prior shard would
-  // publish a consumer graph with a call edge to nothing.
+  // The unchanged consumer text must acquire a different published shard key;
+  // the call-edge contents are not independently checked here.
   nextConsumerKey := session.graphStore.sourceKeys[consumerKeyFile]
-  if nextConsumerKey == initialConsumerKey {
+  if nextConsumerKey == "" || nextConsumerKey == initialConsumerKey {
     t.Fatalf("dependent shard identity %q survived a newly resolved import", nextConsumerKey)
   }
   if !containsUpsertedShardKey(next, nextConsumerKey) {

package/cmd/ttscgraph/serve_shards_rebuild_declaration_edit_test.go

@@ -7,8 +7,18 @@ import (
 )
 
 // TestServeShardsRebuildDeclarationEdit verifies that a declaration-file
-// movement publishes one honest complete replacement instead of entering the
-// authored-source partial builder with an empty invalidation set.
+// edit reports rebuild from the initial generation and leaves committed facts
+// equal to a full projection over the same compiler. Complete replacement
+// payloads, internal closure selection, and rebuild counts are not observed.
+//
+// 1. Publish a project whose local value calls an ambient number-returning declaration.
+// 2. Change the ambient declaration to return string.
+// 3. Require a rebuild response based on the initial generation and committed-fact equality with the full projection.
+//
+// @evidence contracts/testing.md#behavioral-verification Require a changed rebuild response based on the initial generation and committed-fact equality with the full projection. This does not independently certify complete upsert membership, internal invalidation closures, or rebuild counts.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: changing the ambient api.d.ts return type from number to string must make the next shard snapshot mode rebuild, changed, with BaseGeneration equal to the initial generation, and the committed shards must equal a full projection. The full-projection comparison runs another lane over the same compiler and extraction helpers, so it cannot independently detect a shared checker or extraction defect.
+// @evidence contracts/testing.md#distinguishing-cases Publish a project whose local value calls an ambient number-returning declaration. Change the ambient declaration to return string. Require a changed rebuild response based on the initial generation and committed-fact equality with the full projection.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsRebuildDeclarationEdit is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsRebuildDeclarationEdit(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -24,7 +34,7 @@ func TestServeShardsRebuildDeclarationEdit(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  initial, _, _, err := session.SnapshotShards()
+  initial, _, _, err := snapshotGraphShardState(session)
   if err != nil || initial == nil {
     t.Fatalf("initial shard snapshot = snapshot:%v error:%v", initial != nil, err)
   }
@@ -32,7 +42,7 @@ func TestServeShardsRebuildDeclarationEdit(t *testing.T) {
     t.Fatal(err)
   }
 
-  replacement, mode, changed, err := session.SnapshotShards()
+  replacement, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_shards_refresh_cross_file_implementation_test.go

@@ -8,8 +8,18 @@ import (
 )
 
 // TestServeShardsRefreshCrossFileImplementation verifies that an assignment
-// source and the declaration node whose implementation span it owns enter one
-// replacement transaction.
+// carries install.ts edge evidence and its removal reports incremental with
+// a changed, present Service shard digest. Full-lane equality shares the same
+// compiler; assignment-shard payloads are not independently asserted here.
+//
+// 1. Publish Service.run and a separate install.ts assignment whose implementation calls helper.
+// 2. Remove the cross-file assignment without changing service.ts.
+// 3. Require initial evidence to name src/install.ts, an incremental replacement of the declaration shard digest and equality with the full projection.
+//
+// @evidence contracts/testing.md#behavioral-verification Require initial evidence to name src/install.ts, an incremental replacement of the declaration shard digest and equality with the full projection.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over Service.run and an install.ts assignment calling helper: the initial edge from Service.run to helper must carry evidence file src/install.ts, and removing the assignment (service.ts untouched) must give mode incremental, changed, with a different digest for the Service shard and committed shards equal to a full projection. The full-projection comparison runs another lane over the same compiler and extraction helpers, so it cannot independently detect a shared checker or extraction defect.
+// @evidence contracts/testing.md#distinguishing-cases Publish Service.run and a separate install.ts assignment whose implementation calls helper. Remove the cross-file assignment without changing service.ts. Require initial evidence to name src/install.ts, an incremental replacement of the declaration shard digest and equality with the full projection.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsRefreshCrossFileImplementation is a Go source-unit entry. snapshotGraphShardState calls the actual prepareShardSnapshot transaction and completes each prepared projection, including fallback, 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 TestServeShardsRefreshCrossFileImplementation(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -26,7 +36,7 @@ func TestServeShardsRefreshCrossFileImplementation(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  if snapshot, _, _, err := session.SnapshotShards(); err != nil || snapshot == nil {
+  if snapshot, _, _, err := snapshotGraphShardState(session); err != nil || snapshot == nil {
     t.Fatalf("initial shard snapshot = snapshot:%v error:%v", snapshot != nil, err)
   }
   serviceSource := session.compiler.Program().SourceFile(service)
@@ -34,7 +44,11 @@ func TestServeShardsRefreshCrossFileImplementation(t *testing.T) {
     t.Fatal("service source was absent from resident program")
   }
   serviceKey := session.graphStore.sourceKeys[serviceSource.FileName()]
-  before := session.graphStore.shards[serviceKey].digest
+  initialService, exists := session.graphStore.shards[serviceKey]
+  if serviceKey == "" || !exists || initialService.digest == "" {
+    t.Fatal("initial Service shard has no committed identity or digest")
+  }
+  before := initialService.digest
   evidenceFile := ""
   for _, edge := range session.graphStore.shards[serviceKey].shard.Edges {
     if strings.Contains(edge.From, "#Service.run:method") && strings.Contains(edge.To, "#helper:function") && edge.Evidence != nil {
@@ -49,7 +63,7 @@ func TestServeShardsRefreshCrossFileImplementation(t *testing.T) {
   if err := os.WriteFile(install, []byte("import { Service } from './service';\nexport function helper(): void {}\nexport function install(value: Service): void { void value; }\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  snapshot, mode, changed, err := session.SnapshotShards()
+  snapshot, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -59,5 +73,10 @@ func TestServeShardsRefreshCrossFileImplementation(t *testing.T) {
   if session.graphStore.shards[serviceKey].digest == before {
     t.Fatal("declaration shard retained its cross-file implementation evidence")
   }
+  currentServiceKey := session.graphStore.sourceKeys[serviceSource.FileName()]
+  currentService, exists := session.graphStore.shards[currentServiceKey]
+  if currentServiceKey == "" || !exists || currentService.digest == "" || currentService.digest == before {
+    t.Fatalf("current Service shard was not replaced with a changed digest: key=%q shard=%#v", currentServiceKey, currentService)
+  }
   assertServeShardFactsMatchFullDump(t, session)
 }