@ttsc/evidence 0.30.4 → 0.31.0

package/lib/structures/ITtscEvidenceRules.d.ts

@@ -0,0 +1,93 @@
+import type { ITtscEvidenceDocumentedConfig } from "./ITtscEvidenceDocumentedConfig";
+import type { ITtscEvidenceGraphConfig } from "./ITtscEvidenceGraphConfig";
+/**
+ * Rule names of the Evidence lint contributor with their option contracts.
+ *
+ * Pass this interface as the generic argument of `ITtscLintConfig` so every
+ * Evidence rule receives exact severity-plus-options checking, and a rule that
+ * takes no options accepts a severity only:
+ *
+ * ```ts
+ * import type { ITtscEvidenceRules } from "@ttsc/evidence";
+ * import type { ITtscLintConfig } from "@ttsc/lint";
+ *
+ * export default {
+ *   rules: { "evidence/singular": "error" },
+ * } satisfies ITtscLintConfig<ITtscEvidenceRules>;
+ * ```
+ *
+ * @evidence contracts/common.md#principled-implementation Each rule name maps to the options object the rule accepts, or to `void` when it takes severity only, which is exactly the shape the lint package's contributor overlay consumes.
+ * @evidence contracts/common.md#clear-and-simple-design One ordinary exported interface lists the five rules once, so no ambient module augmentation is needed and the member comments stay beside the names they describe.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The options of the two configurable rules reference their declared config types rather than an unknown slot, and the optionless rules are not given an invented options object.
+ * @evidence contracts/common.md#meaningful-documentation The example shows the user side of the pattern and each member explains the rule it names, following the documentation guidance.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This interface lists rule names and option types and names no path, file, filesystem or process itself.
+ */
+export interface ITtscEvidenceRules {
+    /**
+     * Declares this project's evidence graph.
+     *
+     * The claims define the citing populations and the independently complete
+     * evidence references each one must acknowledge.
+     */
+    "evidence/graph": ITtscEvidenceGraphConfig;
+    /**
+     * Requires a JSDoc block on every selected export.
+     *
+     * A JSDoc block is the only place a TypeScript declaration's `@evidence` tag
+     * is read from, so an export without one cannot cite anything.
+     */
+    "evidence/documented": ITtscEvidenceDocumentedConfig;
+    /**
+     * Requires one public identity per TypeScript file, named after the file.
+     *
+     * The counted unit is an identity rather than an export, so declaration
+     * merging of a single name stays legal: `export interface ISomething` beside
+     * `export namespace ISomething`, `export class Something` beside `export
+     * namespace Something`, and `export const something` beside `export default
+     * something` are each one identity.
+     *
+     * A file that only re-exports owns no identity and is never reported, and an
+     * `index` file is exempt from the name match while still limited to one
+     * identity.
+     *
+     * The rule takes no options; per-directory scoping belongs in the outer
+     * `files` setting of `lint.config.ts`.
+     */
+    "evidence/singular": void;
+    /**
+     * Reports every JSDoc `@todo` tag in a checked file.
+     *
+     * A remaining `@todo` is a contract the declaration has not realized yet, so
+     * each tag fails the build with its own text until the declaration is
+     * realized and the tag removed. Every declaration's block is read, exported
+     * or not, on any symbol kind.
+     *
+     * The rule takes no options; per-directory scoping belongs in the outer
+     * `files` setting of `lint.config.ts`.
+     */
+    "evidence/todo": void;
+    /**
+     * Requires a review beside every acknowledgement.
+     *
+     * Every `@evidence` and `@evidenceExclude` on a public identity must be
+     * answered by `@evidenceReview` or `@evidenceExcludeReview`, respectively,
+     * naming the same target. The citation states why this declaration answers
+     * for that target; the review states what was verified. Those are different
+     * questions, and only the first one is written unless something asks for the
+     * second.
+     *
+     * A review is an annotation of a citation, never an acknowledgement of a
+     * unit. It discharges no coverage, contributes no host to `uniqueEvidence`,
+     * and counts toward no `singleEvidencePerSymbol` total, so enabling this rule
+     * cannot change a single `evidence/graph` diagnostic.
+     *
+     * The optional `#`-prefixed fingerprint token is carried without being
+     * interpreted here. `evidence/graph` validates it against the cited content
+     * under a reference's `requireReview`, which is what makes a review expire
+     * when the thing it reviewed moves.
+     *
+     * The rule takes no options; per-directory scoping belongs in the outer
+     * `files` setting of `lint.config.ts`.
+     */
+    "evidence/review": void;
+}

