@ttsc/wasm 0.30.4 → 0.31.1

package/shim-vendor/shim/compiler/emit_sourcemap.go

@@ -5,25 +5,21 @@
 // tsgo's Program.Emit has no hook to inject a custom transformer, so ttsc's
 // driver assembles the per-file emit pipeline by hand (see GetSourceFilesToEmit
 // / GetScriptTransformers / GetOutputPathsFor). That hand-assembly must also
-// reproduce every step the emitter would otherwise run: building the printer's
+// reproduce the selected text/map assembly steps: building the printer's
 // options from the compiler options, the source-map branch a bare printer.Write
 // with a nil generator drops entirely, the `emitBOM` byte-order mark, and the
-// `WriteFileData` the emitter hands its writeFile callback. This file ports
+// trailer position the emitter places in WriteFileData. This file ports
 // internal/compiler/emitter.go's `emitJSFile` PrinterOptions construction and
-// the whole of its `printSourceFile` so a build that goes through a plugin
-// transform honors the same compiler options — and produces the same map (and
-// `//# sourceMappingURL=` trailer, and the same first bytes) — a plain build
-// does.
+// its printing, source-map and BOM assembly policy. The driver owns writing
+// returned artifacts and its metadata; upstream diagnostic/write-result and
+// SourceMaps receipt machinery is not reproduced by this helper. Byte and map
+// compatibility depends on the actual transformed nodes and retained provenance.
 //
 // Keep it in sync with that emitter source when the pin is bumped. Anything
 // `emitJSFile` sets and this file omits takes the Go zero value, which silently
 // turns the option off for every project that emits through a plugin transform,
 // and anything `printSourceFile` does around the printer that this file omits
 // is missing from the plugin lane's output even when the option set matches.
-// `printer_options_field_set_matches_pinned_emitter_test.go` fails when the pin
-// changes the PrinterOptions field set,
-// `write_file_data_field_set_matches_pinned_emitter_test.go` fails when it
-// changes the WriteFileData field set, and
 // `emit_plugin_transform_matches_plain_emit_for_printer_options_test.go` fails
 // when a forwarded option stops matching the plain emit.
 package compiler
@@ -39,17 +35,32 @@ import (
 )
 
 // PrintedFile is the rendered output of one source file in the plugin-transform
