ttsc 0.30.4 → 0.31.0

package/cmd/ttsc/api_transform.go

@@ -16,80 +16,101 @@ import (
   cwdutil "github.com/samchon/ttsc/packages/ttsc/internal/cwd"
 )
 
+// apiTransformResult separates source output, compiler dependencies and
+// native-plugin evaluation observations so each keeps its own reuse meaning.
 type apiTransformResult struct {
-  // TypeScript contains every non-library source file visible through the
-  // Program facade, keyed the same way api-compile keys emitted files.
+  // Diagnostics may accompany partial source results.
   Diagnostics []apiCompileDiagnostic `json:"diagnostics,omitempty"`
-  TypeScript  map[string]string      `json:"typescript"`
+
+  // TypeScript contains the parsed text of every non-declaration source the
+  // Program facade exposes, keyed like api-compile output. Linked program hooks
+  // run before the read but mutate the parsed AST in place, so this text is the
+  // file as parsed (including any source preamble), not a printed AST.
+  TypeScript map[string]string `json:"typescript"`
+
   // Graph is the host-owned reference graph of the loaded program (direct
   // resolved reference edges, global-scope files, tsconfig extends chain),
   // keyed like TypeScript. Consumers use it to register every file whose
   // content can influence a transformed module, so bundler caches invalidate
   // soundly without per-plugin reporting.
   Graph *driver.TransformGraph `json:"graph,omitempty"`
-  // Dependencies and DependenciesComplete are the envelope's dependency side
-  // channel. This lane runs no plugin transform at all — each output is the
-  // file's own parsed text — so every file is complete with an empty list
-  // unless a linked plugin is active and declares otherwise; see
-  // driver.Program.TransformDependenciesFor.
-  Dependencies         map[string][]string `json:"dependencies,omitempty"`
-  DependenciesComplete []string            `json:"dependenciesComplete,omitempty"`
+
+  // Dependencies records inputs declared by the linked source contributors.
+  // This lane does not run emit transformers or type-driven emit lowering.
+  Dependencies map[string][]string `json:"dependencies,omitempty"`
+
+  // DependenciesComplete lists only files whose every source contributor
+  // declared completeness. With no contributors, every file is complete.
+  DependenciesComplete []string `json:"dependenciesComplete,omitempty"`
+
   // HostInputs are absolute native plugin config files evaluated while this
-  // generation loaded. JavaScript hosts merge them with descriptor inputs.
-  HostInputs         []string           `json:"hostInputs,omitempty"`
-  HostInputHashes    map[string]*string `json:"hostInputHashes,omitempty"`
+  // generation loaded or transformed. JavaScript hosts merge descriptor inputs.
+  HostInputs []string `json:"hostInputs,omitempty"`
+
+  // HostInputHashes contains consistent evaluation-time SHA-256 observations.
+  // Null means observed absence; omitted keys mean no reusable content proof.
+  HostInputHashes map[string]*string `json:"hostInputHashes,omitempty"`
+
+  // HostInputRealpaths carries physical identities observed at evaluation.
+  // Null means absence; omitted keys leave symlink or junction identity unknown.
   HostInputRealpaths map[string]*string `json:"hostInputRealpaths,omitempty"`
+
+  // ObservationsComplete is false only for an explicit unsupported observation
+  // boundary reported by a linked hook. Absence does not prove completeness.
+  ObservationsComplete *bool `json:"observationsComplete,omitempty"`
 }
 
 // runAPITransform implements the `api-transform` sub-command. It loads the
 // TypeScript program in no-emit mode and returns the source text of every
-// non-library file as a JSON object, keyed by the same relative-path
+// non-declaration file as a JSON object, keyed by the same relative-path
 // convention as api-compile. Diagnostics are included; partial results are
 // returned even when diagnostics are present.
