ttsc 0.34.3 → 0.36.0

package/driver/compilation_snapshot.go

@@ -0,0 +1,267 @@
+package driver
+
+import (
+  "encoding/base64"
+  "encoding/json"
+  "fmt"
+  "os"
+  "path/filepath"
+  "sync"
+  "time"
+  "unicode/utf8"
+
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+  "github.com/microsoft/typescript-go/shim/vfs"
+)
+
+// compilationSnapshotFS retains the first compiler text, identity and directory
+// answers of one invocation. Sequential native check and transform stages share
+// its private document; a new invocation receives a new document. This is a
+// read-once compiler view, not an atomic snapshot of the whole physical volume.
+// Writes remain with the underlying filesystem and cannot replace captured reads.
+// The invocation owns the uncapped captured text and removes its document after
+// all stages finish. The mutex serializes native compiler readers within a stage;
+// the owning JS coordinator runs stages sequentially, never concurrent writers.
+type compilationSnapshotFS struct {
+  vfs.FS
+  mu    sync.Mutex
+  path  string
+  data  compilationSnapshotData
+  dirty bool
+}
+
+type compilationSnapshotData struct {
+  Version     int                                 `json:"version"`
+  ID          string                              `json:"id"`
+  Reads       map[string]compilationSnapshotRead  `json:"reads"`
+  Files       map[string]bool                     `json:"files"`
+  Directories map[string]bool                     `json:"directories"`
+  Entries     map[string]vfs.Entries              `json:"entries"`
+  Realpaths   map[string]string                   `json:"realpaths"`
+  Stats       map[string]*compilationSnapshotInfo `json:"stats"`
+}
+
+type compilationSnapshotInfo struct {
+  Filename string      `json:"name"`
+  Length   int64       `json:"size"`
+  Bits     os.FileMode `json:"mode"`
+  Modified time.Time   `json:"modified"`
+}
+
+func (i *compilationSnapshotInfo) Name() string       { return i.Filename }
+func (i *compilationSnapshotInfo) Size() int64        { return i.Length }
+func (i *compilationSnapshotInfo) Mode() os.FileMode  { return i.Bits }
+func (i *compilationSnapshotInfo) ModTime() time.Time { return i.Modified }
+func (i *compilationSnapshotInfo) IsDir() bool        { return i.Bits.IsDir() }
+func (i *compilationSnapshotInfo) Sys() any           { return nil }
+
+type compilationSnapshotRead struct {
+  Text string `json:"text"`
+  OK   bool   `json:"ok"`
+}
+
+// compilationSnapshotReadWire keeps normal UTF-8 readable and encodes only
+// text JSON cannot represent losslessly. Decoding happens once when opening a
+// stage, not on each cached compiler read.
+type compilationSnapshotReadWire struct {
+  Text     string `json:"text"`
+  OK       bool   `json:"ok"`
+  Encoding string `json:"encoding,omitempty"`
+}
+
+func (r compilationSnapshotRead) MarshalJSON() ([]byte, error) {
+  value := compilationSnapshotReadWire{Text: r.Text, OK: r.OK}
+  if !utf8.ValidString(value.Text) {
+    value.Text = base64.StdEncoding.EncodeToString([]byte(value.Text))
+    value.Encoding = "base64"
+  }
+  return json.Marshal(value)
+}
+
+func (r *compilationSnapshotRead) UnmarshalJSON(bytes []byte) error {
+  var value compilationSnapshotReadWire
+  if err := json.Unmarshal(bytes, &value); err != nil {
+    return err
+  }
+  switch value.Encoding {
+  case "":
+  case "base64":
+    decoded, err := base64.StdEncoding.DecodeString(value.Text)
+    if err != nil {
+      return fmt.Errorf("invalid compilation snapshot text: %w", err)
+    }
+    value.Text = string(decoded)
+  default:
+    return fmt.Errorf("unknown compilation snapshot text encoding %q", value.Encoding)
+  }
+  r.Text, r.OK = value.Text, value.OK
+  return nil
+}
+
+// openCompilationSnapshot accepts only an invocation-owned versioned document.
+// Invalid or unreadable transport is an error, never permission to read live
+// inputs under another stage's snapshot identity.
+func openCompilationSnapshot(inner vfs.FS, path string) (*compilationSnapshotFS, error) {
+  bytes, err := os.ReadFile(path)
+  if err != nil {
+    return nil, err
+  }
+  var data compilationSnapshotData
+  if err := json.Unmarshal(bytes, &data); err != nil {
+    return nil, err
+  }
+  if data.Version != 1 || data.ID == "" || data.Reads == nil || data.Files == nil || data.Directories == nil || data.Entries == nil || data.Realpaths == nil || data.Stats == nil {
+    return nil, fmt.Errorf("invalid compilation snapshot %q", path)
+  }
+  return &compilationSnapshotFS{FS: inner, path: path, data: data}, nil
+}
+
+func (s *compilationSnapshotFS) key(path string) string {
+  return shimtspath.Canonicalize(vfs.CaseSensitivityOf(s.FS), shimtspath.NormalizePath(path))
+}
+
+func (s *compilationSnapshotFS) realpath(path shimtspath.RootedPath) shimtspath.RootedPath {
+  key := s.key(string(path))
+  if value, ok := s.data.Realpaths[key]; ok {
+    return shimtspath.RootedPath(value)
+  }
+  value := s.FS.Realpath(path)
+  s.data.Realpaths[key] = string(value)
+  s.dirty = true
+  return value
+}
+
+func (s *compilationSnapshotFS) Realpath(path shimtspath.RootedPath) shimtspath.RootedPath {
+  s.mu.Lock()
+  defer s.mu.Unlock()
+  return s.realpath(path)
+}
+
+func (s *compilationSnapshotFS) ReadFile(path shimtspath.RootedFilePath) (string, bool) {
+  s.mu.Lock()
+  defer s.mu.Unlock()
+  key := s.key(string(path))
+  if value, ok := s.data.Reads[key]; ok {
+    return value.Text, value.OK
+  }
+  physical := s.realpath(shimtspath.RootedPath(path))
+  physicalKey := s.key(string(physical))
+  if value, ok := s.data.Reads[physicalKey]; ok {
+    s.data.Reads[key] = value
+    s.dirty = true
+    return value.Text, value.OK
+  }
+  text, ok := s.FS.ReadFile(path)
+  value := compilationSnapshotRead{Text: text, OK: ok}
+  s.data.Reads[key] = value
+  s.dirty = true
+  if ok && filepath.IsAbs(string(physical)) {
+    s.data.Reads[physicalKey] = value
+    s.dirty = true
+  }
+  return text, ok
+}
+
+func (s *compilationSnapshotFS) FileExists(path shimtspath.RootedFilePath) bool {
+  s.mu.Lock()
+  defer s.mu.Unlock()
+  key := s.key(string(path))
+  if value, ok := s.data.Files[key]; ok {
+    return value
+  }
+  value := s.FS.FileExists(path)
+  s.data.Files[key] = value
+  s.dirty = true
+  if value {
+    s.realpath(shimtspath.RootedPath(path))
+  }
+  return value
+}
+
+func (s *compilationSnapshotFS) DirectoryExists(path shimtspath.RootedDirectoryPath) bool {
+  s.mu.Lock()
+  defer s.mu.Unlock()
+  key := s.key(string(path))
+  if value, ok := s.data.Directories[key]; ok {
+    return value
+  }
+  value := s.FS.DirectoryExists(path)
+  s.data.Directories[key] = value
+  s.dirty = true
+  if value {
+    s.realpath(shimtspath.RootedPath(path))
+  }
+  return value
+}
+
+func (s *compilationSnapshotFS) Stat(path shimtspath.RootedPath) vfs.FileInfo {
+  s.mu.Lock()
+  defer s.mu.Unlock()
+  key := s.key(string(path))
+  value, found := s.data.Stats[key]
+  if !found {
+    info := s.FS.Stat(path)
+    if info != nil {
+      value = &compilationSnapshotInfo{Filename: info.Name(), Length: info.Size(), Bits: info.Mode(), Modified: info.ModTime()}
+    }
+    s.data.Stats[key] = value
+    s.dirty = true
+    if info != nil {
+      s.realpath(path)
+    }
+  }
+  if value == nil {
+    return nil
+  }
+  return value
+}
+
+func (s *compilationSnapshotFS) GetAccessibleEntries(path shimtspath.RootedDirectoryPath) vfs.Entries {
+  s.mu.Lock()
+  defer s.mu.Unlock()
+  key := s.key(string(path))
+  value, ok := s.data.Entries[key]
+  if !ok {
+    value = s.FS.GetAccessibleEntries(path)
+    value.Files = append([]string{}, value.Files...)
+    value.Directories = append([]string{}, value.Directories...)
+    s.data.Entries[key] = value
+    s.dirty = true
+  }
+  // The compiler owns its returned slices and may sort them in place.
+  value.Files = append([]string{}, value.Files...)
+  value.Directories = append([]string{}, value.Directories...)
+  if value.Symlinks != nil {
+    copied := make(map[string]struct{}, len(value.Symlinks))
+    for key := range value.Symlinks {
+      copied[key] = struct{}{}
+    }
+    value.Symlinks = copied
+  }
+  return value
+}
+
+// save transfers actual read answers to the next sequential native stage. A
+// complete temporary file is renamed over the private document; no reader is
+// allowed to start until this stage returns. Failed publication leaves no new
+// snapshot authority and the stage reports the native failure.
+func (s *compilationSnapshotFS) save() error {
+  s.mu.Lock()
+  defer s.mu.Unlock()
+  if !s.dirty {
+    return nil
+  }
+  bytes, err := json.Marshal(s.data)
+  if err != nil {
+    return err
+  }
+  staging := s.path + ".next"
+  if err := os.WriteFile(staging, bytes, 0600); err != nil {
+    return err
+  }
+  if err := os.Rename(staging, s.path); err != nil {
+    return err
+  }
+  s.dirty = false
+  return nil
+}