-// emit path. JS is the JavaScript text, already carrying a trailing
-// `//# sourceMappingURL=` comment when a map was produced and a leading UTF-8
-// byte order mark when `emitBOM` is on. MapText/MapPath are the external
-// source-map file and its path; both are empty when no external map is written
-// (source maps disabled, or an inline map encoded into the JS).
+// emit path. JS is the script text, carrying a sourceMappingURL trailer when
+// its selected URL is nonempty and a leading UTF-8 BOM when emitBOM is on.
+// MapText/MapPath contain external map text and its selected destination only
+// when mapping is enabled, maps are not inline and that destination is nonempty.
+// They are otherwise empty. These are returned artifacts, not write receipts.
+//
+// @evidence contracts/common.md#principled-implementation The record separates emitted script, optional external map and map destination, retaining the pinned emitter's pre-BOM trailer coordinate rather than mixing file bytes with writer positions.
+// @evidence contracts/common.md#clear-and-simple-design One per-file result carries related output artifacts; absent external maps use empty values and absent trailers use the documented negative sentinel.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The sentinel and pre-BOM coordinate are compiler protocol values, not patched expected answers; no foreign state or consumer-specific output is introduced.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains map absence, inline output and BOM coordinate effects; every member has native documentation separated by blank source lines.
+// @evidence contracts/portability.md#os-neutral-implementation MapPath preserves the host-resolved native output destination while JS contains URI trailer spelling; the fields keep those distinct rather than equating URL and filesystem identity.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This record represents output and does not choose the printing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This output record does not coordinate computation across consumers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Storage lifetime belongs to the printing operation and its caller, not independently to the result declaration.
 type PrintedFile struct {
-  JS      string
+  // JS contains emitted script text, optional map trailer and optional BOM.
+  JS string
+
+  // MapText contains the external map JSON, or empty text for inline or absent maps.
   MapText string
+
+  // MapPath is the destination for MapText, or empty when no external map is emitted.
   MapPath string
+
   // SourceMapUrlPos is the offset of the `//# sourceMappingURL=` trailer in JS,
-  // or -1 when no trailer was written — the value tsgo's emitter reports as
+  // or -1 when no trailer was written, the value tsgo's emitter reports as
   // WriteFileData.SourceMapUrlPos so a caller can locate and rewrite the
   // trailer without re-scanning the text. Like the emitter's, it is the printer
   // writer's text position, taken BEFORE the `emitBOM` mark is prepended, so a
@@ -62,10 +73,11 @@ type PrintedFile struct {
   SourceMapUrlPos int
 }
 
-// PrintFileWithSourceMap renders sourceFile through a printer built from options
-// and emitContext, optionally generating a source map, mirroring
-// emitter.emitJSFile and emitter.printSourceFile for the single-file
-// plugin-transform path. The PrinterOptions below are emitJSFile's, field for
+// PrintFileWithSourceMap renders node from sourceFile through a printer built
+// from options and emitContext, optionally generating a source map, mirroring
+// their text/map assembly for the single-file plugin-transform path. It returns
+// artifacts; it does not reproduce upstream writes, diagnostics, SourceMaps
+// receipts or complete WriteFileData. The PrinterOptions below are emitJSFile's, field for
 // field: `removeComments`, `newLine`, `noEmitHelpers`, `sourceMap`,
 // `inlineSourceMap`, `inlineSources`, and `target`. When
 // `sourceMap`/`inlineSourceMap` is enabled (and the file is not JSON) it builds a
@@ -73,10 +85,22 @@ type PrintedFile struct {
 // appends the sourceMappingURL trailer, records its offset, and returns the
 // external map text/path (or encodes the map inline). `emitBOM` prepends the
 // UTF-8 byte order mark to the JavaScript afterwards, exactly where
-// printSourceFile does it — outside PrinterOptions, which is why forwarding the
-// whole options struct never reached it. The external map is written without a
-// mark, matching the emitter's own `writeText(sourceMapFilePath, ..., nil)`.
+// printSourceFile does it, outside PrinterOptions, which is why forwarding the
+// whole options struct never reached it. Returned external map text has no BOM,
+// matching the text supplied to upstream's map write.
 // host supplies the same directory/casing context tsgo's emitter reads.
+//
+// The source file, compiler options and host must be nonnil. Original node
+// positions and emitContext provenance determine source-map accuracy.
+//
+// @evidence contracts/common.md#principled-implementation The maintained port follows the pinned emitter's printer options, map eligibility, URI encoding, newline/trailer handling and post-print BOM ordering; upstream printer traversal derives mappings from retained node provenance.
+// @evidence contracts/common.md#clear-and-simple-design One per-file printer/writer/generator owns output assembly, while focused helpers separate source-root, shared map-directory and trailer-URL policy without duplicating output state.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts JSON map suppression, inline maps and pre-BOM offsets implement actual compiler options and output protocol; they do not select fixtures or patch upstream printer behavior.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish printer settings from post-print BOM effects, external from inline maps, path context and provenance requirements; the result documents its coordinate convention explicitly.
+// @evidence contracts/portability.md#os-neutral-implementation Compiler path helpers normalize native output paths, host-provided case sensitivity governs relative identity, and trailer paths are separately URI-encoded; URL spelling is not treated as filesystem casing.
+// @evidence contracts/performance.md#efficient-algorithms Text and mapping collection share one printer invocation; upstream printing can also consult node provenance, semantic helpers, source positions and path text, so this is not a strict one-pass bound over input or output bytes. Map-table copies and JSON serialization, optional base64, trailer writes and a BOM text copy add their own work. The writer's recorded position avoids rescanning emitted text just to locate the trailer.
+// @evidence contracts/performance.md#reuse-equivalent-work Text and source mappings share the printer traversal and EmitContext provenance; no cross-file printer source-index state is reused, and compiler options and transformed nodes determine each output.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Per-call printer, writer and generator hold output buffers, source/name indexes, mapping segments and optional borrowed source text. Map serialization/base64 and BOM assembly can temporarily coexist with those buffers; result strings retain their backing bytes after return. EmitContext and source/semantic graphs remain caller-owned, and this function adds no historical result registry or spawned task. No fixed byte cap is imposed here.
 func PrintFileWithSourceMap(
   emitContext *innerprinter.EmitContext,
   node *innerast.Node,
@@ -105,7 +129,7 @@ func PrintFileWithSourceMap(
     generator = innersourcemap.NewGenerator(
       innertspath.GetBaseFileName(innertspath.NormalizeSlashes(jsFilePath)),
       sourceMapSourceRoot(options),
-      sourceMapDirectory(options, host, jsFilePath, sourceFile),
+      SourceMapDirectory(options, host, jsFilePath, sourceFile),
       innertspath.ComparePathsOptions{
         UseCaseSensitiveFileNames: host.UseCaseSensitiveFileNames(),
         CurrentDirectory:          host.GetCurrentDirectory(),
@@ -154,10 +178,25 @@ func sourceMapSourceRoot(options *innercore.CompilerOptions) string {
   return root
 }
 
-// sourceMapDirectory mirrors emitter.getSourceMapDirectory: the directory the
-// sourcemap generator resolves source paths against, honoring sourceRoot/mapRoot
-// and falling back to the .js output directory.
-func sourceMapDirectory(options *innercore.CompilerOptions, host innerprinter.EmitHost, filePath string, sourceFile *innerast.SourceFile) string {
+// SourceMapDirectory returns the directory the pinned compiler's source-map
+// generator uses to resolve source paths. This is the generator's internal
+// directory context, not the map's published sourceRoot field.
+//
+// A nonempty sourceRoot selects the host's common source directory. Otherwise
+// mapRoot selects the map directory, projecting sourceFile's path into that
+// root when sourceFile is present; a relative mapRoot is based on the common
+// source directory. Without either option, the output file's directory is used.
+// The options and host must be nonnil; sourceFile may be nil.
+//
+// @evidence contracts/common.md#principled-implementation The maintained helper follows pinned emitter.getSourceMapDirectory's sourceRoot precedence, per-source mapRoot projection and relative-root anchoring, returning the exact generator base instead of assuming maps are based on an emitted file directory.
+// @evidence contracts/common.md#clear-and-simple-design One supported public helper owns generator-directory policy for printing and downstream map consumers, avoiding independently implemented path-base rules.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Directory selection follows real compiler options and host context, including URL and relative roots, without a consumer-specific map repair or filesystem guessing.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish internal generator context from published sourceRoot, describe option precedence and path projection, and state nonnil versus optional inputs.
+// @evidence contracts/portability.md#os-neutral-implementation Compiler path helpers handle native roots and URL spelling separately, while per-source projection uses the host's actual current/common directories and case policy rather than an OS-name assumption.
+// @evidence contracts/performance.md#efficient-algorithms Branching applies sourceRoot/mapRoot precedence and compiler path normalization/remapping over path text. Host CommonSourceDirectory/current-directory/case queries are delegated work and may compute or reuse source metadata; the absence of a local file loop does not bound those host costs. Centralizing this policy avoids separate consumer implementations, not all repeated path work.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure path-context calculation does not coordinate completed or in-flight work across requests; map consumers own any per-file index of its results.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Intermediate normalized/remapped path strings are invocation-local, and the returned directory string can retain newly allocated or borrowed backing bytes. Host-owned common-directory/source metadata remains with that host. This helper keeps no independent historical result cache, native handle or running task; callers determine the returned string's retention.
+func SourceMapDirectory(options *innercore.CompilerOptions, host innerprinter.EmitHost, filePath string, sourceFile *innerast.SourceFile) string {
   if len(options.SourceRoot) > 0 {
     return host.CommonSourceDirectory()
   }

package/shim-vendor/shim/compiler/emitassemble.go

@@ -17,14 +17,48 @@ import (
 // GetSourceFilesToEmit returns the source files tsgo would emit for the program
 // (excludes .d.ts and external-library files), linked from the internal package.
 //
+// @evidence contracts/common.md#principled-implementation Linking the pinned compiler's own selection helper preserves its target-file, declaration and compiler-option eligibility decisions rather than recreating emit selection.
+// @evidence contracts/common.md#clear-and-simple-design The direct declaration exposes selection independently of output writing, allowing the driver to insert transformers while retaining compiler ownership of eligible files.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The symbol bridge exposes upstream behavior without replacing it; forceDtsEmit is an actual compiler control, not a fixture exception.
+// @evidence contracts/common.md#meaningful-documentation Native prose describes emitted-file selection and internal linkage, with the acknowledgment separated from the Go linkage directive.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This exposes upstream emit eligibility and does not choose native path identity or perform filesystem access.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GetSourceFilesToEmit declares a signature only; the implementation owns acquisition and release of resources.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GetSourceFilesToEmit declares a signature only; the implementation owns the processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GetSourceFilesToEmit declares a signature only; the implementation owns any shared work.
+//
 //go:linkname GetSourceFilesToEmit github.com/microsoft/typescript-go/internal/compiler.getSourceFilesToEmit
 func GetSourceFilesToEmit(host innercompiler.SourceFileMayBeEmittedHost, targetSourceFile *innerast.SourceFile, forceDtsEmit bool) []*innerast.SourceFile
 
 // OutputPaths holds the resolved output file paths for one source file.
+// Empty fields represent outputs disabled or suppressed by upstream policy,
+// such as a JSON script destination identical to its source location. Resolved
+// destinations do not certify that later emit or writing succeeds.
+//
+// @evidence contracts/common.md#principled-implementation The exact upstream output-path alias preserves separate script, declaration and map destinations, including absent outputs, without losing compiler-resolved path distinctions.
+// @evidence contracts/common.md#clear-and-simple-design One compiler-owned result groups related outputs for a source file, avoiding independently recomputed paths at each sink.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The alias does not insert consumer-specific filenames or alter output policy.
+// @evidence contracts/common.md#meaningful-documentation Native prose states per-file output ownership and the meaning of empty destinations.
+// @evidence contracts/portability.md#os-neutral-implementation Output fields preserve the compiler's host-resolved native destinations, including absent outputs, rather than imposing URL spelling or an OS-derived case policy.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
 type OutputPaths = inneroutputpaths.OutputPaths
 
-// GetOutputPathsFor resolves the .js / .d.ts / map output paths for a source
-// file (honoring rootDir/outDir), the same call tsgo's emitter makes.
+// GetOutputPathsFor resolves script, declaration and map destinations using
+// upstream extension and output-directory policy. The script extension can
+// also be .jsx, .mjs, .cjs or .json; disabled or suppressed outputs are empty.
+// The host supplies the common source directory, current directory and case
+// policy. This is path selection, not proof that emit writes every destination.
+// sourceFile, options and host must satisfy the upstream resolver's premises.
+//
+// @evidence contracts/common.md#principled-implementation The wrapper delegates the same source file, options, host and declaration-emission control to the compiler's output-path algorithm, preserving root and output directory semantics.
+// @evidence contracts/common.md#clear-and-simple-design Output placement remains in upstream's owning helper; this adapter only exposes that boundary to the driver.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No path is fabricated from a consumer or fixture name, and the upstream output resolver is neither copied nor patched.
+// @evidence contracts/common.md#meaningful-documentation Native prose names the output classes, relevant directory options and host context, with a separate acknowledgment section.
+// @evidence contracts/portability.md#os-neutral-implementation Upstream's output resolver receives the actual host directory and path-identity policy; the shim does not guess separators, drive roots or case sensitivity from an OS name.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream allocates a returned OutputPaths object and constructs or borrows destination strings; their backing storage survives with the caller's result. Host-owned directory and case-policy state remains with the host. This bridge acquires no independent file handle or persistent result registry.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream owns extension selection, path normalization, comparison and directory remapping, including work proportional to path text and any host directory lookup. This direct adapter chooses no separate output-path algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Output-path computation and any reusable common-directory or host metadata belong to the upstream resolver and host. This bridge coordinates no independent cache or cross-call producer.
 func GetOutputPathsFor(sourceFile *innerast.SourceFile, options *innercore.CompilerOptions, host inneroutputpaths.OutputPathsHost, forceDtsEmit bool) *inneroutputpaths.OutputPaths {
   return inneroutputpaths.GetOutputPathsFor(sourceFile, options, host, forceDtsEmit)
 }

package/shim-vendor/shim/compiler/emithook.go

@@ -20,13 +20,23 @@ import (
 //
 // `sourceFile` is the marking target, not the file that gets transformed.
 // Upstream reads it for two per-file constants (in-JS-file, JSX language
-// variant) and then hands it to emitResolver.MarkLinkedReferencesRecursively,
-// whose marks the import-elision transformer later reads back through
-// EmitContext.ParseNode. A caller that runs a plugin pass first must therefore
+// variant) and, unless isolated modules without import elision, JSX transform
+// or decorator metadata makes marking unnecessary, hands it to
+// emitResolver.MarkLinkedReferencesRecursively, whose marks the import-elision
+// transformer later reads back through EmitContext.ParseNode. A caller that runs a plugin pass first must therefore
 // pass the PARSE tree here and the transformed tree to TransformSourceFile;
 // upstream's own emitter passes one file to both only because it has nothing in
 // between. Re-check this when the pin moves: a new use of the parameter inside
 // getScriptTransformers could make the two roles diverge further.
 //
+// @evidence contracts/common.md#principled-implementation Linking the pinned builtin chain preserves compiler transform ordering; the parse-tree argument supplies stable linked-reference marks that transformed nodes retrieve through EmitContext provenance.
+// @evidence contracts/common.md#clear-and-simple-design The helper exposes chain assembly without running transforms, keeping plugin insertion in the driver and builtin ordering in the compiler.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The source-file distinction follows the pinned helper's marking semantics rather than masking an arbitrary transform failure; linkage exposes the function without replacing its implementation.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain chain contents, marking versus transformation roles and the version-pin premise, with Go linkage retained outside the prose section.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GetScriptTransformers declares a signature only; the implementation owns acquisition and release of resources.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GetScriptTransformers declares a signature only; the implementation owns the processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GetScriptTransformers declares a signature only; the implementation owns any shared work.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetScriptTransformers is a signature without a body here; path and platform behavior belongs to the implementation that supplies it.
+//
 //go:linkname GetScriptTransformers github.com/microsoft/typescript-go/internal/compiler.getScriptTransformers
 func GetScriptTransformers(emitContext *innerprinter.EmitContext, host innerprinter.EmitHost, sourceFile *innerast.SourceFile) []*innertransformers.Transformer

package/shim-vendor/shim/compiler/go.mod

@@ -2,13 +2,13 @@ module github.com/microsoft/typescript-go/shim/compiler
 
 go 1.26
 
-require github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157
+require github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063
 
 require (
-	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
 	github.com/zeebo/xxh3 v1.1.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.43.0 // indirect
-	golang.org/x/text v0.36.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
 )

package/shim-vendor/shim/compiler/go.sum

@@ -1,22 +1,22 @@
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 h1:nxP4pPoyqOAgX8lYDFCfl3DyKeXErCvSvhcyzwGV9CE=
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
-github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157 h1:llOMPhKDiQ+UEJiAaQuuWaJOTg5V7tNNTEf9JPWoYSY=
-github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157/go.mod h1:m8YA0PMC7ti0GW0RI05D6fEcjQeu98XVS+FWF+VDW2k=
+github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063 h1:UUVrjTrD+7nkVvkJTjxwA5+SaZ5n1uyAffm2zX2gn+o=
+github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063/go.mod h1:s3yhRRZ7nzSZaiKicku520Tj9Mvewr9y2UtrvpwOmDE=
 github.com/peter-evans/patience v0.3.0 h1:rX0JdJeepqdQl1Sk9c9uvorjYYzL2TfgLX1adqYm9cA=
 github.com/peter-evans/patience v0.3.0/go.mod h1:Kmxu5sY1NmBLFSStvXjX1wS9mIv7wMcP/ubucyMOAu0=
 github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
 github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
 github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
 github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
-golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
+golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
 gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
 gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=

package/shim-vendor/shim/compiler/incremental.go

@@ -29,10 +29,10 @@ import (
   "github.com/microsoft/typescript-go/internal/execute/incremental"
 )
 
-// EmitFreshWithBuildInfo runs a full emit through tsgo's own incremental
-// program, so an `incremental` or `composite` project gets the `.tsbuildinfo`
-// tsgo would have written, in the exact format and location
-// `outputpaths.GetBuildInfoFileName` resolves from the compiler options.
+// EmitFreshWithBuildInfo emits through a new upstream incremental wrapper
+// around the supplied checked Program, with no previous wrapper/snapshot.
+// Its build-information format and candidate location come from upstream
+// snapshot serialization and outputpaths.GetBuildInfoFileName.
 //
 // This is the emit half of `tsc.go::performIncrementalCompilation`, which the
 // tsgo CLI takes whenever `CompilerOptions.IsIncremental()`. A host that builds
@@ -40,14 +40,28 @@ import (
 // emitting through it) never reaches that CLI path, so without this the build
 // information is silently dropped even though the options parsed cleanly.
 //
-// "Fresh" is the load-bearing word: no previous snapshot is supplied, so
-// `programToSnapshot` marks every file changed and this emits the whole program
-// exactly as `Program.Emit` does, then writes the build info. A ttsc plugin's
+// "Fresh" in EmitFreshWithBuildInfo means no previous snapshot is supplied.
+// When upstream incremental-state tracking is enabled, initial construction
+// tracks loaded files and makes their applicable output pending rather than
+// reusing prior emit signatures or diagnostics. TargetSourceFile still selects
+// single-file emission; noEmit/noEmitOnError, cancellation, blocked output and
+// write failure retain their upstream behavior. A whole-program eligible emit
+// attempts pending build info, but a record is not guaranteed on every call.
+// The supplied Program and context must be valid for this emit round. A plugin's
 // output is not a pure function of the source text a build info records — it
 // also depends on the plugin binary, its config file, and its contributors —
 // so reusing a previous snapshot to skip a file would serve stale transformed
-// output. Producing the record is sound; consuming it needs plugin identity in
-// the invalidation key first.
+// output. Using a record to skip plugin effects requires a reuse identity that
+// covers every relevant input and effect, not source text alone.
+//
+// @evidence contracts/common.md#principled-implementation A nil previous wrapper prevents reuse of old snapshot emit signatures/diagnostics and initializes applicable pending output under upstream emit controls; source-only prior state cannot establish plugin-effect equivalence.
+// @evidence contracts/common.md#clear-and-simple-design One upstream incremental-program construction owns full emit and build-info output, avoiding a separate record serializer or a partially reused emit path.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Fresh emission is grounded in absent plugin identity in the snapshot key, not a blanket retry masking stale output; no fake build-info or consumer-specific cache key is introduced.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the in-process build-info connection, fresh pending state, emit/cancellation/write limits and plugin-effect invalidation rather than unconditional output or incremental reuse.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This wrapper chooses snapshot reuse, while Program.Host and the upstream incremental emitter own native output-path and filesystem decisions.
+// @evidence contracts/performance.md#efficient-algorithms The fresh wrapper reuses the checked Program but builds snapshot file hashes, references and semantic metadata; eligible output then incurs emission and additional build-info table traversal/JSON serialization. File, reference, source/output-byte and diagnostic populations drive this work. Delegating the actual engine avoids a separate record implementation, not those traversals; prior snapshot skipping is unsafe without plugin-equivalent inputs/effects.
+// @evidence contracts/performance.md#reuse-equivalent-work The supplied checked Program is reused, while no previous incremental wrapper is admitted. Skipping effectful emission requires identity and invalidation covering all plugin/runtime/configuration/contributor dependencies and effects; quiet source text alone cannot authorize it.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The invocation acquires an incremental snapshot with file/reference/pending/diagnostic state plus temporary emission and build-info serialization storage. It retains the supplied Program while upstream work runs; returned results and WriteFile callback data may retain output or semantic references afterward. This adapter keeps no historical snapshot registry or independent running-task owner, and caller/host/upstream own result, callback and Program lifetimes on success, error or cancellation.
 func EmitFreshWithBuildInfo(ctx context.Context, program *Program, options EmitOptions) *EmitResult {
   incrementalProgram := incremental.NewProgram(
     program,
@@ -64,13 +78,12 @@ func incrementalGetReferencedFiles(program *innercompiler.Program, file *inneras
 //go:linkname incrementalFileAffectsGlobalScope github.com/microsoft/typescript-go/internal/execute/incremental.fileAffectsGlobalScope
 func incrementalFileAffectsGlobalScope(file *innerast.SourceFile) bool
 
-// GetReferencedFilePaths returns the canonical paths of every file that `file`
-// directly references in `program`: resolved imports and re-exports (type-only
-// included), `/// <reference>` targets, resolved type reference directives,
-// module augmentations, and ambient-module declaration files. This is exactly
-// the per-file `referencedMap` entry tsgo's incremental engine stores in
-// `tsbuildinfo`, so the result is the sound language-semantic upper bound on
-// which program files a symbol in `file` can resolve through.
+// GetReferencedFilePaths adapts the upstream incremental reference set:
+// import/re-export and string module-augmentation symbols' declaration files,
+// path directives, resolved type directives and ambient-module declarations.
+// It is not a transitive symbol-reachability closure or proof that every path
+// is a loaded source. Extensionless path-directive adaptation below can also
+// differ from the raw upstream build-info entry.
 //
 // The returned strings are tspath.Path values (case-canonicalized on
 // case-insensitive filesystems); map them back to real file names through
@@ -78,6 +91,17 @@ func incrementalFileAffectsGlobalScope(file *innerast.SourceFile) bool
 // Extensionless path references are replaced with the source file Program
 // actually loaded because the upstream incremental helper retains their raw
 // directive path instead of the selected extension-bearing path.
+// Program and file must be nonnil and belong to the same loaded program.
+// Returned order follows the compiler's reference set; it is not sorted.
+//
+// @evidence contracts/common.md#principled-implementation Upstream's semantic reference set is combined with the same program's resolved path directives, replacing extensionless raw paths with loaded source identities and deduplicating canonical paths; project-reference redirects use the program's actual declaration-to-source mapping.
+// @evidence contracts/common.md#clear-and-simple-design The exported function owns reference-set adaptation while a private helper resolves resident and virtual declaration sources through one program context.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The extra project-reference lookup addresses supported unbuilt declaration outputs using compiler redirects and supported extensions, rather than guessing filenames or special-casing projects.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs identify reference categories, canonical spelling, extension replacement, same-program premises and unsorted output with descriptive text separate from tags.
+// @evidence contracts/portability.md#os-neutral-implementation Path identity uses Program.UseCaseSensitiveFileNames and compiler path helpers, while project-reference redirects recover the loaded filename rather than inferring native case behavior from the OS.
+// @evidence contracts/performance.md#efficient-algorithms Adaptation uses expected linear map/set processing in upstream reference count plus path-directive count, with path-text hashing/canonicalization and a bounded supported-extension search per unresolved directive. Before that, upstream obtains a checker and visits import/augmentation symbols, their declarations and ambient modules; semantic lookup, declaration parent walks and host/project-reference queries are additional delegated work, not bounded by the returned path count alone.
+// @evidence contracts/performance.md#reuse-equivalent-work Loaded Program resolutions, sources and checker state are reused, while the reference set and adaptation maps are rebuilt per invocation. Upstream checker queries may populate semantic caches; this adapter coordinates no cross-Program cache or separate resolver producer.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream acquires a file checker with a deferred release callback and may retain semantic state under its Program/checker owner. Reference, replacement and deduplication sets are invocation-local; returned slice/string ownership transfers to the caller and may share existing path backing storage. The bridge keeps no historical result registry.
 func GetReferencedFilePaths(program *Program, file *innerast.SourceFile) []string {
   set := incrementalGetReferencedFiles(program, file)
   if set == nil {
@@ -138,10 +162,22 @@ func getSourceFileFromReference(program *Program, file *innerast.SourceFile, ref
   return nil
 }
 
-// FileAffectsGlobalScope reports whether editing `file` can change the global
-// scope: global-scope module augmentations, ambient declaration files, and
-// script (non-module) files. Mirrors the predicate tsgo's incremental engine
-// uses to decide that a change must invalidate every file in the program.
+// FileAffectsGlobalScope reports the upstream incremental engine's global
+// impact classification, first ensuring the source file is bound. A global
+// augmentation is true; otherwise external/CommonJS modules and JSON are false.
+// A remaining script is true only when it has a statement other than a
+// string-literal-named module declaration. Empty or ambient-external-only
+// scripts are not automatically global-impact files.
+// file must be a nonnil compiler source file.
+//
+// @evidence contracts/common.md#principled-implementation The wrapper delegates the pinned incremental engine's global-scope predicate, preserving the same distinction used for program-wide semantic invalidation.
+// @evidence contracts/common.md#clear-and-simple-design One predicate exposes compiler-owned classification without an independent global-scope analysis.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No path, project name or expected invalidation result is special-cased; the foreign predicate remains unchanged.
+// @evidence contracts/common.md#meaningful-documentation Native prose states binding, augmentation/module/JSON/script distinctions, empty/ambient-only limits and the nonnil source-file premise without certifying every edit's runtime invalidation result.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Global-scope syntax classification has no native filesystem or process boundary.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream binding and global-impact classification own their algorithms: an unbound file can incur AST binding, then augmentation/statement scans short-circuit according to the classification. This direct bridge chooses no independent traversal or impact analysis.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Upstream IsBound/BindOnce and its binder pool own binding reuse; this bridge coordinates no separate impact-result cache or cross-generation producer/invalidation policy.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Binding can acquire a pooled binder and populate source-owned symbols, flow and classification state; its defer returns and resets the binder while that bound AST state survives under the file owner. The bridge returns only a boolean and keeps no independent state registry or handle, but does not equate that with absence of delegated retention.
 func FileAffectsGlobalScope(file *innerast.SourceFile) bool {
   return incrementalFileAffectsGlobalScope(file)
 }

package/shim-vendor/shim/compiler/resolution.go

@@ -18,6 +18,15 @@ import (
 )
 
 // ProgramResolutionKind distinguishes module and type-reference resolution.
+//
+// @evidence contracts/common.md#principled-implementation The two discriminants select the compiler's distinct module-name and type-directive algorithms, retaining their different result semantics.
+// @evidence contracts/common.md#clear-and-simple-design One small enum selects the replay operation without encoding the distinction in task names or separate task containers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The constants identify actual resolver operations rather than expected results or consumer-specific behavior.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies both resolution categories before the acknowledgment block.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The enum selects a semantic operation and carries no native path or platform capability.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The discriminant representation does not own resolution processing.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The enum does not coordinate shared computation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The enum owns no retained state or running resource.
 type ProgramResolutionKind uint8
 
 const (
@@ -26,17 +35,47 @@ const (
 )
 
 // ProgramResolutionTask is one resolution already performed by a resident
-// Program. The exported fields provide deterministic host ordering while the
+// Program. Exported fields let a host explicitly sort and group tasks; the
+// record itself imposes no order. The
 // unexported fields retain the exact compiler context needed for replay.
+// Keep tasks with their originating Program options and project-reference
+// metadata unchanged; ReplayProgramResolutions accepts one coherent source's
+// task group, not arbitrary tasks from different programs.
+//
+// @evidence contracts/common.md#principled-implementation The record retains name, resolution mode, lexical containing path, expected target and originating options/project redirects, preserving the inputs needed to compare compiler resolution rather than only resolved filenames.
+// @evidence contracts/common.md#clear-and-simple-design Public ordering/provenance fields are distinct from private replay context, allowing hosts to group tasks without manufacturing the compiler state used for semantic replay.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Expected results preserve actual package and symlink identities; task construction does not synthesize answers for consumer names.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state resident-program provenance and coherent-group ownership; documented public fields have blank source lines between them.
+// @evidence contracts/portability.md#os-neutral-implementation Lexical containing and resolved filenames remain distinct from loaded source/target filenames and canonical cache keys, preserving casing and project-reference spelling needed by native resolution.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This task record represents work selected by its producer, not the resolution algorithm owner.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The task type does not independently validate or coordinate reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retention of task arrays and referenced Program metadata belongs to producer and caller operations, not independently to the record declaration.
 type ProgramResolutionTask struct {
+  // ContainingFile is recovered source/config context when available, otherwise
+  // the resident canonical cache-key spelling used for replay.
   ContainingFile string
-  Kind           ProgramResolutionKind
-  Mode           core.ResolutionMode
-  Name           string
-  ResolvedFile   string
-  SourceFile     string
-  TargetFile     string
-  Universal      bool
+
+  // Kind selects module or type-reference resolution.
+  Kind ProgramResolutionKind
+
+  // Mode carries the compiler's import-versus-require resolution mode.
+  Mode core.ResolutionMode
+
+  // Name is the original module or type-directive specifier.
+  Name string
+
+  // ResolvedFile is the resident resolver's target spelling, or empty if unresolved.
+  ResolvedFile string
+
+  // SourceFile names the loaded containing source, or is empty when none was
+  // found, including automatic directives.
+  SourceFile string
+
+  // TargetFile names the loaded target after project-reference substitution, if available.
+  TargetFile string
+
+  // Universal marks automatic directives whose containing context is synthetic.
+  Universal bool
 
   compilerOptions     *core.CompilerOptions
   currentDirectory    string
@@ -47,6 +86,21 @@ type ProgramResolutionTask struct {
 
 // ProgramResolutionTasks returns every cached module and type-reference
 // resolution, including unresolved entries and automatic type directives.
+// A nil Program returns nil. Returned tasks retain Program option and redirect
+// pointers; the caller owns their storage and must preserve that context.
+// Enumeration order follows compiler maps and is not sorted. TargetFile is
+// populated only when the target resolves to a loaded source. Extraction may
+// initialize referenced configs' input/output maps and query a native realpath
+// for a preserved symlink redirect; it does not replay module resolution.
+//
+// @evidence contracts/common.md#principled-implementation Enumerating the resident compiler's module and type-directive caches retains both successes and failures; containing paths recover loaded-source or semantic-config spelling, and expected results include package, target and link identity.
+// @evidence contracts/common.md#clear-and-simple-design One append closure shares task construction across both compiler cache traversals, while private helpers own source-redirect and project-reference context reconstruction.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The inferred-types filename is the compiler's automatic-directive context, and recovering its lexical directory addresses actual case-canonical cache keys without relaxing result comparison.
+// @evidence contracts/common.md#meaningful-documentation Native prose states cache coverage, nil behavior and retained Program-pointer lifetime; task fields document the lexical-versus-loaded path distinctions.
+// @evidence contracts/portability.md#os-neutral-implementation Compiler canonical cache keys are not replayed as lexical filenames: source/config context restores spelling, and redirects use actual filesystem Realpath plus Program case policy rather than OS guesses.
+// @evidence contracts/performance.md#efficient-algorithms Two cache traversals append one task per resolution and share one reference-context snapshot. Additional work includes reference-graph traversal, source/output map scans and first-use output-path construction, path hashing/canonicalization and selected native Realpath queries for symlink context. Map/string backing and referenced config/source population matter beyond just the returned task count; extraction does not independently replay imports.
+// @evidence contracts/performance.md#reuse-equivalent-work Cached resident resolutions and one shared project-reference context are reused across tasks from the same Program, preserving their option and redirect identity rather than sharing across changed programs.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned task slice retains option, expected-result strings and redirect metadata, plus a shared context's directory set and output-to-reference map when present. These pointers can keep parsed project/config/source graphs reachable beyond the shallow map size. First-use input/output maps remain owned by referenced configs; invocation-local traversal/snapshot containers add no independent historical registry or running task, and callers bound how long they retain the result.
 func ProgramResolutionTasks(program *Program) []ProgramResolutionTask {
   if program == nil {
     return nil
@@ -69,7 +123,7 @@ func ProgramResolutionTasks(program *Program) []ProgramResolutionTask {
       // their containing directory, falling back to cwd for configless hosts.
       // Secondary lookup (package subpaths and relative types) preserves this
       // spelling in resolvedFileName or a symlink's originalPath. Replaying a
-      // lowercased key falsely rejected unchanged programs in #1353. Restore
+      // lowercased key would falsely reject unchanged programs. Restore
       // the input context here; keep the strict result comparison below so
       // actual target, package and link changes still invalidate the program.
       containingDirectory := program.GetCurrentDirectory()
@@ -136,6 +190,20 @@ func programResolutionContext(program *Program, source ast.HasFileName) (module.
 
 // ReplayProgramResolutions resolves one source's tasks with one fresh upstream
 // resolver and reports whether every result still matches the resident Program.
+// Tasks must share compiler options, current directory and project-reference
+// context. An empty group, nil filesystem or missing options returns false.
+// Every supported task is submitted even after a mismatch; group-local caches
+// can satisfy equivalent lookups without repeating native reads. Equality is
+// over the projected result fields, not a complete filesystem snapshot proof.
+//
+// @evidence contracts/common.md#principled-implementation A fresh upstream resolver replays each kind with its original name, mode, lexical containing file and redirect, then compares the complete projected result including unresolved, package and symlink identity; tasks require one coherent originating context.
+// @evidence contracts/common.md#clear-and-simple-design One resolver and project-reference filesystem view belong to a group, while result projection centralizes equality and the loop continues submitting tasks after a mismatch instead of stopping at the first changed result.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Virtual declaration existence follows actual project-reference source mappings; unsupported resolver write operations panic rather than silently fabricating effects, and full result equality is not weakened to hide changed identities.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains coherent-group premises, invalid-input refusal and why replay continues after a mismatch, with separate descriptive and acknowledgment sections.
+// @evidence contracts/portability.md#os-neutral-implementation The supplied filesystem determines case sensitivity, existence and realpaths; the virtual declaration view uses canonical compiler paths and tracks native symlinks while preserving lexical resolver inputs.
+// @evidence contracts/performance.md#efficient-algorithms Each supported task makes one resolver call and compares projected string/scalar fields, with group-local caches sharing eligible lookups. Actual resolver work includes ancestor/package probing, manifest bytes and path processing; tracing can bypass result-cache hits. Virtual declaration and known-link fallback scans can multiply directory/link population across existence queries, with native source-existence and realpath work in addition to map membership.
+// @evidence contracts/performance.md#reuse-equivalent-work One fresh resolver and cached virtual filesystem share equivalent lookups within a coherent group; a new replay filesystem prevents prior observation results from hiding changed native inputs.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Fresh resolver and optional virtual/cached filesystem state retain entries, manifest buffers, projected results and known links for the synchronous group. This adapter keeps no historical registry or spawned task after return, making otherwise-unreferenced local state eligible for collection without promising immediate reclamation. Borrowed task/config graphs and observations retained by the supplied filesystem stay under their owners, with no fixed population or byte cap imposed here.
 func ReplayProgramResolutions(tasks []ProgramResolutionTask, filesystem vfs.FS) bool {
   if len(tasks) == 0 || filesystem == nil || tasks[0].compilerOptions == nil {
     return false
@@ -392,6 +460,21 @@ func (fs *projectReferenceResolutionFS) directoryExistsIfProjectReferenceDeclara
 
 // ReplayAutomaticTypeDirectiveDiscovery repeats the compiler's exact wildcard
 // type-root enumeration over filesystem so a host can observe its inputs.
+// Nil program, filesystem or compiler options performs no discovery.
+// Explicit non-wildcard types can return without filesystem enumeration.
+// Wildcard discovery also reads package manifests to omit typings-null packages;
+// this function discards the returned names, not filesystem observation state.
+// Default wildcard roots require a config path or nonempty resident cwd, as
+// required by the upstream effective-root helper.
+//
+// @evidence contracts/common.md#principled-implementation The compiler's automatic-type directive enumeration receives the resident options and current directory over the observation filesystem, reproducing wildcard discovery inputs rather than inferring them from only previously resolved targets.
+// @evidence contracts/common.md#clear-and-simple-design A minimal resolution host exposes filesystem and cwd directly to the owning discovery helper; enumeration results need not be retained because observation is the required effect.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Replay preserves real enumeration effects through a supported host instead of injecting assumed type-package names or patching the compiler's cache.
+// @evidence contracts/common.md#meaningful-documentation Native prose states wildcard discovery's observation purpose and nil-input no-op behavior, with separate tags.
+// @evidence contracts/portability.md#os-neutral-implementation Discovery obtains directories and entries from the caller's filesystem and resident cwd through the compiler host, without inferring type-root availability or casing from the OS.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream owns effective-root construction, directory enumeration, package-manifest reads/parsing, wildcard substitution and name deduplication. Costs include ancestor/path text, entries, manifest bytes and selected type-name population; this direct adapter chooses no separate discovery algorithm and discards only the returned names.
+// @evidence contracts/performance.md#reuse-equivalent-work Enumeration itself is the input-observation effect, so a resident list cannot replace traversal on a new filesystem observation; callers may share the resulting observation proof only when its filesystem snapshot is equivalent.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream discovery can allocate root/name lists, package buffers and parsed manifest state during the synchronous call. The result is discarded here, while compiler options and any filesystem caches or collected observation entries remain under their existing owners. This adapter keeps no independent historical name registry or running task and imposes no bound on caller-owned observation retention.
 func ReplayAutomaticTypeDirectiveDiscovery(program *Program, filesystem vfs.FS) {
   if program == nil || filesystem == nil || program.Options() == nil {
     return

package/shim-vendor/shim/core/enums_gen.go

@@ -2,8 +2,8 @@
 //
 // Completes every exposed enum family: re-exports each member not already
 // re-exported elsewhere in the shim package, so a plugin that can name the
-// enum type can name all of its values. Prevents the #230 class (a sibling
-// const silently missing). Regenerate after a typescript-go bump with
+// enum type can name all of its values. Prevents a partially re-exported
+// family (a sibling const silently missing). Regenerate after a typescript-go bump with
 // `pnpm --filter ttsc shim:audit -fix`.
 
 package core