+//
+// 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.
 func runAPITransform(args []string) int {
-  fs := flag.NewFlagSet("api-transform", flag.ContinueOnError)
-  fs.SetOutput(stderr)
-  tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
-  cwdOverride := fs.String("cwd", "", "override the working directory")
-  singleThreaded := fs.Bool("singleThreaded", false, "run TypeScript-Go single-threaded")
-  checkers := fs.Int("checkers", 0, "type-checker pool size (0 = TypeScript-Go default)")
-  tsgoArgsRaw := fs.String("tsgo-args", "", "JSON array of forwarded tsgo CLI flags")
-  // See cmd/ttsc/build.go's filterHostArgs call for the rationale.
-  if err := fs.Parse(filterHostArgs(args)); err != nil {
-    return 2
+  request, code := prepareAPITransformInvocation(args)
+  if code != 0 {
+    return code
   }
-
-  cwd, err := cwdutil.Resolve(*cwdOverride, getwd)
+  cwd := request.cwd
+  prog, diags, err := driver.LoadProgram(cwd, request.tsconfigPath, request.options)
   if err != nil {
-    fmt.Fprintf(stderr, "ttsc: %v\n", err)
+    fmt.Fprintf(stderr, "ttsc api-transform: %v\n", err)
     return 2
   }
-
-  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
-  if err != nil {
-    fmt.Fprintf(stderr, "ttsc: %v\n", err)
-    return 2
+  if prog != nil {
+    defer prog.Close()
   }
+  return writeTransformedProgramResponse(prog, diags, cwd)
+}
 
-  prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
-    ForceNoEmit:        true,
-    SemanticConfigPath: os.Getenv(driver.SemanticConfigPathEnv),
-    SingleThreaded:     *singleThreaded,
-    Checkers:           *checkers,
-    TsgoArgs:           tsgoArgs,
-  })
-  if err != nil {
-    fmt.Fprintf(stderr, "ttsc api-transform: %v\n", err)
-    return 2
-  }
+// writeTransformedProgramResponse borrows the loaded generation for the actual
+// source/reference-graph envelope and performs no emit operation. The caller
+// owns Close after all consumers. This operation does not require changing the
+// Program's NoEmit option; runAPITransform still loads with ForceNoEmit:true.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain attached to the owning operation and its callers.
+// Common: Principled implementation: The borrowed Program supplies the actual graph before SourceFiles hooks, source texts, diagnostics and observation metadata in the original sequence.
+// Common: Clear and simple design: The wrapper owns parse/load/Close and this operation owns the unchanged no-emission source envelope.
+// Common: Prohibited implementation shortcuts: No source text or graph is fabricated, diagnostic omitted, option silently toggled or cached response replayed; nil Program/config-diagnostic and writer-error branches remain.
+// Common: Meaningful documentation: Borrowing and the distinct ForceNoEmit true wrapper policy are explicit; callers must close only after all consumers.
+// Portability: OS-neutral implementation: Existing apiOutputKey and native JSON serialization preserve path and byte conventions without a subprocess or new filesystem-case assumption.
+// 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 {
   typescript := map[string]string{}
   var dependencies driver.TransformDependencies
   var graph *driver.TransformGraph
   var hostInputs []string
   var hostInputHashes map[string]*string
   var hostInputRealpaths map[string]*string