package/driver/compilation_snapshot_keeps_inputs_across_stages_test.go

@@ -0,0 +1,130 @@
+package driver
+
+import (
+  "os"
+  "path/filepath"
+  "reflect"
+  "sync"
+  "testing"
+
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+)
+
+// TestCompilationSnapshotKeepsInputsAcrossStages verifies captured text,
+// absence, identity and directory answers survive edits and stage handoff.
+// A disk comparison cannot establish which bytes an earlier compiler used.
+//
+// 1. Read authored existing, empty and missing files and directory membership.
+// 2. Edit and create those paths, then read concurrently and from a new stage.
+// 3. Open a new invocation and require it to observe the edited inputs.
+//
+// @evidence contracts/testing.md#behavioral-verification The actual snapshot VFS serves old text and absence after disk mutation, persists those answers to another stage and admits new bytes only in a new invocation.
+// @evidence contracts/testing.md#independent-expectations Literal BEFORE, AFTER, empty and missing states, authored Unicode/invalid byte text and the original directory listing define the oracle independently of snapshot serialization.
+// @evidence contracts/testing.md#distinguishing-cases Existing, empty, Unicode plus invalid UTF-8 text, failed reads, missing existence, returned slice mutation, concurrent readers, sequential stage handoff and a new invocation exercise distinct read-once boundaries; malformed transport must fail.
+// @evidence contracts/testing.md#execution-ownership This in-process driver Go unit calls its maintained VFS directly over a private temporary tree; it starts no compiler, installation or product host.
+func TestCompilationSnapshotKeepsInputsAcrossStages(t *testing.T) {
+  root := t.TempDir()
+  source := filepath.Join(root, "source.ts")
+  empty := filepath.Join(root, "empty.ts")
+  encoded := filepath.Join(root, "encoded.ts")
+  encodedText := "// \xff\x80\nexport const value = \"한글😀\";\n"
+  missing := filepath.Join(root, "missing.ts")
+  write := func(file, text string) {
+    t.Helper()
+    if err := os.WriteFile(file, []byte(text), 0600); err != nil {
+      t.Fatal(err)
+    }
+  }
+  write(source, "BEFORE")
+  write(empty, "")
+  write(encoded, encodedText)
+  newDocument := func(id string) string {
+    t.Helper()
+    file := filepath.Join(t.TempDir(), "snapshot.json")
+    write(file, `{"version":1,"id":"`+id+`","reads":{},"files":{},"directories":{},"entries":{},"realpaths":{},"stats":{}}`)
+    return file
+  }
+  document := newDocument("first")
+  first, err := openCompilationSnapshot(DefaultFS(), document)
+  if err != nil {
+    t.Fatal(err)
+  }
+  file := shimtspath.RootedFilePathFromAbsolute(source)
+  absent := shimtspath.RootedFilePathFromAbsolute(missing)
+  directory := shimtspath.RootedDirectoryPathFromAbsolute(root)
+  if text, ok := first.ReadFile(file); !ok || text != "BEFORE" {
+    t.Fatalf("first read: %q %v", text, ok)
+  }
+  if text, ok := first.ReadFile(shimtspath.RootedFilePathFromAbsolute(empty)); !ok || text != "" {
+    t.Fatalf("empty read: %q %v", text, ok)
+  }
+  if _, ok := first.ReadFile(absent); ok || first.FileExists(absent) {
+    t.Fatal("missing input was present")
+  }
+  if !first.DirectoryExists(directory) {
+    t.Fatal("source directory missing")
+  }
+  if text, ok := first.ReadFile(shimtspath.RootedFilePathFromAbsolute(encoded)); !ok || text != encodedText {
+    t.Fatalf("encoded first read: %q %v", text, ok)
+  }
+  physical := first.Realpath(shimtspath.RootedPath(shimtspath.RootedFilePathFromAbsolute(source)))
+  original := first.GetAccessibleEntries(directory)
+  expected := append([]string{}, original.Files...)
+  original.Files[0] = "caller mutation"
+  write(source, "AFTER")
+  write(empty, "FILLED")
+  write(encoded, "AFTER")
+  write(missing, "CREATED")
+  var readers sync.WaitGroup
+  for range 8 {
+    readers.Go(func() {
+      if text, ok := first.ReadFile(file); !ok || text != "BEFORE" {
+        t.Errorf("concurrent read: %q %v", text, ok)
+      }
+    })
+  }
+  readers.Wait()
+  if err := first.save(); err != nil {
+    t.Fatal(err)
+  }
+  second, err := openCompilationSnapshot(DefaultFS(), document)
+  if err != nil {
+    t.Fatal(err)
+  }
+  if text, ok := second.ReadFile(file); !ok || text != "BEFORE" {
+    t.Fatalf("next stage: %q %v", text, ok)
+  }
+  if text, ok := second.ReadFile(shimtspath.RootedFilePathFromAbsolute(empty)); !ok || text != "" {
+    t.Fatalf("empty next stage: %q %v", text, ok)
+  }
+  if text, ok := second.ReadFile(shimtspath.RootedFilePathFromAbsolute(encoded)); !ok || text != encodedText {
+    t.Fatalf("encoded next stage: %q %v", text, ok)
+  }
+  if _, ok := second.ReadFile(absent); ok || second.FileExists(absent) {
+    t.Fatal("next stage admitted a created input")
+  }
+  if !reflect.DeepEqual(second.GetAccessibleEntries(directory).Files, expected) {
+    t.Fatal("directory answer changed")
+  }
+  if second.Realpath(shimtspath.RootedPath(shimtspath.RootedFilePathFromAbsolute(source))) != physical {
+    t.Fatal("physical source coordinate changed")
+  }
+  fresh, err := openCompilationSnapshot(DefaultFS(), newDocument("next"))
+  if err != nil {
+    t.Fatal(err)
+  }
+  if text, ok := fresh.ReadFile(file); !ok || text != "AFTER" {
+    t.Fatalf("new invocation: %q %v", text, ok)
+  }
+  if !fresh.FileExists(absent) {
+    t.Fatal("new invocation missed created source")
+  }
+  write(document, `{"version":2}`)
+  if _, err := openCompilationSnapshot(DefaultFS(), document); err == nil {
+    t.Fatal("invalid snapshot accepted")
+  }
+  write(document, "{")
+  if _, err := openCompilationSnapshot(DefaultFS(), document); err == nil {
+    t.Fatal("malformed snapshot accepted")
+  }
+}

