@descryy/runtime-contracts 0.2.0 → 0.3.0

package/dist/evidence.js

@@ -1,26 +1,16 @@
 /**
- * Evidence contract.
+ * Evidence contract, per §13 (evidence model), plus `evidenceId` (the
+ * ID-reference pattern Execution uses) and `stackTrace`. `confidence` is
+ * the resolution-honesty axis (§9), never conflated with environment
+ * fidelity (lives on Execution/Capability). Redaction per §25.
  *
- * Field list is verbatim from `documents/descry-runtime-plan.md` §13
- * (Evidence model), plus `evidenceId` (needed for the ID-reference pattern
- * Execution uses) and `stackTrace` (structured detail for the plan's
- * STACK_TRACE event type, per Agent 3's stack-fidelity finding below). Also
- * grounded in the architecture doc's §18.2 (evidence bundling —
- * screenshot/console/network/backend log, "none of these individually
- * would have been enough"), §17.2 (the observe stream), §9 (the three
- * confidence axes — this file's `confidence` field is the resolution-
- * honesty axis, never conflated with environment fidelity, which lives on
- * Execution/Capability instead) and §25 (redaction before storage).
- *
- * Static facts and runtime observations stay separate. Evidence never
- * embeds a graph node's data — `graphNodeId` is a reference into
- * @descryy/ir's identity scheme, resolved by whoever reads it. This file
- * does not, and must not, redefine graph identity or storage.
+ * Evidence never embeds a graph node's data — `graphNodeId` is a reference
+ * into @descryy/ir's identity scheme, resolved by whoever reads it.
  */
 export const EVIDENCE_SOURCES = [
-    // Also the source for VIDEO (runtime-event.ts) -- SCREENSHOT's own
-    // precedent: a captured-artifact *kind* is a RuntimeEventType, not a
-    // watched *domain*, so it reuses this entry rather than adding one.
+    // Also the source for VIDEO (runtime-event.ts): a captured-artifact
+    // *kind* is a RuntimeEventType, not a watched domain, so it reuses this
+    // entry rather than adding one.
     "browser-dom",
     "browser-console",
     "browser-network",
@@ -28,86 +18,53 @@ export const EVIDENCE_SOURCES = [
     "backend-process",
     "process-exit",
     "http-response-payload",
-    /** §17 (Test Runner Support, RT-073): TEST_STARTED/PASSED/FAILED, from a runner's own structured reporter output -- never parsed from printed prose (see `packages/test-runner`'s own module doc for why). */
+    /** RT-073: TEST_STARTED/PASSED/FAILED from a runner's own structured reporter output, never parsed from printed prose. */
     "test-runner",
     /**
-     * RT-219 (runtime self-observability). Every other value in this list
-     * names a domain the runtime is *watching* (a browser, a backend
-     * process, a test runner). `"harness"` names the opposite direction: the
-     * runtime observing **itself** -- a collector/orchestrator/correlator/
-     * evidence-store operation that broke on its own terms, not on the
-     * observed application's. DEC-273's `automation` fault value (Descry's
-     * own harness broke, not the app) had no evidence this repo could point
-     * at to positively establish it; this is that evidence's tag.
-     *
-     * Deliberately a new `source`, not a repurposing of `COLLECTOR_ERROR`
-     * alone. `COLLECTOR_ERROR` already existed (`runtime-event.ts`) for "the
-     * observer failed, not the observed system," but every existing emitter
-     * stamps it with the *domain* source it was observing when it died
-     * (`"backend-process"` for a log collector's consume loop, etc.) --
-     * correct for a collector's own mid-stream failure, but it means a
-     * COLLECTOR_ERROR row is not on its own distinguishable from ordinary
-     * domain evidence by `source` alone, only by `eventType`. A harness
-     * component with no domain of its own (the orchestrator's own
-     * `Promise.all` around `collector.start()`, for instance) has no honest
-     * domain source to reuse, and reusing one anyway would make a self-
-     * failure look like it came from the thing being watched. `"harness"`
-     * is that missing, honestly-named source -- additive, not a
-     * retag of any existing emitter.
+     * RT-219. Every other source names a domain being watched; `"harness"`
+     * is the runtime observing itself — a collector/orchestrator/correlator
+     * operation that broke on its own terms, not the app's. Not
+     * `COLLECTOR_ERROR`: that's stamped with the domain source being watched
+     * when it died, so it's indistinguishable from domain evidence by
+     * `source` alone.
      */
     "harness",
     /**
-     * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency`
-     * mechanism (`@descryy/runtime-controller`'s
-     * `checkDependencyVersions`): a structural comparison finding the
-     * project's lockfile-declared version of a direct dependency does not
-     * match the version actually installed under `node_modules` at
-     * execution time. Same standing as `"harness"` -- a fact the runtime
-     * establishes about its own execution environment, not an observation of
-     * the domain under test, so `signal` stays `null` for records carrying
-     * this source (`classifyEvidenceChannel` fails it closed, same as
-     * `"harness"`).
+     * `checkDependencyVersions`: lockfile-declared dependency version does
+     * not match what's actually installed at execution time. Same standing
+     * as `"harness"` — a fact about the runtime's own environment, so
+     * `signal` stays null for these records (`classifyEvidenceChannel` fails
+     * closed).
      */
     "dependency-check",
     /**
-     * The same ruling's `environment` mechanism
-     * (`checkEnvironmentVersion`): a structural comparison finding the
-     * project's declared runner version (`.nvmrc`/`package.json
-     * engines.node`) does not match the runner version actually observed at
-     * execution (`process.version`). Same standing as `"dependency-check"`.
+     * `checkEnvironmentVersion`: declared runner version (`.nvmrc`/`engines.node`)
+     * does not match the observed runner (`process.version`). Same standing
+     * as `"dependency-check"`.
      */
     "environment-check",
 ];
 export const REDACTION_STATUSES = ["not-required", "redacted", "pending-redaction"];
 /**
- * Source-location reliability is not one axis with a probabilistic middle —
- * it is three structurally different classes (Agent 3's finding), and
- * conflating them into a single confidence number loses exactly the
+ * Three structurally different classes, not one axis with a probabilistic
+ * middle — collapsing them into a confidence number would lose the
  * information a reader needs to judge a location claim:
  *
- * - self-contained: the location came from the process's own captured
- *   state (a Python traceback, a Ruby backtrace, a Go `recover()` frame).
- *   Accurate when captured; the risk is *capture completeness*, not
+ * - self-contained: from the process's own captured state (Python/Ruby
+ *   traceback, Go `recover()` frame). Risk is capture completeness, not
  *   correctness.
  * - debug-info-present / debug-info-stripped: a binary's own line-number
- *   table (Java/Kotlin). A binary outcome — there is no partial case.
- * - side-artifact-resolved / side-artifact-stale / side-artifact-missing:
- *   resolution went through a separate file that can drift or vanish
- *   (a Node source map, a C# PDB, a Swift dSYM). "We mapped it and it's
- *   right" and "we mapped it through an artifact that may be stale" are
- *   different confidence claims, and this type is what lets Evidence say
- *   which one it is instead of reporting both identically.
- * - self-contained-eval-line: same mechanism as self-contained — the
- *   process's own captured backtrace, nothing translated through a side
- *   artifact — but the *line* does not index the named file. Ruby's
- *   `instance_eval`/`eval` frames print a synthetic path,
- *   `(eval at file.rb:12):1`, where `12` is where `eval` was called from
- *   but `1` counts lines within the evaluated string, not within
- *   `file.rb`. Opening `file.rb` at line `1` shows unrelated code, so this
- *   is not a plain self-contained claim; it is not a side-artifact claim
- *   either, since nothing was resolved through a separate file. See
- *   `packages/adapter-ruby/src/ruby-source-location-resolver.ts` for the
- *   one producer of this value.
+ *   table (Java/Kotlin) — binary outcome, no partial case.
+ * - side-artifact-resolved / -stale / -missing: resolved through a
+ *   separate file that can drift or vanish (source map, PDB, dSYM) —
+ *   "mapped and right" vs. "mapped through something that may be stale"
+ *   are different claims.
+ * - self-contained-eval-line: same mechanism as self-contained, but the
+ *   line doesn't index the named file. Ruby's `eval` frames print
+ *   `(eval at file.rb:12):1` — `12` is the eval call site, `1` counts
+ *   lines in the evaluated string, not in `file.rb`. Neither plain
+ *   self-contained nor side-artifact. See
+ *   `packages/adapter-ruby/src/ruby-source-location-resolver.ts`.
  */
 export const SOURCE_LOCATION_RELIABILITIES = [
     "self-contained",
@@ -119,61 +76,31 @@ export const SOURCE_LOCATION_RELIABILITIES = [
     "self-contained-eval-line",
 ];
 /**
- * Whether a captured stack reflects the actual logical call chain is a
- * third, orthogonal axis (Agent 3's finding): concurrency models
- * (coroutines, goroutines, async/await, tokio tasks) can capture a stack
- * successfully while structurally breaking the "reflects the logical
- * caller" guarantee. That is not a low-confidence stack — it is a
- * different kind of evidence, and gets its own field rather than a lower
- * number folded into `confidence`.
+ * Orthogonal to `confidence`: concurrency models (coroutines, goroutines,
+ * async/await, tokio tasks) can capture a stack successfully while
+ * structurally breaking the "reflects the logical caller" guarantee. Not
+ * a low-confidence stack — a different kind of evidence, own field.
  */
 export const STACK_FIDELITIES = ["synchronous", "concurrency-fragmented", "unavailable"];
 /**
- * Which `SourceLocation` an `Evidence` carries for a given stack — one rule,
- * in one place, for every collector that turns a trace into evidence.
- *
- * ## Why it lives in the contract rather than in each collector
- *
- * It was written twice. `backend-observation`'s collector was moved onto
- * `primaryFrameIndex` (RT-083); `browser`'s console collector kept its own
- * `frames[0]` copy and nothing failed, because V8 reports
- * `primaryFrameIndex: 0` and the two rules agree there **by coincidence**.
- * A copied rule is a rule that will hold in one of them, and this one held
- * in one of them for exactly as long as one runtime was involved.
- *
- * ## The empty location, which is the part that is not obvious
+ * Which `SourceLocation` an `Evidence` carries for a stack — one rule, one
+ * place, for every collector (was written twice and only agreed by
+ * coincidence, RT-083, since V8 always reports index 0).
  *
- * `StackFrame.location` is not nullable, so a frame that resolved nothing
- * still carries a `SourceLocation` — one whose `file`, `line` and
- * `functionName` are all null. Returning it would set
- * `Evidence.sourceLocation` to a non-null object naming nothing, and
- * `evidence-package.ts` censuses located evidence with `sourceLocation !==
- * null`. An unsymbolicated crash would be counted as *located* in the very
- * artifact handed to a model — RT-124's shape (a thing reported as the thing
- * it failed to be), one field over.
+ * `StackFrame.location` isn't nullable, so an unresolved frame still
+ * carries a `SourceLocation` with everything null. Returning it as-is
+ * would make `evidence-package.ts`'s `sourceLocation !== null` census
+ * count an unsymbolicated crash as located (measured, RT-126: a Swift CI
+ * crash with an address-only backtrace).
  *
- * Measured rather than imagined (Lane C, RT-126): on a CI runner a real
- * Swift crash produced a real three-thread backtrace in which every frame is
- * address-only — no symbol, no `at file:line`.
+ * Discriminator is `functionName`, not `file`: a stripped JVM frame and a
+ * Rust release frame both have null file but a real symbol, resolvable
+ * against the graph by name — keying on `file` would delete the location
+ * for every stripped build.
  *
- * ## The discriminator is `functionName`, not `file`
- *
- * A stripped JVM frame (`at com.example.Thrower.handler(Unknown Source)`)
- * and a Rust release frame both have a null file **and a real symbol**,
- * which `SourceLocation.file`'s own doc calls real evidence that still
- * resolves against the graph by name. `adapter-jvm` and `adapter-rust` each
- * assert exactly that. Keying emptiness on a null file would delete the
- * location for every stripped build in both languages — the case this type
- * was widened to express.
- *
- * ## Nothing is lost by returning null
- *
- * The frames stay on `Evidence.stackTrace` with their raw text and their
- * `reliability`. "There was no stack" and "there was a stack that could name
- * nothing" therefore remain distinguishable **on the same record**, because
- * `stackTrace` separates them. That recoverability is the test for whether
- * nulling a field is honest degradation or information loss; here it is the
- * first.
+ * Nothing is lost by returning null: frames stay on `Evidence.stackTrace`
+ * with raw text and reliability, so "no stack" and "a stack naming
+ * nothing" stay distinguishable on the same record.
  */
 export function primaryFrameLocation(stackTrace) {
     if (stackTrace === null || stackTrace.frames.length === 0)
@@ -190,13 +117,10 @@ export function primaryFrameLocation(stackTrace) {
     return locationNamesNothing(location) ? null : location;
 }
 /**
- * True when a location identifies no place in any source.
- *
- * `column` is deliberately not consulted: a column is an offset into a line,
- * so with no line it names no position and cannot make an otherwise-empty
- * location informative. `reliability` and `resolvedVia` are not consulted
- * either — they record *why* nothing resolved, which describes the failure
- * rather than a place.
+ * True when a location identifies no place in any source. `column` isn't
+ * consulted — an offset into a null line names no position. `reliability`
+ * and `resolvedVia` aren't either — they record why nothing resolved, not
+ * a place.
  */
 export function locationNamesNothing(location) {
     return location.file === null && location.line === null && location.functionName === null;

package/dist/evidence.js.map

@@ -1 +1 @@
-{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,mEAAmE;IACnE,qEAAqE;IACrE,oEAAoE;IACpE,aAAa;IACb,iBAAiB;IACjB,iBAAiB;IACjB,aAAa;IACb,iBAAiB;IACjB,cAAc;IACd,uBAAuB;IACvB,8MAA8M;IAC9M,aAAa;IACb;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS;IACT;;;;;;;;;;;OAWG;IACH,kBAAkB;IAClB;;;;;;OAMG;IACH,mBAAmB;CACX,CAAC;AAGX,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,cAAc,EAAE,UAAU,EAAE,mBAAmB,CAAU,CAAC;AAG7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,gBAAgB;IAChB,oBAAoB;IACpB,qBAAqB;IACrB,wBAAwB;IACxB,qBAAqB;IACrB,uBAAuB;IACvB,0BAA0B;CAClB,CAAC;AAgDX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,aAAa,EAAE,wBAAwB,EAAE,aAAa,CAAU,CAAC;AAqIlG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAA6B;IAChE,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvE,MAAM,KAAK,GAAG,UAAU,CAAC,iBAAiB,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/E,MAAM,IAAI,UAAU,CAClB,qBAAqB,MAAM,CAAC,KAAK,CAAC,mBAAmB,UAAU,CAAC,MAAM,CAAC,MAAM,0BAA0B;YACrG,oGAAoG;YACpG,qGAAqG,CACxG,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC;IAC5D,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC1D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAwB;IAC3D,OAAO,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,YAAY,KAAK,IAAI,CAAC;AAC5F,CAAC"}
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,oEAAoE;IACpE,wEAAwE;IACxE,gCAAgC;IAChC,aAAa;IACb,iBAAiB;IACjB,iBAAiB;IACjB,aAAa;IACb,iBAAiB;IACjB,cAAc;IACd,uBAAuB;IACvB,0HAA0H;IAC1H,aAAa;IACb;;;;;;;OAOG;IACH,SAAS;IACT;;;;;;OAMG;IACH,kBAAkB;IAClB;;;;OAIG;IACH,mBAAmB;CACX,CAAC;AAGX,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,cAAc,EAAE,UAAU,EAAE,mBAAmB,CAAU,CAAC;AAG7F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,gBAAgB;IAChB,oBAAoB;IACpB,qBAAqB;IACrB,wBAAwB;IACxB,qBAAqB;IACrB,uBAAuB;IACvB,0BAA0B;CAClB,CAAC;AA6BX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,aAAa,EAAE,wBAAwB,EAAE,aAAa,CAAU,CAAC;AA0FlG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAA6B;IAChE,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvE,MAAM,KAAK,GAAG,UAAU,CAAC,iBAAiB,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/E,MAAM,IAAI,UAAU,CAClB,qBAAqB,MAAM,CAAC,KAAK,CAAC,mBAAmB,UAAU,CAAC,MAAM,CAAC,MAAM,0BAA0B;YACrG,oGAAoG;YACpG,qGAAqG,CACxG,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC;IAC5D,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAwB;IAC3D,OAAO,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,YAAY,KAAK,IAAI,CAAC;AAC5F,CAAC"}