package/lib/structures/TtscEvidenceGraphMarkdownSymbol.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A Markdown node kind that can become an evidence unit or host an evidence
+ * declaration.
+ *
+ * `"file"` is the document root. `"h1"` through `"h4"` select ATX heading
+ * sections at that exact level; Setext headings and H5/H6 headings are outside
+ * this contract.
+ *
+ * These nodes form the Markdown outline: the file contains every heading, and a
+ * heading contains the lower-level headings before the next heading of equal or
+ * higher level. An `@evidence` target, or an `@evidenceExclude` target allowed
+ * by its reference policy, acknowledges its selected node and every selected
+ * descendant. A reference selector still defines which descendants are
+ * obligations; an unselected ancestor remains addressable as their aggregate
+ * scope.
+ *
+ * A file evidence target is its path relative to the reference's root, or the
+ * project root when none is declared, with `/` separators. A declaration may
+ * spell those separators as `/` or `\`. A heading target appends its anchor,
+ * such as `docs/orders.md#create-order`. An explicit `{#anchor}` suffix wins.
+ * Its anchor must start with an ASCII letter or digit and may then contain
+ * ASCII letters, digits, `.`, `_`, `:`, and `-`.
+ *
+ * Without an explicit anchor, the heading becomes a lowercase slug: letters,
+ * numbers, and `_` remain; whitespace and `-` collapse to `-`; other
+ * punctuation is removed. Two selected headings that produce the same target
+ * are ambiguous and need distinct explicit anchors.
+ *
+ * Targets are one whitespace-delimited declaration token. A Markdown source
+ * path therefore cannot contain whitespace; the rule reports such a file with a
+ * rename diagnostic instead of creating an impossible obligation.
+ *
+ * @evidence contracts/common.md#principled-implementation The literal union represents exactly the supported file and ATX H1-H4 outline nodes; explicit anchors and generated slugs address those nodes under the documented target grammar.
+ * @evidence contracts/common.md#clear-and-simple-design One shared outline vocabulary serves both declaration hosts and reference units without introducing a separate enum or parser-node facade.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported heading forms and whitespace-containing source addresses are stated limitations rather than silently fabricated targets.
+ * @evidence contracts/common.md#meaningful-documentation The comment gives supported headings, containment, anchor precedence, slug construction and address limitations in distinct paragraphs before the tags.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type lists Markdown unit kinds and names no path, file, filesystem or process.
+ */
+export type TtscEvidenceGraphMarkdownSymbol = "file" | "h1" | "h2" | "h3" | "h4";

package/lib/{typings → structures}/TtscEvidenceGraphPrismaSymbol.d.ts

@@ -34,5 +34,11 @@
  * claim may separately accept `@evidenceExclude` in an unattached top-level
  * triple-slash run in a matching file; that carrier has no Prisma symbol and
  * never hosts `@evidence`.
+ *
+ * @evidence contracts/common.md#principled-implementation Models, stored fields and relation fields match Prisma's parsed datamodel distinctions; views share model shape while enums and other schema settings intentionally have no graph unit.
+ * @evidence contracts/common.md#clear-and-simple-design The three-value union is reused on both sides of the graph and leaves parsing, namespacing and address construction to their owning operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Relation classification comes from the parser rather than an attribute-presence heuristic that would miss inverse relation fields.
+ * @evidence contracts/common.md#meaningful-documentation Distinct paragraphs explain semantic classification, containment, prisma-prefixed targets, cross-file identity and unsupported schema constructs.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type lists Prisma unit kinds and names no path, file, filesystem or process.
  */
 export type TtscEvidenceGraphPrismaSymbol = "model" | "column" | "relation";

