ttsc 0.30.3 → 0.31.0

package/cmd/ttscgraph/serve_shards_refresh_dependent_diagnostics_test.go

@@ -6,14 +6,19 @@ import (
   "testing"
 )
 
-// TestServeShardsRefreshDependentDiagnostics proves a public API edit rebuilds
-// the reverse semantic closure. The dependent source text is unchanged while
-// its checker diagnostic changes, so reusing that shard would be stale.
+// TestServeShardsRefreshDependentDiagnostics verifies that the authored public
+// return-type edit extracts the producer and unchanged consumer and transmits
+// the consumer's new assignment diagnostic in its replacement shard.
 //
 //  1. Commit a producer and consumer whose public types initially agree.
-//  2. Change only the producer's exported return type.
+//  2. Change the producer's exported return type and matching return literal.
 //  3. Require both sources to be re-extracted and the new consumer diagnostic
 //     to be transmitted in its replacement shard.
+//
+// @evidence contracts/testing.md#behavioral-verification The authored number-to-string public return-type edit reports incremental and replaces the unchanged consumer's shard with its new assignment diagnostic; the extracted file list is exactly the consumer and producer. Other dependency topologies are not certified.
+// @evidence contracts/testing.md#independent-expectations Initial consumer shard identity/digest must exist and have no src/consumer.ts code 2322 diagnostic. After the producer's number-to-string return-type edit, mode must be incremental and changed, the consumer digest must differ and be upserted, and its transmitted shard must contain a src/consumer.ts code 2322 error. Extracted files must be exactly [consumer, value], in that order. The full-projection comparison shares compiler and extraction helpers and cannot independently detect their shared defects.
+// @evidence contracts/testing.md#distinguishing-cases Commit a producer and consumer whose public types initially agree; Change the producer's exported return type and matching return literal while leaving the consumer unchanged; Require both sources to be re-extracted and the new consumer diagnostic to be transmitted in its replacement shard.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsRefreshDependentDiagnostics 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 TestServeShardsRefreshDependentDiagnostics(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -30,7 +35,7 @@ func TestServeShardsRefreshDependentDiagnostics(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)
   }
   consumerSource := session.compiler.Program().SourceFile(consumer)
@@ -38,12 +43,21 @@ func TestServeShardsRefreshDependentDiagnostics(t *testing.T) {
     t.Fatal("consumer source was absent from resident program")
   }
   consumerKey := session.graphStore.sourceKeys[consumerSource.FileName()]
