ttsc 0.30.4 → 0.31.0

package/internal/lspserver/lsp_didsave_keeps_the_incremental_changed_uri_path_test.go

@@ -16,19 +16,22 @@ func (s *incrementalSaveSource) InvalidateResidentPrograms(uris ...string) {
   s.calls = append(s.calls, append([]string(nil), uris...))
 }
 
-// TestLSPDidSaveKeepsTheIncrementalChangedURIPath verifies the two boundaries the
-// new open and watched-file invalidations must not erode: a save of a known
-// source still travels as one changed URI, and a didChange on a dirty buffer
-// still sends the resident daemon nothing at all.
+// TestLSPDidSaveKeepsTheIncrementalChangedURIPath checks recorded invalidation
+// dispatch for a supplied save URI followed by a ranged change notification.
 //
-// The resident daemon exists to avoid a cold parse+bind+checker per verb. A save
-// that degraded into a full reload, or an invalidation per keystroke, would trade
-// exactly that away — so widening the set of signals that reach the daemon has to
-// leave these two untouched.
+// The owned recorder implements the supported resident invalidation capability;
+// it does not create a daemon or compiler Program. No initial document text is
+// cached, so this unit does not establish successful ranged text splicing,
+// incremental compiler reuse or avoided parse/bind/checker work.
 //
-//  1. Save a document and assert the daemon is told that one URI changed.
+//  1. Supply a save notification and assert the recorder receives one URI.
 //  2. Send a ranged didChange for the same document.
 //  3. Assert no further resident invalidation was recorded.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual handleEditorEnvelope dispatches exactly one supplied URI to the owned InvalidateResidentPrograms recorder for didSave. A subsequent ranged didChange returns without another recorded invalidation. No actual daemon update or cached-text splice result is asserted.
