ttsc 0.30.4 → 0.31.0

package/internal/lspserver/lsp_plugin_completion_resolve_stays_local_test.go

@@ -8,13 +8,18 @@ import (
 
 // TestLSPPluginCompletionResolveStaysLocal verifies completion ownership.
 //
-// TypeScript-Go advertises resolve support but dereferences its private data
-// payload for every resolved item. A plugin hint has no such payload and is
-// already complete, so forwarding it upstream can fault the language server.
+// The merger creates a marked item and the direct editor-envelope handler
+// answers its resolve request through a buffered frame. No upstream compiler
+// is running here, so this unit does not observe an upstream crash or forwarding.
 //
 //  1. Encode a plugin completion and send that item back as a resolve request.
 //  2. Assert the proxy answers locally with the item unchanged.
-//  3. Assert an upstream-owned item remains unhandled and is still forwarded.
+//  3. Assert the supplied unmarked item remains unhandled with no editor output.
+//
+// @evidence contracts/testing.md#behavioral-verification A merged plugin item's resolve request is handled locally and its decoded result equals the decoded submitted item; the supplied unmarked item returns unhandled and writes no editor bytes. Actual upstream forwarding is outside this direct dispatch unit.
+// @evidence contracts/testing.md#independent-expectations Decoded equality with the submitted item is a preservation oracle, not an independent oracle for every field generated by the merger. A separate literal evidence label and insertion check establishes the supplied item's content; JSON whitespace and response IDs are not asserted.
+// @evidence contracts/testing.md#distinguishing-cases A plugin item and an upstream item differ by ownership marker.
+// @evidence contracts/testing.md#execution-ownership The discoverable Go unit directly invokes the actual merger and Proxy dispatcher, then decodes one response from bytes.Buffer through FrameReader and ParseEnvelope. It starts no child or host, installs no consumer and creates no temporary project; supported owned streams carry the observations.
 func TestLSPPluginCompletionResolveStaysLocal(t *testing.T) {
   merged := mergeCompletionResponse(
     []byte(`{"jsonrpc":"2.0","id":1,"result":null}`),
@@ -60,6 +65,10 @@ func TestLSPPluginCompletionResolveStaysLocal(t *testing.T) {
   if err := json.Unmarshal(item, &want); err != nil {
     t.Fatalf("decode original plugin item: %v", err)
   }
+  submitted, ok := want.(map[string]any)
+  if !ok || submitted["label"] != "evidence" || submitted["insertText"] != "evidence" {
+    t.Fatalf("plugin item lost its literal content: %s", item)
+  }
   gotJSON, _ := json.Marshal(got)
   wantJSON, _ := json.Marshal(want)
   if !bytes.Equal(gotJSON, wantJSON) {

package/internal/lspserver/lsp_plugin_selection_inputs.go

@@ -0,0 +1,283 @@
+package lspserver
+
+import (
+  "fmt"
+  "os"
+  "path/filepath"
+  "runtime"
+  "strings"
+)
+
+// NativePluginSelectionInputs carries the launcher-declared selection baseline
+// in the plugin manifest. Host comparisons of reported changes can request a
+// restart; the value itself neither observes changes nor authenticates capture.
+//
+// Both kinds of input travel by directory, each directory with the names of
+// the files in it and the digest each had (projectInputReloadFileDigest). A
+// descriptor can include missing resolution candidates, while source entries
+// describe selected file populations. Normalization resolves directories per
+// lane group rather than each filename; a directory occurring in both lanes
+// can be queried again. A source directory's listing is an input as
+// well, counted by the build's own rule, which the launcher hands over as data
+// rather than the host keeping a copy of it.
+//
+// @evidence contracts/common.md#principled-implementation Directory-grouped filename/digest maps distinguish recorded descriptor candidates from source populations whose listing also affects selection.
+// @evidence contracts/common.md#clear-and-simple-design Build-owned omission and pruning rules travel as data rather than duplicated host build policy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Launcher-observed inputs and source rules supply the baseline instead of a fixed package-specific list. The wire shape does not prove producer completeness or capture freshness; host normalization and comparisons own its admission.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain directory grouping, missing candidates and listing ownership, with separated member prose under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The host validates absolute local directories and recorded file-entry names (rejecting separators, NUL and dot-parent entries), then attempts native directory identity with lexical/unknown-case fallback. Policy-name lists remain literal entry filters; protocol URLs are not used as native paths. Supplied hash syntax and sequential comparisons are not an atomic filesystem capture.
+// @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 NativePluginSelectionInputs struct {
+  // DescriptorFiles maps every directory holding a file the plugin load read
+  // or probed to the name of each such file, with its digest: the project's
+  // config chain, the manifests plugin discovery reads, the descriptors, and
+  // what they resolved. Only those files count; the rest of the directory is
+  // not an input.
+  DescriptorFiles map[string]map[string]string `json:"descriptorFiles,omitempty"`
+
+  // SourceFiles maps every plugin source directory to the name of every file
+  // directly inside it that the build keys on, with its digest. A directory
+  // with no such file is present with an empty map.
+  SourceFiles map[string]map[string]string `json:"sourceFiles,omitempty"`
+
+  // OmittedNames are the names of files the build never keys on.
+  OmittedNames []string `json:"omittedNames,omitempty"`
+
+  // OmittedSuffixes are the suffixes of files the build never keys on.
+  OmittedSuffixes []string `json:"omittedSuffixes,omitempty"`
+
+  // PrunedDirectoryNames are the names of directories the build passes over.
+  PrunedDirectoryNames []string `json:"prunedDirectoryNames,omitempty"`
+}
+
+// pluginSelectionInputs groups accepted entries by attempted directory identity;
+// repeated lane groups can perform native queries before sharing the record.
+type pluginSelectionInputs struct {
+  directories     map[string]*pluginSelectionDirectory
+  omittedNames    []string
+  omittedSuffixes []string
+  prunedNames     []string
+}
+
+type pluginSelectionDirectory struct {
+  path string
+
+  // files are the recorded digests by name.
+  files map[string]string
+
+  // listing marks a plugin source directory, whose entries are an input by
+  // the build's rule, beside the recorded files.
+  listing bool
+}
+
+// newPluginSelectionInputs resolves inputs. A directory named by both kinds
+// holds the files of both and is a source directory.
+func newPluginSelectionInputs(
+  inputs NativePluginSelectionInputs,
+) (pluginSelectionInputs, error) {
+  out := pluginSelectionInputs{
+    directories:     map[string]*pluginSelectionDirectory{},
+    omittedNames:    append([]string(nil), inputs.OmittedNames...),
+    omittedSuffixes: append([]string(nil), inputs.OmittedSuffixes...),
+    prunedNames:     append([]string(nil), inputs.PrunedDirectoryNames...),
+  }
+  add := func(lane map[string]map[string]string, listing bool) error {
+    for directory, files := range lane {
+      if strings.TrimSpace(directory) == "" ||
+        !isAbsoluteLocalLSPProjectInputPath(directory, runtime.GOOS) {
+        return fmt.Errorf(
+          "plugin selection directory %q is not an absolute local path",
+          directory,
+        )
+      }
+      resolved := realProjectInputPath(directory)
+      key := projectInputPathKey(resolved)
+      entry := out.directories[key]
+      if entry == nil {
+        entry = &pluginSelectionDirectory{
+          path:  resolved,
+          files: map[string]string{},
+        }
+        out.directories[key] = entry
+      }
+      entry.listing = entry.listing || listing
+      for name, digest := range files {
+        if name == "" || name == "." || name == ".." || strings.ContainsAny(name, "/\\\x00") {
+          return fmt.Errorf(
+            "plugin selection file %q in %q is not a file name",
+            name,
+            directory,
+          )
+        }
+        if !validProjectInputFingerprint(digest) {
+          return fmt.Errorf(
+            "plugin selection file %q in %q has an invalid fingerprint",
+            name,
+            directory,
+          )
+        }
+        entry.files[name] = digest
+      }
+    }
+    return nil
+  }
+  if err := add(inputs.DescriptorFiles, false); err != nil {
+    return pluginSelectionInputs{}, err
+  }
+  if err := add(inputs.SourceFiles, true); err != nil {
+    return pluginSelectionInputs{}, err
+  }
+  return out, nil
+}
+
+// watchDirectories are the directories whose entries an observer of the
+// selection has to hear.
+func (inputs pluginSelectionInputs) watchDirectories() []string {
+  out := make([]string, 0, len(inputs.directories))
+  for _, directory := range inputs.directories {
+    out = append(out, directory.path)
+  }
+  return out
+}
+
+// current reports whether every directory still holds what the selection was
+// loaded from.
+func (inputs pluginSelectionInputs) current() bool {
+  for _, directory := range inputs.directories {
+    if !inputs.directoryCurrent(directory) {
+      return false
+    }
+  }
+  return true
+}
+
+// matchesChange reports whether a change to location changes the selection:
+// whether a directory it can affect no longer holds what the selection was
+// loaded from. A change affects the directory holding location, and every
+// directory at or below location, which a client may report as one change
+// when a tree appears or disappears at once.
+func (inputs pluginSelectionInputs) matchesChange(location string) bool {
+  if len(inputs.directories) == 0 {
+    return false
+  }
+  native := projectInputFilesystemPath(location)
+  changed := projectInputPathKey(realProjectInputPath(native))
+  parent := projectInputPathKey(realProjectInputPath(filepath.Dir(native)))
+  within := strings.TrimRight(changed, "/") + "/"
+  for key, directory := range inputs.directories {
+    if key != parent && key != changed && !strings.HasPrefix(key, within) {
+      continue
+    }
+    if !inputs.directoryCurrent(directory) {
+      return true
+    }
+  }
+  return false
+}
+
+// directoryCurrent reports whether directory holds what the selection was
+// loaded from: every recorded file with its digest, a missing one still
+// missing, and for a source directory, by the build's rule, no other file the
+// build keys on and no subdirectory the build would read that was not a
+// source directory then.
+func (inputs pluginSelectionInputs) directoryCurrent(
+  directory *pluginSelectionDirectory,
+) bool {
+  for name, digest := range directory.files {
+    if projectInputReloadFileDigest(filepath.Join(directory.path, name)) !=
+      digest {
+      return false
+    }
+  }
+  if !directory.listing {
+    return true
+  }
+  entries, err := os.ReadDir(directory.path)
+  if err != nil {
+    return false
+  }
+  for _, entry := range entries {
+    name := entry.Name()
+    link := projectInputEntryIsLink(
+      filepath.Join(directory.path, name),
+      entry.Type(),
+    )
+    // A directory, or a link standing where one would, that the build
+    // passes over, as its own walk skips it.
+    if (entry.IsDir() || link) && inputs.pruned(name) {
+      continue
+    }
+    if entry.IsDir() {
+      if !inputs.knownSource(filepath.Join(directory.path, name)) {
+        return false
+      }
+      continue
+    }
+    if inputs.omitted(name) {
+      continue
+    }
+    // Any other link is one the build refuses, which a new selection has to
+    // report; any other irregular entry is none the build reads.
+    if link {
+      return false
+    }
+    if !entry.Type().IsRegular() {
+      continue
+    }
+    if !directory.has(name) {
+      return false
+    }
+  }
+  return true
+}
+
+// knownSource reports whether location is one of the source directories.
+func (inputs pluginSelectionInputs) knownSource(location string) bool {
+  directory, ok := inputs.directories[projectInputPathKey(
+    realProjectInputPath(location),
+  )]
+  return ok && directory.listing
+}
+
+func (inputs pluginSelectionInputs) omitted(name string) bool {
+  for _, omitted := range inputs.omittedNames {
+    if name == omitted {
+      return true
+    }
+  }
+  for _, suffix := range inputs.omittedSuffixes {
+    if strings.HasSuffix(name, suffix) {
+      return true
+    }
+  }
+  return false
+}
+
+func (inputs pluginSelectionInputs) pruned(name string) bool {
+  for _, pruned := range inputs.prunedNames {
+    if name == pruned {
+      return true
+    }
+  }
+  return false
+}
+
+// has reports whether a file is recorded under the name a listing spells, by
+// the case semantics of the directory itself (projectInputPathKey): a Windows
+// directory opted into case sensitivity, or a case-sensitive macOS volume,
+// holds Foo.go and foo.go as two files, and folding by platform alone would take
+// a new foo.go for the recorded Foo.go.
+func (directory *pluginSelectionDirectory) has(name string) bool {
+  if _, ok := directory.files[name]; ok {
+    return true
+  }
+  key := projectInputPathKey(filepath.Join(directory.path, name))
+  for candidate := range directory.files {
+    if projectInputPathKey(filepath.Join(directory.path, candidate)) == key {
+      return true
+    }
+  }
+  return false
+}

package/internal/lspserver/lsp_plugin_selection_inputs_follow_directory_case_semantics_windows_test.go

@@ -0,0 +1,81 @@
+//go:build windows
+
+package lspserver
+
+import (
+  "os"
+  "path/filepath"
+  "testing"
+)
+
+// TestPluginSelectionInputsFollowDirectoryCaseSemantics verifies a plugin
+// direct selection currentness distinguishes a new source file differing by
+// case, where the directory keeps the two apart.
+//
+// Folding case on every Windows and macOS directory would be wrong: a Windows
+// directory opted into case sensitivity holds Foo.go and foo.go as two files, so
+// a new foo.go must not be taken for the recorded Foo.go. The test observes
+// currentness directly, without running a session or loading a plugin binary.
+//
+//  1. Record Foo.go as the only source of a case-sensitive directory, and assert
+//     the selection is current.
+//  2. Create foo.go beside it, and assert the selection is no longer current.
+//  3. On an ordinary directory, assert a recorded name spelled in another case
+//     still stands for the file on disk.
+//
+// @evidence contracts/testing.md#behavioral-verification A new source file differing from a recorded one only by case makes the selection stale in a case-sensitive directory, while on an ordinary directory a differently cased recorded name still stands for the file.
+// @evidence contracts/testing.md#independent-expectations Literal true/false currentness expectations rely on separately checked native directory flags: sensitive=true after setup and sensitive=false for the ordinary root. Supplied baseline digests use the actual digest helper, so their independent hash correctness is not certified.
+// @evidence contracts/testing.md#distinguishing-cases The sensitive root receives Foo.go followed by a distinct foo.go; the insensitive root contains only Bar.go and supplies the recorded spelling bar.go. The ordinary lane does not create a second differently cased file.
+// @evidence contracts/testing.md#execution-ownership This Windows-only Go unit calls actual selection construction/currentness on owned native directories. Existing setup runs fsutil once and skips the whole case on its failure; this does not identify every failure as unavailable capability. Native flag queries establish accepted premises, and no Go build, plugin sidecar, installed consumer or product host runs.
+func TestPluginSelectionInputsFollowDirectoryCaseSemantics(t *testing.T) {
+  sensitive := t.TempDir()
+  enableProjectInputCaseSensitivity(t, sensitive)
+  if enabled, known := tryQueryProjectInputDirectoryCaseSensitivity(sensitive); !known || !enabled {
+    t.Fatalf("case-sensitive fixture premise is unconfirmed: enabled=%v known=%v", enabled, known)
+  }
+  recorded := filepath.Join(sensitive, "Foo.go")
+  if err := os.WriteFile(recorded, []byte("package main\n"), 0o644); err != nil {
+    t.Fatal(err)
+  }
+  inputs, err := newPluginSelectionInputs(NativePluginSelectionInputs{
+    SourceFiles: map[string]map[string]string{
+      sensitive: {"Foo.go": projectInputReloadFileDigest(recorded)},
+    },
+  })
+  if err != nil {
+    t.Fatal(err)
+  }
+  if !inputs.current() {
+    t.Fatal("an unchanged case-sensitive source directory was not current")
+  }
+  if err := os.WriteFile(
+    filepath.Join(sensitive, "foo.go"),
+    []byte("package main\n"),
+    0o644,
+  ); err != nil {
+    t.Fatal(err)
+  }
+  if inputs.current() {
+    t.Fatal("a case-distinct new source was taken for the recorded file")
+  }
+
+  ordinary := t.TempDir()
+  if enabled, known := tryQueryProjectInputDirectoryCaseSensitivity(ordinary); !known || enabled {
+    t.Fatalf("case-insensitive fixture premise is unconfirmed: enabled=%v known=%v", enabled, known)
+  }
+  file := filepath.Join(ordinary, "Bar.go")
+  if err := os.WriteFile(file, []byte("package main\n"), 0o644); err != nil {
+    t.Fatal(err)
+  }
+  aliased, err := newPluginSelectionInputs(NativePluginSelectionInputs{
+    SourceFiles: map[string]map[string]string{
+      ordinary: {"bar.go": projectInputReloadFileDigest(file)},
+    },
+  })
+  if err != nil {
+    t.Fatal(err)
+  }
+  if !aliased.current() {
+    t.Fatal("a case alias on an ordinary directory lost its file")
+  }
+}

package/internal/lspserver/lsp_position_conversions_span_astral_and_combining_runes_test.go

@@ -3,13 +3,11 @@ package lspserver
 import "testing"
 
 // TestLSPPositionConversionsSpanAstralAndCombiningRunes verifies that both
-// proxy-side position converters spend a UTF-16 budget, not a byte or rune one,
-// across every width a line can hold.
+// position helper and its completion wrapper spend the supplied UTF-16 budget
+// on nine authored ASCII, BMP, astral, combining and line-boundary inputs.
 //
-// UTF-16 is the encoding ttscserver pins for the whole session
-// (constrainInitializePositionEncoding), so these two helpers are the contract
-// for every feature that maps an editor column onto the cached buffer:
-// incremental didChange splicing and plugin completion. An astral rune is the
+// The wrapper delegates to lspPositionToByteOffset; agreement between their
+// outputs is not an independent implementation oracle. An astral rune is the
 // boundary that separates the three counting schemes at once — four bytes, one
 // rune, two UTF-16 units — and a combining mark is the boundary where two runes
 // render as one grapheme but still cost two units.
@@ -18,6 +16,11 @@ import "testing"
 //     CJK, an astral rune, and a combining sequence.
 //  2. Assert both converters return the same byte offset for each.
 //  3. Assert the line walk, the end-of-line column, and an out-of-range column.
+//
+// @evidence contracts/testing.md#behavioral-verification The helper and its delegating wrapper return literal offsets on nine supplied positive cases, including LF, bare CR and CRLF line walks; the helper alone rejects column 99 past the final line. Direct utf16Length calls require four units for a mixed prefix and zero for empty text. Actual edits, completion requests and session negotiation are not executed.
+// @evidence contracts/testing.md#independent-expectations Expected offsets are literal byte counts from the UTF-16 definition.
+// @evidence contracts/testing.md#distinguishing-cases ASCII and BMP distinguish byte width, an astral rune distinguishes rune and UTF-16 width, and a combining sequence still counts its separate code points. Before-astral/end-of-line positions, three line separators, the helper's past-end refusal and empty width complete this authored matrix; malformed text and positions inside a surrogate pair are not covered.
+// @evidence contracts/testing.md#execution-ownership The discoverable Go unit directly calls lspPositionToByteOffset, offsetForPosition and utf16Length on authored strings. It uses no substitute operation, temporary directory, child, installed consumer or product host; the positive subtests remain individually named.
 func TestLSPPositionConversionsSpanAstralAndCombiningRunes(t *testing.T) {
   cases := []struct {
     name      string
@@ -79,6 +82,26 @@ func TestLSPPositionConversionsSpanAstralAndCombiningRunes(t *testing.T) {
     },
   }
 
+  cases = append(cases, struct {
+    name      string
+    text      string
+    line      int
+    character int
+    want      int
+    wantOK    bool
+  }{
+    "bare CR reaches target line", "a\rconst \U0001D499 = 1;", 1, 8, 12, true,
+  }, struct {
+    name      string
+    text      string
+    line      int
+    character int
+    want      int
+    wantOK    bool
+  }{
+    "CRLF is one line boundary", "a\r\nconst \U0001D499 = 1;", 1, 8, 13, true,
+  })
+
   for _, testCase := range cases {
     t.Run(testCase.name, func(t *testing.T) {
       got, ok := lspPositionToByteOffset(testCase.text, lspPositionWire{
@@ -101,15 +124,14 @@ func TestLSPPositionConversionsSpanAstralAndCombiningRunes(t *testing.T) {
     })
   }
 
-  // A column past the end of the line is a cache/editor divergence, not a
-  // clamped position: the buffer cache drops its entry rather than splice at a
-  // guessed byte.
+  // The direct helper rejects this past-end column; cache eviction is not
+  // exercised by this call.
   if got, ok := lspPositionToByteOffset("const \U0001D499", lspPositionWire{Character: 99}); ok {
     t.Errorf("lspPositionToByteOffset past end = (%d, true), want ok=false", got)
   }
 
-  // The completion replace range is measured in the same units, so the filter
-  // width of a mixed-width prefix must agree with the columns above.
+  // Independently authored width expectations exercise the width helper;
+  // this does not construct a completion replacement range.
   if units := utf16Length("é\U0001D499"); units != 4 {
     t.Errorf("utf16Length = %d, want 4 (e + combining acute + astral pair)", units)
   }

package/internal/lspserver/lsp_project_context_transport_identity_test.go

@@ -1,14 +1,26 @@
 package lspserver
 
-import "testing"
+import (
+  "os/exec"
+  "testing"
+)
 
 // TestLSPProjectContextTransportIdentityTracksEffectiveArgv verifies resident
-// identity follows the actual launch arguments, not a dormant capability flag.
+// key distinguishes whether supplied project context would be passed. Its
+// failed-start resident calls create two keyed records, not two live sessions.
+//
+// @evidence contracts/testing.md#behavioral-verification Two entries differing in name and ProjectContextArgs share a key without context but differ with the supplied nonempty context. Direct serveRun calls then leave two keyed resident records despite failed starts. Actual child argv or successful session reuse is not observed.
+// @evidence contracts/testing.md#independent-expectations Literal equality without context, inequality with context and record count two express the supplied transport policy. Key strings are not copied from the implementation, and the missing binary premise is checked before native start attempts.
+// @evidence contracts/testing.md#distinguishing-cases Absent context makes the differing flag dormant; supplied context makes it effective. The same missing binary is used for both entries, whose names also differ. Empty or whitespace context and distinct context payload contents are outside this matrix.
+// @evidence contracts/testing.md#execution-ownership The discoverable Go unit directly calls pluginKey and NativePluginSource.serveRun with an owned temporary cwd and descriptors. Actual command setup and failed native Start attempts are reached; no child successfully starts under the checked missing-binary premise, and no consumer or product host is installed.
 func TestLSPProjectContextTransportIdentityTracksEffectiveArgv(t *testing.T) {
   withoutContext := NativeLSPPluginEntry{
     Binary: "ttsc-no-such-shared-sidecar",
     Name:   "@ttsc/without-context",
   }
+  if path, err := exec.LookPath(withoutContext.Binary); err == nil {
+    t.Fatalf("missing-binary premise is false: %s", path)
+  }
   withContext := withoutContext
   withContext.Name = "@ttsc/with-context"
   withContext.ProjectContextArgs = true

package/internal/lspserver/lsp_project_diagnostics.go

@@ -22,16 +22,37 @@ type projectDiagnosticsRefreshResult struct {
   selected    int
 }
 
-// ProjectDiagnostics evaluates project rules without requiring an open
-// document and returns the latest successful publication from every capable
-// sidecar.
+// ProjectDiagnostics requests document-independent rules from capable transports
+// and returns the retained compatible-URI aggregate. This legacy entry discards
+// refresh completeness metadata; its result is not proof that all producers
+// succeeded or share one input capture.
+//
+// @evidence contracts/common.md#principled-implementation Nil owner selection requests all capable producers and returns the aggregate publication separately from refresh bookkeeping.
+// @evidence contracts/common.md#clear-and-simple-design The owner-aware operation is the single implementation of project diagnostics refresh.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts This legacy entry shares the same producer policy rather than compensating with another query path.
+// @evidence contracts/common.md#meaningful-documentation Native prose states document-independent and last-successful publication behavior, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The delegated owner-aware operation owns native execution and logical config URI translation.
+// @evidence contracts/performance.md#efficient-algorithms The owner-aware delegate includes transport/key hashing, native queries/fallback, reply decoding, publication copies and native URI aggregation. Forwarding does not remove its payload-dependent work or blocking costs.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The delegated refresh owns resident sharing and generation validity.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Child and publication lifetimes belong to the delegated source operation.
 func (s *NativePluginSource) ProjectDiagnostics() *LSPProjectDiagnostics {
   return s.ProjectDiagnosticsForOwners(nil).publication
 }
 
 // ProjectDiagnosticsForOwners refreshes only the diagnostics-capable producers
 // named by owners. A nil owner list preserves the legacy all-producer request;
-// an empty non-nil list is a successful no-op.
+// an empty non-nil list selects no producer query, but still advances the
+// generation and builds an aggregate of all retained records, including native
+// URI restatement. Owner selection limits refresh queries, not returned owners.
+//
+// @evidence contracts/common.md#principled-implementation Nil owners selects all capable queries and empty non-nil selects none. Per-producer generation guards preserve last-good records; refreshed marks received nonempty-URI publications even if an older store is rejected. Aggregate output also includes unselected retained owners and can mix concurrent generations.
+// @evidence contracts/common.md#clear-and-simple-design Selection and execution produce separate completion/receipt metadata, then read the retained aggregate. Queries and stores are not one atomic transaction or a common filesystem capture.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Failed producers are not reported as successful clears; optional verb fallback addresses older resident protocol support explicitly.
+// @evidence contracts/common.md#meaningful-documentation Native prose states owner-list distinctions, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Native argv remains separate from protocol URIs. URI translation compares native realpath/ancestor-fallback keys with the cached client spelling and uses Windows owning-directory flags when observable; this best-effort mapping does not authenticate the producer or guarantee fresh physical identity after topology changes.
+// @evidence contracts/performance.md#efficient-algorithms Owner/transport lookups hash string bytes; selected queries include native work, possible resident-to-direct fallback, decoding, copies, logging and trace IO. Manifest aggregation scans retained records and resolves project paths/case flags under its read lock. Empty owner selection still pays aggregation, not merely constant-time selection.
+// @evidence contracts/performance.md#reuse-equivalent-work Sidecar state sharing requires caller invalidations and producer semantics. Generation guards reject older per-producer stores but do not certify one common capture or fresh untouched owners. The client project key is resolved once, so later native topology changes are not automatically remeasured for that cached key.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Per-producer output caps do not impose an aggregate age/byte budget or outstanding-call limit. Last-good records and nested data remain reachable after Close, and shallow diagnostic copies can share them with returned values. Source cancellation requests child termination and resident cleanup but does not join these refresh calls or certify descendants; there is no open-session computation deadline.
 func (s *NativePluginSource) ProjectDiagnosticsForOwners(
   owners []string,
 ) projectDiagnosticsRefreshResult {

package/internal/lspserver/lsp_project_diagnostics_capability_is_independent_test.go

@@ -2,6 +2,7 @@ package lspserver
 
 import (
   "bytes"
+  "os/exec"
   "strings"
   "testing"
 )
@@ -16,8 +17,13 @@ import (
 //
 //  1. Configure a topology-only plugin and a diagnostics-only plugin.
 //  2. Seed the diagnostics producer, then make its next refresh fail to launch.
-//  3. Assert only the explicitly capable producer was invoked.
-//  4. Assert its last-good publication remains available after the failure.
+//  3. Assert only the explicitly capable producer appears in failed-call logs.
+//  4. Assert one retained diagnostic still carries its last-good code.
+//
+// @evidence contracts/testing.md#behavioral-verification The failed refresh logs the diagnostics-only descriptor's name but not the topology-only name; its aggregate still contains one diagnostic with literal last-good code. These error-name observations distinguish selection here, not a successful protocol response or every retained field.
+// @evidence contracts/testing.md#independent-expectations Descriptor names, one diagnostic and last-good code are literal expectations. Both binaries are independently required to be absent from executable lookup before the actual failed start paths are reached; absence of a log alone would not establish selection without the positive capable-producer observation.
+// @evidence contracts/testing.md#distinguishing-cases A topology-only and a diagnostics-only plugin expose the two capability combinations.
+// @evidence contracts/testing.md#execution-ownership The discoverable Go unit seeds actual NativePluginSource records and calls ProjectDiagnostics with an owned log buffer and descriptors. Selected command setup reaches failed resident/direct native starts under the missing-binary premise, without an installed consumer, temporary project or running product host.
 func TestLSPProjectDiagnosticsCapabilityIsIndependent(t *testing.T) {
   topologyOnly := NativeLSPPluginEntry{
     Binary:        "ttsc-no-such-topology-only-sidecar",
@@ -29,6 +35,11 @@ func TestLSPProjectDiagnosticsCapabilityIsIndependent(t *testing.T) {
     Name:               "@ttsc/diagnostics-only",
     ProjectDiagnostics: true,
   }
+  for _, plugin := range []NativeLSPPluginEntry{topologyOnly, diagnosticsOnly} {
+    if path, err := exec.LookPath(plugin.Binary); err == nil {
+      t.Fatalf("missing-binary premise is false: %s", path)
+    }
+  }
   var log bytes.Buffer
   source := &NativePluginSource{
     err:     &log,

package/internal/lspserver/lsp_project_diagnostics_program_input_overlap_refreshes_all_producers_test.go

@@ -2,6 +2,7 @@ package lspserver
 
 import (
   "bytes"
+  "os/exec"
   "path/filepath"
   "strings"
   "testing"
@@ -10,16 +11,20 @@ import (
 // TestLSPProjectDiagnosticsProgramInputOverlapRefreshesAllProducers verifies a
 // declared input that can also belong to the Program widens diagnostic scope.
 //
-// Only the first producer declares the path, but both project-rule producers
-// observe the shared Program. TypeScript and resolveJsonModule JSON edits must
-// therefore refresh both, while a path that can only be data keeps the
-// owner-scoped behavior pinned by
+// Only the first supplied snapshot declares each tested path. The direct scope
+// policy widens .ts and .json inputs; neither an actual Program nor a filesystem
+// edit runs here. Non-Program data scoping is separately exercised by
 // lsp_project_diagnostics_refreshes_only_input_owners_test.go.
 //
 //  1. Declare one shared-Program path for the first producer only.
 //  2. Resolve its owner scope and widen it as a watched Program input.
 //  3. Assert the scope became all-producer.
 //  4. Refresh and assert both producers were invoked.
+//
+// @evidence contracts/testing.md#behavioral-verification Supplied .ts and .json URIs initially match one retained owner, then the direct watched-input scope policy marks all. A separate explicit nil-owner refresh selects two descriptors, is incomplete and logs both failed producers; this is not an end-to-end scope-to-refresh dispatch or actual Program membership check.
+// @evidence contracts/testing.md#independent-expectations One matched owner, all=true, selected=2, complete=false and both descriptor-name errors are literal observations. Checked absent binaries establish the failed native-start premise; expected values are not derived from scope-policy output.
+// @evidence contracts/testing.md#distinguishing-cases Only the first producer declares the path, so owner-only scoping would invoke one.
+// @evidence contracts/testing.md#execution-ownership Named .ts and .json Go subtests directly seed NativePluginSource snapshots, query Proxy owner scope, widen it and explicitly request an all-owner refresh. Owned native temporary roots supply URI identity, while missing binaries reach failed resident/direct start attempts; no consumer or product host is installed and no Program is constructed.
 func TestLSPProjectDiagnosticsProgramInputOverlapRefreshesAllProducers(
   t *testing.T,
 ) {
@@ -38,6 +43,11 @@ func TestLSPProjectDiagnosticsProgramInputOverlapRefreshesAllProducers(
         ProjectDiagnostics: true,
         ProjectInputs:      true,
       }
+      for _, plugin := range []NativeLSPPluginEntry{first, second} {
+        if path, err := exec.LookPath(plugin.Binary); err == nil {
+          t.Fatalf("missing-binary premise is false: %s", path)
+        }
+      }
       var log bytes.Buffer
       source := &NativePluginSource{
         err:     &log,