+  var observationsComplete *bool
   if prog != nil {
-    defer prog.Close()
     // Compute the reference graph before SourceFiles() runs linked plugin
     // hooks: those mutate parsed ASTs in place, and the graph must describe
     // the original source's resolved references — the transform's inputs —
@@ -103,6 +124,10 @@ func runAPITransform(args []string) int {
     hostInputs = prog.PluginHostInputs()
     hostInputHashes = prog.PluginHostInputHashes()
     hostInputRealpaths = prog.PluginHostInputRealpaths()
+    if prog.PluginObservationsIncomplete() {
+      incomplete := false
+      observationsComplete = &incomplete
+    }
   }
 
   result := apiTransformResult{
@@ -113,16 +138,79 @@ func runAPITransform(args []string) int {
     HostInputs:           hostInputs,
     HostInputHashes:      hostInputHashes,
     HostInputRealpaths:   hostInputRealpaths,
+    ObservationsComplete: observationsComplete,
     TypeScript:           typescript,
   }
   for _, diag := range diags {
     result.Diagnostics = append(result.Diagnostics, toAPICompileDiagnostic(diag))
   }
 
-  data, _ := json.Marshal(result)
-  fmt.Fprintln(stdout, string(data))
+  if err := json.NewEncoder(stdout).Encode(result); err != nil {
+    fmt.Fprintf(stderr, "ttsc api-transform: write result: %v\n", err)
+    return 3
+  }
   if driver.CountErrors(diags) > 0 {
     return 2
   }
   return 0
 }
+
+// prepareAPITransformLoadOptions is the exact options policy used by the real
+// runAPITransform parse path. It explicitly keeps ForceNoEmit:true distinct
+// from compile's ForceEmit:true; no mutable Program option is flipped for reuse.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain attached to the owning operation and its callers.
+// Common: Principled implementation: The real runAPITransform parse path consumes the exact ForceNoEmit true policy while preserving all parsed threading, semantic-config and tsgo argument fields.
+// Common: Clear and simple design: One value constructor isolates loader policy from the borrowed source-envelope operation.
+// Common: Prohibited implementation shortcuts: Original compile/transform policy differences remain explicit and are not merged merely to lower a producer count.
+// Common: Meaningful documentation: Native prose identifies the actual caller and forbids mutable Program option flipping for reuse.
+// Portability: OS-neutral implementation: Existing native path and argv values are forwarded without shell or separator conversion.
+// Performance: Efficient algorithms: Constant-size value construction forwards the parsed argv slice without an extra traversal.
+// Performance: Reuse equivalent work: The constructor performs no compilation or result replay and stores no prior request state.
+// Performance: Bound retention and release resources: Parsed values remain caller-owned through synchronous loading; no independent resource or retention owner is introduced.
+func prepareAPITransformLoadOptions(semanticConfigPath string, singleThreaded bool, checkers int, tsgoArgs []string) driver.LoadProgramOptions {
+  return driver.LoadProgramOptions{ForceNoEmit: true, SemanticConfigPath: semanticConfigPath, SingleThreaded: singleThreaded, Checkers: checkers, TsgoArgs: tsgoArgs}
+}
+
+// prepareAPITransformInvocation parses the original native API argv and returns its exact cwd, selected config and loader policy.
+// The real wrapper consumes this operation directly; tests observe preparation
+// separately from actual loaded compiler work and never replay a command result.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain with the owning operation and its actual callers.
+// Common: Principled implementation: Original flags, cwd resolution, diagnostic branches and status/stream ownership remain in this actual production path.
+// Common: Clear and simple design: Preparation and loaded-program work have explicit separate owners; no hidden second compiler producer is added.
+// Common: Prohibited implementation shortcuts: No loader is mocked, public export invented, option difference hidden, source result fabricated or previous status returned as an actual invocation.
+// Common: Meaningful documentation: Native prose identifies actual wrapper consumption, borrowing boundaries and independent preparation versus compiler observations.
+// Portability: OS-neutral implementation: Existing native cwd/path and argument-array semantics remain; no symlink, shell, forced separator or filesystem-case policy is introduced.
+// Performance: Efficient algorithms: Native flag parsing scales with argv; loaded compiler/output work remains in the existing driver and JSON/emit owners.
+// Performance: Reuse equivalent work: No request or command-result cache is retained. Immutable input sharing belongs to a local test family with separately declared selected configurations and load modes.
+// Performance: Bound retention and release resources: One FlagSet and decoded argv/options value transfer to the synchronous caller; no Program lease or process is acquired during preparation.
+func prepareAPITransformInvocation(args []string) (apiCommandRequest, int) {
+  fs := flag.NewFlagSet("api-transform", flag.ContinueOnError)
+  fs.SetOutput(stderr)
+  tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
+  cwdOverride := fs.String("cwd", "", "override the working directory")
+  singleThreaded := fs.Bool("singleThreaded", false, "run TypeScript-Go single-threaded")
+  checkers := fs.Int("checkers", 0, "type-checker pool size (0 = TypeScript-Go default)")
+  tsgoArgsRaw := fs.String("tsgo-args", "", "JSON array of forwarded tsgo CLI flags")
+  // See cmd/ttsc/build.go's filterHostArgs call for the rationale.
+  if err := fs.Parse(filterHostArgs(args)); err != nil {
+    return apiCommandRequest{}, 2
+  }
+
+  cwd, err := cwdutil.Resolve(*cwdOverride, getwd)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc: %v\n", err)
+    return apiCommandRequest{}, 2
+  }
+
+  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc: %v\n", err)
+    return apiCommandRequest{}, 2
+  }
+
+  return apiCommandRequest{cwd: cwd, tsconfigPath: *tsconfigPath, options: prepareAPITransformLoadOptions(os.Getenv(driver.SemanticConfigPathEnv), *singleThreaded, *checkers, tsgoArgs)}, 0
+}

