ttsc 0.30.4 → 0.31.0

package/driver/session.go

@@ -4,22 +4,35 @@ import (
   "context"
 
   shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+  "github.com/samchon/ttsc/packages/ttsc/internal/e2etrace"
 )
 
 // Session is a resident compiler host for incremental type-checking: it keeps a
-// loaded program alive and re-parses only the changed file on each edit (reusing
-// the unchanged ASTs and refreshing the checker for the updated Program),
-// instead of recompiling the whole project per request.
+// loaded program alive across single-file edits. Native UpdateProgram either
+// builds a new generation reusing eligible old data or reconstructs the program;
+// its reused-data result does not mean the old Program object is returned.
 //
 // It is the driver-level incremental type-check primitive. The resident
 // transform path (utility-host `serve`) deliberately does not use it: the
 // linked-plugin pass mutates source ASTs in place, so a transform cannot reuse a
 // warm clean program and must rebuild a fresh one per edit. Session therefore
-// provides type-check reuse, not transform reuse (samchon/ttsc#255).
+// provides type-check reuse, not transform reuse.
 //
 // Construct one per project (cwd absolute), feed file edits through Apply, and
 // read the resident program's source through SourceText. Apply reuses the
-// existing program when the edited file's import/reference graph is unchanged.
+// old program data when native file/parse/reference compatibility and package
+// redirect checks permit it. Apply requires an existing resident member and
+// the native single-changed-file precondition; config or broader filesystem
+// changes require the caller's reload policy.
+//
+// @evidence contracts/common.md#principled-implementation A project anchor, overlay and Program represent one resident type-checking session; transformed mutable AST reuse is not its contract.
+// @evidence contracts/common.md#clear-and-simple-design The session groups incremental state while filesystem overrides and compiler operations keep their own owners.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Reuse uses TypeScript-Go UpdateProgram rather than a fixture cache or patched checker method.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish type-check reuse from transforms and state anchor and edit behavior under documentation-skill guidance.
+// @evidence contracts/portability.md#os-neutral-implementation The supplied absolute anchor and overlay use native lexical compiler paths and reported case policy; this representation performs no independent directory capability or physical-alias probe.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This type groups resident state; NewSession and Apply choose its processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The representation does not independently decide whether an edit can reuse a Program.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Resource acquisition and lease release belong to the session's constructor, Apply and Close operations.
 type Session struct {
   cwd     string
   overlay *OverlayFS
@@ -28,6 +41,17 @@ type Session struct {
 
 // NewSession loads the project over an overlay filesystem and keeps the
 // resulting program resident. cwd must be absolute; tsconfig may be relative.
+// The session installs its own DefaultFS overlay, replacing options.FS. A
+// failed or absent program load returns no Session, with the load diagnostics.
+//
+// @evidence contracts/common.md#principled-implementation Loading over the same overlay retained by the session lets subsequent edits reach the compiler's filesystem.
+// @evidence contracts/common.md#clear-and-simple-design Construction creates one overlay and delegates config and checker setup to LoadProgram.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A failed load returns diagnostics instead of manufacturing an empty resident Program.
+// @evidence contracts/common.md#meaningful-documentation Native prose states resident ownership and absolute-cwd precondition following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation DefaultFS supplies native capabilities and the overlay uses that case policy without OS-name inference.
+// @evidence contracts/performance.md#efficient-algorithms Construction adds a fresh native metadata-cache/overlay and delegates config parsing, input discovery, full program construction and checker setup. Config/source/path bytes and reached native entries drive loading work and retained state; delegation does not make compilation constant-cost.
+// @evidence contracts/performance.md#reuse-equivalent-work One loaded Program serves later session edits; updates use its existing compiler state instead of loading on every request.
+// @evidence contracts/performance.md#bound-retention-and-release-resources A successful session owns the current checker lease and retains its Program, native filesystem caches and overlay. Program data, metadata and distinct overridden text have no session-wide byte/population cap. Close releases the checker lease; dropping caller ownership allows remaining state to be reclaimed only when other aliases no longer retain it.
 func NewSession(cwd, tsconfig string, options LoadProgramOptions) (*Session, []Diagnostic, error) {
   overlay := NewOverlayFS(DefaultFS())
   options.FS = overlay
@@ -42,9 +66,20 @@ func NewSession(cwd, tsconfig string, options LoadProgramOptions) (*Session, []D
 }
 
 // Apply sets the in-memory content of one file and incrementally updates the
-// resident program. It returns whether the update reused the existing program
-// (true) or had to rebuild it because the file's import/reference graph changed
-// (false).
+// resident program. absPath must identify an existing resident member, and the
+// caller must satisfy native UpdateProgram's single-changed-file precondition.
+// True means the new generation reused old program data; false selects full
+// reconstruction. Native parse/reference/package-redirect checks decide this,
+// not import graph equality alone. The driver facade itself remains stable.
+//
+// @evidence contracts/common.md#principled-implementation The edited overlay is installed before UpdateProgram; a returned replacement checker and host replace the corresponding facade fields together.
+// @evidence contracts/common.md#clear-and-simple-design One operation owns buffer update, incremental compiler update and checker-lease replacement.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The compiler's update result determines reuse, with no filename-specific bypass or invented success.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains true and false reuse results following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Resident member spelling, supplied cwd and captured overlay case policy feed native ToPath; these are lexical compiler keys, not independent physical-alias or directory capability proofs.
+// @evidence contracts/performance.md#efficient-algorithms Overlay/key setup processes path bytes; SourceFile may run pending linked hooks before indexed lookup. Native update reads/parses the edited member and either clones file collections and initializes a new checker pool while sharing eligible data, or performs full reconstruction. File/reference/source populations and native host work therefore remain costs even on a reused-data result.
+// @evidence contracts/performance.md#reuse-equivalent-work Under the caller's existing-member/single-change contract, native parse options, import/reference/augmentation/ambient-name compatibility and package-redirect checks determine data reuse. Every successful result is a new Program generation; transformed mutable AST reuse is not supported by this type-check session contract.
+// @evidence contracts/performance.md#bound-retention-and-release-resources A returned replacement releases the old checker lease before acquiring/installing the new checker and host. Current native data and uncapped overlay text remain session-owned, with earlier generation data possibly shared or retained by other aliases; lease replacement does not bound bytes or reclaim all old state. Close and caller ownership govern later release.
 func (s *Session) Apply(absPath, content string) bool {
   s.overlay.Set(absPath, content)
   name := absPath
@@ -55,6 +90,7 @@ func (s *Session) Apply(absPath, content string) bool {
   newHost := DefaultHost(s.cwd, s.prog.FS)
   newProg, reused := s.prog.TSProgram.UpdateProgram(changed, newHost, nil)
   if newProg != nil {
+    e2etrace.Program("program-construction", "driver-update", "constructor-returned", reused, newProg)
     if s.prog.checkerRelease != nil {
       s.prog.checkerRelease()
     }
@@ -63,19 +99,41 @@ func (s *Session) Apply(absPath, content string) bool {
     s.prog.Checker = checker
     s.prog.checkerRelease = release
     s.prog.Host = newHost
+    e2etrace.Program("program-load-outcome", "driver-update", "facade-installed", reused, newProg)
   }
   return reused
 }
 
-// Program returns the resident program, reflecting every Apply so far. The
-// handle changes when an edit reshapes the import graph, so callers should read
-// it after Apply rather than caching it across edits.
+// Program returns the resident driver facade, reflecting every Apply so far.
+// Apply can replace its TSProgram, Checker, and Host; callers must not retain
+// those generation-specific fields across edits.
+//
+// @evidence contracts/common.md#principled-implementation The current facade pointer exposes the compiler state installed by the latest Apply.
+// @evidence contracts/common.md#clear-and-simple-design This accessor introduces no second Program copy or ownership wrapper.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor returns actual resident state without a stale-result fallback.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the stable facade from replaceable generation-specific fields under documentation-skill guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Returning an existing Program pointer performs no native filesystem or process boundary operation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This accessor performs no algorithm choice or input-dependent computation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Retrieval does not establish whether resident compiler work remains valid.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This borrowed handle accessor acquires or releases no owned resource.
 func (s *Session) Program() *Program {
   return s.prog
 }
 
 // SourceText returns the source text the resident program currently holds for
 // absPath, or ("", false) when the program has no such file.
+// The delegated SourceFile lookup may first run pending linked hooks; their
+// latched failure is not returned by this text accessor. Text is the resident
+// parsed version, including any source-level preamble, not a new disk receipt.
+//
+// @evidence contracts/common.md#principled-implementation Lookup returns the resident source's text, distinguishing a missing file from empty content with the boolean.
+// @evidence contracts/common.md#clear-and-simple-design Source text retrieval delegates identity lookup to Program.SourceFile rather than duplicating it.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No disk reread is substituted for the resident source version.
+// @evidence contracts/common.md#meaningful-documentation Native prose states resident-version and missing-file behavior following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Path lookup uses the driver Program's normalized source-file spelling; no native capability is inferred from OS names.
+// @evidence contracts/performance.md#efficient-algorithms Program.SourceFile adds path normalization/hash work and indexed lookup, plus any first pending linked-hook execution and its delegated source/native costs. Once hooks are latched this accessor introduces no separate reread or parse; it returns the resident text string without copying its bytes.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This accessor reads state already owned by the session and does not coordinate compilation requests.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returning a string reference does not create a session-owned historical buffer or checker lease.
 func (s *Session) SourceText(absPath string) (string, bool) {
   file := s.prog.SourceFile(absPath)
   if file == nil {
@@ -84,7 +142,17 @@ func (s *Session) SourceText(absPath string) (string, bool) {
   return file.Text(), true
 }
 
-// Close releases the resident program's resources.
+// Close releases the current Program's checker lease. It does not clear the
+// resident Program or overlay, dispose all native data, or forbid later calls.
+//
+// @evidence contracts/common.md#principled-implementation Closing the current Program releases its checker lease; an absent Program has no lease to release.
+// @evidence contracts/common.md#clear-and-simple-design Session cleanup delegates lease ownership to Program.Close without a second release ledger.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Cleanup uses the recorded release callback rather than suppressing a compiler failure or guessing an upstream handle.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies cleanup responsibility following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This cleanup delegates an in-process checker lease and crosses no native path or process boundary.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Cleanup contains no input-dependent algorithm or data-structure choice.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Lease release does not decide equivalence of compilation requests.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Sequential repeated Close is safe through Program.Close's cleared lease-release callback. The Session still retains its Program, FS/cache and overlay; caller ownership and other aliases govern their later reclamation, with no cleared-buffer or full native-disposal promise from this method.
 func (s *Session) Close() error {
   if s.prog != nil {
     return s.prog.Close()

package/driver/sourcemap_preamble.go

@@ -35,17 +35,28 @@ const inlineSourceMapMarker = "//# sourceMappingURL=data:application/json;base64
 // output with `inlineSourceMap` carries it base64-embedded in a
 // `//# sourceMappingURL=data:...` trailer. Non-map, non-JS/declaration outputs
 // (e.g. `.tsbuildinfo`) are never scanned. Returns (text, false) when there is
-// nothing to correct (no preamble, no map, or unparseable).
+// nothing to correct or the required JSON/base64 fields cannot be decoded.
+// This is a compatibility transformer, not a complete source-map validator.
+// Inline handling selects the last literal marker on an admitted carrier; it
+// does not parse JavaScript to prove that marker belongs to a trailing comment.
 //
-// This is the single entry point every map-emitting path funnels through so the
-// preamble correction is applied uniformly — the utility host's WriteFile (tsgo
-// native emit) and the driver's plugin-transform emit (EmitWithPluginTransformers,
-// e.g. typia + @ttsc/banner) both call it, external and inline alike.
+// This compatibility helper only knows a leading-line offset. Native emit
+// callers use Program.NewSourceMapCorrector, which has the generation's exact
+// preamble regions and source directory policy.
 //
 // NOTE: this is NOT idempotent — applying it twice shifts source lines up by
 // dropLines twice. Each emit path must call it exactly once per file; a writeFile
 // passed to an emit path that already self-corrects (EmitWithPluginTransformers)
 // must not call it again.
+//
+// @evidence contracts/common.md#principled-implementation Filename suffix selects external-map or inline-map correction under the caller's leading-line offset contract. Absent markers and failed required JSON/base64 decoding leave input unchanged; full mapping validity and source eligibility are not independently certified.
+// @evidence contracts/common.md#clear-and-simple-design One suffix dispatch delegates JSON mapping changes to AdjustSourceMapForPreamble.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Map carriers use supported output extensions and the declared inline trailer rather than fixture filenames or guessed output positions.
+// @evidence contracts/common.md#meaningful-documentation Native prose states carrier behavior, unchanged-result conditions, and one-time use following the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms Filename case conversion scans path text; an inline carrier adds a last-marker scan, base64 decoding/encoding and output reconstruction. Delegated JSON, source/content and VLQ processing scale with map and embedded-source bytes; unsupported suffixes avoid scanning output text.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This function owns no shared cache or delivery coordinator; callers must enforce the documented one-time correction, which this operation does not independently track.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Temporary decoding buffers are local and no resident collection or resource is retained.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation AdjustEmittedSourceMap computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func AdjustEmittedSourceMap(fileName, text string, dropLines int) (string, bool) {
   if dropLines <= 0 {
     return text, false
@@ -110,23 +121,34 @@ func adjustInlineSourceMap(text string, dropLines int) (string, bool) {
 // every mapping for real code lands `dropLines` lines too far down (on blank or
 // nonexistent lines), so a debugger jumps to the wrong place.
 //
-// This rewrites the map's `mappings` to undo that shift, per source: a segment is
-// only adjusted when its source file (`sources[sourceIndex]`) is one the preamble
-// was injected into (`isSourcePreambleTarget`) — so a mixed map (e.g. a bundled
-// `.js`/`.json` map under `outFile`) leaves `.json` segments alone. For an
+// This rewrites the map's `mappings` using a filename-suffix source mask. With
+// a decoded sources array and an in-range source index, non-target suffixes
+// remain unshifted, so a mixed `.js`/`.json` map leaves `.json` segments alone.
+// Missing or undecodable sources, and out-of-range mapping indices, default to
+// adjustment rather than independently proving which files received a preamble.
+// Callers must supply valid maps and the appropriate leading-line contract. For an
 // adjusted source, segments inside the preamble region (source line < dropLines)
 // are dropped — those generated lines are the emitted preamble comment, which has
 // no real-source counterpart and is left unmapped — and every remaining segment's
 // source line is moved up by dropLines so it points at the real file. The
 // generated side is untouched.
 //
-// dropLines is the number of newlines the preamble adds (strings.Count(preamble,
-// "\n")). The drop region assumes the preamble occupies the leading source lines
-// [0, dropLines); for a hashbang file ApplySourcePreamble inserts the preamble
-// after the shebang line, so the region is nominally off by one — but shebang and
-// preamble-comment lines never carry node mappings, so real-code correction is
-// unaffected. Returns (rewritten, true) on success, or (input, false) when there
-// is nothing to do or the map cannot be parsed (the caller then writes it as-is).
+// dropLines is the count of complete leading source lines to remove. This API
+// assumes the injected region is [0, dropLines); it cannot describe BOM,
+// hashbang, or partial-line insertion. Use Program.NewSourceMapCorrector for
+// emitted artifacts or Program.AuthoredSourceMap for a syntactic printer map.
+// Returns (rewritten, true) when changed, or (input, false) when there is nothing
+// to do or required JSON fields cannot be decoded. Mapping segments are handled
+// permissively; the result does not certify complete source-map validity.
+//
+// @evidence contracts/common.md#principled-implementation The line-only API removes leading injected source lines and recomputes source-map deltas while preserving generated-column-only segments; exact BOM/hashbang/same-line placement requires the Program.AuthoredSourceMap boundary instead.
+// @evidence contracts/common.md#clear-and-simple-design JSON extraction, source eligibility, segment shifting, and embedded-content trimming are separate helpers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Delta accumulators track decoded source positions even for dropped mappings, avoiding a constant encoded-delta patch that corrupts later segments.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state leading-line limitations, exact-correction alternatives, and single-application behavior following the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms JSON decoding/serialization scans map bytes; mapping line/segment splits and VLQ decoding/encoding process mapping text, while source masks scan filename bytes and optional content trimming processes embedded-source text. These invocation-local arrays and output buffers scale with those inputs; one segment pass maintains separate input/output delta accumulators instead of rescanning earlier segments.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A map correction owns no cross-request cache or shared computation coordinator.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Decoded JSON and segment buffers are invocation-local without a retained cache or external handle.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation AdjustSourceMapForPreamble computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func AdjustSourceMapForPreamble(mapText string, dropLines int) (string, bool) {
   if dropLines <= 0 || strings.TrimSpace(mapText) == "" {
     return mapText, false

package/driver/transform_dependencies.go

@@ -9,16 +9,29 @@ import (
 // the per-file input lists a producer reports and the subset of files whose
 // list is complete.
 //
-// A producer that declares nothing leaves both fields empty, so its envelope is
-// byte-identical to what it was before this existed. The lane with no linked
-// plugin at all is the deliberate exception: nothing there can contribute to a
-// file, so every file is listed.
+// A producer that declares nothing leaves both fields empty, so its envelope
+// carries neither. The lane with no linked
+// contributor at all is the deliberate exception: the completeness test has
+// no contributor declarations to require, so every transformed file is listed.
+// This side channel does not independently certify resolver, host or plugin
+// source inputs reported through other envelope fields.
+//
+// @evidence contracts/common.md#principled-implementation Reported dependencies and explicit completeness are distinct; an empty contributor set is complete without pretending silent contributors proved anything.
+// @evidence contracts/common.md#clear-and-simple-design One per-file adjacency map and one complete-file list carry separate facts.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing declarations remain incomplete rather than becoming complete because a transform succeeded.
+// @evidence contracts/common.md#meaningful-documentation Native field prose defines completeness, input scope, and the no-contributor case following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Dependencies and Complete use producer cwd-relative slash keys, with slash-normalized absolute coordinates outside cwd or across volumes. These protocol spellings do not certify physical identity or native case policy; native conversion belongs to TransformOutputKey, while this type preserves the reported dependency coordinate system.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Aggregation owns traversal; this type is the result schema.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The schema does not coordinate cached transform work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned value owns no resident cache or external resource.
 type TransformDependencies struct {
-  // Complete lists the files whose Dependencies entry is the whole input set
-  // beyond the file itself and the universal compiler-option chain.
+  // Complete lists files declared by every applicable preamble/program
+  // contributor (including the empty-contributor case), not independent proof
+  // that no resolver, host or plugin-source input remains.
   Complete []string
-  // Dependencies maps a transformed file to the files whose content influenced
-  // its output, keyed and valued like every other envelope section.
+
+  // Dependencies maps a transformed file to contributor-reported inputs,
+  // keyed and valued like every other envelope section.
   Dependencies map[string][]string
 }
 
@@ -48,14 +61,28 @@ type TransformDependencies struct {
 // With no linked plugin at all the contributor set is empty and every file is
 // complete with an empty list, which is the rule above stated for the lane that
 // has nothing but the host in it. A contributor that declares nothing leaves
-// every file unlisted, which is exactly the behaviour of every producer written
-// before this existed.
+// every file unlisted, the same as a producer that predates the declaration.
 //
 // An embedder that supplies LoadProgramOptions.SourcePreamble itself, rather
 // than obtaining it from a linked plugin, makes the same claim about that text
 // by calling this: the preamble must be a function of inputs its envelope
 // reports elsewhere, the way a plugin's preamble is a function of the config
 // files it reports as host inputs.
+//
+// This call can apply linked program hooks for the first time; later calls
+// reuse the latched outcome but recompute dependency aggregation. It ignores
+// the hook error locally, so callers must separately admit successful output.
+// Completeness records contributor declarations, not independently verified
+// coverage of arbitrary plugin reads or an atomic declaration snapshot.
+//
+// @evidence contracts/common.md#principled-implementation Syntactic host output excludes type-driven emit lowering; completeness requires every actual preamble/program contributor to declare its own consumed inputs.
+// @evidence contracts/common.md#clear-and-simple-design The method enumerates transformed-file keys then delegates contributor classification and declaration folding to their owners.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A silent contributor remains incomplete; emit-only plugins are excluded because this envelope lane does not execute their transforms.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain syntactic output, contributors, and the embedder's preamble responsibility following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation All file keys pass through TransformOutputKey with the supplied project cwd instead of native-separator assumptions.
+// @evidence contracts/performance.md#efficient-algorithms Source filtering/key conversion visits resident files and path text. Contributor classification visits registered entries; each transformed file visits applicable contributors, copies their reported dependency lists under locks, hashes/deduplicates input strings and sorts final distinct lists/completeness keys. Initial hook work can be arbitrary; repeated aggregation is not memoized or bounded by a configured work/byte ceiling.
+// @evidence contracts/performance.md#reuse-equivalent-work First use can execute linked program hooks, whose success/error is latched for the current Program generation; subsequent calls do not rerun them. Recorded declarations are read again to derive current per-file completeness, while key conversion and aggregation repeat. No equivalence across changed Program generations is established here.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Temporary keys, per-file input sets and copied declaration lists grow with sources/contributors/dependency path bytes; result maps/arrays transfer to the caller. Linked hooks/declarations and their latched outcome remain with the caller-owned Program, without a separate historical result cache in this method. No dependency population/byte cap or caller-result disposal policy is supplied.
 func (p *Program) TransformDependenciesFor(cwd string) TransformDependencies {
   if p == nil {
     return TransformDependencies{}
@@ -166,6 +193,7 @@ type pluginFileDeclaration struct {
   completeAll  bool
   dependencies map[string]map[string]struct{}
   mu           sync.Mutex
+
   // rejected holds the files whose reported list this plugin could not state
   // in full, because one of its members was unusable as a key.
   rejected map[string]struct{}

package/driver/transform_dependencies_declares_every_file_without_a_contributor_test.go

@@ -5,15 +5,16 @@ import (
   "testing"
 )
 
-// TestTransformDependenciesDeclaresEveryFileWithoutAContributor verifies the
-// rule the host declares under when nothing else can contribute: a
-// source-to-source transform is syntactic, so a file the host alone produced
-// depends on its own text and the compiler options, and on nothing else.
+// TestTransformDependenciesDeclaresEveryFileWithoutAContributor supplies two
+// file keys and no contributors directly to the aggregation operation. Both
+// keys are declared complete and the dependency map remains nil. This checks
+// the empty-contributor rule, not host output, plugin classification, or a
+// consumer's decision to stop revalidating a reference closure.
 //
-// With an empty contributor set the aggregation is vacuously satisfied for
-// every file, which is what lets a plugin-free project's consumer stop
-// revalidating each delivered module's whole reference closure
-// (samchon/ttsc#1259).
+// @evidence contracts/testing.md#behavioral-verification aggregateTransformDependencies with no contributors returns both supplied keys as complete and a nil dependency map.
+// @evidence contracts/testing.md#independent-expectations The expected complete list and nil dependency map are literals.
+// @evidence contracts/testing.md#distinguishing-cases The empty contributor set is the vacuous case, contrasted with the contributor cases in sibling tests.
+// @evidence contracts/testing.md#execution-ownership This driver Go unit calls the unexported aggregation with two literal keys and an empty declaration ledger. It uses no filesystem fixture, consumer installation, compiler Program, or product process.
 func TestTransformDependenciesDeclaresEveryFileWithoutAContributor(t *testing.T) {
   keys := []string{"src/main.ts", "src/types.ts"}
 

package/driver/transform_dependencies_drops_a_self_reported_dependency_test.go

@@ -2,13 +2,14 @@ package driver
 
 import "testing"
 
-// TestTransformDependenciesDropsASelfReportedDependency verifies a file never
-// enters its own dependency list.
+// TestTransformDependenciesDropsASelfReportedDependency supplies one self-edge
+// to the declaration ledger and checks that aggregation emits no dependency
+// entry. It does not execute a consumer's text comparison or watch registration.
 //
-// The file's own text sits outside the completeness contract by construction —
-// every consumer compares it before anything else — so a self-edge would only
-// make a bundler register the module it is already transforming as one of that
-// module's watch inputs.
+// @evidence contracts/testing.md#behavioral-verification A file reported as its own dependency does not appear in the dependency list.
+// @evidence contracts/testing.md#independent-expectations The literal zero-entry expectation follows from the side-channel rule that a file's own text is not an additional dependency.
+// @evidence contracts/testing.md#distinguishing-cases A self-edge is the only input; other edges are covered by sibling tests.
+// @evidence contracts/testing.md#execution-ownership This driver Go unit records one literal self-edge and calls the unexported aggregation in-process. It uses no filesystem fixture, consumer installation, compiler Program, or product process.
 func TestTransformDependenciesDropsASelfReportedDependency(t *testing.T) {
   declarations := newPluginFileDeclarations()
   declarations.forPlugin(0).addDependency("src/main.ts", "src/main.ts")

package/driver/transform_dependencies_keys_a_reported_path_like_the_envelope_test.go

@@ -6,16 +6,16 @@ import (
   "testing"
 )
 
-// TestTransformDependenciesKeysAReportedPathLikeTheEnvelope verifies a plugin's
-// reported paths reach the envelope under the same key convention as every other
-// section.
+// TestTransformDependenciesKeysAReportedPathLikeTheEnvelope reports a source
+// dependency through an absolute slash spelling and completeness through an
+// absolute native spelling. The cwd-relative dependency is emitted under the
+// two expected project-relative keys. A blank source report contributes nothing
+// to these asserted entries. No compiler output or consumer join is exercised.
 //
-// A plugin reports the spellings its host handed it — absolute program file
-// names, which the compiler normalizes to forward slashes on every platform, or
-// paths relative to the plugin's cwd. Keying either differently from
-// `typescript` would leave a consumer unable to join the sections at all, and on
-// Windows the two spellings differ by separator alone, which is exactly the kind
-// of mismatch that passes on POSIX CI and fails on a developer's machine.
+// @evidence contracts/testing.md#behavioral-verification PluginContext reporting normalizes the supplied source and dependency spellings before aggregation returns the literal src/main.ts completeness and src/consulted.d.ts dependency entries.
+// @evidence contracts/testing.md#independent-expectations The expected keys are literal project-relative slash paths built from a real temporary directory.
+// @evidence contracts/testing.md#distinguishing-cases Absolute slash/native source spellings meet the same expected key; a different dependency uses a cwd-relative spelling. The blank source report leaves these expected entries unchanged. The test does not compare absolute and relative spellings of the same file.
+// @evidence contracts/testing.md#execution-ownership This driver Go unit supplies callbacks backed by its own declaration ledger to PluginContext and calls aggregation. A real temporary root establishes native absolute paths; no files, compiler Program, consumer, or child process are created.
 func TestTransformDependenciesKeysAReportedPathLikeTheEnvelope(t *testing.T) {
   // A real directory, so the absolute spellings below are absolute under the
   // running platform's own rule rather than under POSIX's alone.

package/driver/transform_dependencies_requires_every_contributor_to_declare_test.go

@@ -6,13 +6,18 @@ import (
 )
 
 // TestTransformDependenciesRequiresEveryContributorToDeclare verifies the
-// aggregation rule over a composed plugin set: a file is complete only when
-// every contributing plugin declared it, because a consumer cannot attribute
-// one plugin's reported inputs back to it.
+// aggregation rule for two supplied contributor indexes: one per-file claim
+// leaves the file incomplete, while the second contributor's all-file claim
+// admits the literal key to the complete list.
 //
 // It also pins that reporting and declaring are separate acts: a plugin's
-// dependency list widens what consumers invalidate on even while the file
-// itself stays unlisted (samchon/ttsc#1263).
+// dependency remains in the aggregate even while the file stays unlisted as
+// complete. Consumer invalidation and plugin classification are not exercised.
+//
+// @evidence contracts/testing.md#behavioral-verification With two supplied contributors, the aggregate preserves the reported dependency while one contributor is silent, then lists the file complete after that contributor declares every file complete.
+// @evidence contracts/testing.md#independent-expectations The partial dependency and final completeness expectations are literal lists for the two authored contributor states; the final dependency list is not separately asserted.
+// @evidence contracts/testing.md#distinguishing-cases One declaring plugin alone and then both declaring contrast, so the silent contributor blocks the claim.
+// @evidence contracts/testing.md#execution-ownership This driver Go unit mutates its own declaration ledger and calls aggregation directly. It uses no filesystem fixture, compiler Program, consumer installation, or child process.
 func TestTransformDependenciesRequiresEveryContributorToDeclare(t *testing.T) {
   declarations := newPluginFileDeclarations()
   first := declarations.forPlugin(0)

package/driver/transform_dependencies_stays_silent_for_an_undeclared_contributor_test.go

@@ -3,13 +3,15 @@ package driver
 import "testing"
 
 // TestTransformDependenciesStaysSilentForAnUndeclaredContributor verifies that
-// a plugin able to change transform output blocks every completeness claim
-// until it makes one itself.
+// one supplied contributor index without a declaration leaves the supplied
+// file key out of the complete list. It exercises the conservative aggregation
+// rule, not historical producer behavior, plugin classification, or a consumer's
+// invalidation bound.
 //
-// This is the compatibility half of the contract: every producer written before
-// the declaration existed keeps the host-owned bound exactly, and a plugin whose
-// output depends on the type graph cannot have that bound narrowed on its
-// behalf (samchon/ttsc#1263).
+// @evidence contracts/testing.md#behavioral-verification A contributor that never declares leaves the file out of the complete list.
+// @evidence contracts/testing.md#independent-expectations The literal zero-length expectation follows from requiring an explicit completeness declaration from the supplied contributor.
+// @evidence contracts/testing.md#distinguishing-cases The undeclared contributor is the negative neighbor of the declared contributor in sibling tests.
+// @evidence contracts/testing.md#execution-ownership This driver Go unit calls aggregation with literal inputs and its own empty ledger. It uses no filesystem fixture, compiler Program, consumer installation, or child process.
 func TestTransformDependenciesStaysSilentForAnUndeclaredContributor(t *testing.T) {
   out := aggregateTransformDependencies(
     []string{"src/main.ts"},

package/driver/transform_dependencies_withdraws_completeness_after_an_unusable_dependency_test.go

@@ -6,11 +6,15 @@ import "testing"
 // verifies a dependency the host could not key withdraws the claim it belonged
 // to, instead of leaving a complete list with a member missing from it.
 //
-// A plugin whose own lookup answered nothing for one input is the case: it
-// reports what it has and declares the file complete, and a host that dropped
-// the unusable member would publish exactly the under-declaration the protocol
-// blames on the plugin — manufactured by the host. Only the affected file loses
-// the claim; the plugin's other files keep theirs.
+// The authored context first declares every file complete, then reports an
+// empty dependency for src/main.ts. The returned complete list keeps only
+// src/other.ts, which received no dependency report. No plugin lookup failure,
+// consumer protocol, or successful dependency entry is exercised.
+//
+// @evidence contracts/testing.md#behavioral-verification A dependency the host could not key withdraws the completeness claim of that file only; the plugin's other files keep theirs.
+// @evidence contracts/testing.md#independent-expectations The expected complete lists are literal file keys for the affected and unaffected files.
+// @evidence contracts/testing.md#distinguishing-cases An empty dependency withdraws one file's prior all-file claim; the other file has no dependency report and remains complete.
+// @evidence contracts/testing.md#execution-ownership This driver Go unit connects PluginContext reporting to its own declaration ledger and aggregates two literal keys. A temporary root supplies native path context; no files, compiler Program, installed consumer, or child process are created.
 func TestTransformDependenciesWithdrawsCompletenessAfterAnUnusableDependency(t *testing.T) {
   cwd := t.TempDir()
   declarations := newPluginFileDeclarations()