-  before := session.graphStore.shards[consumerKey].digest
+  initialConsumer, exists := session.graphStore.shards[consumerKey]
+  if consumerKey == "" || !exists || initialConsumer.digest == "" {
+    t.Fatal("initial consumer shard has no committed identity or digest")
+  }
+  before := initialConsumer.digest
+  for _, diagnostic := range initialConsumer.shard.Diagnostics {
+    if diagnostic.File == "src/consumer.ts" && diagnostic.Code == 2322 {
+      t.Fatal("initial number-to-number consumer already has the assignment diagnostic")
+    }
+  }
 
   if err := os.WriteFile(value, []byte("export function value(): string { return 'one'; }\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)
   }
@@ -55,15 +69,24 @@ func TestServeShardsRefreshDependentDiagnostics(t *testing.T) {
     t.Fatal("dependent diagnostic retained its previous shard digest")
   }
   upserted := false
+  transmittedAssignmentDiagnostic := false
   for _, upsert := range snapshot.Upserts {
     if upsert.Shard.Key == consumerKey {
       upserted = true
+      for _, diagnostic := range upsert.Shard.Diagnostics {
+        if diagnostic.File == "src/consumer.ts" && diagnostic.Code == 2322 && diagnostic.Category == "error" {
+          transmittedAssignmentDiagnostic = true
+        }
+      }
       break
     }
   }
   if !upserted {
     t.Fatal("public API edit did not transmit the changed dependent shard")
   }
+  if !transmittedAssignmentDiagnostic {
+    t.Fatal("replacement consumer shard did not transmit the literal assignment diagnostic")
+  }
   valueKeyFile := session.compiler.Program().SourceFile(value).FileName()
   consumerKeyFile := consumerSource.FileName()
   if len(session.graphStore.extractedFiles) != 2 ||

package/cmd/ttscgraph/serve_shards_rename_moves_source_identity_test.go

@@ -7,18 +7,21 @@ import (
 )
 
 // TestServeShardsRenameMovesSourceIdentity verifies a renamed source deletes its
-// old shard and publishes a new one whose coordinates name the new path.
+// old shard key and upserts a different key mapped to the new resident path.
 //
-// A rename is a delete and a create at the filesystem layer but not at the
-// resolution layer: the old path can still be imported, and the shard key binds
-// the path, so carrying the old identity forward would leave the consumer with
-// two coordinates for one declaration. The dependent's import is rewritten in
-// the same step, which is what keeps the program resolvable and proves the
-// closure covers both ends of the move.
+// The consumer import is rewritten with the rename, and its committed key must
+// change. This unit observes resident-path membership and shard-key changes;
+// it does not inspect wire coordinate text, consumer upsert payloads, actual
+// resolution diagnostics, or consumer application of the move.
 //
 //  1. Commit a project whose consumer imports a source by its original path.
 //  2. Rename that source and repoint the import in the same generation.
-//  3. Require the old shard deleted, a new shard published, and the dependent replaced.
+//  3. Require the old shard deleted, a new shard upserted, and the consumer's committed key changed.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies explicit deletion of the original shard key, resident membership and an upserted different key for the renamed source, and a nonempty changed consumer key. Wire coordinate text, consumer upsert payloads, and actual resolution diagnostics are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over a consumer importing ./original: after renaming it to renamed.ts and repointing the import, the snapshot must be changed with BaseGeneration equal to the initial generation, Deletes must contain the old shard key, the store must drop the old source identity, the renamed source must hold a new, upserted shard key different from the old one, and the consumer's shard key must change. The test does not assert the new shard's coordinates text.
+// @evidence contracts/testing.md#distinguishing-cases Commit a project whose consumer imports a source by its original path; Rename that source and repoint the import in the same generation; Require the old shard deleted, a new shard upserted, and the consumer's committed key changed.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsRenameMovesSourceIdentity 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 TestServeShardsRenameMovesSourceIdentity(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -35,7 +38,7 @@ func TestServeShardsRenameMovesSourceIdentity(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)
   }
@@ -61,7 +64,7 @@ func TestServeShardsRenameMovesSourceIdentity(t *testing.T) {
   }
   writeGraphFile(t, consumerFile, "import { moved } from './renamed';\nexport function consume(): number { return moved(); }\n")
 
-  next, mode, changed, err := session.SnapshotShards()
+  next, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -89,7 +92,7 @@ func TestServeShardsRenameMovesSourceIdentity(t *testing.T) {
     t.Fatalf("generation did not publish the renamed source shard %q", renamedKey)
   }
   nextConsumerKey := session.graphStore.sourceKeys[consumerKeyFile]
-  if nextConsumerKey == initialConsumerKey {
+  if nextConsumerKey == "" || nextConsumerKey == initialConsumerKey {
     t.Fatalf("dependent shard identity %q survived a repointed import", nextConsumerKey)
   }
 }

package/cmd/ttscgraph/serve_shards_retry_preserves_committed_generation_test.go

@@ -7,10 +7,20 @@ import (
   "testing"
 )
 
