ttsc 0.34.1 → 0.34.3

package/cmd/ttsc/api_transform.go

@@ -69,13 +69,16 @@ type apiTransformResult struct {
 // The actual preparation supplies ForceNoEmit and resolved argv/cwd. This
 // wrapper owns its one LoadProgram call and closes a nonnil acquired Program
 // after the borrowed source-response operation returns. That response owner
-// constructs the graph before linked source hooks and never emits files.
+// constructs the graph before linked source hooks and never emits files. Failed
+// config/argument parsing retains its actual recovery graph without a Program.
 func runAPITransform(args []string) int {
   request, code := prepareAPITransformInvocation(args)
   if code != 0 {
     return code
   }
   cwd := request.cwd
+  var recovery *driver.TransformGraph
+  request.options.OnFailureInputs = func(graph *driver.TransformGraph) { recovery = graph }
   prog, diags, err := driver.LoadProgram(cwd, request.tsconfigPath, request.options)
   if err != nil {
     fmt.Fprintf(stderr, "ttsc api-transform: %v\n", err)
@@ -84,7 +87,7 @@ func runAPITransform(args []string) int {
   if prog != nil {
     defer prog.Close()
   }
-  return writeTransformedProgramResponse(prog, diags, cwd)
+  return writeTransformedProgramResponse(prog, diags, cwd, recovery)
 }
 
 // writeTransformedProgramResponse borrows the loaded generation for the actual
@@ -102,14 +105,21 @@ func runAPITransform(args []string) int {
 // Performance: Efficient algorithms: The original graph, resident-file enumeration and one JSON encoding remain; work scales with actual graph/source/envelope bytes.
 // Performance: Reuse equivalent work: An immutable no-plugin generation already emitted to memory can supply its original source text and graph without a second load. This is operation-level reuse, not a claim of equal compile/transform loader policies.
 // Performance: Bound retention and release resources: The caller retains the checker lease across borrowing and closes it once after the final consumer; this operation creates invocation-local envelope collections and does not own the lease or a retained cache.
-func writeTransformedProgramResponse(prog *driver.Program, diags []driver.Diagnostic, cwd string) int {
+func writeTransformedProgramResponse(prog *driver.Program, diags []driver.Diagnostic, cwd string, recovery ...*driver.TransformGraph) int {
   typescript := map[string]string{}
   var dependencies driver.TransformDependencies
   var graph *driver.TransformGraph
+  if len(recovery) != 0 {
+    graph = recovery[0]
+  }
   var hostInputs []string
   var hostInputHashes map[string]*string
   var hostInputRealpaths map[string]*string
   var observationsComplete *bool
+  if prog == nil {
+    unavailable := false
+    observationsComplete = &unavailable
+  }
   if prog != nil {
     // Compute the reference graph before SourceFiles() runs linked plugin
     // hooks: those mutate parsed ASTs in place, and the graph must describe

package/cmd/ttsc/api_transform_config_recovery_test.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+  "encoding/json"
+  "slices"
+  "testing"
+)
+
+// TestAPITransformConfigFailureRetainsRecoveryInputs verifies the actual
+// built-in transform command transports failed-load observations.
+//
+// Source output cannot carry repair inputs when config parsing creates no Program.
+//
+//  1. Run the actual API command on a missing extended config and response file.
+//  2. Decode its native stdout envelope and retain the failure status.
+//  3. Require missing config predicates and response reads without source output.
+//
+// @evidence contracts/testing.md#behavioral-verification Real runAPITransform consumes its ordinary argument preparation and loader, then serializes failed-load recovery metadata rather than dropping it with the nil Program.
+// @evidence contracts/testing.md#independent-expectations Status 2, empty TypeScript, literal missing.json/main.rsp inputs and a false existence predicate define expected failure transport independently of command output.
+// @evidence contracts/testing.md#distinguishing-cases A pre-Program config failure contrasts the existing semantic-error Program case; actual argv response expansion remains observable in the failure graph on both targets.
+// @evidence contracts/testing.md#execution-ownership The command Go runner owns one temporary project and invocation-local captured streams; the actual command executes in process without a separate build or compiler subprocess.
+func TestAPITransformConfigFailureRetainsRecoveryInputs(t *testing.T) {
+  root := t.TempDir()
+  writeCommandProjectFile(t, root, "tsconfig.json", `{"extends":"./missing.json","files":["main.ts"]}`)
+  writeCommandProjectFile(t, root, "main.ts", "export const value = 1;\n")
+  writeCommandProjectFile(t, root, "main.rsp", "--strict\n")
+  code, output, stderr := captureCommand(t, func() int {
+    return runAPITransform([]string{"--cwd", root, "--tsconfig", "tsconfig.json", "--tsgo-args", `["@main.rsp"]`})
+  })
+  var result apiTransformResult
+  if err := json.Unmarshal([]byte(output), &result); err != nil {
+    t.Fatalf("response decode: %v stdout=%s stderr=%s", err, output, stderr)
+  }
+  if code != 2 || len(result.TypeScript) != 0 || result.Graph == nil || !slices.Contains(result.Graph.ResolutionInputs, "missing.json") || !slices.Contains(result.Graph.ResolutionInputs, "main.rsp") {
+    t.Fatalf("lost config recovery metadata: code=%d output=%s stderr=%s", code, output, stderr)
+  }
+  if result.ObservationsComplete == nil || *result.ObservationsComplete {
+    t.Fatalf("failed load claimed complete observations: %s", output)
+  }
+  absent := result.Graph.InputObservations["missing.json"].FileExists
+  if absent == nil || *absent {
+    t.Fatalf("lost config absence predicate: %s", output)
+  }
+}

package/driver/check_observations.go

@@ -11,8 +11,10 @@ import (
 // caller must keep the Program open until this snapshot is written. Command
 // status and diagnostics remain independent of these observation facts.
 //
-// A nil Program publishes empty observation collections and an explicit incomplete
-// marker, because no generation supplied input authority. For a loaded Program,
+// A nil Program publishes empty hook observation collections and an explicit
+// incomplete marker. WriteCheckRecoveryObservationsJSON additionally accepts
+// actual failed-load CLI/config predicates without completed Program authority.
+// For a loaded Program,
 // only an explicit hook limitation adds that marker. Its absence does not prove
 // the population complete or repair missing or conflicting individual proofs.
 // The caller owns a fresh result path, its parent directory and eventual artifact
@@ -27,6 +29,23 @@ import (
 // @evidence contracts/performance.md#reuse-equivalent-work The same check generation's recorded observations supply the result without reparsing sources or reexecuting configuration hooks.
 // @evidence contracts/performance.md#bound-retention-and-release-resources Scope snapshots and encoding buffers are call-local without a payload cap. The shared publisher closes its temporary descriptor before rename and attempts removal on failure, returning cleanup errors; the caller owns the Program, fresh destination, parent directory and final artifact removal.
 func WriteCheckObservationsJSON(fileName string, program *Program) error {
+  return WriteCheckRecoveryObservationsJSON(fileName, program, nil)
+}
+
+// WriteCheckRecoveryObservationsJSON publishes check observations with an
+// optional failed-load recovery graph. A loaded Program always supplies its own
+// graph instead; nil Program remains explicitly incomplete. The recovery graph
+// comes from that invocation's OnFailureInputs sink, not a later filesystem read.
+//
+// @evidence contracts/common.md#principled-implementation Loaded Program observations retain their generation; only a nil Program admits supplied failed-load predicates, with explicit incomplete hook authority.
+// @evidence contracts/common.md#clear-and-simple-design One publisher serves the original two-argument API and native callers retaining failed-load recovery inputs.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No fake Program, reconstructed resolver or later read supplies recovery metadata; status remains separate.
+// @evidence contracts/common.md#meaningful-documentation Native prose states recovery provenance, Program precedence and incomplete authority.
+// @evidence contracts/portability.md#os-neutral-implementation Native absolute path validation and the existing same-directory private publisher retain observation spellings unchanged.
+// @evidence contracts/performance.md#efficient-algorithms Program accessors snapshot current ledgers and graph; JSON encoding and publication visit retained predicate/path bytes and allocate the serialized payload without a population cap.
+// @evidence contracts/performance.md#reuse-equivalent-work The invocation's existing observations supply metadata without another compiler load or filesystem proof read.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns Program/recovery lifetimes and the final artifact; call-local snapshots and encoding buffers add no historical registry, and the shared publisher closes temporary handles.
+func WriteCheckRecoveryObservationsJSON(fileName string, program *Program, recovery *TransformGraph) error {
   if !filepath.IsAbs(fileName) {
     return fmt.Errorf("driver: check observations path must be absolute: %q", fileName)
   }
@@ -35,6 +54,9 @@ func WriteCheckObservationsJSON(fileName string, program *Program) error {
   realpaths := map[string]*string{}
   var complete *bool
   var graph *TransformGraph
+  if program == nil {
+    graph = recovery
+  }
   if program == nil || program.PluginObservationsIncomplete() {
     unavailable := false
     complete = &unavailable

package/driver/compileraliases/names.go

@@ -0,0 +1,69 @@
+// Package compileraliases discovers npm aliases by their declared package target.
+package compileraliases
+
+import (
+  "encoding/json"
+  "os"
+  "path/filepath"
+  "sort"
+  "strings"
+)
+
+// Names returns declared npm aliases targeting typescript, followed by the
+// ordinary typescript name. The nearest ancestor manifest declaring TypeScript
+// or its aliases owns discovery; installed dependency trees are not scanned.
+// Callers still resolve each name and verify its installed package identity.
+//
+// @evidence contracts/common.md#principled-implementation npm aliases declare a real target independently of their exposed name. Ancestor manifest dependency maps supply those arbitrary names, while installed identity and native version remain with the caller.
+// @evidence contracts/common.md#clear-and-simple-design This package owns declaration discovery once for all Go config evaluators; each evaluator retains its existing Node-style manifest and platform resolution.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Only npm's target syntax and the real typescript identity are constants. No alias name, consumer or fixture controls selection.
+// @evidence contracts/common.md#meaningful-documentation The comment defines filename anchors, ancestor traversal, output ordering and the caller's verification obligation; read or parse errors propagate except absent manifests.
+// @evidence contracts/portability.md#os-neutral-implementation filepath.Abs, Dir and Join follow native paths; os.ReadFile closes its handles and no shell or filesystem case assumption is used.
+// @evidence contracts/performance.md#efficient-algorithms The walk parses ancestor manifest bytes and visits D dependency declarations once; A unique aliases require O(A) retained names and O(A log A) sorting. No installed package population is traversed.
+//
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Mutable project declarations have no invalidation owner here, so every call reads current bytes.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous reads retain no handle; the returned name slice transfers to the caller.
+func Names(anchor string) ([]string, error) {
+  absolute, err := filepath.Abs(anchor)
+  if err != nil {
+    return nil, err
+  }
+  aliases := make(map[string]struct{})
+  for directory := filepath.Dir(absolute); ; directory = filepath.Dir(directory) {
+    body, err := os.ReadFile(filepath.Join(directory, "package.json"))
+    if err != nil && !os.IsNotExist(err) {
+      return nil, err
+    }
+    if err == nil {
+      var project map[string]any
+      if err := json.Unmarshal(body, &project); err != nil {
+        return nil, err
+      }
+      declaresTypeScript := false
+      for _, field := range []string{"dependencies", "devDependencies", "optionalDependencies"} {
+        dependencies, _ := project[field].(map[string]any)
+        if _, exists := dependencies["typescript"]; exists {
+          declaresTypeScript = true
+        }
+        for name, value := range dependencies {
+          specifier, ok := value.(string)
+          if name != "typescript" && ok && (specifier == "npm:typescript" || strings.HasPrefix(specifier, "npm:typescript@")) {
+            aliases[name] = struct{}{}
+          }
+        }
+      }
+      if declaresTypeScript || len(aliases) != 0 {
+        break
+      }
+    }
+    if filepath.Dir(directory) == directory {
+      break
+    }
+  }
+  names := make([]string, 0, len(aliases)+1)
+  for name := range aliases {
+    names = append(names, name)
+  }
+  sort.Strings(names)
+  return append(names, "typescript"), nil
+}

package/driver/compileraliases/names_test.go

@@ -0,0 +1,57 @@
+package compileraliases
+
+import (
+  "os"
+  "path/filepath"
+  "reflect"
+  "testing"
+)
+
+// TestNamesUsesTheNearestCompilerDeclaration verifies npm alias discovery from
+// declarations rather than a reserved exposed name.
+//
+// 1. Declare arbitrary aliases across all supported dependency maps.
+// 2. Discover them from a nested file, excluding a different npm target.
+// 3. Give the nested package its own compiler declaration and require isolation.
+//
+// @evidence contracts/testing.md#behavioral-verification Calls Names over authored manifests and compares the candidate names it returns; an npm target lookalike must be excluded and a workspace's own compiler declaration must stop ancestor alias discovery.
+// @evidence contracts/testing.md#independent-expectations The aliases alpha, middle and zeta target typescript by literal npm syntax; the contract sorts them before the ordinary typescript fallback. A local typescript declaration independently prescribes the singleton fallback.
+// @evidence contracts/testing.md#distinguishing-cases Exercises dependencies, devDependencies and optionalDependencies, an unrelated target, nested discovery, local declaration isolation, malformed metadata failure and an absent local manifest after removal.
+// @evidence contracts/testing.md#execution-ownership This directly discovered Go unit calls Names in-process over t.TempDir inputs. It resolves no installed compiler and starts no process.
+func TestNamesUsesTheNearestCompilerDeclaration(t *testing.T) {
+  root := t.TempDir()
+  nested := filepath.Join(root, "workspace")
+  if err := os.MkdirAll(nested, 0o755); err != nil {
+    t.Fatal(err)
+  }
+  write := func(file, body string) {
+    t.Helper()
+    if err := os.WriteFile(file, []byte(body), 0o644); err != nil {
+      t.Fatal(err)
+    }
+  }
+  write(filepath.Join(root, "package.json"), `{"dependencies":{"zeta":"npm:typescript@7","unrelated":"npm:typescript-helper@7"},"devDependencies":{"alpha":"npm:typescript@next"},"optionalDependencies":{"middle":"npm:typescript"}}`)
+  anchor := filepath.Join(nested, "lint.config.ts")
+  got, err := Names(anchor)
+  want := []string{"alpha", "middle", "zeta", "typescript"}
+  if err != nil || !reflect.DeepEqual(got, want) {
+    t.Fatalf("Names = %v, %v; want %v", got, err, want)
+  }
+  manifest := filepath.Join(nested, "package.json")
+  write(manifest, `{"devDependencies":{"typescript":"7.0.2"}}`)
+  got, err = Names(anchor)
+  if err != nil || !reflect.DeepEqual(got, []string{"typescript"}) {
+    t.Fatalf("local Names = %v, %v; want [typescript]", got, err)
+  }
+  write(manifest, "{")
+  if _, err := Names(anchor); err == nil {
+    t.Fatal("malformed manifest must fail discovery")
+  }
+  if err := os.Remove(manifest); err != nil {
+    t.Fatal(err)
+  }
+  got, err = Names(anchor)
+  if err != nil || !reflect.DeepEqual(got, want) {
+    t.Fatalf("restored Names = %v, %v; want %v", got, err, want)
+  }
+}

package/driver/graph.go

@@ -37,7 +37,7 @@ const bundledScheme = "bundled:///"
 //     results. They are a separate class from resolved edges: a predicate or
 //     package manifest changing can change an unchanged reference's meaning.
 //   - ResolutionInputs lists automatic type discovery and resolution inputs
-//     whose state can affect every source file, including type-root directory
+//     whose state can affect every source file, including compiler response files and type-root directory
 //     membership.
 //   - InputObservations preserves the independent filesystem predicates the
 //     compiler actually asked. InputHashes and InputRealpaths retain the legacy
@@ -48,6 +48,14 @@ const bundledScheme = "bundled:///"
 //     project's root specs and compared paths with, so a host deciding the
 //     same membership uses the compiler's policy rather than a guess from the
 //     platform.
+//   - ContentMapperInputs lists mapper manifests and upstream-declared dynamic
+//     dependencies for every output. They are declarations, not observed reads,
+//     and require independent before/after dependency witnesses.
+//
+// A failed-load recovery graph contains only the CLI/config predicates observed
+// before Program construction failed. Empty source/config lists and absent
+// membership settings supply no completed Program authority. Failure status and
+// explicit observation limitations remain in the containing response.
 //
 // Keys and values use the same convention as the envelope's `typescript`
 // map: project-relative slash paths, falling back to slash-normalized
@@ -62,6 +70,11 @@ 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 {
+  // Membership is the effective native root-admission and output-exclusion policy.
+  Membership *TransformMembership `json:"membership,omitempty"`
+  // ContentMapperInputs are declared project dependencies, not observed reads.
+  // Consumers witness them before compilation independently of graph proof.
+  ContentMapperInputs       []string                             `json:"contentMapperInputs,omitempty"`
   Edges                     map[string][]string                  `json:"edges"`
   Globals                   []string                             `json:"globals"`
   Configs                   []string                             `json:"configs"`
@@ -94,6 +107,7 @@ func NewTransformGraph(prog *Program, cwd string) *TransformGraph {
   }
   resolution := ObserveProgramResolutions(prog, cwd)
   graph := &TransformGraph{
+    Membership:                programRootMembership(prog),
     Edges:                     map[string][]string{},
     Globals:                   []string{},
     Configs:                   []string{},
@@ -101,6 +115,22 @@ func NewTransformGraph(prog *Program, cwd string) *TransformGraph {
     ResolutionInputs:          resolution.Universal,
     UseCaseSensitiveFileNames: prog.TSProgram.UseCaseSensitiveFileNames(),
   }
+  for _, input := range prog.mapperDependencies {
+    graph.ContentMapperInputs = append(graph.ContentMapperInputs, TransformOutputKey(cwd, input))
+  }
+  sort.Strings(graph.ContentMapperInputs)
+  argumentInputs := map[string]struct{}{}
+  for _, input := range graph.ResolutionInputs {
+    argumentInputs[input] = struct{}{}
+  }
+  for _, input := range prog.compilerArgumentInputs {
+    key := TransformOutputKey(cwd, input)
+    if _, found := argumentInputs[key]; !found {
+      graph.ResolutionInputs = append(graph.ResolutionInputs, key)
+      argumentInputs[key] = struct{}{}
+    }
+  }
+  sort.Strings(graph.ResolutionInputs)
   for _, file := range prog.TSProgram.SourceFiles() {
     fileName := file.FileName()
     if strings.HasPrefix(string(fileName), bundledScheme) {
@@ -135,6 +165,13 @@ func (graph *TransformGraph) attachInputProof(prog *Program, cwd string) {
   if prog == nil || prog.inputObserver == nil {
     return
   }
+  graph.attachObservedInputProof(prog.inputObserver, cwd)
+}
+
+// attachObservedInputProof projects only this observer's existing predicates.
+// Failed CLI/config loads use it without constructing a compiler Program;
+// successful graph construction retains the same realized-source requirements.
+func (graph *TransformGraph) attachObservedInputProof(observer *inputObservationFS, cwd string) {
   inputs := map[string]struct{}{}
   realized := map[string]struct{}{}
   addRealized := func(input string) {
@@ -174,14 +211,14 @@ func (graph *TransformGraph) attachInputProof(prog *Program, cwd string) {
     if !filepath.IsAbs(file) {
       file = filepath.Join(cwd, file)
     }
-    observation, predicateFailure := prog.inputObserver.predicateProof(file)
+    observation, predicateFailure := observer.predicateProof(file)
     if predicateFailure == "" {
       observations[input] = observation
     }
     var hash, realpath *string
     legacyFailure := predicateFailure
     if predicateFailure == "" {
-      hash, realpath, legacyFailure = prog.inputObserver.proof(file)
+      hash, realpath, legacyFailure = observer.proof(file)
     }
     if legacyFailure != "" {
       // A resolver input can have a complete predicate proof that the legacy

package/driver/input_observation.go

@@ -271,6 +271,22 @@ func boolPointer(value bool) *bool {
   return &value
 }
 
+// readPaths snapshots the lexical reads already made through this observer.
+// LoadProgram calls it immediately after upstream argument parsing, before
+// configuration or source reads can enter the population. It performs no new
+// filesystem query and keeps failed/conflicting observations for graph proof.
+func (fs *inputObservationFS) readPaths() []string {
+  fs.mu.Lock()
+  defer fs.mu.Unlock()
+  paths := make([]string, 0, len(fs.observationOrder))
+  for _, key := range fs.observationOrder {
+    if fs.observations[key].proof.ReadFile != nil {
+      paths = append(paths, fs.observationSpellings[key])
+    }
+  }
+  return paths
+}
+
 func (fs *inputObservationFS) observationKey(path string) string {
   if !filepath.IsAbs(path) {
     return ""

package/driver/program.go

@@ -323,7 +323,10 @@ type Program struct {
   Host shimcompiler.CompilerHost
   // hosts builds every generation's Host and owns the content-mapper processes
   // those hosts share; Close releases it.
-  hosts *shimcompiler.ProjectHosts
+  hosts                  *shimcompiler.ProjectHosts
+  mapperDependencies     []string
+  mapperDependencyError  error
+  compilerArgumentInputs []string
 
   // FS is the input-observing filesystem, including any source preamble layer.
   FS            vfs.FS
@@ -340,10 +343,10 @@ type Program struct {
 // the program. `ForceEmit` is used by `ttsc --emit` and runtime compilation
 // so execution still works when the project defaults to `noEmit`.
 //
-// @evidence contracts/common.md#principled-implementation Explicit overrides and an optional FS represent caller-owned load choices separately from resolved tsconfig values.
+// @evidence contracts/common.md#principled-implementation Explicit overrides, an optional FS and a failure-observation sink represent caller-owned load choices separately from resolved tsconfig values.
 // @evidence contracts/common.md#clear-and-simple-design One options value carries load-time choices; compiler option merging stays with LoadProgram and the native parser.
 // @evidence contracts/common.md#prohibited-implementation-shortcuts Dedicated fields express supported overrides without deriving policy from a fixture or consumer name.
-// @evidence contracts/common.md#meaningful-documentation Native member prose explains force emit, semantic config ownership, threading and optional FS under documentation-skill guidance.
+// @evidence contracts/common.md#meaningful-documentation Native member prose explains force emit, semantic config ownership, threading, optional FS and failed-load observation ownership under documentation-skill guidance.
 // @evidence contracts/portability.md#os-neutral-implementation FS supplies native capabilities and path fields retain caller spellings for the loader's supported normalization boundary.
 // @evidenceExclude contracts/performance.md#efficient-algorithms Options encode choices but perform no compilation algorithm.
 // @evidenceExclude contracts/performance.md#reuse-equivalent-work This input value does not establish whether loaded work can be shared.
@@ -394,6 +397,12 @@ type LoadProgramOptions struct {
   // is used. A resident Session passes an overlay FS so in-memory edits stay
   // visible to the program and to incremental UpdateProgram calls.
   FS vfs.FS
+
+  // OnFailureInputs receives the actual CLI/config input observations if this
+  // load exits after observation starts but before a Program is acquired. It
+  // runs synchronously once; it does not report a completed source population.
+  // Successful loads expose their graph through NewTransformGraph instead.
+  OnFailureInputs func(*TransformGraph)
 }
 
 // Close releases the checker pool lease acquired by LoadProgram and, on the
@@ -582,13 +591,13 @@ func forceSingleChecker(parsed *tsoptions.ParsedCommandLine) {
 // callers should provide an absolute anchor. tsconfigPath may be relative to it.
 //
 // @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; private helpers each own one policy.
+// @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. 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#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. Success transfers the lease, generation trees and input/plugin ledgers to Program without a byte cap; Close releases only the checker callback, while caller reachability controls facade state and separately retained plugin callbacks.
+// @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) {
   if !filepath.IsAbs(cwd) {
     if abs, err := filepath.Abs(cwd); err == nil {
@@ -616,6 +625,14 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
     fs = DefaultFS()
   }
   inputObserver := newInputObservationFS(fs)
+  loaded := false
+  if options.OnFailureInputs != nil {
+    defer func() {
+      if !loaded {
+        options.OnFailureInputs(inputObserver.recoveryGraph(cwd))
+      }
+    }()
+  }
   fs = inputObserver
   if options.SourcePreamble != "" {
     fs = sourcePreambleFS{
@@ -646,6 +663,7 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
   if len(cliDiags) > 0 {
     return nil, cliDiags, nil
   }
+  compilerArgumentInputs := inputObserver.readPaths()
 
   // Config identity is explicit; argument conversion uses the original argv
   // base, while the Program and linked plugin state retain their selected cwd.
@@ -684,21 +702,26 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
   hosts := shimcompiler.NewProjectHosts(parsed)
   host = projectHost(hosts, cwd, fs)
   tsProgram, _, _ := CreateProgramFromConfig(parsed, host)
+  mapperDependencies, mapperDependencyError := hosts.Dependencies()
 
   checker, done := tsProgram.GetTypeChecker(context.Background())
   prog := &Program{
-    TSProgram:      tsProgram,
-    ParsedConfig:   parsed,
-    Checker:        checker,
-    checkerRelease: done,
-    Host:           host,
-    hosts:          hosts,
-    FS:             fs,
-    inputObserver:  inputObserver,
-    SourcePreamble: options.SourcePreamble,
+    TSProgram:              tsProgram,
+    ParsedConfig:           parsed,
+    Checker:                checker,
+    checkerRelease:         done,
+    Host:                   host,
+    hosts:                  hosts,
+    mapperDependencies:     mapperDependencies,
+    mapperDependencyError:  mapperDependencyError,
+    compilerArgumentInputs: compilerArgumentInputs,
+    FS:                     fs,
+    inputObserver:          inputObserver,
+    SourcePreamble:         options.SourcePreamble,
   }
   prog.plugins = pluginState
   e2etrace.Program("program-load-outcome", "driver-create", "facade-installed", false, tsProgram)
+  loaded = true
   return prog, nil, nil
 }
 
@@ -1101,6 +1124,9 @@ func (p *Program) diagnostics(files []*ast.SourceFile) []Diagnostic {
   // `driver: nil program` above is the precedent for a driver-level entry with
   // no file or code.
   var out []Diagnostic
+  if p.mapperDependencyError != nil {
+    out = append(out, Diagnostic{Severity: SeverityError, Message: "driver: content mapper dependencies: " + p.mapperDependencyError.Error()})
+  }
   if p.pluginsApplied && p.pluginsApplyErr != nil {
     out = append(out, Diagnostic{
       Severity: SeverityError,

package/driver/recovery_graph.go

@@ -0,0 +1,25 @@
+package driver
+
+import (
+  "sort"
+
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+)
+
+// recoveryGraph retains the predicates already observed before a failed load.
+// Empty source/config populations make no Program-membership claim; every
+// observed path is universal recovery input, including missing candidates.
+// Snapshotting and proof projection perform no new filesystem operation. Work
+// and returned storage follow observed paths/predicates plus path sorting.
+func (fs *inputObservationFS) recoveryGraph(cwd string) *TransformGraph {
+  graph := &TransformGraph{
+    Edges: map[string][]string{}, Globals: []string{}, Configs: []string{},
+    UseCaseSensitiveFileNames: fs.caseSensitivity == shimtspath.CaseSensitive,
+  }
+  for _, input := range fs.observedPaths() {
+    graph.ResolutionInputs = append(graph.ResolutionInputs, TransformOutputKey(cwd, input))
+  }
+  sort.Strings(graph.ResolutionInputs)
+  graph.attachObservedInputProof(fs, cwd)
+  return graph
+}

package/driver/target_ts70.go

@@ -9,9 +9,21 @@ import (
   ast "github.com/microsoft/typescript-go/shim/ast"
   shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
   shimprinter "github.com/microsoft/typescript-go/shim/printer"
+  shimtsoptions "github.com/microsoft/typescript-go/shim/tsoptions"
   shimtspath "github.com/microsoft/typescript-go/shim/tspath"
 )
 
+// programRootMembership uses the 7.0 supported-extension APIs and effective
+// parsed options. A facade constructed without parsed config has no report.
+func programRootMembership(prog *Program) *TransformMembership {
+  if prog.ParsedConfig == nil || prog.ParsedConfig.CompilerOptions() == nil {
+    return nil
+  }
+  options := prog.ParsedConfig.CompilerOptions()
+  groups := shimtsoptions.GetSupportedExtensions(options, nil)
+  return transformMembership(prog, shimtsoptions.GetSupportedExtensionsWithJsonIfResolveJsonModule(options, groups))
+}
+
 // TypeScript 7.0 compiler target.
 //
 // The driver's emit and diagnostic glue calls compiler APIs whose signatures

package/driver/target_ts71.go

@@ -9,9 +9,21 @@ import (
   ast "github.com/microsoft/typescript-go/shim/ast"
   shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
   shimprinter "github.com/microsoft/typescript-go/shim/printer"
+  shimtsoptions "github.com/microsoft/typescript-go/shim/tsoptions"
   shimtspath "github.com/microsoft/typescript-go/shim/tspath"
 )
 
+// programRootMembership uses the 7.1 supported-extension APIs with the Program's
+// actual mapper extensions. No root selection is reimplemented here.
+func programRootMembership(prog *Program) *TransformMembership {
+  if prog.ParsedConfig == nil || prog.ParsedConfig.CompilerOptions() == nil {
+    return nil
+  }
+  options := prog.ParsedConfig.CompilerOptions()
+  groups := shimtsoptions.GetSupportedExtensions(options, prog.TSProgram.ContentMapperExtensions())
+  return transformMembership(prog, shimtsoptions.GetSupportedExtensionsWithJsonIfResolveJsonModule(options, groups))
+}
+
 // TypeScript 7.1 compiler target.
 //
 // The driver's emit and diagnostic glue calls compiler APIs whose signatures

package/driver/transform_dependencies.go

@@ -15,6 +15,9 @@ import (
 // no contributor declarations to require, so every transformed file is listed.
 // This side channel does not independently certify resolver, host or plugin
 // source inputs reported through other envelope fields.
+// Content mapper manifests and upstream-declared dynamic project inputs are
+// added for every file independently of plugin completeness. These declarations
+// carry no compiler-read proof; consumers witness them before a compilation.
 //
 // @evidence contracts/common.md#principled-implementation Reported dependencies and explicit completeness are distinct; an empty contributor set is complete without pretending silent contributors proved anything.
 // @evidence contracts/common.md#clear-and-simple-design One per-file adjacency map and one complete-file list carry separate facts.
@@ -95,7 +98,25 @@ func (p *Program) TransformDependenciesFor(cwd string) TransformDependencies {
   for _, file := range files {
     keys = append(keys, TransformOutputKey(cwd, string(file.FileName())))
   }
-  return p.plugins.transformDependencies(keys)
+  out := p.plugins.transformDependencies(keys)
+  if len(p.mapperDependencies) != 0 {
+    for _, key := range keys {
+      inputs := map[string]struct{}{}
+      for _, input := range out.Dependencies[key] {
+        inputs[input] = struct{}{}
+      }
+      for _, input := range p.mapperDependencies {
+        name := TransformOutputKey(cwd, input)
+        if name != key {
+          inputs[name] = struct{}{}
+        }
+      }
+      if len(inputs) != 0 {
+        out.Dependencies = appendDependencyEntry(out.Dependencies, key, inputs)
+      }
+    }
+  }
+  return out
 }
 
 // transformDependencies aggregates every contributing plugin's declarations