package/driver/compilation_snapshot_preserves_checked_emission_test.go

@@ -0,0 +1,100 @@
+package driver
+
+import (
+  "os"
+  "path/filepath"
+  "strings"
+  "testing"
+
+  shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+)
+
+// TestCompilationSnapshotPreservesCheckedEmission verifies consecutive compiler
+// stages check and emit captured text after the physical source is edited.
+// The next invocation must still reject the new ill-typed source.
+//
+// 1. Load and check an authored string assignment under a private snapshot.
+// 2. Introduce an incompatible number, then load and emit the captured source.
+// 3. Start a fresh snapshot and require the actual type error to be reported.
+//
+// @evidence contracts/testing.md#behavioral-verification Real driver loading, diagnostics, graph capture and emission share captured BEFORE text across two native Programs while a new invocation reports TS2322 for the changed disk source.
+// @evidence contracts/testing.md#independent-expectations Authored string and number assignments define TypeScript assignability; literal BEFORE emission and diagnostic code 2322 do not come from implementation snapshots.
+// @evidence contracts/testing.md#distinguishing-cases A same-invocation stage must preserve old successful emission while a new invocation must observe the adjacent type error; source graph identity and output provenance must remain populated.
+// @evidence contracts/testing.md#execution-ownership This Go driver unit exercises linked compiler APIs in-process over private files, without a consumer installation, native build or spawned product host.
+func TestCompilationSnapshotPreservesCheckedEmission(t *testing.T) {
+  root := t.TempDir()
+  source := filepath.Join(root, "source.ts")
+  config := filepath.Join(root, "tsconfig.json")
+  document := filepath.Join(t.TempDir(), "inputs.json")
+  write := func(file, text string) {
+    t.Helper()
+    if err := os.WriteFile(file, []byte(text), 0600); err != nil {
+      t.Fatal(err)
+    }
+  }
+  fresh := func(id string) {
+    write(document, `{"version":1,"id":"`+id+`","reads":{},"files":{},"directories":{},"entries":{},"realpaths":{},"stats":{}}`)
+  }
+  write(config, `{"compilerOptions":{"target":"es2020","module":"commonjs","types":[],"strict":true},"files":["source.ts"]}`)
+  write(source, `export const value: string = "BEFORE";`)
+  fresh("first")
+  t.Setenv("TTSC_COMPILATION_SNAPSHOT", document)
+  load := func() *Program {
+    t.Helper()
+    program, diagnostics, err := LoadProgram(root, config, LoadProgramOptions{})
+    if err != nil || program == nil || len(diagnostics) != 0 {
+      t.Fatalf("load: %v %v", err, diagnostics)
+    }
+    return program
+  }
+  first := load()
+  if diagnostics := first.Diagnostics(); len(diagnostics) != 0 {
+    t.Fatalf("first check: %v", diagnostics)
+  }
+  if err := first.Close(); err != nil {
+    t.Fatal(err)
+  }
+  write(source, `export const value: string = 123;`)
+  second := load()
+  defer second.Close()
+  if diagnostics := second.Diagnostics(); len(diagnostics) != 0 {
+    t.Fatalf("captured check: %v", diagnostics)
+  }
+  graph := NewTransformGraph(second, root)
+  if graph.CompilationSnapshot != "first" || len(graph.InputProofFailures) != 0 {
+    t.Fatalf("graph lost captured authority: %+v", graph)
+  }
+  var emitted strings.Builder
+  writer, provenance, err := second.NewEmitProvenanceRecorder(func(_ shimtspath.RootedFilePath, text string, _ *shimcompiler.WriteFileData) error {
+    emitted.WriteString(text)
+    return nil
+  })
+  if err != nil {
+    t.Fatal(err)
+  }
+  if _, diagnostics, err := second.EmitAll(NewRewriteSet(), writer); err != nil || len(diagnostics) != 0 {
+    t.Fatalf("emit: %v %v", err, diagnostics)
+  }
+  if !strings.Contains(emitted.String(), "BEFORE") || strings.Contains(emitted.String(), "123") {
+    t.Fatalf("emitted another input: %s", emitted.String())
+  }
+  if len(provenance()) == 0 {
+    t.Fatal("captured emission lost source ownership")
+  }
+  if err := second.Close(); err != nil {
+    t.Fatal(err)
+  }
+  fresh("next")
+  next := load()
+  defer next.Close()
+  found := false
+  for _, diagnostic := range next.Diagnostics() {
+    if diagnostic.Code == 2322 {
+      found = true
+    }
+  }
+  if !found {
+    t.Fatal("new invocation did not report the edited source's TS2322")
+  }
+}