-// TestServeShardsRetryPreservesCommittedGeneration verifies projection failure
-// cannot advance the native shard store. The same captured compiler change is
-// retried against the prior base and publishes exactly the next sequence only
-// after every replacement validates.
+// TestServeShardsRetryPreservesCommittedGeneration verifies that the authored
+// relative-root failure keeps the committed store object and pending change.
+// Repairing the root retries against the original base with the next sequence.
+// In-place store contents, every validation failure, and recovered source facts
+// are not independently asserted here.
+//
+// 1. Publish an initial shard store and capture its committed identity.
+// 2. Edit a source, force a relative-root projection failure, then repair the root and retry.
+// 3. Require failure to preserve the store and pending change, then publish exactly the next sequence against the prior generation on the incremental lane.
+//
+// @evidence contracts/testing.md#behavioral-verification Require the authored relative-root failure to return no snapshot or changed flag, retain the committed store object, and leave pending set; repair must report incremental and publish the next sequence against the original generation. In-place store contents, other failure categories, and recovered source facts are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal states: with the session cwd set to a relative path the snapshot must fail with an error containing 'project root', return no snapshot, report unchanged state, keep the same committed store object and leave pending set; after the root is repaired the retry must be mode incremental, changed, with Sequence equal to the initial sequence plus one and BaseGeneration equal to the initial generation.
+// @evidence contracts/testing.md#distinguishing-cases Publish an initial shard store and capture its committed identity. Edit a source, force a relative-root projection failure, then repair the root and retry. Require failure to preserve the store and pending change, then publish exactly the next sequence against the prior generation on the incremental lane.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsRetryPreservesCommittedGeneration 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 TestServeShardsRetryPreservesCommittedGeneration(t *testing.T) {
   root := graphSessionFixture(t)
   session, err := newGraphSession(root, "tsconfig.json")
@@ -18,7 +28,7 @@ func TestServeShardsRetryPreservesCommittedGeneration(t *testing.T) {
     t.Fatal(err)
   }
   defer session.Close()
-  initial, _, _, err := session.SnapshotShards()
+  initial, _, _, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -29,7 +39,7 @@ func TestServeShardsRetryPreservesCommittedGeneration(t *testing.T) {
   }
 
   session.cwd = "relative-project"
-  snapshot, _, changed, err := session.SnapshotShards()
+  snapshot, _, changed, err := snapshotGraphShardState(session)
   if err == nil || !strings.Contains(err.Error(), "project root") {
     t.Fatalf("projection error = %v, want absolute-root rejection", err)
   }
@@ -38,7 +48,7 @@ func TestServeShardsRetryPreservesCommittedGeneration(t *testing.T) {
   }
 
   session.cwd = root
-  recovered, mode, changed, err := session.SnapshotShards()
+  recovered, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }

package/cmd/ttscgraph/serve_shards_reuse_unaffected_sources_test.go

@@ -8,13 +8,19 @@ import (
 )
 
 // TestServeShardsReuseUnaffectedSources verifies a private body edit advances
-// only the changed content-addressed source shard. TypeScript's forced
-// declaration output proves the public shape stayed fixed, so neither the
-// dependent nor unrelated source is re-extracted or retransmitted.
+// the authored changed source's shard key while the consumer and unrelated
+// peer keep their keys and are neither extracted nor upserted. The owner uses
+// declaration-shape comparison to select this closure; this unit observes the
+// selected files and publication, not declaration output or every public type.
 //
 //  1. Commit a project where one source has a dependent and an unrelated peer.
 //  2. Change only the source's private function body and request another shard snapshot.
 //  3. Require one extracted source and no dependent or unrelated shard replacement.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies the authored private-body edit changes and upserts the value source key, extracts only that source, and preserves the consumer/unrelated keys without their upserts. The forced declaration output and general public-type equivalence are not independently observed.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over value.ts, a dependent consumer.ts and an unrelated peer: a private body edit must give mode incremental with BaseSequence and BaseGeneration equal to the initial snapshot, a new key for value.ts whose old key is in Deletes, unchanged keys for the other two, exactly one extracted file (value.ts), preserved wire provenance for the unrelated source, and no upsert of the dependent or unrelated key. The test overwrites the unrelated source's physical provenance path with a foreign-looking path to prove the wire path is carried rather than recomputed.
