ttsc 0.30.3 → 0.31.0

package/internal/lspserver/lsp_server.go

@@ -5,11 +5,14 @@ import (
   "errors"
   "fmt"
   "io"
+  "os"
   "os/exec"
   "path/filepath"
   "runtime/debug"
   "sync"
   "time"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/e2etrace"
 )
 
 // ErrLSPUpstreamPanic wraps a panic recovered from inside an upstream
@@ -22,11 +25,20 @@ var ErrLSPUpstreamPanic = errors.New("ttscserver: tsgo upstream runner panicked"
 // upstream runner seam; the recovered stack is attached for diagnostics.
 //
 // recover() per the Go spec catches panics but NOT runtime.Goexit, so
-// a Goexit raised from inside fn surfaces as a clean nil return here
-// (the upstream goroutine exits without an error). Hosting code that
+// a Goexit raised from inside fn runs deferred cleanup and exits its goroutine
+// without returning from this helper. Hosting code that
 // must turn Goexit into a typed error should run fn in a separate
 // goroutine and join on a sentinel channel — outside this helper's
 // scope today.
+//
+// @evidence contracts/common.md#principled-implementation Deferred recovery assigns the named error return, wrapping ErrLSPUpstreamPanic and formatting the recovered value plus current goroutine stack. The panic value is textual context, not a wrapped error identity; runtime.Goexit remains a nonreturning goroutine exit.
+// @evidence contracts/common.md#clear-and-simple-design The helper contains panic conversion while invocation-specific runner ownership stays outside it.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Panic is surfaced through a typed error rather than discarded as a successful upstream run.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish panic recovery from Goexit, following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Panic recovery is a Go runtime boundary, not a native filesystem or process representation.
+// @evidence contracts/performance.md#efficient-algorithms Normal completion invokes the callback once with fixed recovery setup. Panic conversion formats its value and captures the stack through debug.Stack, which doubles its buffer until runtime.Stack fits; stack depth, formatted bytes and any custom formatting method add input-dependent work. Callback execution has no deadline here.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each callback invocation may have distinct effects and is not shared here.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The runner owner controls goroutines and native children; this helper does not acquire them.
 func RecoverPanicAs(fn func() error) (err error) {
   defer func() {
     if r := recover(); r != nil {
@@ -38,16 +50,28 @@ func RecoverPanicAs(fn func() error) (err error) {
 
 // LSPServerOptions wires ttscserver to its three channels of state:
 // editor stdio for the LSP transport, an optional ttsc PluginSource for
-// merging plugin diagnostics into the stream, and the tsgo binary that
-// provides the upstream LSP server.
+// local contributions, and an upstream runner. The default upstream is the
+// selected tsgo executable; an embedding can supply its own runner/validator.
+//
+// @evidence contracts/common.md#principled-implementation Editor transport, plugin source and invocation-scoped upstream dependency pair distinguish owned local contributions from external compiler service.
+// @evidence contracts/common.md#clear-and-simple-design One invocation value supplies streams, project context and supported advertisement policy without global runner replacement.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Custom runner/validator injection uses a supported seam rather than monkey patching process globals.
+// @evidence contracts/common.md#meaningful-documentation Native member prose documents nil meaning, stream closure, ignored compatibility settings and dependency-pair validation, with documentation-skill spacing.
+// @evidence contracts/portability.md#os-neutral-implementation Native Cwd and absolute executable paths remain separate from io transport and protocol identifiers; runner implementations own platform execution.
+// @evidenceExclude contracts/performance.md#efficient-algorithms RunLSPServer owns processing strategy rather than this options value.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The options do not coordinate sharing across sessions.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The serving operation acquires pipes and tasks; options only provide their dependencies.
 type LSPServerOptions struct {
   // In is the editor-side reader; ttscserver reads JSON-RPC frames from
-  // it and forwards or handles them. RunLSPServer closes it on shutdown
-  // if it also implements io.Closer so blocked frame reads can unblock.
+  // it and forwards or handles them. Shutdown attempts Close when supported,
+  // ignoring its error; whether that interrupts a blocked read belongs to the
+  // supplied stream's implementation.
   In io.Reader
+
   // Out is the editor-side writer; ttscserver writes both upstream
   // responses and locally-synthesized messages to it.
   Out io.Writer
+
   // Err is the upstream tsgo server's stderr sink. ttscserver does not
   // log to it directly.
   Err io.Writer
@@ -55,28 +79,38 @@ type LSPServerOptions struct {
   // Cwd is the project root used as the upstream tsgo process working
   // directory. An empty string is rejected before any process starts.
   Cwd string
-  // TsgoBinary is the absolute path to the project-selected
-  // native TypeScript (typescript) executable.
+
+  // TsgoBinary is the absolute path required by the default native runner.
+  // A custom runner/validator owns its own use and admission policy.
   TsgoBinary string
+
   // Source contributes ttsc plugin diagnostics / code actions /
   // executeCommand handling. Nil falls back to NullPluginSource{}.
   Source PluginSource
+
   // SymbolProvider answers textDocument/documentSymbol and
-  // textDocument/references locally from ttsc's compiler-backed code graph.
-  // Nil leaves those methods forwarded to upstream tsgo.
+  // textDocument/references from ttsc's compiler-backed code graph when
+  // upstream tsgo does not advertise the capability; RunLSPServer does not
+  // force local answers over an advertised one. Nil leaves those methods
+  // forwarded to upstream tsgo.
   SymbolProvider SymbolProvider
+
   // SuppressExecuteCommandProvider keeps ttsc command ids out of the
   // initialize response for clients that route wrapper commands themselves.
   SuppressExecuteCommandProvider bool
+
   // SuppressedExecuteCommandIDs filters specific ttsc command ids out of the
   // initialize response while leaving other plugin command ids registered.
   SuppressedExecuteCommandIDs []string
+
   // ExecuteCommandIDPrefix namespaces advertised executeCommand ids for hosts
   // that run multiple language clients in one global command registry.
   ExecuteCommandIDPrefix string
+
   // ProgressDelay is accepted for CLI compatibility. The external tsgo
   // LSP command does not currently expose a progress-delay flag.
   ProgressDelay time.Duration
+
   // Upstream binds one runner and its validation policy to this invocation.
   // The zero value selects the production tsgo process and validates
   // TsgoBinary. Embedders supplying a Runner may also supply a Validator;
@@ -85,6 +119,11 @@ type LSPServerOptions struct {
   Upstream LSPUpstream
 }
 
+// ErrLSPExitWithoutShutdown is returned when the editor ended the session with
+// the LSP `exit` notification without a `shutdown` request before it, which
+// the specification answers with exit status 1.
+var ErrLSPExitWithoutShutdown = errors.New("exit notification received before a shutdown request")
+
 // ErrLSPCwdRequired is returned when LSPServerOptions.Cwd is empty.
 // ttsc surfaces a clean error here instead of starting tsgo from an
 // undefined project directory.
@@ -98,19 +137,52 @@ var ErrLSPTsgoBinaryRequired = errors.New("ttscserver: tsgo binary is required")
 // custom upstream validator without the runner whose prerequisites it checks.
 var ErrLSPUpstreamRunnerRequired = errors.New("ttscserver: custom upstream validator requires a runner")
 
-// LSPUpstreamRunner is the seam tests use to substitute the external
-// tsgo process with a controllable fake.
+// LSPUpstreamRunner serves one invocation through the supplied input/output.
+// Embedders may provide an in-process runner; cancellation and completion belong
+// to that runner rather than a global process replacement.
+//
+// @evidence contracts/common.md#principled-implementation Context, streams and invocation options describe one upstream execution with an explicit error result.
+// @evidence contracts/common.md#clear-and-simple-design A function dependency permits hosted or native execution without another server implementation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Supported invocation injection replaces no foreign methods or global executable policy.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies embedding and cancellation responsibility, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The callable abstracts native process differences while the default runner uses executable and argv vectors.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The concrete runner owns its computation strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Invocation execution is not coordinated by this function type.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Concrete runners acquire and release their tasks and handles.
 type LSPUpstreamRunner func(ctx context.Context, in io.Reader, out io.Writer, opts LSPServerOptions) error
 
 // LSPUpstreamValidator checks one invocation's upstream prerequisites before
 // the proxy or runner goroutines start.
+//
+// @evidence contracts/common.md#principled-implementation A validation error prevents runner and proxy startup for the invocation whose prerequisites were checked.
+// @evidence contracts/common.md#clear-and-simple-design Validation is paired with its runner instead of applied as a global native assumption.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A custom runner may own custom prerequisites without bypassing another runner's required validation.
+// @evidence contracts/common.md#meaningful-documentation Native prose states validation occurs before goroutines start, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The validator can interpret its runner's native requirements rather than imposing an executable policy on in-process hosts.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This function type defines validation, not its algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The serving invocation owns validation coordination.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Implementations own any temporary prerequisite probes.
 type LSPUpstreamValidator func(opts LSPServerOptions) error
 
-// LSPUpstream is the immutable dependency pair captured by RunLSPServer for
+// LSPUpstream is the dependency pair copied by RunLSPServer for
 // one invocation. Its zero value selects the production tsgo runner and
 // validation policy.
+//
+// @evidence contracts/common.md#principled-implementation A runner and its validator form one invocation dependency; the zero pair selects the production default and a validator-only pair is invalid.
+// @evidence contracts/common.md#clear-and-simple-design Copying the function pair ties admission and execution to the selected dependencies for that invocation; it does not freeze state captured by their closures or shared option fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Invocation-scoped selection changes no global process hook. A custom runner owns its prerequisites when no custom validator is supplied.
+// @evidence contracts/common.md#meaningful-documentation Native prose and members state copied-pair, zero-value and custom admission meaning under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Native validation belongs to the native runner; the representation also supports in-process execution.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The captured functions choose their algorithms.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The pair coordinates no execution across invocations.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function-pair value acquires no running task or native handle; the serving operation and concrete runner own their respective resource boundaries.
 type LSPUpstream struct {
-  Runner    LSPUpstreamRunner
+  // Runner performs the invocation. Nil with a nil Validator selects the
+  // default native runner; nil with a non-nil Validator is rejected.
+  Runner LSPUpstreamRunner
+
+  // Validator optionally checks the selected custom runner's prerequisites.
+  // Nil for a custom Runner leaves those prerequisites with the runner.
   Validator LSPUpstreamValidator
 }
 
@@ -136,7 +208,10 @@ func defaultUpstreamRunner(ctx context.Context, in io.Reader, out io.Writer, opt
   cmd.Stdin = in
   cmd.Stdout = out
   cmd.Stderr = opts.Err
-  if err := cmd.Run(); err != nil {
+  observation := e2etrace.BeginCommand(cmd, "Run")
+  err := cmd.Run()
+  observation.Result(err)
+  if err != nil {
     if ctx.Err() != nil {
       return ctx.Err()
     }
@@ -145,10 +220,11 @@ func defaultUpstreamRunner(ctx context.Context, in io.Reader, out io.Writer, opt
   return nil
 }
 
-// RunLSPServer starts an upstream `tsgo --lsp --stdio` process and the byte-level
-// proxy, blocking until either side returns. The first non-graceful
-// error wins; ErrFrameClosed and context cancellation are treated as
-// clean shutdown so editor close sequences do not look like crashes. Once the
+// RunLSPServer runs the selected upstream runner and byte-level proxy and waits
+// for both wrapper goroutines. The default runner starts `tsgo --lsp --stdio`.
+// After joining, the first non-graceful error in runner-then-proxy order wins;
+// this is not completion-time ordering. Frame closure, cancellation and closed
+// pipe/input errors are omitted from that selection. Once the
 // editor has sent `exit`, an upstream runner failure joins that set: the
 // upstream is required to terminate at that point, so its status no longer
 // describes the session (see Proxy.editorRequestedExit).
@@ -158,8 +234,18 @@ func defaultUpstreamRunner(ctx context.Context, in io.Reader, out io.Writer, opt
 //  1. Open two pipes around the tsgo process (editor->server, server->editor).
 //  2. Spawn the upstream runner (real tsgo process or a test fake) reading/writing those pipes.
 //  3. Run the proxy in parallel.
-//  4. A watchdog cascades context cancellation by closing every pipe so both
-//     halves unblock; the goroutines' own defers close the rest.
+//  4. A watchdog requests closure of the pipe writers and a closeable editor
+//     reader on cancellation; the runner/proxy defers close their other ends.
+//     Arbitrary injected readers, writers and runners need their own exit policy.
+//
+// @evidence contracts/common.md#principled-implementation Invocation validation precedes pipe acquisition. The watchdog and wrapper defers request cancellation/closure, then runner and proxy errors are selected in that order after their join; editor exit discards the runner result. Exit without prior shutdown remains a distinct error only after other non-graceful errors have been considered.
+// @evidence contracts/common.md#clear-and-simple-design Two pipe pairs isolate transport and one child context signals teardown. The wait group joins the runner/proxy wrappers, not every pump, watchdog or local task they may initiate.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Ignoring upstream exit status after editor exit follows the LSP lifecycle rather than hiding a failed active session.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state error folding and numbered lifecycle ownership, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The default validator requires an absolute executable and the default runner uses exec.CommandContext with separate argv and cwd. A custom runner/validator owns its native prerequisites. Editor closability and interruption depend on the injected stream; proxy editor-exit handling can return without its remaining input pump completing.
+// @evidence contracts/performance.md#efficient-algorithms Fixed pipe/context/wait-group setup delegates source observer registration, runner execution and proxy frame/payload processing. Their native, JSON, text and retained-input costs still belong to this invocation; custom validators/runners and blocking streams have no time budget imposed here.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A live LSP invocation has distinct streams and effects and cannot share another invocation's pumps.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Pipe endpoint closure is attempted with ignored errors; the runner/proxy wrappers are joined. The watchdog, remaining editor pump, copied observers and local tasks are not independently joined. Cancellation requests source shutdown but is not a certificate of descendant termination. The default Cmd has no explicit WaitDelay and injected streams or runners can block the join indefinitely; retained session populations have no overall byte budget.
 func RunLSPServer(ctx context.Context, opts LSPServerOptions) error {
   if opts.Cwd == "" {
     return ErrLSPCwdRequired
@@ -257,14 +343,31 @@ func RunLSPServer(ctx context.Context, opts LSPServerOptions) error {
     if errors.Is(err, io.ErrClosedPipe) {
       continue
     }
+    // The teardown above closes the editor input, and a read it ends reports
+    // os.ErrClosed.
+    if errors.Is(err, os.ErrClosed) {
+      continue
+    }
     return err
   }
+  if proxy.editorRequestedExit() && !proxy.editorRequestedShutdown() {
+    return ErrLSPExitWithoutShutdown
+  }
   return nil
 }
 
 // DenyNpmInstall is kept for source compatibility with older driver
 // embedders that hosted tsgo in-process. The process wrapper cannot
 // override tsgo's internal ATA callback.
+//
+// @evidence contracts/common.md#principled-implementation This compatibility callable always returns an explicit denial error; it does not install an ATA policy into the external tsgo process.
+// @evidence contracts/common.md#clear-and-simple-design A source-compatible stub preserves the old callable without pretending to own external compiler callbacks.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The documented limitation avoids monkey patching foreign ATA internals or claiming an unenforced policy.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the historical embedding API from current process-wrapper capability, following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This stub does not spawn npm or interpret a native executable path.
+// @evidence contracts/performance.md#efficient-algorithms The denial formats every supplied argument into a new error string, with time and temporary/output bytes growing with argument count and text length. It performs no installation or native executable discovery.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work No installation computation is performed or coordinated.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The stub acquires no retained resource.
 func DenyNpmInstall(_ string, args []string) ([]byte, error) {
   return nil, fmt.Errorf("ttscserver: npm install disabled in LSP host (args=%v)", args)
 }

package/internal/lspserver/lsp_symbols.go

@@ -12,6 +12,15 @@ import "encoding/json"
 
 // LSPSymbolKind mirrors the LSP SymbolKind enum. Only the members the graph's
 // node kinds map onto are named here; the numeric values are the wire contract.
+//
+// @evidence contracts/common.md#principled-implementation Integer discriminants retain LSP SymbolKind values while naming the graph-supported subset.
+// @evidence contracts/common.md#clear-and-simple-design One enum serves hierarchy and usage results without compiler node dependencies.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Named values are protocol constants rather than guessed graph outputs.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains the supported subset and numeric wire meaning, following the documentation skill.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type LSPSymbolKind int
 
 const (
@@ -26,20 +35,51 @@ const (
 
 // LSPDocumentSymbol is the hierarchical shape returned by
 // textDocument/documentSymbol. Range spans the whole declaration and
-// SelectionRange the name (LSP requires SelectionRange to be contained in
-// Range). Children nest members (a class's methods) under their owner.
+// SelectionRange identifies the contained navigation span. The graph provider
+// uses the whole declaration span for both because it lacks a separate name
+// span. Children nest members (a class's methods) under their owner.
+//
+// @evidence contracts/common.md#principled-implementation Whole and selection ranges remain distinct while recursive Children represent declaration ownership.
+// @evidence contracts/common.md#clear-and-simple-design The hierarchical result reuses ranges and kinds without mixing query state into nodes.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The graph supplies actual names and ranges; the shape does not encode expected declarations.
+// @evidence contracts/common.md#meaningful-documentation Native prose documents selection containment and child ownership, following the documentation skill.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type LSPDocumentSymbol struct {
-  Name           string              `json:"name"`
-  Kind           LSPSymbolKind       `json:"kind"`
-  Range          LSPRange            `json:"range"`
-  SelectionRange LSPRange            `json:"selectionRange"`
-  Children       []LSPDocumentSymbol `json:"children,omitempty"`
+  // Name is the declaration's display name.
+  Name string `json:"name"`
+
+  // Kind classifies the declaration using LSP SymbolKind discriminants.
+  Kind LSPSymbolKind `json:"kind"`
+
+  // Range covers the declaration in session UTF-16 coordinates.
+  Range LSPRange `json:"range"`
+
+  // SelectionRange is contained in Range and need not isolate the name.
+  SelectionRange LSPRange `json:"selectionRange"`
+
+  // Children nest owned declarations; an empty list is omitted.
+  Children []LSPDocumentSymbol `json:"children,omitempty"`
 }
 
 // LSPLocation is the wire shape of an LSP Location: a range inside a document,
 // returned by textDocument/references for each usage site.
+//
+// @evidence contracts/common.md#principled-implementation URI plus range identifies a usage independently of the document currently open in the editor.
+// @evidence contracts/common.md#clear-and-simple-design Reference results and related diagnostics share this location value.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Locations are producer values rather than guessed local filenames.
+// @evidence contracts/common.md#meaningful-documentation Native prose describes document usage sites, following the documentation skill.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type LSPLocation struct {
-  URI   string   `json:"uri"`
+  // URI identifies the target document using protocol spelling.
+  URI string `json:"uri"`
+
+  // Range locates the site in that document's session UTF-16 coordinates.
   Range LSPRange `json:"range"`
 }
 
@@ -49,22 +89,61 @@ type LSPLocation struct {
 // answers; see shouldAnswerDocumentSymbolLocally / shouldAnswerReferencesLocally.
 //
 // Implementations may load a compiler Program lazily and must be safe to call
-// from multiple goroutines: the proxy invokes them off its pump goroutine so a
-// slow program load never blocks other traffic.
+// from multiple goroutines. DocumentSymbols and References run in separate
+// query goroutines rather than on the editor pump. Their replies still share
+// frame serialization, and this does not bound custom provider work or the
+// synchronous invalidation call.
+//
+// @evidence contracts/common.md#principled-implementation Hierarchy, usage lookup and invalidation are separate operations over the provider's compiler-backed state.
+// @evidence contracts/common.md#clear-and-simple-design The proxy depends on semantic queries without exposing graph construction or program storage.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Supported injection supplies local answers without replacing upstream symbol methods.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs document fallback selection and concurrent invocation, following the documentation skill.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type SymbolProvider interface {
   // DocumentSymbols returns the declarations in the document identified by uri
   // as a hierarchy of LSPDocumentSymbol. A document with no declarations
   // yields an empty (non-nil) slice.
+  //
+  // @evidence contracts/common.md#principled-implementation URI selects one document whose declarations form an ownership hierarchy.
+  // @evidence contracts/common.md#clear-and-simple-design This query returns wire nodes while the implementation owns compiler loading.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts Results come through the provider boundary instead of patched upstream methods.
+  // @evidence contracts/common.md#meaningful-documentation Native prose states hierarchy and empty-result meaning, following the documentation skill.
+  // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources DocumentSymbols declares a signature only; the implementation owns acquisition and release of resources.
+  // @evidenceExclude contracts/performance.md#efficient-algorithms DocumentSymbols declares a signature only; the implementation owns the processing strategy.
+  // @evidenceExclude contracts/performance.md#reuse-equivalent-work DocumentSymbols declares a signature only; the implementation owns any shared work.
+  // @evidenceExclude contracts/portability.md#os-neutral-implementation DocumentSymbols is a signature without a body here; path and platform behavior belongs to the implementation that supplies it.
   DocumentSymbols(uri string) ([]LSPDocumentSymbol, error)
 
   // References returns the usage locations of the symbol at pos in the document
   // identified by uri. includeDeclaration adds the symbol's own declaration to
   // the result. A position that resolves to no symbol yields an empty slice.
+  //
+  // @evidence contracts/common.md#principled-implementation URI and UTF-16 position select a symbol; includeDeclaration distinguishes declaration sites from usages.
+  // @evidence contracts/common.md#clear-and-simple-design The query returns shared location values without exposing symbol identity internals.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts A missing symbol yields no usages instead of guessed same-name matches.
+  // @evidence contracts/common.md#meaningful-documentation Native prose explains declaration inclusion and empty results, following the documentation skill.
+  // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources References declares a signature only; the implementation owns acquisition and release of resources.
+  // @evidenceExclude contracts/performance.md#efficient-algorithms References declares a signature only; the implementation owns the processing strategy.
+  // @evidenceExclude contracts/performance.md#reuse-equivalent-work References declares a signature only; the implementation owns any shared work.
+  // @evidenceExclude contracts/portability.md#os-neutral-implementation References is a signature without a body here; path and platform behavior belongs to the implementation that supplies it.
   References(uri string, pos LSPPosition, includeDeclaration bool) ([]LSPLocation, error)
 
-  // Invalidate discards any cached compiler state so the next DocumentSymbols or
-  // References call reflects the current sources. The proxy calls it on
-  // didChange/didSave; a provider that recomputes on every call may no-op.
+  // Invalidate withdraws published cached compiler state from later queries.
+  // The proxy calls it on didChange/didSave; an uncached provider may no-op.
+  // In-flight queries may still hold an earlier snapshot, and invalidation alone
+  // does not certify a new native capture or cancel that work.
+  //
+  // @evidence contracts/common.md#principled-implementation Invalidation withdraws compiler-backed state before later queries use it.
+  // @evidence contracts/common.md#clear-and-simple-design Cache policy stays with the provider that owns the state.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts An uncached provider may legitimately do nothing; a cached provider cannot fake freshness by retaining disproven state.
+  // @evidence contracts/common.md#meaningful-documentation Native prose documents triggers and the uncached exception, following the documentation skill.
+  // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Invalidate declares a signature only; the implementation owns acquisition and release of resources.
+  // @evidenceExclude contracts/performance.md#efficient-algorithms Invalidate declares a signature only; the implementation owns the processing strategy.
+  // @evidenceExclude contracts/performance.md#reuse-equivalent-work Invalidate declares a signature only; the implementation owns any shared work.
+  // @evidenceExclude contracts/portability.md#os-neutral-implementation Invalidate is a signature without a body here; path and platform behavior belongs to the implementation that supplies it.
   Invalidate()
 }
 

package/internal/lspserver/lsp_watched_file_changes_reach_compiler_caches_test.go

@@ -41,22 +41,23 @@ func watchedFilesEnvelope(t *testing.T, params string) Envelope {
 }
 
 // TestLSPWatchedFileChangesReachCompilerCaches verifies that a
-// workspace/didChangeWatchedFiles batch refreshes both compiler-backed caches,
-// and that only a plain edit to a plain source file is refreshed incrementally.
+// direct workspace/didChangeWatchedFiles dispatch selects invalidation calls.
 //
-// The repository's VS Code client watches `**/{tsconfig,jsconfig}*.json`, which
-// its documentSelector excludes, so a config edit can reach ttsc through no other
-// notification; before this the proxy had no arm for the method at all and the
-// sidecar's documented full-reload fallback was unreachable. A created or deleted
-// file and a config edit each reshape the root set or the compiler options, which
-// tsgo's per-file UpdateProgram cannot express, so they must drop the warm
-// Program rather than update it.
+// Owned optional source/provider implementations record invalidation arguments
+// and counts. No actual compiler cache, Program, editor watch registration or
+// upstream forwarding runs here; empty URI calls represent full invalidation
+// requests rather than an observed Program being dropped.
 //
 //  1. Send a `changed` event for one ordinary source file and assert the resident
 //     refresh carries exactly that URI.
 //  2. Send a tsconfig edit, a created file, and a deleted file, and assert each
-//     drops the whole Program instead.
+//     requests invalidation with an empty URI list instead.
 //  3. Send an undecodable batch (full reload) and an empty batch (no-op).
+//
+// @evidence contracts/testing.md#behavioral-verification Direct dispatch over eleven authored batches records symbol-provider invalidation counts and exact source invalidation URI lists: ordinary edits are localized, config/topology/unlocalizable batches request an empty list, and an empty batch makes neither call. handled=false permits forwarding but does not execute it.
+// @evidence contracts/testing.md#independent-expectations Expected refresh payloads are literal URIs and drop decisions.
+// @evidence contracts/testing.md#distinguishing-cases Single/multiple source edits, tsconfig/scoped-tsconfig/jsconfig, creation/deletion, mixed config-source, absent type, undecodable changes and empty changes are individually named cases. The expected localized/empty/no-call requests differ; actual downstream cache transitions are outside this unit.
+// @evidence contracts/testing.md#execution-ownership The discoverable Go unit's named subtests call actual Proxy dispatch with owned optional invalidator/provider recorders and io.Discard streams. It uses no foreign-method replacement, native process, temporary project, installed consumer or running product host.
 func TestLSPWatchedFileChangesReachCompilerCaches(t *testing.T) {
   cases := []struct {
     name    string

package/internal/sourceprocess/complete_group.go

@@ -0,0 +1,70 @@
+package sourceprocess
+
+import (
+  "errors"
+  "fmt"
+  "syscall"
+  "time"
+)
+
+// groupOperations supplies the original child's wait and the native group
+// operations. The caller retains the unreaped child until signal returns;
+// neither a numeric PID lookup nor this policy creates that authority.
+//
+// The POSIX caller supplies actual signal, wait and reaping capabilities and
+// retains their resources; the local record allows an owned clock in policy
+// tests without replacing global syscalls or granting authority from a PID.
+type groupOperations struct {
+  signal func(int, syscall.Signal) error
+  wait   func() error
+  reap   func(int) error
+  now    func() time.Time
+  sleep  func(time.Duration)
+}
+
+// completeGroup sends the final destructive signal while the original child
+// still reserves its group identity, consumes that child's wait, then proves
+// group absence independently. After wait it sends only signal zero: a reused
+// numeric group can cause conservative failure, never destructive re-signaling.
+//
+// A signal refusal does not prove absence. EPERM from a post-wait observation
+// remains unknown and is observed within the existing five-second budget;
+// only ESRCH certifies absence. Persistent uncertainty, presence and other
+// native failures preserve failure, including the final signal's cause.
+//
+// Original wait errors remain separate from retirement failures. Native wait,
+// reaping and syscall costs can exceed the between-observation budget; it is
+// not a deadline on original child joining. No earlier result is reused, and
+// only local operation references and errors survive until return.
+func completeGroup(group int, operations groupOperations) (waitErr, retirementErr error) {
+  signalErr := operations.signal(-group, syscall.SIGKILL)
+  waitErr = operations.wait()
+  deadline := operations.now().Add(5 * time.Second)
+  for {
+    if err := operations.reap(group); err != nil {
+      retirementErr = fmt.Errorf("post-wait group reaping: %w", err)
+      break
+    }
+    err := operations.signal(-group, 0)
+    if errors.Is(err, syscall.ESRCH) {
+      return waitErr, nil
+    }
+    if err != nil && !errors.Is(err, syscall.EPERM) {
+      retirementErr = fmt.Errorf("post-wait group observation: %w", err)
+      break
+    }
+    if !operations.now().Before(deadline) {
+      if err != nil {
+        retirementErr = fmt.Errorf("post-wait group %d absence remains unproved after termination: %w", group, err)
+      } else {
+        retirementErr = fmt.Errorf("post-wait group %d still exists after termination", group)
+      }
+      break
+    }
+    operations.sleep(10 * time.Millisecond)
+  }
+  if signalErr != nil {
+    retirementErr = errors.Join(fmt.Errorf("pre-wait final group signal: %w", signalErr), retirementErr)
+  }
+  return waitErr, retirementErr
+}