ttsc 0.30.4 → 0.31.1

package/driver/emit_provenance.go

@@ -0,0 +1,155 @@
+package driver
+
+import (
+  "encoding/json"
+  "errors"
+  "fmt"
+  "path/filepath"
+  "slices"
+  "strings"
+  "sync"
+
+  shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+)
+
+// NewEmitProvenanceRecorder wraps a writer and returns a build-owned snapshot
+// function for successfully written JavaScript outputs. The compiler's actual
+// eligible source list and output resolver determine candidates; neither sibling
+// filenames nor source maps establish ownership.
+//
+// Snapshot keys are absolute native output paths. Values are sorted, distinct
+// physical source paths recorded by this compiler generation's input observer.
+// An empty value means an output was written but its eligible owners or some
+// owner's physical proof were unavailable or inconsistent. Multiple values
+// preserve ambiguity. An empty object means no JavaScript write succeeded.
+//
+// Call the snapshot after emission finishes. It remains attached to its captured
+// generation's ledger and never resolves an alias against post-build disk state.
+// The ledger does not claim an atomic filesystem or file
+// descriptor snapshot; conflicting observed predicates invalidate ownership.
+// A nil writer uses DefaultWriteFile. Writer and snapshot hold the same mutex;
+// the supplied writer must not reenter either returned closure. Writer errors
+// prevent recording that callback even if the writer already had partial effects.
+//
+// @evidence contracts/common.md#principled-implementation Native eligible sources and resolved script destinations intersect only successful unskipped writes; all candidate generation-time physical proofs are required, with unknown and multiple owners represented explicitly.
+// @evidence contracts/common.md#clear-and-simple-design One compiler-owned candidate index, one serialized writer and one snapshot separate eligibility, successful publication and physical provenance without a same-stem fallback.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The recorder delegates supported emit-path helpers and actual writers; later realpath, fixture filenames or extension precedence cannot fabricate a unique source owner.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain snapshot timing, native keys, physical proof, ambiguity, unknown values and the non-atomic ledger limitation following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Compiler path normalization and its coordinate case policy index candidate collisions; recorded native physical paths prove source identity separately from that policy, preserving lexical output names without an OS-derived identity guess.
+// @evidence contracts/performance.md#efficient-algorithms Latched linked hooks and native eligibility/output-path helpers precede the source index. Candidate/path normalization and text keys contribute work; each callback delegates arbitrary writer work, then records a successful script row. Snapshot visits each written row's candidates, compares captured proofs, deduplicates physical paths and sorts each owner list with path-text comparison costs; shared candidate lists can be revisited across written spellings.
+// @evidence contracts/performance.md#reuse-equivalent-work One generation's native eligibility and output paths serve every writer callback; the snapshot reuses captured input observations without re-reading source bytes or recomputing an independent compiler Program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Returned closures retain the captured input ledger and uncapped candidate/write path lists until their owner releases them. Snapshots allocate independent maps/slices; delegated writer resource release belongs to that writer. Shared locking serializes writer and snapshot with no deadline or reentrant acquisition; no independent descriptor or lease is acquired here.
+func (p *Program) NewEmitProvenanceRecorder(writeFile shimcompiler.WriteFile) (shimcompiler.WriteFile, func() map[string][]string, error) {
+  if p == nil || p.TSProgram == nil {
+    return nil, nil, errors.New("driver: nil program")
+  }
+  if err := p.ApplyLinkedPlugins(); err != nil {
+    return nil, nil, err
+  }
+  program := p.TSProgram
+  observer := p.inputObserver
+  cwd := program.GetCurrentDirectory()
+  caseSensitive := program.UseCaseSensitiveFileNames()
+  nativePath := func(name string) string {
+    return filepath.FromSlash(shimtspath.GetNormalizedAbsolutePath(name, cwd))
+  }
+  coordinateKey := func(name string) string {
+    return shimtspath.GetCanonicalFileName(
+      shimtspath.NormalizePath(nativePath(name)),
+      caseSensitive,
+    )
+  }
+  candidates := map[string][]string{}
+  host := &pluginEmitHost{program: program}
+  for _, source := range shimcompiler.GetSourceFilesToEmit(host, nil, false) {
+    output := shimcompiler.GetOutputPathsFor(source, program.Options(), host, false).JsFilePath()
+    switch strings.ToLower(filepath.Ext(output)) {
+    case ".js", ".jsx", ".mjs", ".cjs":
+      key := coordinateKey(output)
+      candidates[key] = append(candidates[key], nativePath(source.FileName()))
+    }
+  }
+  if writeFile == nil {
+    writeFile = func(name, text string, _ *shimcompiler.WriteFileData) error {
+      return DefaultWriteFile(name, text)
+    }
+  }
+  written := map[string]string{}
+  var mu sync.Mutex
+  record := func(name, text string, data *shimcompiler.WriteFileData) error {
+    mu.Lock()
+    defer mu.Unlock()
+    if err := writeFile(name, text, data); err != nil {
+      return err
+    }
+    if data == nil || !data.SkippedDtsWrite {
+      switch strings.ToLower(filepath.Ext(name)) {
+      case ".js", ".jsx", ".mjs", ".cjs":
+        written[nativePath(name)] = coordinateKey(name)
+      }
+    }
+    return nil
+  }
+  snapshot := func() map[string][]string {
+    mu.Lock()
+    defer mu.Unlock()
+    result := map[string][]string{}
+    for output, key := range written {
+      physical := map[string]struct{}{}
+      known := observer != nil && len(candidates[key]) != 0
+      if known {
+        for _, source := range candidates[key] {
+          proof, failure := observer.predicateProof(source)
+          if failure != "" || proof.ReadFile == nil || !proof.ReadFile.OK ||
+            proof.Realpath == nil || !proof.Realpath.OK || !filepath.IsAbs(proof.Realpath.Path) {
+            known = false
+            break
+          }
+          physical[filepath.Clean(proof.Realpath.Path)] = struct{}{}
+        }
+      }
+      owners := []string{}
+      if known {
+        for source := range physical {
+          owners = append(owners, source)
+        }
+        slices.Sort(owners)
+      }
+      result[output] = owners
+    }
+    return result
+  }
+  return record, snapshot, nil
+}
+
+// WriteEmitProvenanceJSON writes one private build-result object to an absolute
+// native path as an output-to-source map, preserving the command's existing
+// stdout stream. The caller owns a fresh result path and its parent directory.
+// Publication follows a successful temporary write and close. The file preserves
+// the supplied snapshot independently of command status or diagnostics; this
+// encoder does not authenticate the snapshot's recorded-write origin. Consumers
+// must validate it before admission. A nil map is rejected rather than written
+// as null.
+//
+// @evidence contracts/common.md#principled-implementation A caller-owned absolute result path receives every supplied emittedSources row, preserving empty and unknown-row values without authenticating their origin; encoding or publication failure returns an error.
+// @evidence contracts/common.md#clear-and-simple-design One encoder and one native write keep machine metadata independent of compiler diagnostic streams.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The writer never substitutes stdout scraping or a successful empty result for a failed metadata publication.
+// @evidence contracts/common.md#meaningful-documentation Native prose states absolute-path admission, private parent ownership, stream separation and ownership proof's distinction from command success following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation filepath validates native absolute grammar and the shared same-directory publisher performs native write, close and rename without shell commands or separator substitution.
+// @evidence contracts/performance.md#efficient-algorithms JSON serialization sorts map keys by text and encodes every supplied row and owner string before one native publication; costs include key comparisons, payload bytes and temporary key/encoding buffers, without per-row files or source-tree enumeration.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Artifact publication borrows a completed snapshot and coordinates no reusable compiler or identity work.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Encoding bytes 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 borrowed snapshot, fresh destination, parent directory and final artifact removal.
+func WriteEmitProvenanceJSON(fileName string, emittedSources map[string][]string) error {
+  if !filepath.IsAbs(fileName) {
+    return fmt.Errorf("driver: emit provenance path must be absolute: %q", fileName)
+  }
+  if emittedSources == nil {
+    return errors.New("driver: missing emit provenance snapshot")
+  }
+  data, err := json.Marshal(emittedSources)
+  if err != nil {
+    return err
+  }
+  return writePrivateResult(fileName, data)
+}