+// @evidence contracts/testing.md#distinguishing-cases Commit a project where one source has a dependent and an unrelated peer; Change only the source's private function body and request another shard snapshot; Require one extracted source and no dependent or unrelated shard replacement.
+// @evidence contracts/testing.md#execution-ownership TestServeShardsReuseUnaffectedSources 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 TestServeShardsReuseUnaffectedSources(t *testing.T) {
   root := t.TempDir()
   writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
@@ -30,7 +36,7 @@ func TestServeShardsReuseUnaffectedSources(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 +58,11 @@ func TestServeShardsReuseUnaffectedSources(t *testing.T) {
   initialValueKey := session.graphStore.sourceKeys[valueKeyFile]
   initialConsumerKey := session.graphStore.sourceKeys[consumerKeyFile]
   initialUnrelatedKey := session.graphStore.sourceKeys[unrelatedKeyFile]
+  if initialValueKey == "" || initialConsumerKey == "" || initialUnrelatedKey == "" {
+    t.Fatal("initial generation omitted a fixture source key")
+  }
   unrelatedWireFile := session.graphStore.wireSources[unrelatedKeyFile]
+  alteredUnrelatedProvenance := false
   for index := range session.graphStore.provenance.Sources {
     if session.graphStore.provenance.Sources[index].File != unrelatedKeyFile {
       continue
@@ -66,15 +76,16 @@ func TestServeShardsReuseUnaffectedSources(t *testing.T) {
     } else {
       session.graphStore.provenance.Sources[index].File = "//foreign/share/unrelated.ts"
     }
+    alteredUnrelatedProvenance = true
     break
   }
-  if unrelatedWireFile == "" {
+  if unrelatedWireFile == "" || !alteredUnrelatedProvenance {
     t.Fatal("unrelated source was absent from physical/wire provenance")
   }
   if err := os.WriteFile(valueFile, []byte("export function value(): number { return 2; }\n"), 0o644); err != nil {
     t.Fatal(err)
   }
-  delta, mode, changed, err := session.SnapshotShards()
+  delta, mode, changed, err := snapshotGraphShardState(session)
   if err != nil {
     t.Fatal(err)
   }
@@ -82,9 +93,12 @@ func TestServeShardsReuseUnaffectedSources(t *testing.T) {
     t.Fatalf("incremental coordinates: snapshot=%#v mode=%q changed=%v", delta, mode, changed)
   }
   nextValueKey := session.graphStore.sourceKeys[valueKeyFile]
-  if nextValueKey == initialValueKey {
+  if nextValueKey == "" || nextValueKey == initialValueKey {
     t.Fatal("changed source retained its content-addressed shard key")
   }
+  if !containsUpsertedShardKey(delta, nextValueKey) {
+    t.Fatal("changed source's new shard key was not upserted")
+  }
   if !containsString(delta.Deletes, initialValueKey) {
     t.Fatalf("delta did not delete superseded source shard %q: %v", initialValueKey, delta.Deletes)
   }

package/cmd/ttscgraph/serve_snapshot_proves_its_program_without_a_second_read_test.go

@@ -13,24 +13,28 @@ import (
 )
 
 // TestServeSnapshotProvesItsProgramWithoutASecondRead verifies a single serve
-// response carries everything needed to prove which program produced it.
+// response carries the authored metadata and source-manifest memberships,
+// with supplied disk digests reproducible from the untouched fixture.
 //
-// This is the contract the envelope exists for. A consumer used to be handed
-// paths and nothing else, so proving that the nodes, edges, and the file bytes
-// it was about to read all belonged to one Program meant re-reading the disk
-// afterwards and asking the server a second time whether anything had moved —
-// which narrows the race without closing it, and never proves the bytes read are
-// the bytes the checker resolved against. Everything below has to come out of
-// one frame, because a second frame is the thing being replaced.
+// One request supplies the observed protocol, mode, capabilities, producer,
+// config/root memberships and node-file source entries. Independent native
+// reads reproduce its nonempty disk digests without another server request.
+// This does not authenticate a Program object, verify checker-text digests,
+// establish graph-fact semantics, or close races with later external edits.
 //
 //  1. Take one snapshot of a fixture project.
 //  2. Assert the envelope names its protocol, mode, and capabilities.
-//  3. Assert every file the dump names carries a digest, and that hashing the
-//     file off the disk independently reproduces it.
+//  3. Require non-external node files in the source manifest and independently
+//     reproduce every supplied nonempty disk digest, including at least one.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies the observed metadata and source-manifest memberships in one serve response and independently reproduces its nonempty disk digests over the untouched fixture. The same supplied generation also requires two native same-file spellings to share one wire source while retaining both raw owners; different checker, disk and absent disk witnesses must fail. Program authentication, checker-text hashes, graph semantics, and external-edit races are not certified.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal contract values plus an independent hash: the envelope must carry serveProtocolVersion, mode initial, a non-empty capability list and a dump whose provenance names producer ttscgraph, a TypeScript version, at least one config and one root; every non-external node's file must appear in the digest manifest; and, for every manifest entry with a disk digest, SHA-256 of the file read from disk by the test must equal it (at least one must be reproduced). A manifest that omitted files or carried digests the bytes do not reproduce fails.
+// @evidence contracts/testing.md#distinguishing-cases Take one snapshot of an untouched fixture; Assert the envelope metadata and source-manifest memberships; Independently reproduce supplied nonempty disk digests, including at least one, without another server request. Alias proof normalization uses two authored spellings of the same existing native source; conflicting checker text, disk content and missing disk proof are separate refusals without another Program or process.
+// @evidence contracts/testing.md#execution-ownership TestServeSnapshotProvesItsProgramWithoutASecondRead 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 TestServeSnapshotProvesItsProgramWithoutASecondRead(t *testing.T) {
   root := graphSessionFixture(t)
   var output bytes.Buffer
-  if code := serveSnapshots(strings.NewReader("{\"id\":1}\n"), &output, root, "tsconfig.json"); code != 0 {
+  if code := serveSourceSnapshots(strings.NewReader("{\"id\":1}\n"), &output, root, "tsconfig.json"); code != 0 {
     t.Fatalf("serveSnapshots exited %d", code)
   }
 
@@ -71,9 +75,8 @@ func TestServeSnapshotProvesItsProgramWithoutASecondRead(t *testing.T) {
     t.Fatal("universe fingerprinted no root file")
   }
 
-  // Every file a node names must appear in the manifest. A file with facts but
-  // no digest is exactly the gap the manifest closes: a consumer would have to
-  // trust it.
+  // Every non-external node file must have a source-manifest entry. This check
+  // does not reproduce the checker-text digest or authenticate the node facts.
   digests := make(map[string]graph.SourceDigest, len(provenance.Sources))
   for _, source := range provenance.Sources {
     digests[source.File] = source
@@ -96,7 +99,7 @@ func TestServeSnapshotProvesItsProgramWithoutASecondRead(t *testing.T) {
     }
     content, err := os.ReadFile(filepath.Join(root, filepath.FromSlash(file)))
     if err != nil {
-      continue
+      t.Fatalf("cannot independently read disk-digested source %q: %v", file, err)
     }
     if got := graph.Digest(sha256.Sum256(content)); got != source.Disk {
       t.Fatalf("independent read of %q hashes to %s, manifest says %s", file, got, source.Disk)
@@ -104,6 +107,44 @@ func TestServeSnapshotProvesItsProgramWithoutASecondRead(t *testing.T) {
     proven++
   }
   if proven == 0 {
-    t.Fatal("no file's digest could be reproduced from disk, so the manifest proves nothing")
+    t.Fatal("no supplied disk digest was independently reproduced")
+  }
+  // The two raw spellings name one native file in this generation. Only
+  // complete matching checker/disk witnesses permit one wire identity.
+  var file string
+  if len(provenance.Sources) == 0 {
+    t.Fatal("the initial source generation must be nonempty")
+  }
+  var picked graph.SourceDigest
+  for _, source := range provenance.Sources {
+    if source.Checker != "" && source.Disk != "" {
+      picked = source
+      break
+    }
+  }
+  if picked.File == "" {
+    t.Fatal("no complete native generation source was available for alias proof")
+  }
+  file = filepath.Join(root, filepath.FromSlash(picked.File))
+  alias := filepath.Dir(file) + string(filepath.Separator) + "." + string(filepath.Separator) + filepath.Base(file)
+  first := picked
+  first.File = file
+  second := first
+  second.File = alias
+  pair := provenance
+  pair.Sources = []graph.SourceDigest{first, second}
+  normalized, owners, err := normalizeServeGraphProvenance(root, pair, true)
+  if err != nil || len(normalized.Sources) != 1 || len(owners) != 2 || owners[file] != owners[alias] {
+    t.Fatalf("same native source aliases were not retained at one proven wire owner: %v, %#v", err, owners)
+  }
+  for _, bad := range []graph.SourceDigest{
+    {File: alias, Checker: "different-generation", Disk: first.Disk},
+    {File: alias, Checker: first.Checker, Disk: "different-content"},
+    {File: alias, Checker: first.Checker},
+  } {
+    pair.Sources = []graph.SourceDigest{first, bad}
+    if _, _, err := normalizeServeGraphProvenance(root, pair, true); err == nil {
+      t.Fatalf("a conflicting or incomplete alias proof was accepted: %#v", bad)
+    }
   }
 }

package/cmd/ttscgraph/serve_source_encoding_test.go

@@ -0,0 +1,133 @@
+package main
+
+import (
+  "crypto/sha256"
+  "encoding/binary"
+  "os"
+  "path/filepath"
+  "strings"
+  "testing"
+  "unicode/utf16"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
+)
+
+// TestServeSourceEncodingKeepsRawIdentityAndDecodedResidentText verifies eight
+// source encodings through one real resident compiler and shard owner.
+//
+// Cold and unchanged snapshots contrast an unrelated edit, encoded edits and
+// restoration. Raw disk digests remain byte hashes while overlay source text
+// stays compiler-decoded. Every independent file assertion is collected.
+//
+// 1. Load eight encoded sources into one real resident compiler.
+// 2. Request unchanged, unrelated-edit, encoded-edit and restored snapshots.
+// 3. Check publication, decoded text and raw-byte identity independently.
+//
+// @evidence contracts/testing.md#behavioral-verification The real resident graph session publishes cold and incremental shard snapshots, retains decoded compiler text, and keeps raw disk hashes and changed-source decisions consistent for all eight encodings.
+// @evidence contracts/testing.md#independent-expectations Literal source text and BOM/endian byte encoding define both domains; standard SHA-256 supplies expected raw identity independently of session hashing and decoding.
+// @evidence contracts/testing.md#distinguishing-cases UTF-8 BOM, UTF-16 LE/BE and five newline spellings run through unchanged requests, an unrelated source edit, encoded edits, restoration and another unchanged request; every source assertion is collected independently.
+// @evidence contracts/testing.md#execution-ownership This Go source-unit entry calls the actual resident compiler and prepared shard transaction through snapshotGraphShardState with explicit empty ignore membership. The owned fixture and compiler close in this process; no consumer installation, native product build or product child is used.
+func TestServeSourceEncodingKeepsRawIdentityAndDecodedResidentText(t *testing.T) {
+  root := t.TempDir()
+  writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{"compilerOptions":{"target":"ES2022","module":"commonjs","strict":true},"include":["src"]}`)
+  writeGraphFile(t, filepath.Join(root, "src", "unrelated.ts"), "export const unrelated = 1;\n")
+  names := []string{"Utf8Bom", "Utf16Le", "Utf16Be", "Lf", "CrLf", "Cr", "Ls", "Ps"}
+  text := func(name, suffix string) string {
+    separator := map[string]string{"CrLf": "\r\n", "Cr": "\r", "Ls": "\u2028", "Ps": "\u2029"}[name]
+    if separator == "" {
+      separator = "\n"
+    }
+    return strings.Join([]string{"/** " + name + suffix + " docs. */", "export function " + name + "(): string {", "  return \"" + name + suffix + "\";", "}", ""}, separator)
+  }
+  bytesOf := func(name, source string) []byte {
+    if name == "Utf8Bom" {
+      return append([]byte{0xef, 0xbb, 0xbf}, []byte(source)...)
+    }
+    if name != "Utf16Le" && name != "Utf16Be" {
+      return []byte(source)
+    }
+    units := utf16.Encode([]rune(source))
+    var order binary.ByteOrder = binary.LittleEndian
+    result := make([]byte, 2+len(units)*2)
+    copy(result, []byte{0xff, 0xfe})
+    if name == "Utf16Be" {
+      order = binary.BigEndian
+      copy(result, []byte{0xfe, 0xff})
+    }
+    for i, unit := range units {
+      order.PutUint16(result[2+i*2:], unit)
+    }
+    return result
+  }
+  write := func(suffix string) {
+    for _, name := range names {
+      file := filepath.Join(root, "src", name+".ts")
+      if err := os.MkdirAll(filepath.Dir(file), 0o755); err != nil {
+        t.Fatal(err)
+      }
+      if err := os.WriteFile(file, bytesOf(name, text(name, suffix)), 0o644); err != nil {
+        t.Fatal(err)
+      }
+    }
+  }
+  write("")
+  session, err := newGraphSession(root, "tsconfig.json")
+  if err != nil {
+    t.Fatal(err)
+  }
+  defer session.Close()
+  verify := func(stage, suffix, expectedMode string) {
+    snapshot, mode, changed, err := snapshotGraphShardState(session)
+    if err != nil {
+      t.Fatal(err)
+    }
+    if mode != expectedMode {
+      t.Errorf("%s mode=%s want=%s", stage, mode, expectedMode)
+    }
+    if expectedMode == serveModeUnchanged {
+      if snapshot != nil || changed {
+        t.Errorf("%s unexpectedly published a changed snapshot", stage)
+      }
+    } else if snapshot == nil || !changed {
+      t.Errorf("%s did not publish its changed snapshot", stage)
+    }
+    hashes, digests, err := hashProgramSources(session.compiler.Program())
+    if err != nil {
+      t.Fatal(err)
+    }
+    for _, name := range names {
+      file := filepath.Join(root, "src", name+".ts")
+      source := session.compiler.Program().SourceFile(file)
+      if source == nil {
+        t.Errorf("%s missing source %s", stage, name)
+        continue
+      }
+      if source.Text() != text(name, suffix) {
+        t.Errorf("%s %s decoded text=%q want=%q", stage, name, source.Text(), text(name, suffix))
+      }
+      rawHash := sha256.Sum256(bytesOf(name, text(name, suffix)))
+      if hashes[source.FileName()] != rawHash {
+        t.Errorf("%s %s invalidation identity differs from raw bytes", stage, name)
+      }
+      if digests[source.FileName()] != graph.Digest(rawHash) {
+        t.Errorf("%s %s disk digest differs from raw bytes", stage, name)
+      }
+    }
+    changes, deleted, err := changedSources(hashes)
+    if err != nil {
+      t.Fatal(err)
+    }
+    if deleted || len(changes) != 0 {
+      t.Errorf("%s unchanged encoded sources marked dirty: %v deleted=%v", stage, changes, deleted)
+    }
+  }
+  verify("cold", "", serveModeInitial)
+  verify("unchanged", "", serveModeUnchanged)
+  writeGraphFile(t, filepath.Join(root, "src", "unrelated.ts"), "export const unrelated = 2;\n")
+  verify("unrelated edit", "", serveModeIncremental)
+  write(" edited")
+  verify("encoded edits", " edited", serveModeIncremental)
+  write("")
+  verify("restored", "", serveModeIncremental)
+  verify("restored unchanged", "", serveModeUnchanged)
+}