+// @evidence contracts/testing.md#independent-expectations The expected single URI and zero further invalidations are literal.
+// @evidence contracts/testing.md#distinguishing-cases Save and keystroke edits are the two signals; widening other signals must not change either.
+// @evidence contracts/testing.md#execution-ownership This Go unit constructs the actual Proxy with supported discard streams and an owned optional-capability recorder embedding NullPluginSource, then invokes its notification handler on authored JSON. It creates no directory or sidecar and starts no compiler, process or product host. Save schedules NullPluginSource diagnostics asynchronously without joining or asserting that result; the observed recorder calls are synchronous dispatch.
 func TestLSPDidSaveKeepsTheIncrementalChangedURIPath(t *testing.T) {
   const uri = "file:///project/src/main.ts"
   plugins := &incrementalSaveSource{}

package/internal/lspserver/lsp_document_diagnostics_omits_cached_project_when_current_result_has_none_test.go

@@ -1,18 +1,27 @@
 package lspserver
 
-import "testing"
+import (
+  "os/exec"
+  "testing"
+)
 
 // TestLSPDocumentDiagnosticsOmitsCachedProjectWhenCurrentResultHasNone
 // verifies last-good cache state is not presented as a current document-cycle
 // project result.
 //
-// A parse failure can make lsp-diagnostics omit project data. Returning the
-// prior cache in that response lets the proxy complete a newer pending external
-// refresh with stale evidence.
+// A selected binary that cannot be resolved prevents current publication.
+// The result must omit Project while the separately queried snapshot retains
+// the seeded diagnostic code. This unit does not exercise JSON parse failure,
+// successful publication, a proxy refresh or every cached publication field.
 //
 //  1. Seed one producer's last-good project publication.
 //  2. Make the current document diagnostic invocation fail before publication.
-//  3. Assert document diagnostics omit Project while the cache remains intact.
+//  3. Assert document diagnostics omit Project while one stale-coded cache entry remains.
+//
+// @evidence contracts/testing.md#behavioral-verification When the unresolved producer cannot publish a current result, actual Diagnostics returns Project=nil while the separately queried cache snapshot is nonnil and contains exactly one diagnostic with literal code stale. Other cached fields and successful/parse-failure publications are not asserted.
+// @evidence contracts/testing.md#independent-expectations Absent Project, nonnil snapshot, one cached diagnostic and its code stale are independent literal state checks.
+// @evidence contracts/testing.md#distinguishing-cases The failing run and the seeded cache are the two states that a stale-cache return would conflate.
+// @evidence contracts/testing.md#execution-ownership This Go unit seeds the actual NativePluginSource cache and calls actual Diagnostics and projectDiagnosticsSnapshot. A native LookPath premise requires its supplied binary to be unresolvable before Diagnostics attempts the resident and one-shot command paths; no sidecar is installed or successfully started, and no temporary directory or substituted query operation exists. The asserted cache fields are nonnil snapshot, one entry and literal code stale; selected runtime execution remains unverified.
 func TestLSPDocumentDiagnosticsOmitsCachedProjectWhenCurrentResultHasNone(
   t *testing.T,
 ) {
@@ -20,6 +29,9 @@ func TestLSPDocumentDiagnosticsOmitsCachedProjectWhenCurrentResultHasNone(
     Binary: "ttsc-no-such-document-diagnostics-sidecar",
     Name:   "@ttsc/cached",
   }
+  if _, err := exec.LookPath(plugin.Binary); err == nil {
+    t.Fatalf("missing sidecar premise failed: %q resolves to an executable", plugin.Binary)
+  }
   source := &NativePluginSource{plugins: []NativeLSPPluginEntry{plugin}}
   source.storeProjectDiagnostics(
     plugin,

package/internal/lspserver/lsp_envelope.go

@@ -10,14 +10,23 @@ import (
 )
 
 // ErrInvalidJSONRPC is returned by ParseEnvelope when the body has a
-// `jsonrpc` field present and not equal to "2.0". A missing field is
-// tolerated to stay compatible with editors that omit it.
+// nonempty decoded `jsonrpc` string other than "2.0". Missing, empty and
+// null values are tolerated by the decoding/version-check compatibility policy.
 var ErrInvalidJSONRPC = errors.New("lsp: jsonrpc field must be \"2.0\"")
 
 // Envelope is the minimal JSON-RPC view ttscserver needs to dispatch
 // messages without re-serializing them. id is decoded as json.RawMessage
 // because LSP allows both numbers and strings and we must round-trip
 // whichever shape the editor used in correlating responses.
+//
+// @evidence contracts/common.md#principled-implementation Raw IDs and payloads preserve numeric precision and nested JSON while Method supports dispatch.
+// @evidence contracts/common.md#clear-and-simple-design Routing fields are viewed independently of method-specific payload types.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown payloads are not reconstructed from expected answers.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains raw ID ownership and the routing view, 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 Envelope struct {
   JSONRPC string          `json:"jsonrpc,omitempty"`
   ID      json.RawMessage `json:"id,omitempty"`
@@ -31,6 +40,15 @@ type Envelope struct {
 // inner params/result/error payloads. Unknown fields are ignored, which
 // matches the LSP base protocol's forward-compatibility expectation. A
 // non-empty `jsonrpc` value other than "2.0" is rejected.
+//
+// @evidence contracts/common.md#principled-implementation JSON decoding validates syntax and retains raw payloads; a nonempty incompatible version returns the shared error.
+// @evidence contracts/common.md#clear-and-simple-design Decoding and version validation form one dispatch entry boundary.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing version is explicit compatibility policy; malformed JSON is not repaired.
+// @evidence contracts/common.md#meaningful-documentation Native prose states version tolerance and unknown-field behavior, following the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Parsed strings and raw payload copies transfer in the returned envelope; no cross-frame retained state or external handle is owned here.
+// @evidence contracts/performance.md#efficient-algorithms json.Unmarshal scans the message syntax and allocates decoded routing strings and copies of raw payloads. Work and temporary/returned bytes grow with message size; this decoder supplies no frame-size bound and does not semantically decode method payloads.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This stateless frame decoder has no cross-frame equivalence cache or coordination policy; callers own any repeated-message reuse.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Decodes JSON-RPC bytes only; it handles no path or file and has no platform branch.
 func ParseEnvelope(body []byte) (Envelope, error) {
   var env Envelope
   if err := json.Unmarshal(body, &env); err != nil {
@@ -44,25 +62,62 @@ func ParseEnvelope(body []byte) (Envelope, error) {
 
 // IsRequest reports whether the envelope represents a request expecting
 // a response (id present, method present).
+//
+// @evidence contracts/common.md#principled-implementation ID presence and nonempty Method identify the request routing shape.
+// @evidence contracts/common.md#clear-and-simple-design Handlers share one field-based request predicate.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Classification does not special-case known method names.
+// @evidence contracts/common.md#meaningful-documentation Native prose states classification premises, following the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IsRequest acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms IsRequest performs a fixed number of steps with no loop or recursion over caller data.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work IsRequest computes one result per call, so there is no repeated work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IsRequest computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (e Envelope) IsRequest() bool {
   return len(e.ID) > 0 && e.Method != ""
 }
 
 // IsNotification reports whether the envelope is a one-way notification.
+//
+// @evidence contracts/common.md#principled-implementation Method presence without an ID identifies one-way routing.
+// @evidence contracts/common.md#clear-and-simple-design Classification is independent of notification payload types.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No editor-specific notification identity is substituted.
+// @evidence contracts/common.md#meaningful-documentation Native prose states one-way meaning, following the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IsNotification acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms IsNotification performs a fixed number of steps with no loop or recursion over caller data.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work IsNotification computes one result per call, so there is no repeated work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IsNotification computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (e Envelope) IsNotification() bool {
   return len(e.ID) == 0 && e.Method != ""
 }
 
 // IsResponse reports whether the envelope is a response (id present,
-// method absent — either result or error will be set).
+// method absent). It does not require or validate a result/error payload.
+//
+// @evidence contracts/common.md#principled-implementation ID presence without Method identifies response routing; consumers validate payload meaning.
+// @evidence contracts/common.md#clear-and-simple-design Correlation shares one response predicate.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The predicate fabricates neither result nor error.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies routing fields, following the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IsResponse acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms IsResponse performs a fixed number of steps with no loop or recursion over caller data.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work IsResponse computes one result per call, so there is no repeated work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IsResponse computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (e Envelope) IsResponse() bool {
   return len(e.ID) > 0 && e.Method == ""
 }
 
-// IsErrorResponse reports whether a response envelope carries an error
-// object. JSON-RPC §5.1 forbids `result` and `error` both being present
+// IsErrorResponse reports whether a response-shaped envelope has a nonempty
+// error payload whose trimmed bytes differ from null; it does not validate an
+// error object. JSON-RPC §5.1 forbids `result` and `error` both being present
 // on the same response, so the proxy uses this to skip merging plugin
 // contributions into upstream failures.
+//
+// @evidence contracts/common.md#principled-implementation A present error payload other than trimmed null marks a response-shaped envelope for failure routing. Error-object validation and result/error exclusivity are not established by this predicate.
+// @evidence contracts/common.md#clear-and-simple-design Response classification is reused before error inspection.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Failures are not rewritten as successful contributions.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the result/error protocol constraint, following the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IsErrorResponse acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidence contracts/performance.md#efficient-algorithms Response field checks are constant work, but bytes.TrimSpace scans leading/trailing error bytes before comparing the remaining bytes with null. The method validates neither error-object shape nor result/error exclusivity and allocates no copied error payload.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work IsErrorResponse computes one result per call, so there is no repeated work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IsErrorResponse computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (e Envelope) IsErrorResponse() bool {
   return e.IsResponse() && len(e.Error) > 0 && !bytes.Equal(bytes.TrimSpace(e.Error), []byte("null"))
 }
@@ -75,12 +130,30 @@ func (e Envelope) IsErrorResponse() bool {
 // string id `"42"`. Ids whose JSON value is not a number or string
 // (LSP forbids these as request ids) produce the empty key, which
 // callers treat as "no entry".
+//
+// @evidence contracts/common.md#principled-implementation The helper preserves integer-shaped literals beyond int64 and separates quoted strings from numeric IDs. Decimal/exponent forms use float64 conversion and collapse integral converted values within plus/minus 2^53; that conversion is not proof that the original decimal was exactly representable. It decodes one leading JSON value rather than validating exhaustion of arbitrary raw input.
+// @evidence contracts/common.md#clear-and-simple-design Raw cancellation IDs and envelope correlation share one helper.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Large IDs are not rounded to make differently encoded examples match.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain numeric equivalence, string distinction and invalid-ID absence, following the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IDKey transfers its returned string and owns no cross-call retained state or external handle; decoder buffers are invocation-local.
+// @evidence contracts/performance.md#efficient-algorithms Delegation includes JSON decoding and its buffers, numeric-literal scans/conversion or string quoting, with work and temporary/output bytes depending on raw ID length and decoded shape. Non-ID arrays/objects can still be decoded before rejection; there is no fixed-step or input-size cap here.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work IDKey computes one result per call, so there is no repeated work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IDKey computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (e Envelope) IDKey() string {
   return idKeyFromRaw(e.ID)
 }
 
 // IDKeyFromRaw exposes the shared id-key normalizer to the public driver
 // compatibility layer without exporting the helper from that package.
+//
+// @evidence contracts/common.md#principled-implementation Delegation preserves Envelope.IDKey's correlation semantics for raw callers.
+// @evidence contracts/common.md#clear-and-simple-design The compatibility entry exposes the existing normalizer without duplicating parsing.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts This wrapper shares the owning parser rather than compensating for a conflicting implementation.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains the compatibility caller, following the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a string key and retains nothing.
+// @evidence contracts/performance.md#efficient-algorithms The shared decoder includes input-byte scanning, decoding buffers and numeric conversion or string quoting. Delegation preserves that raw-length/shape-dependent work and output allocation rather than making it constant-time.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A pure function of one raw id with nothing to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Derives a map key from raw JSON bytes only; it touches no path or file.
 func IDKeyFromRaw(raw json.RawMessage) string {
   return idKeyFromRaw(raw)
 }
@@ -93,9 +166,9 @@ func IDKeyFromRaw(raw json.RawMessage) string {
 //
 // Numbers are decoded via json.Decoder.UseNumber() so the full int64
 // range round-trips exactly: decoding into `any` would produce float64
-// and any id past 2^53 would silently collide with its neighbor. LSP
-// places no upper bound on numeric ids, so the helper preserves the
-// high-bit fidelity peers may rely on. Strings are quoted so the proxy
+// and integer-shaped IDs past 2^53 could collide with their neighbors.
+// This compatibility policy preserves integer literals beyond int64 without
+// certifying their protocol validity. Strings are quoted so the proxy
 // never confuses a numeric id `42` with a string id `"42"`. Anything
 // the type switch below does not recognize as a JSON-RPC id shape
 // (boolean, null, array, object — none of which LSP allows for ids)
@@ -125,9 +198,9 @@ func idKeyFromRaw(raw json.RawMessage) string {
       return lit
     }
     // Float-shaped literal (`1.0`, `1.5`, `1e2`). Collapse to integer
-    // form only when the value is exactly representable as int64;
-    // 2^53 bounds the safe range because float64 loses unit precision
-    // past that magnitude.
+    // form when the converted float64 is integral within plus/minus 2^53.
+    // The conversion can round the original decimal; this is a converted-value
+    // policy, not exact decimal equivalence.
     if f, err := v.Float64(); err == nil {
       const maxSafeFloat = float64(int64(1) << 53)
       if f >= -maxSafeFloat && f <= maxSafeFloat && f == float64(int64(f)) {

package/internal/lspserver/lsp_executable_project_input_change_requests_launcher_restart_test.go

@@ -20,19 +20,22 @@ func (s executableProjectInputSource) ProjectInputReloadMatchesChange(
   return uri == s.reloadURI
 }
 
-// TestLSPExecutableProjectInputChangeRequestsLauncherRestart verifies an input
-// that can alter the descriptor's contributor set cannot be handled as an
-// ordinary native resident-program refresh.
+// TestLSPExecutableProjectInputChangeRequestsLauncherRestart checks the proxy's
+// lifecycle frame and restart sentinel for an owned source's reload selection.
 //
-// The JavaScript launcher owns descriptor evaluation and native contributor
-// compilation, so the already-running Go process cannot safely mutate this
-// selection in place.
+// The source supplies a URI-equality policy, not actual descriptor evaluation.
+// The unit observes the proxy boundary; it does not start a JavaScript launcher,
+// compile contributors, forward upstream or assert a physical host restart.
 //
 //  1. Send a watched change for the source's executable reload URI.
 //  2. Assert the proxy announces the expected lifecycle transition, then
-//     returns its stable restart sentinel before forwarding.
-//  3. Send an unrelated change and assert it follows the ordinary forwarded
-//     invalidation path without another lifecycle notification.
+//     returns its stable restart sentinel with handled=false.
+//  3. Send an unrelated change and assert no error, handled=false and no frame.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual handleEditorEnvelope for the owned source's reload URI returns handled=false plus ErrLSPPluginSelectionChanged and emits the literal lifecycle method/reason frame. An unrelated URI returns no error, handled=false and no remaining editor bytes. No actual upstream forwarding, native invalidation call or launcher restart is observed.
+// @evidence contracts/testing.md#independent-expectations The lifecycle notification and the restart sentinel are literals from the proxy contract.
+// @evidence contracts/testing.md#distinguishing-cases The executable reload URI and an unrelated URI take different paths.
+// @evidence contracts/testing.md#execution-ownership This Go unit builds an actual Proxy with supported bytes.Buffer/io.Discard streams and an owned optional reload-matcher source embedding NullPluginSource. Actual notification handling and framed output execute, then actual frame/envelope readers decode the result. It creates no directory or sidecar and starts no compiler, process, installed consumer or product host.
 func TestLSPExecutableProjectInputChangeRequestsLauncherRestart(t *testing.T) {
   reloadURI := "file:///project/lint.config.ts"
   var editor bytes.Buffer

package/internal/lspserver/lsp_external_watched_change_retains_program_test.go

@@ -2,8 +2,9 @@ package lspserver
 
 import "testing"
 
-// TestExternalWatchedChangeRetainsProgram verifies external data events preserve
-// the warm Program without hiding TypeScript root-set changes.
+// TestExternalWatchedChangeRetainsProgram checks the retain-or-reload admission
+// predicate on fifteen authored URI/change-kind pairs. No Program is constructed,
+// retained, reloaded, or incrementally updated in this direct predicate unit.
 //
 // Project-input globs may overlap source files even though Markdown and
 // OpenAPI are the common case, but a JSON path may also be a resolveJsonModule
@@ -14,6 +15,11 @@ import "testing"
 //  1. Retain changed Markdown and Swagger inputs.
 //  2. Retain an in-place TypeScript edit for incremental Program update.
 //  3. Reload package metadata, created/deleted modules, and project configs.
+//
+// @evidence contracts/testing.md#behavioral-verification Compares fifteen direct predicate results with literal booleans for selected data/source/JSON/package/config changes and invalid URI/type premises. The results select retain-or-reload policy; actual Program lifetime, root population, event delivery, and incremental refresh are not observed.
+// @evidence contracts/testing.md#independent-expectations The expected retain-or-reload decision is a literal per event kind.
+// @evidence contracts/testing.md#distinguishing-cases A JSON path that can be a resolveJsonModule source is the boundary between data and Program topology.
+// @evidence contracts/testing.md#execution-ownership Directly supplies URI strings and optional integer kinds to externalWatchedChangeRetainsProgram in this process. It substitutes no seam, creates no native fixture, loads no Program, resolves no sidecar, and starts no product process or editor connection.
 func TestExternalWatchedChangeRetainsProgram(t *testing.T) {
   changed := fileChangeTypeChanged
   created := fileChangeTypeCreated

package/internal/lspserver/lsp_frame.go

@@ -30,27 +30,41 @@ var ErrFrameClosed = errors.New("lsp: frame stream closed")
 // gigabyte-scale frame.
 var ErrFrameTooLarge = errors.New("lsp: frame exceeds maximum size")
 
-// MaxFrameBytes caps Content-Length to 64 MiB. The largest payload the
-// LSP base protocol routinely produces is workspace symbol responses
-// for very large monorepos; 64 MiB leaves a wide margin over any real
-// editor traffic while still capping attacker-supplied lengths.
+// MaxFrameBytes caps announced Content-Length to 64 MiB before body allocation.
+// A larger incoming frame is rejected with ErrFrameTooLarge.
 const MaxFrameBytes = 64 << 20
 
-// MaxHeaderBytes caps the LSP header block to 64 KiB. Real LSP traffic carries
-// only Content-Length plus occasional Content-Type, so anything larger is a
-// malformed peer rather than useful protocol data.
+// MaxHeaderBytes caps incoming header scanning to 64 KiB, including optional
+// headers, so unknown header population cannot cause unbounded accumulation.
 const MaxHeaderBytes = 64 << 10
 
 // FrameReader decodes Content-Length-framed JSON-RPC messages from r. It
-// is intentionally permissive about extra headers (we forward whatever the
-// peer sent) and strict about the Content-Length value because tsgo's
-// upstream writer always emits one.
+// accepts extra headers and returns them separately; the proxy's WriteFrame
+// recreates only Content-Length. The caller owns the underlying reader.
+//
+// @evidence contracts/common.md#principled-implementation A buffered stream reader retains bytes beyond each frame so subsequent frames remain aligned.
+// @evidence contracts/common.md#clear-and-simple-design One reader owns framing state without owning transport closure.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Extra headers follow protocol tolerance rather than particular editor payloads.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes returned headers, outgoing framing and reader ownership, following the documentation skill.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Read chooses the framing algorithm; this type carries its buffered input.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The type does not coordinate shared computations across readers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The transport owner controls closure; this representation owns no native handle independently.
+// @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 FrameReader struct {
   br *bufio.Reader
 }
 
 // NewFrameReader wraps r with an internal buffered reader. r is consumed
 // lazily; the underlying reader is never closed by the FrameReader.
+//
+// @evidence contracts/common.md#principled-implementation bufio.Reader preserves unread stream bytes across frame boundaries.
+// @evidence contracts/common.md#clear-and-simple-design Construction wraps one caller-owned reader and returns framing state.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Supported buffering avoids mutating the foreign reader implementation.
+// @evidence contracts/common.md#meaningful-documentation Native prose states lazy consumption and closure ownership, following the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms bufio.NewReader allocates a default-sized buffer or reuses an existing sufficiently large bufio.Reader, then returns one framing wrapper without reading the stream. An already larger caller buffer is preserved, not reduced to the framing caps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Distinct streams cannot share unread framing state.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned reader owns its buffer while the caller retains transport closure.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation NewFrameReader computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func NewFrameReader(r io.Reader) *FrameReader {
   return &FrameReader{br: bufio.NewReader(r)}
 }
@@ -58,6 +72,15 @@ func NewFrameReader(r io.Reader) *FrameReader {
 // Read returns the next message body together with the raw header block
 // (without trailing CRLFCRLF). The header block is preserved so callers
 // that proxy traffic verbatim do not lose Content-Type or vendor headers.
+//
+// @evidence contracts/common.md#principled-implementation Header parsing obtains a nonnegative bounded length and io.ReadFull consumes exactly that body; EOF between frames differs from a truncated frame.
+// @evidence contracts/common.md#clear-and-simple-design Header accumulation precedes bounded body allocation, with Content-Length recognition delegated to one helper.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Case-insensitive header names and size caps follow framing policy rather than known editor messages.
+// @evidence contracts/common.md#meaningful-documentation Native prose states separate header and body returns, following the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms Header slicing, accumulation, parsing and body copying process H header bytes and B body bytes with O(H+B) byte work/storage under independent per-frame caps, in addition to the reader's retained buffer. Arbitrary reader latency is not bounded by those counts: this method supplies no deadline or cancellation, and caps do not bound how many completed frames callers retain.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Consuming the next stream frame is effectful and cannot reuse a previous frame's body.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Per-frame buffers are returned to the caller; the transport owner closes the reader.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Read computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (fr *FrameReader) Read() (headers string, body []byte, err error) {
   var headerBuf strings.Builder
   contentLength := -1
@@ -129,6 +152,15 @@ func parseContentLength(line string) (int, bool) {
 // uses CRLF line endings to match the LSP base protocol exactly so editors
 // that strict-parse the header block (notably VS Code's client) accept the
 // message without warnings.
+//
+// @evidence contracts/common.md#principled-implementation Byte length and CRLF framing delimit the exact body; the writer must obey io.Writer's short-write error contract.
+// @evidence contracts/common.md#clear-and-simple-design Header and body are written directly while the caller owns synchronization.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Protocol line endings are legitimate constants, independent of native text conventions.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains outgoing header syntax and its reason, following the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms Framing formats the length header and passes the existing B-byte body directly without concatenating a frame copy. io.WriteString can additionally copy header bytes when the writer lacks StringWriter; writer buffering, copying and blocking remain delegated costs. This function provides no output-size cap, write deadline or cancellation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each frame write is an externally visible transport effect.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function neither retains the body nor takes ownership of the writer.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation WriteFrame computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func WriteFrame(w io.Writer, body []byte) error {
   header := fmt.Sprintf("Content-Length: %d\r\n\r\n", len(body))
   if _, err := io.WriteString(w, header); err != nil {

package/internal/lspserver/lsp_hints_absence_is_not_an_error_test.go

@@ -2,32 +2,34 @@ package lspserver
 
 import (
   "bytes"
+  "os/exec"
   "testing"
 )
 
-// TestLSPHintsAbsenceIsNotAnError pins that a plugin without the hint verb is
-// silent, not broken.
+// TestLSPHintsAbsenceIsNotAnError checks silent discovery for an unresolved binary.
 //
-// Every plugin built before this channel existed rejects `lsp-hints` as an
-// unknown command, and that is permanent and universal rather than a
-// transitional state. Treating it as a discovery failure would print an error
-// per plugin per editor session, forever, for a feature those plugins were never
-// asked to provide. It is the optional-interface reasoning applied to the wire:
-// absence is an answer.
-//
-// A real sidecar that cannot run reaches the same path as one that rejects the
-// verb — both return an error from run — so an unresolvable binary is a faithful
-// stand-in and keeps the test from needing a compiled fixture.
+// Failed execution and a rejected optional verb share discovery's run-error
+// branch, but this unit supplies only the former. It does not run a legacy
+// plugin, identify why a real plugin rejected a verb or certify every failure.
 //
 //  1. Discover hints from a plugin whose sidecar cannot answer.
 //  2. Assert the corpus is empty.
 //  3. Assert nothing was written to the log.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual discoverCompletionHints on the supplied unresolved binary leaves CompletionHints empty and writes no bytes to the owned logger. The test does not observe a successfully started producer or certify rejection of an unsupported verb.
+// @evidence contracts/testing.md#independent-expectations Zero hints and zero log bytes are literal expectations for the supported silent run-error branch. With no seeded corpus, these observations do not independently prove an attempted invocation or successful producer decoding.
+// @evidence contracts/testing.md#distinguishing-cases The unresolved executable supplies a run error, not a successful producer's unknown-verb reply or malformed JSON. Those causes are not distinguished by this unit; no universal legacy-plugin compatibility is certified.
+// @evidence contracts/testing.md#execution-ownership This Go unit calls actual native discovery with an owned bytes.Buffer logger and requires native LookPath to reject the supplied binary beforehand. Actual resident/direct command paths attempt the unresolved selection; no sidecar is installed or successfully started. No temporary directory or substituted discovery operation exists; runtime selection and native execution remain unverified.
 func TestLSPHintsAbsenceIsNotAnError(t *testing.T) {
+  const missingBinary = "ttsc-no-such-plugin-binary"
+  if _, err := exec.LookPath(missingBinary); err == nil {
+    t.Fatalf("missing sidecar premise failed: %q resolves to an executable", missingBinary)
+  }
   var log bytes.Buffer
   source := &NativePluginSource{
     err: &log,
     plugins: []NativeLSPPluginEntry{
-      {Binary: "ttsc-no-such-plugin-binary", Name: "@ttsc/legacy"},
+      {Binary: missingBinary, Name: "@ttsc/legacy"},
     },
   }
 
@@ -38,8 +40,7 @@ func TestLSPHintsAbsenceIsNotAnError(t *testing.T) {
   }
   if log.Len() != 0 {
     t.Errorf(
-      "a plugin without the hint verb was logged as a failure:\n%s\n"+
-        "every plugin predating this channel would print that every session",
+      "unresolved hint discovery wrote unexpected log bytes:\n%s",
       log.String(),
     )
   }

package/internal/lspserver/lsp_hints_refresh_coalesces_concurrent_requests_test.go

@@ -6,24 +6,34 @@ import (
   "time"
 )
 
-// TestLSPHintsRefreshCoalescesConcurrentRequests pins the scheduler that keeps
-// rediscovery off the editor's hot path.
+// TestLSPHintsRefreshCoalescesConcurrentRequests checks callback coalescing.
 //
-// One refresh costs a process spawn and a Program load per plugin, and the
-// events that schedule it arrive in bursts: a multi-file save, a formatter
-// rewriting several documents, a watched config change landing with them. Both
-// naive answers are wrong — running one refresh per event stacks spawns behind
-// each other, and dropping events while one runs leaves the corpus a generation
-// behind the edit that caused it. Exactly one rerun observes the newest state
-// for the cost of one refresh.
+// The owned callback waits on a channel while five more requests are scheduled.
+// The unit observes generations 1 and 2, no third start during a 200ms window,
+// and generation 3 from a later schedule. It does not measure editor latency,
+// process/Program work or refreshed corpus contents, or independently inspect
+// whether the scheduler is idle before that last schedule.
 //
 //  1. Hold a run open and schedule several more requests behind it.
 //  2. Release it and assert exactly one rerun followed, with a newer generation.
-//  3. Schedule again once idle and assert the refresher restarts.
+//  3. Schedule again after the quiet window and assert generation 3 arrives.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual coalescingRefresh.schedule returns while its owned callback is blocked. Five further schedules produce observed generations [1 2], no additional start during the 200ms quiet window, and a later callback reports generation 3. The deadlines bound this unit's observation, not a universal scheduler latency or permanent absence of future work.
+// @evidence contracts/testing.md#independent-expectations The run count and generation order are literal expectations.
+// @evidence contracts/testing.md#distinguishing-cases Dropping events or running one per event would produce the wrong count.
+// @evidence contracts/testing.md#execution-ownership This Go unit invokes the actual package-local scheduler with owned channel callbacks and a mutex-protected generation slice. Actual goroutine scheduling runs; no directory, sidecar, compiler, process, editor or product host runs. Deferred cleanup closes admission and releases the owned blocking channel even on assertion failure; it does not assert a scheduler join or native lifecycle.
 func TestLSPHintsRefreshCoalescesConcurrentRequests(t *testing.T) {
   var refresh coalescingRefresh
   started := make(chan struct{}, 8)
   release := make(chan struct{})
+  defer func() {
+    refresh.close()
+    select {
+    case <-release:
+    default:
+      close(release)
+    }
+  }()
 
   var mu sync.Mutex
   var generations []uint64
@@ -58,8 +68,7 @@ func TestLSPHintsRefreshCoalescesConcurrentRequests(t *testing.T) {
     t.Fatalf("refresh generations = %v, want [1 2] — each run needs a newer stamp", ran)
   }
 
-  // A request that arrives once the refresher is idle starts a fresh run rather
-  // than being swallowed by the finished one.
+  // The later request must produce generation 3; idle state is not inspected.
   idle := make(chan uint64, 1)
   refresh.schedule(func(generation uint64) { idle <- generation })
   select {

package/internal/lspserver/lsp_hints_refresh_ignores_a_superseded_generation_test.go

@@ -4,37 +4,45 @@ import "testing"
 
 // TestLSPHintsRefreshIgnoresASupersededGeneration pins the staleness guard.
 //
-// Refresh cycles are driven by editor events, and the answer the user is waiting
-// for is the newest one. A cycle that started earlier can still finish later —
-// its sidecar took longer, or a spawn was slow — and without a generation stamp
-// its result would silently restore the corpus the newer cycle just replaced.
-// The user would then see items for a rule they had already disabled, with no
-// event left to correct it.
+// The unit supplies generation 2, then 1, then 3 directly to the cache writer.
+// It observes selected insertion text through the snapshot accessor, not actual
+// refresh concurrency, sidecar completion order or editor presentation.
 //
 //  1. Store a corpus produced by a newer generation.
 //  2. Store the older generation's result afterwards.
 //  3. Assert the newer corpus stands, and that a still-newer one replaces it.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual storeCompletionHints accepts generation 2 with returns, rejects generation 1 with stale, and preserves returns. Generation 3 with param is accepted and exposed, then an equal-generation successful empty store is accepted and clears the corpus. The bool result distinguishes accepted empty publication from a rejected stale result; actual refresh scheduling is not asserted.
+// @evidence contracts/testing.md#independent-expectations The expected surviving corpus is a literal per store order.
+// @evidence contracts/testing.md#distinguishing-cases Covers newer and equal-generation acceptance, stale rejection with retained contents, and successful-empty clearing. The acceptance result prevents observation from claiming a stale result was published.
+// @evidence contracts/testing.md#execution-ownership This Go unit directly invokes actual NativePluginSource cache storage and snapshot methods on an owned plugin entry and literal hints. Binary/name are opaque cache metadata here; no command discovery, filesystem fixture, sidecar, compiler, process, product host or LSP transport runs, and no operation is substituted.
 func TestLSPHintsRefreshIgnoresASupersededGeneration(t *testing.T) {
   plugin := NativeLSPPluginEntry{Binary: "ttsc-lint", Name: "@ttsc/lint"}
   source := &NativePluginSource{plugins: []NativeLSPPluginEntry{plugin}}
 
-  source.storeCompletionHints(plugin, 2, []LSPCompletionHint{
+  if !source.storeCompletionHints(plugin, 2, []LSPCompletionHint{
     {Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "returns"}}},
-  })
-  source.storeCompletionHints(plugin, 1, []LSPCompletionHint{
+  }) { t.Error("newer corpus was not accepted") }
+  if source.storeCompletionHints(plugin, 1, []LSPCompletionHint{
     {Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "stale"}}},
-  })
+  }) { t.Error("stale corpus claimed publication") }
 
   hints := source.CompletionHints()
   if len(hints) != 1 || len(hints[0].Items) != 1 || hints[0].Items[0].Insert != "returns" {
     t.Fatalf("an older refresh generation overwrote a newer corpus: %#v", hints)
   }
 
-  source.storeCompletionHints(plugin, 3, []LSPCompletionHint{
+  if !source.storeCompletionHints(plugin, 3, []LSPCompletionHint{
     {Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "param"}}},
-  })
+  }) { t.Error("new generation was not accepted") }
   hints = source.CompletionHints()
   if len(hints) != 1 || hints[0].Items[0].Insert != "param" {
     t.Fatalf("the guard rejected a newer generation as well: %#v", hints)
   }
+  if !source.storeCompletionHints(plugin, 3, nil) {
+    t.Error("successful equal-generation empty corpus was not accepted")
+  }
+  if hints := source.CompletionHints(); len(hints) != 0 {
+    t.Errorf("successful-empty publication retained hints: %#v", hints)
+  }
 }