package/driver/graph.go

@@ -16,17 +16,18 @@ import (
 const bundledScheme = "bundled:///"
 
 // TransformGraph is the host-owned reference-graph section of a transform
-// envelope (`graph` in the stdout JSON). It carries the language-semantic
-// input set of a transform under `tsc --incremental` semantics, so cache
-// layers (bundler filesystem caches, watch graphs) can register every file
-// whose content can influence a transformed module's output:
+// envelope (`graph` in the stdout JSON). It reports the loaded compiler
+// program's references, global contributors, configuration ancestry and
+// resolver observations. Consumers choose graph inputs alongside independent
+// plugin and host inputs; this graph alone does not certify every dependency
+// of an arbitrary plugin's transformed output or continued filesystem freshness:
 //
 //   - Edges maps each file to its direct resolved references — imports,
 //     re-exports, `/// <reference>` targets, type reference directives, and
 //     ambient-module declaration files, type-only edges included. A leaf file
 //     has an empty list so the node and its compiler-time input proof remain
-//     explicit. Direct edges are the minimal sufficient statistic; consumers
-//     that need a flat per-file list compute the reachability closure themselves.
+//     explicit. Consumers that need a flat per-file graph list compute the
+//     reachability closure themselves.
 //   - Globals lists the files that contribute to the global scope (ambient
 //     declaration files, script files, global augmentations, `typeRoots`
 //     entries). A change to any of them can affect every file.
@@ -43,20 +44,34 @@ const bundledScheme = "bundled:///"
 //     collapsed content/identity projection for older consumers.
 //   - InputProofFailures gives a stable reason when a realized member lacks
 //     proof or a replayed resolver predicate changed.
+//   - UseCaseSensitiveFileNames is the case policy the compiler matched the
+//     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.
 //
 // Keys and values use the same convention as the envelope's `typescript`
 // map: project-relative slash paths, falling back to slash-normalized
 // absolute paths outside the project root (see TransformOutputKey).
+//
+// @evidence contracts/common.md#principled-implementation Resolved references, globals, resolver predicates, and proof failures retain distinct meanings in the envelope.
+// @evidence contracts/common.md#clear-and-simple-design Each field carries one input class or observation projection under the shared key convention.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler observations and explicit failures replace guessed dependencies or assumed validity.
+// @evidence contracts/common.md#meaningful-documentation Native prose defines the input classes, leaf semantics, case policy, and key convention following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The reported compiler case policy is distinct from slash-normalized protocol keys and reported native realpaths carried by observations/InputRealpaths. Native VFS realpath errors can retain lexical spelling, so presence alone does not certify physical alias resolution. TransformOutputKey preserves cwd-relative or outside-root/cross-volume absolute coordinates; neither protocol spelling nor absent proof establishes capabilities from an OS name.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Graph construction owns traversal; this type describes the result.
+// @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 {
-  Edges              map[string][]string                  `json:"edges"`
-  Globals            []string                             `json:"globals"`
-  Configs            []string                             `json:"configs"`
-  Candidates         map[string][]string                  `json:"candidates,omitempty"`
-  ResolutionInputs   []string                             `json:"resolutionInputs,omitempty"`
-  InputObservations  map[string]TransformInputObservation `json:"inputObservations,omitempty"`
-  InputHashes        map[string]*string                   `json:"inputHashes,omitempty"`
-  InputRealpaths     map[string]*string                   `json:"inputRealpaths,omitempty"`
-  InputProofFailures map[string]string                    `json:"inputProofFailures,omitempty"`
+  Edges                     map[string][]string                  `json:"edges"`
+  Globals                   []string                             `json:"globals"`
+  Configs                   []string                             `json:"configs"`
+  Candidates                map[string][]string                  `json:"candidates,omitempty"`
+  ResolutionInputs          []string                             `json:"resolutionInputs,omitempty"`
+  InputObservations         map[string]TransformInputObservation `json:"inputObservations,omitempty"`
+  InputHashes               map[string]*string                   `json:"inputHashes,omitempty"`
+  InputRealpaths            map[string]*string                   `json:"inputRealpaths,omitempty"`
+  InputProofFailures        map[string]string                    `json:"inputProofFailures,omitempty"`
+  UseCaseSensitiveFileNames bool                                 `json:"useCaseSensitiveFileNames"`
 }
 
 // NewTransformGraph computes the reference graph of a loaded program, keyed
