ttsc 0.33.1 → 0.34.0

package/driver/emit_plugin_output.go

@@ -6,6 +6,7 @@ import (
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
   shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
 )
 
 // PluginEmitError reports compiler errors from a native plugin emit. The same
@@ -63,7 +64,7 @@ func (p *Program) pluginEmitDiagnostics(phase string, raw []*shimast.Diagnostic)
     Diagnostics:  diagnostics,
     Phase:        phase,
     Declarations: p.TSProgram.Options().GetEmitDeclarations(),
-    cwd:          p.TSProgram.GetCurrentDirectory(),
+    cwd:          string(p.TSProgram.GetCurrentDirectory()),
   }
 }
 
@@ -74,22 +75,22 @@ type pluginEmitOutput struct {
 }
 
 type pluginEmitFile struct {
-  name string
+  name shimtspath.RootedFilePath
   text string
   data *shimcompiler.WriteFileData
 }
 
 func newPluginEmitOutput(writeFile shimcompiler.WriteFile, buffered bool) *pluginEmitOutput {
   if writeFile == nil {
-    writeFile = func(name, text string, _ *shimcompiler.WriteFileData) error {
-      return DefaultWriteFile(name, text)
+    writeFile = func(name shimtspath.RootedFilePath, text string, _ *shimcompiler.WriteFileData) error {
+      return DefaultWriteFile(string(name), text)
     }
   }
   return &pluginEmitOutput{writeFile: writeFile, buffered: buffered}
 }
 
 // The caller serializes declaration writes; JavaScript and flush are serial.
-func (o *pluginEmitOutput) write(name, text string, data *shimcompiler.WriteFileData) error {
+func (o *pluginEmitOutput) write(name shimtspath.RootedFilePath, text string, data *shimcompiler.WriteFileData) error {
   if !o.buffered {
     return o.writeFile(name, text, data)
   }

package/driver/emit_provenance.go

@@ -52,43 +52,40 @@ func (p *Program) NewEmitProvenanceRecorder(writeFile shimcompiler.WriteFile) (s
   program := p.TSProgram
   observer := p.inputObserver
   cwd := program.GetCurrentDirectory()
-  caseSensitive := program.UseCaseSensitiveFileNames()
+  caseSensitivity := shimcompiler.ProgramCaseSensitivity(program)
   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,
-    )
+    return shimtspath.Canonicalize(caseSensitivity, shimtspath.NormalizePath(nativePath(name)))
   }
   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)) {
+  for _, source := range shimcompiler.SourceFilesToEmit(host) {
+    output := shimcompiler.OutputPathsFor(source, program.Options(), host).JsFilePath()
+    switch strings.ToLower(filepath.Ext(string(output))) {
     case ".js", ".jsx", ".mjs", ".cjs":
-      key := coordinateKey(output)
-      candidates[key] = append(candidates[key], nativePath(source.FileName()))
+      key := coordinateKey(string(output))
+      candidates[key] = append(candidates[key], nativePath(string(source.FileName())))
     }
   }
   if writeFile == nil {
-    writeFile = func(name, text string, _ *shimcompiler.WriteFileData) error {
-      return DefaultWriteFile(name, text)
+    writeFile = func(name shimtspath.RootedFilePath, text string, _ *shimcompiler.WriteFileData) error {
+      return DefaultWriteFile(string(name), text)
     }
   }
   written := map[string]string{}
   var mu sync.Mutex
-  record := func(name, text string, data *shimcompiler.WriteFileData) error {
+  record := func(name shimtspath.RootedFilePath, 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)) {
+      switch strings.ToLower(filepath.Ext(string(name))) {
       case ".js", ".jsx", ".mjs", ".cjs":
-        written[nativePath(name)] = coordinateKey(name)
+        written[nativePath(string(name))] = coordinateKey(string(name))
       }
     }
     return nil

package/driver/graph.go

@@ -103,10 +103,10 @@ func NewTransformGraph(prog *Program, cwd string) *TransformGraph {
   }
   for _, file := range prog.TSProgram.SourceFiles() {
     fileName := file.FileName()
-    if strings.HasPrefix(fileName, bundledScheme) {
+    if strings.HasPrefix(string(fileName), bundledScheme) {
       continue
     }
-    key := TransformOutputKey(cwd, fileName)
+    key := TransformOutputKey(cwd, string(fileName))
     if shimcompiler.FileAffectsGlobalScope(file) {
       graph.Globals = append(graph.Globals, key)
     }
@@ -216,17 +216,17 @@ func referenceTargets(prog *Program, cwd string, file *ast.SourceFile) []string
   paths := shimcompiler.GetReferencedFilePaths(prog.TSProgram, file)
   targets := make([]string, 0, len(paths))
   for _, referencedPath := range paths {
-    // Referenced paths are case-canonicalized tspath.Path values; recover the
+    // Referenced paths are case-canonicalized tspath.PathKey values; recover the
     // resident source and its real spelling from the Program. The incremental
     // helper can retain a raw extensionless project-reference directive even
     // when no corresponding source became resident. That spelling is a
     // resolver candidate, not a realized graph edge, and has no compiler-time
     // content proof.
-    resolved := prog.TSProgram.GetSourceFileByPath(shimtspath.Path(referencedPath))
-    if resolved == nil || resolved == file || strings.HasPrefix(resolved.FileName(), bundledScheme) {
+    resolved := prog.TSProgram.GetSourceFileByPath(shimtspath.PathKey(referencedPath))
+    if resolved == nil || resolved == file || strings.HasPrefix(string(resolved.FileName()), bundledScheme) {
       continue
     }
-    targets = append(targets, TransformOutputKey(cwd, resolved.FileName()))
+    targets = append(targets, TransformOutputKey(cwd, string(resolved.FileName())))
   }
   sort.Strings(targets)
   return targets
@@ -241,10 +241,10 @@ func configChain(prog *Program, cwd string) []string {
     return configs
   }
   if source := parsed.ConfigFile.SourceFile; source != nil {
-    configs = append(configs, TransformOutputKey(cwd, source.FileName()))
+    configs = append(configs, TransformOutputKey(cwd, string(source.FileName())))
   }
   for _, extended := range parsed.ExtendedSourceFiles() {
-    configs = append(configs, TransformOutputKey(cwd, extended))
+    configs = append(configs, TransformOutputKey(cwd, string(extended)))
   }
   return configs
 }

package/driver/host.go

@@ -12,6 +12,7 @@ package driver
 import (
   "github.com/microsoft/typescript-go/shim/bundled"
   shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
   "github.com/microsoft/typescript-go/shim/vfs"
   "github.com/microsoft/typescript-go/shim/vfs/cachedvfs"
   "github.com/microsoft/typescript-go/shim/vfs/osvfs"
@@ -34,21 +35,30 @@ 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()`.
+// DefaultHost returns a CompilerHost over fs that can find tsgo's bundled
+// library files via `bundled.LibPath()`. On the TypeScript 7.0 target the host
+// carries cwd as the Program's working directory; on 7.1 the parsed command
+// line's base directory anchors a Program, and cwd is unused.
 // 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#principled-implementation The supplied FS and cwd are passed to the target's upstream CompilerHost constructor through shimcompiler.NewHost 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/common.md#meaningful-documentation Native prose names each target's use of cwd 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)
+  return shimcompiler.NewHost(shimtspath.RootedDirectoryPath(cwd), fs, shimtspath.RootedDirectoryPath(bundled.LibPath()))
+}
+
+// projectHost is DefaultHost for a Program built from a parsed project: on the
+// TypeScript 7.1 target, hosts transforms the project's content-mapped files
+// through its content mappers. A nil hosts yields DefaultHost's host.
+func projectHost(hosts *shimcompiler.ProjectHosts, cwd string, fs vfs.FS) shimcompiler.CompilerHost {
+  return hosts.Host(shimtspath.RootedDirectoryPath(cwd), fs, shimtspath.RootedDirectoryPath(bundled.LibPath()))
 }

package/driver/input_observation.go

@@ -142,7 +142,7 @@ type observedInput struct {
 // of attaching post-compile disk hashes to an earlier result.
 type inputObservationFS struct {
   vfs.FS
-  caseSensitive        bool
+  caseSensitivity      shimtspath.CaseSensitivity
   mu                   sync.Mutex
   observations         map[string]observedInput
   observationOrder     []string
@@ -152,14 +152,15 @@ type inputObservationFS struct {
 func newInputObservationFS(inner vfs.FS) *inputObservationFS {
   return &inputObservationFS{
     FS:                   inner,
-    caseSensitive:        inner.UseCaseSensitiveFileNames(),
+    caseSensitivity:      vfs.CaseSensitivityOf(inner),
     observations:         map[string]observedInput{},
     observationSpellings: map[string]string{},
   }
 }
 
-func (fs *inputObservationFS) FileExists(path string) bool {
-  exists := fs.FS.FileExists(path)
+func (fs *inputObservationFS) FileExists(file shimtspath.RootedFilePath) bool {
+  exists := fs.FS.FileExists(file)
+  path := shimtspath.RootedPath(file)
   proof := TransformInputObservation{FileExists: boolPointer(exists)}
   if exists {
     // Existence participates in resolution, but only ReadFile returns bytes
@@ -171,8 +172,9 @@ func (fs *inputObservationFS) FileExists(path string) bool {
   return exists
 }
 
-func (fs *inputObservationFS) ReadFile(path string) (string, bool) {
-  contents, ok := fs.FS.ReadFile(path)
+func (fs *inputObservationFS) ReadFile(file shimtspath.RootedFilePath) (string, bool) {
+  contents, ok := fs.FS.ReadFile(file)
+  path := shimtspath.RootedPath(file)
   if ok {
     digest := sha256.Sum256([]byte(contents))
     hash := hex.EncodeToString(digest[:])
@@ -192,8 +194,9 @@ func (fs *inputObservationFS) ReadFile(path string) (string, bool) {
   return contents, ok
 }
 
-func (fs *inputObservationFS) DirectoryExists(path string) bool {
-  exists := fs.FS.DirectoryExists(path)
+func (fs *inputObservationFS) DirectoryExists(directory shimtspath.RootedDirectoryPath) bool {
+  exists := fs.FS.DirectoryExists(directory)
+  path := shimtspath.RootedPath(directory)
   proof := TransformInputObservation{DirectoryExists: boolPointer(exists)}
   if exists {
     proof.Realpath = fs.currentRealpath(path)
@@ -202,9 +205,9 @@ func (fs *inputObservationFS) DirectoryExists(path string) bool {
   return exists
 }
 
-func (fs *inputObservationFS) GetAccessibleEntries(path string) vfs.Entries {
-  entries := fs.FS.GetAccessibleEntries(path)
-  fs.observe(path, observedInput{
+func (fs *inputObservationFS) GetAccessibleEntries(directory shimtspath.RootedDirectoryPath) vfs.Entries {
+  entries := fs.FS.GetAccessibleEntries(directory)
+  fs.observe(shimtspath.RootedPath(directory), observedInput{
     proof: TransformInputObservation{
       AccessibleEntries: &TransformInputEntriesObservation{
         Directories: append([]string{}, entries.Directories...),
@@ -215,7 +218,7 @@ func (fs *inputObservationFS) GetAccessibleEntries(path string) vfs.Entries {
   return entries
 }
 
-func (fs *inputObservationFS) Stat(path string) vfs.FileInfo {
+func (fs *inputObservationFS) Stat(path shimtspath.RootedPath) vfs.FileInfo {
   info := fs.FS.Stat(path)
   kind := "missing"
   if info == nil {
@@ -242,16 +245,16 @@ func (fs *inputObservationFS) Stat(path string) vfs.FileInfo {
   return info
 }
 
-func (fs *inputObservationFS) Realpath(path string) string {
+func (fs *inputObservationFS) Realpath(path shimtspath.RootedPath) shimtspath.RootedPath {
   realpath := fs.FS.Realpath(path)
   fs.observe(path, observedInput{
-    proof: TransformInputObservation{Realpath: realpathObservation(realpath)},
+    proof: TransformInputObservation{Realpath: realpathObservation(string(realpath))},
   })
   return realpath
 }
 
-func (fs *inputObservationFS) currentRealpath(path string) *TransformInputRealpathObservation {
-  return realpathObservation(fs.FS.Realpath(path))
+func (fs *inputObservationFS) currentRealpath(path shimtspath.RootedPath) *TransformInputRealpathObservation {
+  return realpathObservation(string(fs.FS.Realpath(path)))
 }
 
 func realpathObservation(realpath string) *TransformInputRealpathObservation {
@@ -272,13 +275,11 @@ func (fs *inputObservationFS) observationKey(path string) string {
   if !filepath.IsAbs(path) {
     return ""
   }
-  return shimtspath.GetCanonicalFileName(
-    shimtspath.NormalizePath(path),
-    fs.caseSensitive,
-  )
+  return shimtspath.Canonicalize(fs.caseSensitivity, shimtspath.NormalizePath(path))
 }
 
-func (fs *inputObservationFS) observe(path string, next observedInput) {
+func (fs *inputObservationFS) observe(rooted shimtspath.RootedPath, next observedInput) {
+  path := string(rooted)
   key := fs.observationKey(path)
   if key == "" {
     return

package/driver/input_observation_test.go

@@ -9,6 +9,7 @@ import (
   "runtime"
   "testing"
 
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
   "github.com/samchon/ttsc/packages/ttsc/driver/windowsjunction"
 )
 
@@ -23,13 +24,13 @@ func TestInputObservationFSRejectsRestoredContent(t *testing.T) {
     t.Fatal(err)
   }
   observed := newInputObservationFS(DefaultFS())
-  if contents, ok := observed.ReadFile(file); !ok || contents != "A" {
+  if contents, ok := observed.ReadFile(shimtspath.RootedFilePathFromAbsolute(file)); !ok || contents != "A" {
     t.Fatalf("first read = %q, %v", contents, ok)
   }
   if err := os.WriteFile(file, []byte("B"), 0o644); err != nil {
     t.Fatal(err)
   }
-  if contents, ok := observed.ReadFile(file); !ok || contents != "B" {
+  if contents, ok := observed.ReadFile(shimtspath.RootedFilePathFromAbsolute(file)); !ok || contents != "B" {
     t.Fatalf("second read = %q, %v", contents, ok)
   }
   if err := os.WriteFile(file, []byte("A"), 0o644); err != nil {
@@ -53,16 +54,16 @@ func TestInputObservationFSProvesReadBytesAndMissingCandidates(t *testing.T) {
     t.Fatal(err)
   }
   observed := newInputObservationFS(DefaultFS())
-  if !observed.FileExists(file) {
+  if !observed.FileExists(shimtspath.RootedFilePathFromAbsolute(file)) {
     t.Fatal("selected file was not found")
   }
   if _, _, failure := observed.proof(file); failure != inputProofContentUnavailable {
     t.Fatalf("existence-only proof failure = %q, want %q", failure, inputProofContentUnavailable)
   }
-  if _, ok := observed.ReadFile(file); !ok {
+  if _, ok := observed.ReadFile(shimtspath.RootedFilePathFromAbsolute(file)); !ok {
     t.Fatal("selected file was not read")
   }
-  if observed.FileExists(missing) {
+  if observed.FileExists(shimtspath.RootedFilePathFromAbsolute(missing)) {
     t.Fatal("missing candidate unexpectedly exists")
   }
 
@@ -109,10 +110,10 @@ func testInputObservationFSKeepsFileAndDirectoryPredicatesIndependent(t *testing
     t.Fatal(err)
   }
   observed := newInputObservationFS(DefaultFS())
-  if observed.FileExists(directory) {
+  if observed.FileExists(shimtspath.RootedFilePathFromAbsolute(directory)) {
     t.Fatal("directory unexpectedly satisfied FileExists")
   }
-  if !observed.DirectoryExists(directory) {
+  if !observed.DirectoryExists(shimtspath.RootedDirectoryPathFromAbsolute(directory)) {
     t.Fatal("directory did not satisfy DirectoryExists")
   }
 
@@ -310,7 +311,7 @@ func TestInputObservationFSHashesCompilerDecodedText(t *testing.T) {
     t.Fatal(err)
   }
   observed := newInputObservationFS(DefaultFS())
-  contents, ok := observed.ReadFile(file)
+  contents, ok := observed.ReadFile(shimtspath.RootedFilePathFromAbsolute(file))
   if !ok || contents != text {
     t.Fatalf("compiler read = %q, %v; want decoded text", contents, ok)
   }
@@ -349,10 +350,10 @@ func TestInputObservationFSJoinsSelectedAliasProbeToPhysicalRead(t *testing.T) {
   }
   lexical := filepath.Join(alias, "value.js")
   observed := newInputObservationFS(DefaultFS())
-  if !observed.FileExists(lexical) {
+  if !observed.FileExists(shimtspath.RootedFilePathFromAbsolute(lexical)) {
     t.Fatal("selected lexical alias was not found")
   }
-  if _, ok := observed.ReadFile(physical); !ok {
+  if _, ok := observed.ReadFile(shimtspath.RootedFilePathFromAbsolute(physical)); !ok {
     t.Fatal("selected physical source was not read")
   }
 

package/driver/overlay.go

@@ -22,8 +22,8 @@ import (
 // @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
 type OverlayFS struct {
   vfs.FS
-  caseSensitive bool
-  overrides     map[string]string
+  caseSensitivity shimtspath.CaseSensitivity
+  overrides       map[string]string
 }
 
 // NewOverlayFS returns an overlay over inner with no overrides set.
@@ -32,15 +32,15 @@ type OverlayFS struct {
 // @evidence contracts/common.md#clear-and-simple-design Construction initializes one map and captures the inner VFS in one owner.
 // @evidence contracts/common.md#prohibited-implementation-shortcuts Construction does not alter the inner object or inject sample file contents.
 // @evidence contracts/common.md#meaningful-documentation Native prose states the initially empty overlay following the documentation skill.
-// @evidence contracts/portability.md#os-neutral-implementation Construction captures inner.UseCaseSensitiveFileNames as its canonicalization policy; it performs no independent per-directory capability or physical-alias probe.
+// @evidence contracts/portability.md#os-neutral-implementation Construction captures inner.CaseSensitivity as its canonicalization policy; it performs no independent per-directory capability or physical-alias probe.
 // @evidence contracts/performance.md#bound-retention-and-release-resources The returned overlay keeps inner reachable and owns a fresh override map. Later distinct keys and content bytes have no configured cap or eviction; callers remove entries with Unset or release the overlay. Inner handles and caches remain owned by the supplied filesystem.
 // @evidence contracts/performance.md#efficient-algorithms Construction allocates one empty map and wrapper and queries the inner case policy once, without scanning source files or override populations. Any work performed by that supplied policy query belongs to this delegated call, not a universal constant-time guarantee.
 // @evidenceExclude contracts/performance.md#reuse-equivalent-work Each construction intentionally creates independent mutable override state; the function owns no cross-overlay sharing coordinator or cached constructor result.
 func NewOverlayFS(inner vfs.FS) *OverlayFS {
   return &OverlayFS{
-    FS:            inner,
-    caseSensitive: inner.UseCaseSensitiveFileNames(),
-    overrides:     map[string]string{},
+    FS:              inner,
+    caseSensitivity: vfs.CaseSensitivityOf(inner),
+    overrides:       map[string]string{},
   }
 }
 
@@ -48,7 +48,7 @@ func NewOverlayFS(inner vfs.FS) *OverlayFS {
 // It does not anchor relative paths to the compiler cwd or resolve physical
 // aliases; callers must use compatible spellings when registering and reading.
 func (o *OverlayFS) key(path string) string {
-  return shimtspath.GetCanonicalFileName(shimtspath.NormalizePath(path), o.caseSensitive)
+  return shimtspath.Canonicalize(o.caseSensitivity, shimtspath.NormalizePath(path))
 }
 
 // Set records an in-memory override for path.
@@ -106,8 +106,8 @@ func (o *OverlayFS) Unset(path string) {
 // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The wrapper adds no read cache or native handle ownership. Override strings remain owned by the overlay and caller; fallback temporary resources and retained read state belong to the supplied inner filesystem, not this adapter's release policy.
 // @evidence contracts/performance.md#efficient-algorithms Lookup processes path normalization/case/hash bytes before testing the override map. A hit returns stored text without scanning it; a miss adds the inner read's actual path, input-byte and decoding/cache costs, which are not universally fixed steps.
 // @evidenceExclude contracts/performance.md#reuse-equivalent-work The wrapper adds no completed/in-flight read coordinator or independent disk-content cache; inner reuse remains the supplied filesystem's policy.
-func (o *OverlayFS) ReadFile(path string) (string, bool) {
-  if content, ok := o.overrides[o.key(path)]; ok {
+func (o *OverlayFS) ReadFile(path shimtspath.RootedFilePath) (string, bool) {
+  if content, ok := o.overrides[o.key(string(path))]; ok {
     return content, true
   }
   return o.FS.ReadFile(path)
@@ -123,8 +123,8 @@ func (o *OverlayFS) ReadFile(path string) (string, bool) {
 // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The wrapper retains no new entries or native handles during the query. Existing overrides remain overlay-owned; any temporary handles or metadata caches populated by fallback belong to the supplied inner filesystem.
 // @evidence contracts/performance.md#efficient-algorithms Key normalization/case conversion and hashing process path bytes before one override lookup. Hits require no native query; misses add the supplied filesystem's existence-probe or metadata-cache work rather than a universal fixed cost.
 // @evidenceExclude contracts/performance.md#reuse-equivalent-work This wrapper owns no existence-query sharing coordinator or separate metadata cache; it reads current overrides and delegates inner reuse policy.
-func (o *OverlayFS) FileExists(path string) bool {
-  if _, ok := o.overrides[o.key(path)]; ok {
+func (o *OverlayFS) FileExists(path shimtspath.RootedFilePath) bool {
+  if _, ok := o.overrides[o.key(string(path))]; ok {
     return true
   }
   return o.FS.FileExists(path)