package/lib/{typings → structures}/TtscEvidenceGraphTypeScriptSymbol.d.ts

@@ -94,5 +94,11 @@
  * `@evidenceExclude` when its file belongs to a claim, even when that claim's
  * selector omits its kind. The selector still controls `@evidence`; an
  * unsupported or unexported declaration carries neither form.
+ *
+ * @evidence contracts/common.md#principled-implementation The three semantic kinds distinguish types, callable contracts and data contracts using the documented syntactic host rules; enums, accessors and hidden members remain outside those rules.
+ * @evidence contracts/common.md#clear-and-simple-design A single literal union is shared by claims, references and documentation selection, avoiding divergent kind vocabularies across rules.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification follows declared syntax and public identity rather than guessing callable aliases with an unavailable checker or special-casing a consumer's declarations.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains callable versus data classification, containment, export aliases, type-only visibility and exact addressing so users can select and cite contracts without inferring the parser.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type lists TypeScript unit kinds and names no path, file, filesystem or process.
  */
 export type TtscEvidenceGraphTypeScriptSymbol = "type" | "function" | "property";

package/lib/structures/index.d.ts

@@ -11,3 +11,7 @@ export * from "./ITtscEvidenceGraphReferenceBase";
 export * from "./ITtscEvidenceGraphSwaggerReference";
 export * from "./ITtscEvidenceGraphTypeScriptClaim";
 export * from "./ITtscEvidenceGraphTypeScriptReference";
+export * from "./ITtscEvidenceRules";
+export * from "./TtscEvidenceGraphMarkdownSymbol";
+export * from "./TtscEvidenceGraphPrismaSymbol";
+export * from "./TtscEvidenceGraphTypeScriptSymbol";

package/lib/structures/index.js

@@ -27,3 +27,7 @@ __exportStar(require("./ITtscEvidenceGraphReferenceBase"), exports);
 __exportStar(require("./ITtscEvidenceGraphSwaggerReference"), exports);
 __exportStar(require("./ITtscEvidenceGraphTypeScriptClaim"), exports);
 __exportStar(require("./ITtscEvidenceGraphTypeScriptReference"), exports);
+__exportStar(require("./ITtscEvidenceRules"), exports);
+__exportStar(require("./TtscEvidenceGraphMarkdownSymbol"), exports);
+__exportStar(require("./TtscEvidenceGraphPrismaSymbol"), exports);
+__exportStar(require("./TtscEvidenceGraphTypeScriptSymbol"), exports);

package/native/base.go