@@ -64,17 +79,27 @@ type TransformGraph struct {
 // Hosts stamp the result into their stdout envelope's `graph` field;
 // `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#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#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.
 func NewTransformGraph(prog *Program, cwd string) *TransformGraph {
   if prog == nil || prog.TSProgram == nil {
     return nil
   }
   resolution := ObserveProgramResolutions(prog, cwd)
   graph := &TransformGraph{
-    Edges:            map[string][]string{},
-    Globals:          []string{},
-    Configs:          []string{},
-    Candidates:       resolution.Candidates,
-    ResolutionInputs: resolution.Universal,
+    Edges:                     map[string][]string{},
+    Globals:                   []string{},
+    Configs:                   []string{},
+    Candidates:                resolution.Candidates,
+    ResolutionInputs:          resolution.Universal,
+    UseCaseSensitiveFileNames: prog.TSProgram.UseCaseSensitiveFileNames(),
   }
   for _, file := range prog.TSProgram.SourceFiles() {
     fileName := file.FileName()
@@ -230,6 +255,15 @@ func configChain(prog *Program, cwd string) []string {
 // outside the project root. Every envelope section (`typescript`, `graph`,
 // `dependencies` producers) must share this one implementation so a consumer
 // can join sections by key.
+//
+// @evidence contracts/common.md#principled-implementation One key convention keeps source, dependency, and graph sections joinable across project boundaries.
+// @evidence contracts/common.md#clear-and-simple-design Native relative-path calculation and one escape predicate choose serialization.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Structural traversal and cross-volume checks replace guessed string-prefix roots.
+// @evidence contracts/common.md#meaningful-documentation Native prose states absolute input and outside-root behavior following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation filepath.Rel handles volumes and separators; ToSlash supplies envelope spelling.
+// @evidence contracts/performance.md#efficient-algorithms Native filepath.Rel normalization, volume/segment comparisons, escape-prefix checks and ToSlash output copying scale with cwd/fileName/relative path text. Delegation does not make this conversion constant work; the relative result is preferred when structurally within cwd, with no filesystem traversal or repeated collection scan.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This conversion owns no repeated-work coordinator.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the caller-owned result is retained.
 func TransformOutputKey(cwd, fileName string) string {
   rel, err := filepath.Rel(cwd, fileName)
   if err != nil || isOutsideRelativePath(rel) {

package/driver/host.go

@@ -17,15 +17,38 @@ import (
   "github.com/microsoft/typescript-go/shim/vfs/osvfs"
 )
 
-// DefaultFS returns an OS-backed filesystem wrapped with tsgo's bundled libs so
-// built-in definitions (lib.es*.d.ts, dom, etc.) resolve without a network
-// fetch. Mirrors tsgonest/tsgolint behavior.
+// DefaultFS wraps the shared native OS backend in a fresh metadata cache and
+// the compiler's library adapter. Normal embedded builds use built-in library
+// text; noembed builds instead rely on libraries available on disk. Neither
+// mode downloads libraries here.
+//
+// @evidence contracts/common.md#principled-implementation The compiler's library adapter overlays a fresh cached native backend when embedding is enabled, or preserves that backend for the native noembed library layout.
+// @evidence contracts/common.md#clear-and-simple-design One factory composes the three upstream filesystem layers rather than reproducing their lookup policies.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Bundled resolution uses the supported WrapFS boundary without patching upstream filesystem methods.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains embedded definitions and absence of a network fetch following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The factory preserves the upstream backend's reported compiler case policy and native operations, not a new per-directory or per-volume sensitivity probe.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The fresh metadata cache transfers to the caller-owned FS stack; queried paths, directory entries, realpaths and stat data can grow retained bytes without a cap here. Native cache clearing or losing caller references controls its lifetime, not a driver-owned close operation.
+// @evidence contracts/performance.md#efficient-algorithms Construction allocates an empty metadata-cache wrapper and, in embedded builds, a library wrapper around the shared OS backend; it performs no source scan or metadata population. Later lookups and cache growth belong to the returned stack's use.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call builds a fresh wrapper stack; callers that want one shared stack hold the returned value.
 func DefaultFS() vfs.FS {
   return bundled.WrapFS(cachedvfs.From(osvfs.FS()))
 }
 
 // DefaultHost returns a CompilerHost anchored at cwd that can find tsgo's
 // bundled library files via `bundled.LibPath()`.
+// The constructor retains the supplied cwd and FS without independently
+// normalizing or probing that anchor. In noembed builds the native library
+// provider initializes a process-wide disk location, which can perform native
+// queries or panic if its required library layout is unavailable.
+//
+// @evidence contracts/common.md#principled-implementation The supplied FS and cwd are passed to the upstream CompilerHost with the matching bundled-library location.
+// @evidence contracts/common.md#clear-and-simple-design Host construction stays in one adapter used by initial and incremental program creation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The supported CompilerHost constructor owns behavior without an injected foreign-method replacement.
+// @evidence contracts/common.md#meaningful-documentation Native prose names project anchoring and bundled library lookup under documentation-skill guidance.
+// @evidence contracts/portability.md#os-neutral-implementation The host uses the supplied filesystem's native capabilities and upstream path handling rather than hardcoded OS path rules.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The new host transfers its cwd/library strings and supplied FS reference to the caller; keeping it reachable also keeps that FS stack and its caches reachable. The factory adds no separate host cache, handle or release operation.
+// @evidence contracts/performance.md#efficient-algorithms Host allocation initializes fixed fields; embedded library location is a constant, while first noembed location initialization can query executable/realpath/library metadata under the native provider's once cache. This constructor does not parse source files, but delegated location work is not universally a fixed field assignment.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each returned host retains its supplied cwd/FS without a driver-owned cache or request coordinator; the native library provider owns any process-wide location sharing.
 func DefaultHost(cwd string, fs vfs.FS) shimcompiler.CompilerHost {
   return shimcompiler.NewCompilerHost(cwd, fs, bundled.LibPath(), nil, nil)
 }

package/driver/input_observation.go

@@ -34,39 +34,101 @@ const (
   inputProofUnsupportedInputKind     inputProofFailure = "unsupported-input-kind"
 )
 
-// TransformInputReadObservation is the exact result of one compiler ReadFile
-// predicate. A failed read carries OK=false and no guessed filesystem kind.
+// TransformInputReadObservation reports one compiler ReadFile predicate's
+// success and the digest of its returned text. This is not necessarily a raw
+// disk-byte digest: the native VFS decodes UTF-16 and removes a UTF-8 BOM before
+// returning text. A failed read carries OK=false and no guessed filesystem kind.
+//
+// @evidence contracts/common.md#principled-implementation Failed reads and returned compiler text remain distinct rather than turning an unreadable path into a guessed file kind or claiming a decoded-text hash proves raw disk-byte equality.
+// @evidence contracts/common.md#clear-and-simple-design Read success and content digest form one predicate value.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No later file read manufactures missing evaluation-time content proof.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes failure from file-kind inference following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The boundary value records the actual filesystem read result without assuming OS-specific absence semantics.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The filesystem observer owns hashing; this type describes a read result.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate value does not coordinate reusable work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The value owns no resource or independently retained collection.
 type TransformInputReadObservation struct {
-  OK   bool   `json:"ok"`
+  // OK reports whether the compiler's ReadFile call successfully returned text.
+  OK bool `json:"ok"`
+
+  // Hash is lowercase SHA-256 of the returned string's bytes, absent on failure.
   Hash string `json:"hash,omitempty"`
 }
 
-// TransformInputRealpathObservation is the exact result of one compiler
-// Realpath predicate or an identity read already performed beside a successful
-// existence predicate.
+// TransformInputRealpathObservation reports the filesystem adapter's Realpath
+// result, either queried directly or beside a successful existence predicate.
+// A nonempty result is cleaned and marked OK; the native VFS can return the
+// requested spelling when physical resolution fails, so OK alone is not an
+// independent certificate that every alias resolved physically.
+//
+// @evidence contracts/common.md#principled-implementation Reported Realpath identity remains separate from the lexical input; successful physical resolution can expose symlink/junction identity, while adapter fallback remains a reported spelling rather than proven physical identity.
+// @evidence contracts/common.md#clear-and-simple-design Success and resolved path form one identity predicate.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts An empty adapter result remains failed; a nonempty lexical fallback follows the adapter's actual result and is not independently relabeled as proven physical resolution.
+// @evidence contracts/common.md#meaningful-documentation Native prose specifies Realpath and adjacent existence observation following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Path carries the cleaned native adapter result, distinct from slash-normalized envelope keys. OK distinguishes empty from nonempty results, not every native resolution error: the pinned OS VFS returns its requested spelling on resolution/absolute-path error. No OS-name guess upgrades that fallback into a physical capability proof.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The observer owns native identity lookup; the type is its result.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work An identity value does not coordinate artifact reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The value owns no resource or resident cache.
 type TransformInputRealpathObservation struct {
-  OK   bool   `json:"ok"`
+  // OK reports a nonempty adapter path, including any adapter lexical fallback.
+  OK bool `json:"ok"`
+
+  // Path is the cleaned native adapter result, not independent physical proof.
   Path string `json:"path,omitempty"`
 }
 
 // TransformInputEntriesObservation is the exact result of one compiler
-// GetAccessibleEntries predicate. Both lists retain TypeScript-Go's sorted
-// lexical child names, including followed directory links and junctions.
+// GetAccessibleEntries predicate. Both lists retain returned lexical child
+// names. The native VFS returns sorted entries and follows recognizable links
+// when target stat succeeds; errors or unclassifiable entries can be omitted.
+// An empty list pair is not an independent successful-enumeration certificate.
+//
+// @evidence contracts/common.md#principled-implementation Files and directories preserve the compiler enumeration result, including followed native links, as separate membership constraints.
+// @evidence contracts/common.md#clear-and-simple-design Two returned name lists represent one enumeration without collapsing file and directory membership or inventing an enumeration-success flag.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Directory members come from the observed native predicate rather than a later guessed glob.
+// @evidence contracts/common.md#meaningful-documentation Native prose states ordering, lexical names, and followed-link behavior following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Lists preserve returned native child names, not joined paths or physical identities. The native VFS distinguishes file/directory targets through stat for recognized links/reparse points; failed enumeration or target classification can omit names. Neither empty lists nor discarded link metadata certify complete native membership or an OS-default case policy.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The filesystem observer owns enumeration and copying; this type carries the result.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Membership data does not itself coordinate computation reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller-owned predicate value owns no separate resource lifecycle.
 type TransformInputEntriesObservation struct {
+  // Directories contains the observed accessible child-directory names.
   Directories []string `json:"directories"`
-  Files       []string `json:"files"`
+
+  // Files contains the observed accessible child-file names.
+  Files []string `json:"files"`
 }
 
 // TransformInputObservation preserves independent compiler filesystem
 // predicates for one lexical path. False FileExists and true DirectoryExists
 // are compatible constraints, not a path-kind race.
+//
+// @evidence contracts/common.md#principled-implementation Independent FileExists, DirectoryExists, ReadFile, enumeration, stat, and identity predicates preserve compatible native answers without false kind conflicts.
+// @evidence contracts/common.md#clear-and-simple-design Optional fields distinguish unasked predicates from observed false values.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing predicates remain absent rather than being reconstructed from a collapsed hash projection.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains independent constraints and the nonconflicting example following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Actual native predicate results are represented explicitly without guessed filesystem capabilities or OS case policy.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The observer owns merge and compatibility algorithms; this type defines their proof representation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The representation provides evidence to reuse owners without coordinating artifacts itself.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The proof value acquires no lease or independent resident cache.
 type TransformInputObservation struct {
-  AccessibleEntries *TransformInputEntriesObservation  `json:"accessibleEntries,omitempty"`
-  DirectoryExists   *bool                              `json:"directoryExists,omitempty"`
-  FileExists        *bool                              `json:"fileExists,omitempty"`
-  ReadFile          *TransformInputReadObservation     `json:"readFile,omitempty"`
-  Realpath          *TransformInputRealpathObservation `json:"realpath,omitempty"`
-  Stat              *string                            `json:"stat,omitempty"`
+  // AccessibleEntries records a requested directory-membership predicate.
+  AccessibleEntries *TransformInputEntriesObservation `json:"accessibleEntries,omitempty"`
+
+  // DirectoryExists records the requested directory predicate, including false.
+  DirectoryExists *bool `json:"directoryExists,omitempty"`
+
+  // FileExists records the requested file predicate, including false.
+  FileExists *bool `json:"fileExists,omitempty"`
+
+  // ReadFile records read success and the digest of returned compiler text.
+  ReadFile *TransformInputReadObservation `json:"readFile,omitempty"`
+
+  // Realpath records the adapter result, including any nonempty lexical fallback.
+  Realpath *TransformInputRealpathObservation `json:"realpath,omitempty"`
+
+  // Stat records "missing" for a null adapter result, otherwise directory/file.
+  Stat *string `json:"stat,omitempty"`
 }
 
 type observedInput struct {

package/driver/input_observation_test.go

@@ -3,13 +3,19 @@ package driver
 import (
   "crypto/sha256"
   "encoding/hex"
+  "errors"
   "os"
-  "os/exec"
   "path/filepath"
   "runtime"
   "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver/windowsjunction"
 )
 
+// @evidence contracts/testing.md#behavioral-verification The observing filesystem fails the proof with inputProofContentChanged after a file read as A is changed to B and then restored to A.
+// @evidence contracts/testing.md#independent-expectations The three contents A, B and A and the expected failure constant are written literally.
+// @evidence contracts/testing.md#distinguishing-cases A-B-A is the case a final-state comparison would accept; the second read of B makes the observation fail even though the bytes match again.
+// @evidence contracts/testing.md#execution-ownership TestInputObservationFSRejectsRestoredContent is a Go unit test inside the driver package: it calls the unexported operation in-process with literal inputs or a temporary directory, installing no consumer and starting no product process.
 func TestInputObservationFSRejectsRestoredContent(t *testing.T) {
   root := t.TempDir()
   file := filepath.Join(root, "external.d.ts")
@@ -34,6 +40,10 @@ func TestInputObservationFSRejectsRestoredContent(t *testing.T) {
   }
 }
 
+// @evidence contracts/testing.md#behavioral-verification The proof reports the SHA-256 of the bytes the compiler read, a realpath for the read file, an existence-only failure for an unread file and an observed-missing state for an absent candidate.
+// @evidence contracts/testing.md#independent-expectations The expected digest is computed independently from the literal file contents with crypto/sha256.
+// @evidence contracts/testing.md#distinguishing-cases An existence-only check, a read and a missing candidate are three distinct states with different proof outcomes.
+// @evidence contracts/testing.md#execution-ownership TestInputObservationFSProvesReadBytesAndMissingCandidates is a Go unit test inside the driver package: it calls the unexported operation in-process with literal inputs or a temporary directory, installing no consumer and starting no product process.
 func TestInputObservationFSProvesReadBytesAndMissingCandidates(t *testing.T) {
   root := t.TempDir()
   file := filepath.Join(root, "selected.ts")
@@ -75,6 +85,15 @@ func TestInputObservationFSProvesReadBytesAndMissingCandidates(t *testing.T) {
   }
 }
 
+// TestInputObservationFSPreservesPredicateSemantics covers five named cases:
+// native directory predicates, seven authored repeated-observation pairs,
+// three authored conflicts, and two supplied graph-candidate proof views.
+// It does not build a compiler Program or reproduce a real filesystem race.
+//
+// @evidence contracts/testing.md#behavioral-verification The native directory case preserves independent file/directory predicates. Seven authored observation pairs select their literal change failures, three authored cross-predicate conflicts select predicate-conflict, and supplied graph inputs report the observed candidate failure while retaining the rich speculative proof. Other state pairs and real races are not certified.
+// @evidence contracts/testing.md#independent-expectations Each subtest builds its own literal predicate observations and expected proof outcomes.
+// @evidence contracts/testing.md#distinguishing-cases The five named subtests cover compatible and conflicting predicate sets and graph-level reporting, so one decision difference fails one subtest.
+// @evidence contracts/testing.md#execution-ownership This Go aggregate owns five sequential private cases. One uses an owned native directory and DefaultFS; the others directly merge supplied observations or attach proofs to an authored TransformGraph/Program DTO with no native compiler construction. Actual private operations are called without a consumer or product process, and the private cases are not separately selected declarations.
 func TestInputObservationFSPreservesPredicateSemantics(t *testing.T) {
   t.Run("compatible-file-and-directory-predicates", testInputObservationFSKeepsFileAndDirectoryPredicatesIndependent)
   t.Run("every-repeated-predicate-change", testInputObservationFSRejectsEveryRepeatedPredicateChange)
@@ -278,6 +297,10 @@ func stringPointer(value string) *string {
   return &value
 }
 
+// @evidence contracts/testing.md#behavioral-verification The proof hash covers the BOM-stripped text the compiler decoded rather than the raw bytes on disk.
+// @evidence contracts/testing.md#independent-expectations The expected digest is computed from the literal decoded text, and the file is written with an explicit UTF-8 BOM.
+// @evidence contracts/testing.md#distinguishing-cases A BOM-prefixed file distinguishes hashing the decoded text from hashing the raw bytes.
+// @evidence contracts/testing.md#execution-ownership TestInputObservationFSHashesCompilerDecodedText is a Go unit test inside the driver package: it calls the unexported operation in-process with literal inputs or a temporary directory, installing no consumer and starting no product process.
 func TestInputObservationFSHashesCompilerDecodedText(t *testing.T) {
   root := t.TempDir()
   file := filepath.Join(root, "bom.ts")
@@ -298,6 +321,10 @@ func TestInputObservationFSHashesCompilerDecodedText(t *testing.T) {
   }
 }
 
+// @evidence contracts/testing.md#behavioral-verification A probe through a lexical directory alias joins the physical read of the selected file so the proof reports the physical path.
+// @evidence contracts/testing.md#independent-expectations The expected physical path and bytes come from the test's own directory layout and literal file contents.
+// @evidence contracts/testing.md#distinguishing-cases The alias spelling and the physical spelling differ, so a proof keyed on the lexical path alone fails.
+// @evidence contracts/testing.md#execution-ownership This Go unit owns a native directory-link fixture and calls the actual observation/proof adapter. Windows junction creation uses the existing windowsjunction helper's owned cmd child and opt-in trace; it does not launch Node or a product host. POSIX permission-denied symlink setup is explicitly skipped, while other setup failures fail; no successful alias coverage is certified on a skipped host.
 func TestInputObservationFSJoinsSelectedAliasProbeToPhysicalRead(t *testing.T) {
   root := t.TempDir()
   target := filepath.Join(root, "target")
@@ -311,18 +338,14 @@ func TestInputObservationFSJoinsSelectedAliasProbeToPhysicalRead(t *testing.T) {
   }
   alias := filepath.Join(root, "alias")
   if runtime.GOOS == "windows" {
-    command := exec.Command(
-      "node",
-      "-e",
-      `require("node:fs").symlinkSync(process.argv[1], process.argv[2], "junction")`,
-      target,
-      alias,
-    )
-    if output, err := command.CombinedOutput(); err != nil {
-      t.Skipf("directory junction unavailable on this host: %v: %s", err, output)
+    if err := windowsjunction.Create(alias, target); err != nil {
+      t.Fatalf("create owned directory junction: %v", err)
     }
   } else if err := os.Symlink(target, alias); err != nil {
-    t.Skipf("directory symlink unavailable on this host: %v", err)
+    if errors.Is(err, os.ErrPermission) {
+      t.Skipf("host denied permission for the owned directory symlink fixture: %v", err)
+    }
+    t.Fatalf("create owned directory symlink: %v", err)
   }
   lexical := filepath.Join(alias, "value.js")
   observed := newInputObservationFS(DefaultFS())