package/cmd/ttsc/api_transform_branches_test.go

@@ -5,15 +5,18 @@ import (
   "testing"
 )
 
-// TestAPITransformBranches verifies api-transform rejects invalid command and project setup.
+// TestAPITransformBranches verifies API transform rejects invalid command and project setup.
 //
-// Source-to-source API callers need the same stable wrapper diagnostics as the
-// compile API, but without touching emit. These branches are command-frontdoor
-// behavior rather than TypeScript-Go internals.
+// These cases call the actual noEmit command wrapper. The missing configuration is read from an empty native fixture directory; no source graph or successful source-response assertion is made by this negative setup test.
 //
-// 1. Pass an incomplete flag.
-// 2. Force cwd resolution to fail.
-// 3. Point the API at a missing tsconfig.
+// 1. Pass an incomplete cwd flag and assert rejection.
+// 2. Inject the failing cwd reader and assert its literal cause.
+// 3. Select missing.json in a fresh fixture directory and assert the missing-config cause.
+//
+// @evidence contracts/testing.md#behavioral-verification Direct runAPITransform returns status two for incomplete flags, cwd failure and a missing configuration, with asserted cwd/config diagnostic fragments.
+// @evidence contracts/testing.md#independent-expectations Literal status two, cwd boom and tsconfig not found follow from the authored invalid argv, error reader and absent fixture config. The first check alone cannot distinguish every status-two cause.
+// @evidence contracts/testing.md#distinguishing-cases Parse misuse, implicit cwd failure and explicit cwd/missing config are distinct negative branches; successful source/graph response cases are owned by the aggregate family.
+// @evidence contracts/testing.md#execution-ownership This same-process Go unit calls the owning wrapper and real missing-config resolver, not an installed host or subprocess. captureCommand defers stream/getwd restoration and TempDir owns the native fixture; there is no acquired successful Program in these setup failures.
 func TestAPITransformBranches(t *testing.T) {
   code, _, _ := captureCommand(t, func() int {
     return runAPITransform([]string{"--cwd"})

package/cmd/ttsc/build.go

@@ -3,8 +3,8 @@
 // The build lane accepts the same project-oriented shape as the JavaScript
 // launcher: resolve one tsconfig, create a TypeScript-Go program, optionally
 // emit JavaScript, and report diagnostics through the driver package. It does
-// not load project plugins itself; plugin-selected sidecars are invoked by the
-// JavaScript host before this command receives native work.
+// not discover project descriptors itself. A plugin-selected binary can carry
+// linked Go hooks that the driver runs for its loaded program.
 package main
 
 import (
@@ -19,76 +19,63 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// runBuild implements the `ttsc` project-build lane. Two modes:
+// runBuild loads and checks one project before writing its emitted files.
 //
-//   - default (dry run): analyze quietly, surfacing only diagnostics/errors.
-//   - --emit: also run tsgo's emit pipeline, patching every recognized native
-//     consumer call in the resulting .js files.
+// The resolved compiler options decide whether emission occurs. --emit and
+// --noEmit override that decision; they are mutually exclusive. The driver owns
+// linked plugin hooks and the emit pipeline, while this command owns the output
+// writer and optional emitted-file manifest.
+//
+// An absolute private provenance path receives the raw output-to-source map after
+// completed emission, including successful writes from a build with emit
+// diagnostics. Analysis-only success writes an empty map. Status and diagnostics
+// still describe the build; an absent or invalid artifact supplies no proof.
+//
+// This wrapper consumes the actual build preparation before one LoadProgram
+// call. A nonnil acquired Program remains owned until the borrowed
+// diagnostic/emit/artifact response finishes; deferred Close then releases its
+// checker lease. Preparation, native loading and output publication retain
+// separate owners and their original returned statuses.
 func runBuild(args []string) int {
-  fs := flag.NewFlagSet("build", flag.ContinueOnError)
-  fs.SetOutput(stderr)
-  tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
-  cwdOverride := fs.String("cwd", "", "override the working directory (defaults to process cwd)")
-  quiet := fs.Bool("quiet", true, "suppress the per-call diagnostic summary")
-  verbose := fs.Bool("verbose", false, "print the per-call diagnostic summary")
-  emit := fs.Bool("emit", false, "force emitted .js files (runs tsgo + ttsc rewrite)")
-  noEmit := fs.Bool("noEmit", false, "force analysis-only run with no file writes")
-  outDir := fs.String("outDir", "", "override compilerOptions.outDir for this build")
-  manifestPath := fs.String("manifest", "", "write emitted file list as JSON to this path")
-  singleThreaded := fs.Bool("singleThreaded", false, "run TypeScript-Go single-threaded")
-  checkers := fs.Int("checkers", 0, "type-checker pool size (0 = TypeScript-Go default)")
-  tsgoArgsRaw := fs.String("tsgo-args", "", "JSON array of forwarded tsgo CLI flags")
-  // Strip unknown forwarded tsgo options before fs.Parse so a flag like
-  // `--strict` (which tsgo accepts but cmd/ttsc's FlagSet does not declare)
-  // does not exit 2 before reaching the tsgo lane via `--tsgo-args=<JSON>`.
-  // See packages/ttsc/cmd/ttsc/filter.go for the allow-list source.
-  if err := fs.Parse(filterHostArgs(args)); err != nil {
-    return 2
+  request, code := prepareBuildInvocation(args)
+  if code != 0 {
+    return code
   }
-  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
+  prog, diags, err := driver.LoadProgram(request.cwd, request.tsconfigPath, request.options)
   if err != nil {
     fmt.Fprintf(stderr, "ttsc: %v\n", err)
     return 2
   }
-  if *emit && *noEmit {
-    fmt.Fprintln(stderr, "ttsc: --emit and --noEmit are mutually exclusive")
-    return 2
-  }
-  if *verbose {
-    *quiet = false
-  }
-
-  cwd := *cwdOverride
-  if cwd == "" {
-    var err error
-    cwd, err = getwd()
-    if err != nil {
-      fmt.Fprintf(stderr, "ttsc: could not get working directory: %v\n", err)
-      return 2
-    }
+  if prog != nil {
+    defer prog.Close()
   }
+  return writeBuildProgramResponse(prog, diags, request)
+}
 
-  prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
-    ForceEmit:          *emit,
-    ForceNoEmit:        *noEmit,
-    OutDir:             *outDir,
-    SemanticConfigPath: os.Getenv(driver.SemanticConfigPathEnv),
-    SingleThreaded:     *singleThreaded,
-    Checkers:           *checkers,
-    TsgoArgs:           tsgoArgs,
-  })
-  if err != nil {
-    fmt.Fprintf(stderr, "ttsc: %v\n", err)
-    return 2
-  }
+// writeBuildProgramResponse borrows the real loaded Program for the original diagnostics, optional disk emit, provenance and manifest result.
+// The real wrapper consumes this operation directly; tests observe preparation
+// separately from actual loaded compiler work and never replay a command result.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain with the owning operation and its actual callers.
+// Common: Principled implementation: This borrowed operation preserves config/semantic diagnostic gates, emit/provenance/manifest ordering and actual status/streams; the real wrapper consumes preparation before loading.
+// Common: Clear and simple design: The request supplies resolved command intent; the caller owns load/Close while this operation owns diagnostics and output publication.
+// Common: Prohibited implementation shortcuts: No loader is mocked, public export invented, option difference hidden, source result fabricated or previous status returned as an actual invocation.
+// Common: Meaningful documentation: Native prose identifies actual wrapper consumption, borrowing boundaries and independent preparation versus compiler observations.
+// Portability: OS-neutral implementation: Existing native cwd/path and argument-array semantics remain; no symlink, shell, forced separator or filesystem-case policy is introduced.
+// Performance: Efficient algorithms: Diagnostics and emitted outputs retain their original traversals; compiler work remains in the driver and each requested artifact is serialized once.
+// Performance: Reuse equivalent work: The operation borrows the actual generation and request without replaying status or output. Callers must preserve selected configuration, options and publication-state prerequisites when sharing input.
+// Performance: Bound retention and release resources: The calling wrapper/load owner holds the Program checker lease and closes once after the final borrowed consumer; this operation owns only its original invocation-local collections and stream writes.
+func writeBuildProgramResponse(prog *driver.Program, diags []driver.Diagnostic, request buildCommandRequest) int {
   if len(diags) > 0 {
-    driver.WritePrettyDiagnostics(stderr, diags, cwd)
+    driver.WritePrettyDiagnostics(stderr, diags, request.cwd)
     return 2
   }
-  defer prog.Close()
   if diags := prog.Diagnostics(); len(diags) > 0 {
-    driver.WritePrettyDiagnostics(stderr, diags, cwd)
-    return 2
+    driver.WritePrettyDiagnostics(stderr, diags, request.cwd)
+    if driver.CountErrors(diags) > 0 {
+      return 2
+    }
   }
 
   rewrites := driver.NewRewriteSet()
@@ -96,8 +83,8 @@ func runBuild(args []string) int {
   // three levels deep in the parsed config because TypeScript-Go mirrors the
   // tsconfig object structure verbatim, with a tri-state bool per option.
   shouldEmit := !prog.ParsedConfig.ParsedConfig.CompilerOptions.NoEmit.IsTrue()
-  if !*quiet {
-    fmt.Fprintf(stdout, "// ttsc: tsconfig=%s cwd=%s sites=%d emit=%v\n", *tsconfigPath, cwd, 0, shouldEmit)
+  if !request.quiet {
+    fmt.Fprintf(stdout, "// ttsc: tsconfig=%s cwd=%s sites=%d emit=%v\n", request.tsconfigPath, request.cwd, 0, shouldEmit)
   }
 
   if shouldEmit {
@@ -109,43 +96,71 @@ func runBuild(args []string) int {
         return driver.DefaultWriteFile(fileName, text)
       },
     )
+    var snapshot func() map[string][]string
+    if request.provenancePath != "" {
+      var err error
+      writeFile, snapshot, err = prog.NewEmitProvenanceRecorder(writeFile)
+      if err != nil {
+        fmt.Fprintf(stderr, "ttsc: provenance failed: %v\n", err)
+        return 3
+      }
+    }
     res, eDiags, err := prog.EmitAll(rewrites, writeFile)
     if err != nil {
       fmt.Fprintf(stderr, "ttsc: emit failed: %v\n", err)
       return 3
     }
-    driver.WritePrettyDiagnostics(stderr, eDiags, cwd)
+    // Successful writes remain actual even when another output produced an emit
+    // diagnostic. Publish their ledger before preserving the original failure.
+    var provenanceErr error
+    if snapshot != nil {
+      provenanceErr = driver.WriteEmitProvenanceJSON(request.provenancePath, snapshot())
+    }
+    driver.WritePrettyDiagnostics(stderr, eDiags, request.cwd)
+    if provenanceErr != nil {
+      fmt.Fprintf(stderr, "ttsc: provenance write failed: %v\n", provenanceErr)
+    }
     if driver.CountErrors(eDiags) > 0 {
       fmt.Fprintln(stderr, "ttsc: emit failed; build output is incomplete")
       return 2
     }
-    if !*quiet {
+    if provenanceErr != nil {
+      return 3
+    }
+    if !request.quiet {
       fmt.Fprintf(stdout, "// ttsc: emitted=%d files\n", len(res.EmittedFiles))
       for _, f := range res.EmittedFiles {
         rel := f
-        if abs, err := filepath.Rel(cwd, f); err == nil {
+        if abs, err := filepath.Rel(request.cwd, f); err == nil {
           rel = abs
         }
         fmt.Fprintln(stdout, "  +", rel)
       }
     }
-    if *manifestPath != "" {
+    if request.manifestPath != "" {
       // The manifest is intentionally just the emitted file list. Higher
       // layers already know the project and tsconfig, and tests compare this
       // array as the build contract.
       data, _ := json.Marshal(res.EmittedFiles)
-      if err := os.MkdirAll(filepath.Dir(*manifestPath), 0o755); err != nil {
+      if err := os.MkdirAll(filepath.Dir(request.manifestPath), 0o755); err != nil {
         fmt.Fprintf(stderr, "ttsc: manifest mkdir failed: %v\n", err)
         return 3
       }
-      if err := os.WriteFile(*manifestPath, data, 0o644); err != nil {
+      if err := os.WriteFile(request.manifestPath, data, 0o644); err != nil {
         fmt.Fprintf(stderr, "ttsc: manifest write failed: %v\n", err)
         return 3
       }
     }
   }
 
-  if !*quiet {
+  if request.provenancePath != "" && !shouldEmit {
+    if err := driver.WriteEmitProvenanceJSON(request.provenancePath, map[string][]string{}); err != nil {
+      fmt.Fprintf(stderr, "ttsc: provenance write failed: %v\n", err)
+      return 3
+    }
+  }
+
+  if !request.quiet {
     fmt.Fprintf(stdout, "// ttsc: recognized=%d total=%d rewrites=%d\n", 0, 0, rewrites.Len())
   }
   return 0
@@ -155,6 +170,11 @@ func runBuild(args []string) int {
 // tsgo CLI flags the `ttsc` launcher forwarded — into a string slice. An empty
 // flag yields a nil slice. Shared by the build / api-compile / api-transform
 // subcommands, which all hand the result to driver.LoadProgram.
+//
+// encoding/json supplies []string decoding with its native null handling. A
+// decoding error is wrapped as invalid --tsgo-args for the actual command
+// preparation to report; the helper does not interpret or resolve the
+// forwarded compiler flags.
 func decodeTsgoArgs(raw string) ([]string, error) {
   if raw == "" {
     return nil, nil
@@ -165,3 +185,92 @@ func decodeTsgoArgs(raw string) ([]string, error) {
   }
   return args, nil
 }
+
+// prepareBuildInvocation parses the original build argv, including local/private flags, conflicting emit rejection and real implicit cwd.
+// The real wrapper consumes this operation directly; tests observe preparation
+// separately from actual loaded compiler work and never replay a command result.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain with the owning operation and its actual callers.
+// Common: Principled implementation: Original flags, cwd resolution, diagnostic branches and status/stream ownership remain in this actual production path.
+// Common: Clear and simple design: Preparation and loaded-program work have explicit separate owners; no hidden second compiler producer is added.
+// Common: Prohibited implementation shortcuts: No loader is mocked, public export invented, option difference hidden, source result fabricated or previous status returned as an actual invocation.
+// Common: Meaningful documentation: Native prose identifies actual wrapper consumption, borrowing boundaries and independent preparation versus compiler observations.
+// Portability: OS-neutral implementation: Existing native cwd/path and argument-array semantics remain; no symlink, shell, forced separator or filesystem-case policy is introduced.
+// Performance: Efficient algorithms: Native flag parsing scales with argv; loaded compiler/output work remains in the existing driver and JSON/emit owners.
+// Performance: Reuse equivalent work: No request or command-result cache is retained. Immutable input sharing belongs to a local test family with separately declared selected configurations and load modes.
+// Performance: Bound retention and release resources: One FlagSet and decoded argv/options value transfer to the synchronous caller; no Program lease or process is acquired during preparation.
+func prepareBuildInvocation(args []string) (buildCommandRequest, int) {
+  fs := flag.NewFlagSet("build", flag.ContinueOnError)
+  fs.SetOutput(stderr)
+  tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
+  cwdOverride := fs.String("cwd", "", "override the working directory (defaults to process cwd)")
+  quiet := fs.Bool("quiet", true, "suppress the per-call diagnostic summary")
+  verbose := fs.Bool("verbose", false, "print the per-call diagnostic summary")
+  emit := fs.Bool("emit", false, "force emitted .js files (runs tsgo + ttsc rewrite)")
+  noEmit := fs.Bool("noEmit", false, "force analysis-only run with no file writes")
+  outDir := fs.String("outDir", "", "override compilerOptions.outDir for this build")
+  manifestPath := fs.String("manifest", "", "write emitted file list as JSON to this path")
+  provenancePath := fs.String("emit-provenance-json", "", "private absolute emit provenance result path")
+  singleThreaded := fs.Bool("singleThreaded", false, "run TypeScript-Go single-threaded")
+  checkers := fs.Int("checkers", 0, "type-checker pool size (0 = TypeScript-Go default)")
+  tsgoArgsRaw := fs.String("tsgo-args", "", "JSON array of forwarded tsgo CLI flags")
+  // Strip unknown forwarded tsgo options before fs.Parse so a flag like
+  // `--strict` (which tsgo accepts but cmd/ttsc's FlagSet does not declare)
+  // does not exit 2 before reaching the tsgo lane via `--tsgo-args=<JSON>`.
+  // See packages/ttsc/cmd/ttsc/filter.go for the allow-list source.
+  if err := fs.Parse(filterDeclaredHostArgs(args, fs)); err != nil {
+    return buildCommandRequest{}, 2
+  }
+  if *provenancePath != "" && !filepath.IsAbs(*provenancePath) {
+    fmt.Fprintln(stderr, "ttsc: emit provenance path must be absolute")
+    return buildCommandRequest{}, 2
+  }
+  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc: %v\n", err)
+    return buildCommandRequest{}, 2
+  }
+  if *emit && *noEmit {
+    fmt.Fprintln(stderr, "ttsc: --emit and --noEmit are mutually exclusive")
+    return buildCommandRequest{}, 2
+  }
+  if *verbose {
+    *quiet = false
+  }
+
+  cwd := *cwdOverride
+  if cwd == "" {
+    var err error
+    cwd, err = getwd()
+    if err != nil {
+      fmt.Fprintf(stderr, "ttsc: could not get working directory: %v\n", err)
+      return buildCommandRequest{}, 2
+    }
+  }
+
+  return buildCommandRequest{cwd: cwd, tsconfigPath: *tsconfigPath, quiet: *quiet, manifestPath: *manifestPath, provenancePath: *provenancePath, options: driver.LoadProgramOptions{ForceEmit: *emit, ForceNoEmit: *noEmit, OutDir: *outDir, SemanticConfigPath: os.Getenv(driver.SemanticConfigPathEnv), SingleThreaded: *singleThreaded, Checkers: *checkers, TsgoArgs: tsgoArgs}}, 0
+}
+
+// buildCommandRequest carries resolved argv intent until synchronous load and
+// borrowed execution. Its options preserve ForceEmit/ForceNoEmit distinctions;
+// the value owns no Program or response cache.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds describe the request carrier consumed by the real wrapper.
+// Common: Principled implementation: ForceEmit, ForceNoEmit, verbosity and artifact paths preserve their distinct parsed meanings; selected config and cwd reach the actual load and output operations.
+// Common: Clear and simple design: One value carries prepared command intent across synchronous load and response ownership; no hidden dispatch or compiler producer is introduced.
+// Common: Prohibited implementation shortcuts: The carrier contains actual parsed values, never fabricated output, cached status, mocked loader or a public test-only API.
+// Common: Meaningful documentation: Native prose identifies policy distinctions and the wrapper's Program lease ownership.
+// Portability: OS-neutral implementation: Native cwd/config strings and argv are forwarded without shell, symlink or forced-separator conversion.
+// Performance: Efficient algorithms: Fields transfer in constant-size value copies; the forwarded argv slice is not retraversed or compiled by this carrier.
+// Performance: Reuse equivalent work: Each preparation creates invocation-local intent; the carrier stores no global cache or previous command result.
+// Performance: Bound retention and release resources: Referenced argv remains owned by the synchronous request lifetime; the carrier acquires no checker lease, process or independently retained resource.
+type buildCommandRequest struct {
+  cwd            string
+  tsconfigPath   string
+  quiet          bool
+  manifestPath   string
+  provenancePath string
+  options        driver.LoadProgramOptions
+}