package/driver/graph.go

@@ -70,6 +70,9 @@ const bundledScheme = "bundled:///"
 // @evidenceExclude contracts/performance.md#reuse-equivalent-work This schema carries proof without coordinating artifact reuse.
 // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller-owned value owns no resident cache or resource.
 type TransformGraph struct {
+  // CompilationSnapshot identifies the shared read-once view of every native stage.
+  // It authorizes fresh delivery, not reuse after the disk changes.
+  CompilationSnapshot string `json:"compilationSnapshot,omitempty"`
   // Membership is the effective native root-admission and output-exclusion policy.
   Membership *TransformMembership `json:"membership,omitempty"`
   // ContentMapperInputs are declared project dependencies, not observed reads.
@@ -93,14 +96,14 @@ type TransformGraph struct {
 // `cmd/ttsc api-transform` and the linked-plugin utility host both do.
 // Returns nil only for a nil or unloaded program.
 //
-// @evidence contracts/common.md#principled-implementation Compiler references, global scope, config ancestry, and replayed predicates form one generation's dependency proof.
+// @evidence contracts/common.md#principled-implementation Compiler references, global scope, config ancestry and replayed predicates form one generation's dependency proof; a shared snapshot identity is attached only after its captured answers are published.
 // @evidence contracts/common.md#clear-and-simple-design Reference collection, resolution replay, and proof attachment share one output-key owner.
 // @evidence contracts/common.md#prohibited-implementation-shortcuts Unobserved or contradictory inputs remain failures rather than later filesystem snapshots substituted for compiler reads.
 // @evidence contracts/common.md#meaningful-documentation Native prose specifies envelope integration and unloaded-program behavior following the documentation skill.
 // @evidence contracts/portability.md#os-neutral-implementation Keys use native filepath conversion and compiler case policy; identity metadata comes from reported adapter realpaths, whose native VFS error fallback can retain lexical spelling rather than certifying physical resolution.
-// @evidence contracts/performance.md#efficient-algorithms Direct adjacency avoids computing every transitive closure. Construction scans resident sources/references, converts path text and sorts per-source targets, globals and resolver inputs; a distinct-input set selects proof attachment, whose rich and legacy projections can perform two observer lookups. Resolver task sorting, native replay reads/metadata/enumeration and observation merging remain part of this call's delegated cost; no work or byte ceiling is imposed here.
+// @evidence contracts/performance.md#efficient-algorithms Direct adjacency avoids computing every transitive closure. Construction scans resident sources/references, converts path text and sorts per-source targets, globals and resolver inputs; a distinct-input set selects proof attachment, whose rich and legacy projections can perform two observer lookups. Resolver task sorting, native replay reads/metadata/enumeration and observation merging remain part of this call's delegated cost; dirty snapshot publication additionally encodes and writes the complete captured text, paths and predicate population. No work or byte ceiling is imposed here.
 // @evidence contracts/performance.md#reuse-equivalent-work Final proof projection reuses the current Program observer, including its exact physical-target read for a lexical alias; it does not replace missing compiler evidence with a new read. Resolver replay separately performs native queries and merges contradictions into that generation. No prior graph or later filesystem generation is reused by this constructor.
-// @evidence contracts/performance.md#bound-retention-and-release-resources Temporary adjacency/input/proof maps grow with resident references, distinct paths and reported predicate bytes. Graph arrays/maps transfer to the caller, while replay observations merge into the caller-owned current Program observer. This call owns no resident historical graph cache or native handle, and supplies no population/byte ceiling or caller-lifetime disposal policy.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Temporary adjacency/input/proof maps grow with resident references, distinct paths and reported predicate bytes. Graph arrays/maps transfer to the caller, while replay observations merge into the caller-owned current Program observer. Snapshot encoding adds a temporary complete document buffer, and a failed rename can leave invocation-owned staging for coordinator cleanup. This call owns no resident historical graph cache or persistent native handle, and supplies no population/byte ceiling or caller-lifetime disposal policy.
 func NewTransformGraph(prog *Program, cwd string) *TransformGraph {
   if prog == nil || prog.TSProgram == nil {
     return nil
@@ -154,6 +157,9 @@ func NewTransformGraph(prog *Program, cwd string) *TransformGraph {
     graph.InputProofFailures = resolution.Failures
   }
   graph.attachInputProof(prog, cwd)
+  if snapshot := prog.compilationSnapshot; snapshot != nil && snapshot.save() == nil {
+    graph.CompilationSnapshot = snapshot.data.ID
+  }
   return graph
 }
 

package/driver/program.go

@@ -2,6 +2,7 @@ package driver
 
 import (
   "context"
+  "errors"
   "fmt"
   "io"
   "os"
@@ -329,8 +330,9 @@ type Program struct {
   compilerArgumentInputs []string
 
   // FS is the input-observing filesystem, including any source preamble layer.
-  FS            vfs.FS
-  inputObserver *inputObservationFS
+  FS                  vfs.FS
+  compilationSnapshot *compilationSnapshotFS
+  inputObserver       *inputObservationFS
 
   // SourcePreamble is the injected text used when correcting authored positions.
   SourcePreamble  string
@@ -407,16 +409,16 @@ type LoadProgramOptions struct {
 
 // Close releases the checker pool lease acquired by LoadProgram and, on the
 // TypeScript 7.1 target, stops the project's content-mapper processes. Its
-// error is the content mappers' close error.
+// error joins content-mapper shutdown and compilation-snapshot publication errors.
 //
-// @evidence contracts/common.md#principled-implementation The recorded release callback returns the checker lease once and is cleared after release; the project hosts then close the mapper project and processes the Program's hosts shared.
+// @evidence contracts/common.md#principled-implementation The checker lease and project hosts are detached once; dirty snapshot answers are published through their detached invocation owner, and mapper and publication errors are joined without skipping mapper shutdown.
 // @evidence contracts/common.md#clear-and-simple-design Checker and content-mapper ownership share one cleanup operation instead of independent releases by each consumer.
-// @evidence contracts/common.md#prohibited-implementation-shortcuts Cleanup invokes the owned callbacks rather than patching the checker pool, and returns the mapper close error instead of fabricating success.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Cleanup invokes the owned callbacks rather than patching the checker pool, and returns joined mapper/publication errors instead of fabricating success.
 // @evidence contracts/common.md#meaningful-documentation Native prose names the lease and the mapper processes released and the error returned, following the documentation skill.
-// @evidence contracts/portability.md#os-neutral-implementation Checker release is in-process; stopping a mapper process goes through the shim's os/exec boundary.
-// @evidenceExclude contracts/performance.md#efficient-algorithms Releasing two recorded owners involves no input-processing algorithm.
-// @evidenceExclude contracts/performance.md#reuse-equivalent-work Cleanup does not determine whether compiler outputs may be reused.
-// @evidence contracts/performance.md#bound-retention-and-release-resources Program owns one checker lease and its project hosts; Close clears both, so repeated Close releases neither twice, and leaves facade memory lifetime to the caller.
+// @evidence contracts/portability.md#os-neutral-implementation Checker release is in-process; mapper shutdown uses the shim's os/exec boundary, while dirty snapshot publication uses native file writes and same-directory rename.
+// @evidence contracts/performance.md#efficient-algorithms Release bookkeeping is fixed work; a dirty snapshot additionally serializes and writes its complete captured text, paths and predicates, with temporary encoded bytes proportional to that population.
+// @evidence contracts/performance.md#reuse-equivalent-work Detaching publication ownership prevents repeated Close from overwriting a later stage; a clean snapshot avoids repeated serialization. This does not establish output-cache freshness.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Program owns the checker lease, project hosts and one snapshot publication owner; Close detaches them once. The FS stack and caller aliases can still retain captured text and predicate maps until released; invocation storage cleanup belongs to the coordinator, and publication failure can leave staging for that cleanup.
 func (p *Program) Close() error {
   if p.checkerRelease != nil {
     p.checkerRelease()
@@ -424,7 +426,12 @@ func (p *Program) Close() error {
   }
   hosts := p.hosts
   p.hosts = nil
-  return hosts.Close()
+  var snapshotError error
+  if snapshot := p.compilationSnapshot; snapshot != nil {
+    p.compilationSnapshot = nil
+    snapshotError = snapshot.save()
+  }
+  return errors.Join(hosts.Close(), snapshotError)
 }
 
 // ParseTSConfig parses a tsconfig.json file via tsgo's native JSONC parser.
@@ -590,15 +597,20 @@ func forceSingleChecker(parsed *tsoptions.ParsedCommandLine) {
 // Relative cwd is resolved against the process cwd when filepath.Abs succeeds;
 // callers should provide an absolute anchor. tsconfigPath may be relative to it.
 //
+// An enabled private compilation-snapshot document shares first-read text and
+// lookup answers across sequential native stages. This is not an atomic volume
+// snapshot. Program owns dirty publication through Close; the invocation
+// coordinator owns removal of the private transport storage.
+//
 // @evidence contracts/common.md#principled-implementation Plugin preambles enter before parsing, native CLI/config merging resolves options before Program creation, and the facade associates the observing VFS and borrowed checker with that generation; this is not a certificate of every filesystem access by plugins or their host.
 // @evidence contracts/common.md#clear-and-simple-design One loader orders plugin config, filesystem layers, config overrides and checker acquisition; an optional failure sink transfers only the rejected load's observed recovery inputs.
 // @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid configuration or CLI input returns before construction; an explicitly empty argument list does not fall through to an ancestor's flags.
 // @evidence contracts/common.md#meaningful-documentation Native prose and options document one-shot load, path anchoring, force overrides and checker ownership under documentation-skill guidance.
 // @evidence contracts/portability.md#os-neutral-implementation Native cwd resolution uses filepath/tspath and the chosen VFS provides actual case and path capabilities; semantic wrapper ownership uses an explicit config path.
-// @evidence contracts/performance.md#efficient-algorithms One load composes plugin/preamble work, config/CLI parsing, native Program processing and checker acquisition with VFS observation. A requested failed-load graph additionally snapshots, projects and sorts the observed predicate population and invokes the caller's sink. Read-text hashing runs on each observed read, including repeated reads; config/source bytes, native resolution and directory work, plugin callbacks and retained observation maps govern cost rather than only facade construction.
-// @evidenceExclude contracts/performance.md#reuse-equivalent-work This one-shot factory does not coordinate callers; Session and resident hosts own cross-request compiler reuse.
-// @evidence contracts/performance.md#bound-retention-and-release-resources Errors before checker acquisition return no lease; an optional synchronous sink receives call-owned recovery metadata once after observation starts. Successful loading transfers checker and mapper ownership plus input/plugin ledgers to Program; Close releases owned native resources, while caller reachability controls remaining facade state.
-func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program, []Diagnostic, error) {
+// @evidence contracts/performance.md#efficient-algorithms One load composes plugin/preamble work, config/CLI parsing, native Program processing and checker acquisition with VFS observation. A requested failed-load graph additionally snapshots, projects and sorts the observed predicate population and invokes the caller's sink. An enabled snapshot also parses the preceding full document and publishes its dirty complete captured population. Read-text hashing runs on each observed read, including repeated reads; config/source bytes, native resolution and directory work, plugin callbacks and retained observation maps govern cost rather than only facade construction.
+// @evidence contracts/performance.md#reuse-equivalent-work An enabled private document shares first-read answers only across sequential stages of its invocation; fresh invocations start empty. Session and resident hosts retain ownership of cross-request Program reuse.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Errors before checker acquisition return no lease; an optional synchronous sink receives call-owned recovery metadata once after observation starts. Successful loading transfers checker and mapper ownership plus input/plugin ledgers to Program; Close releases owned native resources and detaches snapshot publication; FS/caller reachability controls captured-memory lifetime, and the invocation coordinator removes transport storage.
+func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (program *Program, diagnostics []Diagnostic, loadError error) {
   if !filepath.IsAbs(cwd) {
     if abs, err := filepath.Abs(cwd); err == nil {
       cwd = abs
@@ -624,6 +636,24 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
   if fs == nil {
     fs = DefaultFS()
   }
+  var snapshot *compilationSnapshotFS
+  if filename := os.Getenv("TTSC_COMPILATION_SNAPSHOT"); filename != "" {
+    var err error
+    snapshot, err = openCompilationSnapshot(fs, filename)
+    if err != nil {
+      return nil, nil, fmt.Errorf("compilation snapshot: %w", err)
+    }
+    fs = snapshot
+    defer func() {
+      if err := snapshot.save(); err != nil {
+        if program != nil {
+          program.Close()
+          program = nil
+        }
+        loadError = errors.Join(loadError, fmt.Errorf("compilation snapshot publication: %w", err))
+      }
+    }()
+  }
   inputObserver := newInputObservationFS(fs)
   loaded := false
   if options.OnFailureInputs != nil {
@@ -716,6 +746,7 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
     mapperDependencyError:  mapperDependencyError,
     compilerArgumentInputs: compilerArgumentInputs,
     FS:                     fs,
+    compilationSnapshot:    snapshot,
     inputObserver:          inputObserver,
     SourcePreamble:         options.SourcePreamble,
   }