@@ -3,7 +3,6 @@ package evidence
 import (
   "errors"
   "io/fs"
-  "os"
   "path"
   "path/filepath"
   "sort"
@@ -28,6 +27,7 @@ import (
 // does: moving the base moves the address space with it (`graph.go`,
 // `materializePackageGlobReference`).
 type populationBase struct {
+  inputs evidenceInputReader
   // Absolute is the canonical directory, and the identity two populations are
   // judged the same base by.
   Absolute string
@@ -226,9 +226,11 @@ func resolveGraphBases(root string, config *graphConfig) {
   for claimIndex := range config.Claims {
     claim := &config.Claims[claimIndex]
     claim.Base = resolvePopulationBase(root, claim.Root)
+    claim.Base.inputs = config.inputs
     for referenceIndex := range claim.References {
       reference := &claim.References[referenceIndex]
       reference.Base = resolvePopulationBase(root, reference.Root)
+      reference.Base.inputs = config.inputs
     }
   }
 }
@@ -288,13 +290,14 @@ func configuredBases(config graphConfig, kind artifactKind) []populationBase {
 //
 // The absolute fallback belongs to the default base alone, which is the only
 // base with no declared spelling, and the project root is then the only thing
-// left to name. Of the four callers, two reach it: `unlistableBaseProblem` and
-// `unresolvedBaseProblem`, both of which a base with no declared root can arrive
-// at. `describePopulation` returns on the default base before it names anything,
-// and `describeBaseDirectoryProblem` is only ever entered through
-// `baseDirectoryProblem`, which does the same. Neither of the two that reach it
-// asks for an edit to a property that is not there, which is what makes the
-// spelling usable where no property exists.
+// left to name. `unlistableBaseProblem`, `unresolvedBaseProblem`, and the two
+// rooted TypeScript reference messages can arrive there with a default base,
+// because `root: "."` resolves back onto the project root.
+// `describePopulation` returns on the default base before it names anything, and
+// `describeBaseDirectoryProblem` is only ever entered through
+// `baseDirectoryProblem`, which does the same. None of the callers that reach
+// the fallback asks for an edit to a property that is not there, which is what
+// makes the spelling usable where no property exists.
 func populationRootLabel(base populationBase) string {
   if base.Declared == "" {
     return filepath.ToSlash(base.Absolute)
@@ -322,7 +325,7 @@ func baseDirectoryProblem(base populationBase, kind artifactKind) string {
   if base.Default {
     return ""
   }
-  info, err := os.Stat(base.Absolute)
+  info, err := base.inputs.Stat(base.Absolute)
   if err == nil && info.IsDir() {
     return ""
   }
@@ -349,7 +352,7 @@ func baseDirectoryProblem(base populationBase, kind artifactKind) string {
   // is that a path means the same thing on both.
   occupied := err == nil
   if errors.Is(err, fs.ErrNotExist) {
-    if _, linkErr := os.Lstat(base.Absolute); linkErr == nil {
+    if _, linkErr := base.inputs.Lstat(base.Absolute); linkErr == nil {
       occupied = true
     }
   }
@@ -510,8 +513,7 @@ func describeBaseDirectoryProblem(
 // Every component is resolved, not only the leaf. A link on an ancestor is
 // exactly what `os.Lstat` of the leaf cannot see, and it is the shape a package
 // manager installs: the workspace dependency is the link and the root an author
-// declares is a directory inside it. Resolving only the leaf left that silent,
-// which is what #1269 recorded.
+// declares is a directory inside it. Resolving only the leaf leaves that silent.
 //
 // The answer is verified rather than trusted, at every component and not only
 // at the last. `resolveLinkedDirectory` gives up after a fixed number of hops
@@ -529,19 +531,18 @@ func describeBaseDirectoryProblem(
 // A base that is not a link costs one `os.Lstat` per path component plus one
 // for this answer, where resolving the leaf alone cost two. It is paid per call
 // rather than per file, and the call count is the graph's own shape rather than
-// this function's: claim-side populations are materialized before the whole
-// configuration, so a base is asked once for each load it appears in. That is
-// at most twice for a Markdown or Prisma claim base and once for its reference
-// bases, and twice those numbers for TypeScript, whose gate asks beside the
+// this function's. Markdown captures the first resolution for each base within
+// one Check. Prisma resolves each load, at most twice for a claim base and once
+// for a reference base. TypeScript asks twice those numbers: its gate asks beside the
 // pass that builds its match table and whose governance pass builds one more
 // from the configuration as declared. All of it stays off the loop this feeds,
 // which is every source file of the project.
 func resolvedBaseDirectory(base populationBase) (string, bool) {
-  from, resolved := resolveLinkedPath(base.Absolute)
+  from, resolved := resolveLinkedPath(base.Absolute, base.inputs)
   if !resolved {
     return from, false
   }
-  info, err := os.Lstat(from)
+  info, err := base.inputs.Lstat(from)
   return from, err == nil && info.IsDir()
 }
 
@@ -564,9 +565,10 @@ func resolvedBaseDirectory(base populationBase) (string, bool) {
 //
 // A component whose chain outran the resolver ends the walk. Joining the rest
 // onto it would produce a path the filesystem opens and every string
-// comparison misses, which is #1269 exactly, one component further up than the
-// case that opened it.
-func resolveLinkedPath(absolute string) (string, bool) {
+// comparison misses, which is the same silent failure as an unresolved leaf, one component
+// further up.
+func resolveLinkedPath(absolute string, readers ...evidenceInputReader) (string, bool) {
+  inputs := inputReader(readers)
   volume := filepath.VolumeName(absolute)
   rest := absolute[len(volume):]
   current := volume + string(filepath.Separator)
@@ -576,7 +578,7 @@ func resolveLinkedPath(absolute string) (string, bool) {
       continue
     }
     walked = true
-    resolved, settled := resolveLinkedDirectory(filepath.Join(current, segment))
+    resolved, settled := resolveLinkedDirectory(filepath.Join(current, segment), inputs)
     if !settled {
       return filepath.FromSlash(resolved), false
     }
@@ -748,7 +750,7 @@ func unreadableWalkEntryProblem(
 // path such as `C:docs` is not absolute by the path API yet resolves against
 // whatever directory that drive is currently on, so it names a different
 // location on two machines while looking superficially safe — the rationale
-// `glob_honors_public_path_contract_test.go` records for the same rejection in
+// `glob_rejects_windows_drive_paths_test.go` records for the same rejection in
 // `files`.
 //
 // `..` is accepted here, and that is the whole point of the property. It is

package/native/bridge_trace.go

@@ -0,0 +1,348 @@
+package evidence
+
+import (
+  "encoding/json"
+  "errors"
+  "io"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "runtime"
+  "strconv"
+  "strings"
+  "sync"
+  "syscall"
+  "time"
+)
+
+const evidenceTraceLimit = 256 * 1024 * 1024
+const evidenceTraceFailureReserve = 4096
+
+var evidenceTraceOnce sync.Once
+var evidenceTraceSink *evidenceTraceWriter
+
+// evidenceTraceWriter owns one private opt-in measurement stream, never a
+// product reply or a cache. Its mutex serializes counters, budget and appends.
+// Files live in the coordinator's existing absolute scratch directory; the
+// coordinator retains them until actual processes join and inspection ends.
+//
+// Principled implementation: A process PID plus CreateTemp nonce separates
+// concurrent writers; exclusive native creation establishes stream identity.
+// Clear and simple design: One writer owns every event and payload budget.
+// Prohibited implementation shortcuts: Disabled observation does no IO, and
+// capture failures neither supply results nor change protocol or cache values.
+// Meaningful documentation: Ownership, activation, limits and failure effects
+// are stated here; this private type is not a product configuration surface.
+// OS-neutral implementation: Native absolute paths and Go file operations own
+// the side channel without a shell or assumptions about filesystem case.
+// Bound retention and release resources: No file handle stays open between
+// writes. Total bytes are capped; file retention belongs to the coordinator.
+type evidenceTraceWriter struct {
+  mutex     sync.Mutex
+  directory string
+  path      string
+  instance  string
+  pid       int
+  ordinal   uint64
+  sequence  uint64
+  bytes     int
+}
+
+// evidenceBridgeTrace pairs one actual lookup with its subsequent Run/parse.
+// An unpaired direct normalizer call explicitly lacks a native lookup value.
+// It retains only the writer and ordinal, not replies or historical requests.
+type evidenceBridgeTrace struct {
+  writer       *evidenceTraceWriter
+  invocation   string
+  kind         string
+  nativeLookup bool
+}
+
+// evidenceTraceEvent is the shared schema-v1 envelope. PID names the observed
+// subject, while WriterPID/Instance identify the writer. A pre-start failure
+// has PID zero; an invocation does not imply an actual process or Program.
+type evidenceTraceEvent struct {
+  Schema     int    `json:"schema"`
+  Event      string `json:"event"`
+  WriterPID  int    `json:"writerPid"`
+  Instance   string `json:"instance"`
+  Sequence   uint64 `json:"sequence"`
+  At         string `json:"at"`
+  Invocation string `json:"invocation"`
+  PID        int    `json:"pid"`
+  Data       any    `json:"data"`
+}
+
+// newEvidenceBridgeTrace allocates a process-local invocation only when the
+// coordinator opted in before the first request. The sink is initialized once
+// per process, so later environment edits cannot split one writer's budget.
+//
+// Principled implementation: The ordinal is allocated under the writer mutex;
+// it is private trace context and is never marshaled into a product request.
+// Clear and simple design: The existing callers carry this optional pointer.
+// Prohibited implementation shortcuts: A missing/invalid sink disables capture
+// but does not fabricate a successful event; the coordinator detects absence.
+// Efficient algorithms: Initialization is once; each allocation is constant
+// work and retains no request content or completed invocation map.
+// Reuse equivalent work: The same writer/budget serves both bridge owners;
+// product computations and cache admission remain with their existing owners.
+// Bound retention and release resources: Only counters/mutex/path persist.
+// Initialization closes its exclusive stream handle before returning.
+// OS-neutral implementation: The opt-in path must be an existing absolute
+// native directory. Helper-owned temp nonces and PIDs do not encode source paths.
+func newEvidenceBridgeTrace(kind string) *evidenceBridgeTrace {
+  evidenceTraceOnce.Do(func() {
+    directory := os.Getenv("TTSC_E2E_TRACE")
+    if directory == "" || !filepath.IsAbs(directory) {
+      return
+    }
+    info, err := os.Stat(directory)
+    if err != nil || !info.IsDir() {
+      return
+    }
+    writer := &evidenceTraceWriter{directory: directory, pid: os.Getpid()}
+    prefix := strconv.Itoa(writer.pid) + "-"
+    file, err := os.CreateTemp(directory, prefix+"*.jsonl")
+    if err != nil {
+      return
+    }
+    writer.path = file.Name()
+    writer.instance = strings.TrimSuffix(strings.TrimPrefix(filepath.Base(writer.path), prefix), ".jsonl")
+    if err := file.Close(); err != nil {
+      return
+    }
+    evidenceTraceSink = writer
+  })
+  writer := evidenceTraceSink
+  if writer == nil {
+    return nil
+  }
+  writer.mutex.Lock()
+  writer.ordinal++
+  invocation := strconv.FormatUint(writer.ordinal, 10)
+  writer.mutex.Unlock()
+  return &evidenceBridgeTrace{writer: writer, invocation: invocation, kind: kind}
+}
+
+// record appends one observed event, with failures reported only to the trace.
+// The caller's actual values are serialized, never generated as an oracle.
+// Each event's transient encoding costs its data size; no event is retained.
+func (trace *evidenceBridgeTrace) record(event string, pid int, data map[string]any) {
+  if trace == nil {
+    return
+  }
+  writer := trace.writer
+  writer.mutex.Lock()
+  defer writer.mutex.Unlock()
+  if err := writer.append(trace.invocation, event, pid, data, false); err != nil {
+    // One bounded failure attempt avoids recursion when the sink itself fails.
+    _ = writer.append(trace.invocation, "trace-integrity-failure", writer.pid,
+      map[string]any{"bridge": trace.kind, "operation": event, "error": err.Error()}, true)
+  }
+}
+
+// append is called with the writer lock held. It charges attempted bytes before
+// IO, bounds the complete stream, and closes the append handle on every path.
+// A reserved tail permits an integrity event after the ordinary budget ends.
+// Core invocation includes the writer instance; the private ordinal remains
+// unchanged for payload filenames and all events use this same boundary.
+// A transient shallow copy preserves caller data while binding the actual Go
+// writer runtime; it does not identify the Node child or installed artifact.
+// It never prints or returns an error to the product operation.
+func (writer *evidenceTraceWriter) append(invocation string, event string, pid int, data map[string]any, failure bool) error {
+  writer.sequence++
+  observedData := make(map[string]any, len(data)+1)
+  for key, value := range data {
+    observedData[key] = value
+  }
+  observedData["writerRuntime"] = runtime.Version()
+  encoded, err := json.Marshal(evidenceTraceEvent{
+    Schema: 1, Event: event, WriterPID: writer.pid, Instance: writer.instance,
+    Sequence: writer.sequence, At: time.Now().UTC().Format(time.RFC3339Nano),
+    Invocation: writer.instance + ":" + invocation, PID: pid, Data: observedData,
+  })
+  if err != nil {
+    return err
+  }
+  encoded = append(encoded, '\n')
+  limit := evidenceTraceLimit - evidenceTraceFailureReserve
+  if failure {
+    limit = evidenceTraceLimit
+  }
+  if len(encoded) > limit-writer.bytes {
+    return errors.New("Evidence trace writer byte budget exceeded")
+  }
+  writer.bytes += len(encoded)
+  file, err := os.OpenFile(writer.path, os.O_WRONLY|os.O_APPEND, 0o600)
+  if err != nil {
+    return err
+  }
+  count, writeErr := file.Write(encoded)
+  closeErr := file.Close()
+  if writeErr != nil {
+    return writeErr
+  }
+  if count != len(encoded) {
+    return io.ErrShortWrite
+  }
+  return closeErr
+}
+
+// capture saves exactly the existing bounded stdout bytes, not reconstructed
+// JSON. A product overflow makes the observation too-large even if its buffered
+// prefix was saved; it cannot serve as a complete wire oracle. Payload names
+// contain only writer-owned identities. No buffer survives this invocation.
+//
+// Principled implementation: Raw bytes and capture status are separate; a
+// prefix, IO failure or budget refusal never becomes a successful observation.
+// Efficient algorithms: One write of the existing slice adds no raw-byte copy.
+// Bound retention and release resources: The existing product limit and 64MiB
+// observation cap bound each payload; the writer's shared 256MiB budget bounds
+// all files/events. Exclusive creation and immediate close own every handle.
+// OS-neutral implementation: filepath.Join and Go IO resolve only a helper-
+// owned basename within the established native scratch directory.
+func (trace *evidenceBridgeTrace) capture(content []byte, productLimit int, exceeded bool) map[string]any {
+  if trace == nil {
+    return nil
+  }
+  writer := trace.writer
+  writer.mutex.Lock()
+  defer writer.mutex.Unlock()
+  metadata := map[string]any{"observedByteLength": len(content), "capture": "complete", "bufferedOnly": true}
+  name := strconv.Itoa(writer.pid) + "-" + writer.instance + "-" + trace.invocation + "-stdout.bin"
+  if productLimit > 64*1024*1024 {
+    productLimit = 64 * 1024 * 1024
+  }
+  charge := len(content)
+  if charge == 0 {
+    // Empty payloads still consume a file identity; a byte-only zero charge
+    // would allow unlimited empty files after the regular budget was exhausted.
+    charge = 1
+  }
+  if len(content) > productLimit || charge > evidenceTraceLimit-evidenceTraceFailureReserve-writer.bytes {
+    metadata["capture"] = "too-large"
+    _ = writer.append(trace.invocation, "trace-integrity-failure", writer.pid,
+      map[string]any{"bridge": trace.kind, "operation": "stdout-capture", "error": "Evidence trace payload budget exceeded"}, true)
+    return metadata
+  }
+  writer.bytes += charge
+  file, err := os.OpenFile(filepath.Join(writer.directory, name), os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+  if err == nil {
+    var count int
+    count, err = file.Write(content)
+    closeErr := file.Close()
+    if err == nil && count != len(content) {
+      err = io.ErrShortWrite
+    }
+    if err == nil {
+      err = closeErr
+    }
+  }
+  metadata["path"] = name
+  if err != nil {
+    metadata["capture"] = "IO-failed"
+    metadata["error"] = err.Error()
+  } else if exceeded {
+    metadata["capture"] = "too-large"
+  }
+  if err != nil || exceeded {
+    _ = writer.append(trace.invocation, "trace-integrity-failure", writer.pid,
+      map[string]any{"bridge": trace.kind, "operation": "stdout-capture", "capture": metadata}, true)
+  }
+  return metadata
+}
+
+// attempt observes the actual prepared command without changing its streams
+// or executable. The timestamp is a lower call bound, not an OS spawn time.
+// Observation IO contributes opt-in overhead inside the unchanged timeout.
+func (trace *evidenceBridgeTrace) attempt(command *exec.Cmd) time.Time {
+  if trace == nil {
+    return time.Time{}
+  }
+  lower := time.Now().UTC()
+  trace.record("process-attempt", 0, map[string]any{
+    "bridge": trace.kind, "argv": command.Args, "cwd": command.Dir,
+    "executable": command.Path, "startLowerBound": lower.Format(time.RFC3339Nano),
+    "started": false, "observation": "before-Cmd.Run",
+  })
+  return lower
+}
+
+// preparationFailure records a real failure before any Run was attempted.
+// Missing stdout is absence, not an invented empty JSON response. This event
+// cannot count a child start or successful parse and never replaces the error.
+func (trace *evidenceBridgeTrace) preparationFailure(err error) {
+  if trace == nil {
+    return
+  }
+  trace.record("bridge-result", trace.writer.pid, map[string]any{
+    "bridge": trace.kind, "nativeLookup": trace.nativeLookup, "preparationError": err.Error(),
+    "stdout":           map[string]any{"capture": "absent", "observedByteLength": 0},
+    "unmarshalOutcome": "not-attempted", "runAttempted": false,
+  })
+}
+
+// result observes completed Run and unmarshal boundaries. The stdout capture
+// is the original buffered slice; outcome IDs come only from successful actual
+// native unmarshal. ProcessState is a native observation, not descendant proof.
+// Signal is read only when the native Sys value exposes supported signal
+// methods. Unavailable authority is distinct from an observed nonsignal exit;
+// native ProcessState text is retained without parsing it into a guessed signal.
+func (trace *evidenceBridgeTrace) result(command *exec.Cmd, stdout *limitedBuffer, stderr *limitedBuffer,
+  start time.Time, end time.Time, runErr error, parseOutcome string, parseErr error,
+  documents []string, problems []string,
+) {
+  if trace == nil {
+    return
+  }
+  pid := 0
+  if command.Process != nil {
+    pid = command.Process.Pid
+  }
+  var status *int
+  var signal any
+  var signalNumber any
+  signalObserved := false
+  processState := ""
+  if command.ProcessState != nil {
+    value := command.ProcessState.ExitCode()
+    status = &value
+    processState = command.ProcessState.String()
+    if state, ok := command.ProcessState.Sys().(interface {
+      Signaled() bool
+      Signal() syscall.Signal
+    }); ok {
+      signalObserved = true
+      if state.Signaled() {
+        signal = state.Signal().String()
+        signalNumber = int(state.Signal())
+      }
+    }
+  }
+  message := ""
+  if runErr != nil {
+    message = runErr.Error()
+  }
+  trace.record("process-result", pid, map[string]any{
+    "bridge": trace.kind, "argv": command.Args, "cwd": command.Dir, "executable": command.Path,
+    "started": command.Process != nil, "exitObserved": command.ProcessState != nil,
+    "status": status, "signal": signal, "signalNumber": signalNumber, "signalObserved": signalObserved,
+    "nativeProcessState": processState, "error": message, "join": "Cmd.Run-return",
+    "startLowerBound": start.Format(time.RFC3339Nano), "startUpperBound": end.Format(time.RFC3339Nano),
+    "stdoutLimitExceeded": stdout.Exceeded, "stderrLimitExceeded": stderr.Exceeded,
+  })
+  metadata := map[string]any{"capture": "absent", "observedByteLength": 0}
+  if command.Process != nil {
+    metadata = trace.capture(stdout.Bytes(), stdout.Limit, stdout.Exceeded)
+  }
+  message = ""
+  if parseErr != nil {
+    message = parseErr.Error()
+  }
+  trace.record("bridge-result", trace.writer.pid, map[string]any{
+    "bridge": trace.kind, "nativeLookup": trace.nativeLookup,
+    "runAttempted": true,
+    "stdout":       metadata, "unmarshalOutcome": parseOutcome, "unmarshalError": message,
+    "documentIds": documents, "problemIds": problems,
+  })
+}