@descryy/runtime-contracts 0.0.0

package/dist/evidence.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Evidence contract.
+ *
+ * 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.
+ */
+import type { RuntimeEventType } from "./runtime-event.ts";
+export declare const EVIDENCE_SOURCES: readonly ["browser-dom", "browser-console", "browser-network", "backend-log", "backend-process", "process-exit", "http-response-payload", "test-runner", "harness", "dependency-check", "environment-check"];
+export type EvidenceSource = (typeof EVIDENCE_SOURCES)[number];
+export declare const REDACTION_STATUSES: readonly ["not-required", "redacted", "pending-redaction"];
+export type RedactionStatus = (typeof REDACTION_STATUSES)[number];
+/**
+ * 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
+ * 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
+ *   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.
+ */
+export declare const SOURCE_LOCATION_RELIABILITIES: readonly ["self-contained", "debug-info-present", "debug-info-stripped", "side-artifact-resolved", "side-artifact-stale", "side-artifact-missing", "self-contained-eval-line"];
+export type SourceLocationReliability = (typeof SOURCE_LOCATION_RELIABILITIES)[number];
+export interface SourceLocation {
+    /**
+     * **Null when the runtime named no source file**, for the same reason
+     * `line` can be null and discovered by the same adapter.
+     *
+     * A stripped JVM frame is `at com.example.Thrower.handler(Unknown Source)`
+     * and a native one is `(Native Method)`: neither carries a filename. The
+     * method name is still real evidence and still resolves against the graph
+     * by symbol, so dropping such frames would delete an entire stack for a
+     * release build.
+     *
+     * The filename is **not** derived from the class name, though the JVM
+     * convention makes that look safe. Kotlin breaks it outright — a class
+     * `Foo` may be declared in `Bar.kt` — and this parser serves both
+     * languages, so the derivation would be right for one and wrong for the
+     * other. Null is the honest answer.
+     */
+    readonly file: string | null;
+    /**
+     * **Null when the runtime genuinely captured no line**, which is a real
+     * state rather than a failure to look — and one this type could not
+     * express until a JVM adapter existed to need it.
+     *
+     * A JVM class compiled without a `LineNumberTable` (`javac -g:none`, and
+     * the default for many release builds) prints
+     * `at com.example.Thrower.handler(Unknown Source)`: the class is real,
+     * the method is real, and there is no line. So is a `(Native Method)`
+     * frame. `reliability: "debug-info-stripped"` describes exactly that
+     * situation — meaning that while this field was required, that enum value
+     * could only ever be attached to a **fabricated** number. The type and
+     * the enum contradicted each other, and the type was wrong.
+     *
+     * A frame with no line is still real evidence: the symbol name alone
+     * resolves against the graph. Dropping such frames would discard an
+     * entire stack for a stripped build, which is the "we could not read it"
+     * case that must degrade honestly rather than vanish.
+     */
+    readonly line: number | null;
+    readonly column: number | null;
+    readonly functionName: string | null;
+    readonly reliability: SourceLocationReliability;
+    /** Set only for the side-artifact-* reliabilities — names the specific map/PDB/dSYM, so a stale-artifact finding is traceable to the file that drifted. Null otherwise. */
+    readonly resolvedVia: string | null;
+}
+/**
+ * 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`.
+ */
+export declare const STACK_FIDELITIES: readonly ["synchronous", "concurrency-fragmented", "unavailable"];
+export type StackFidelity = (typeof STACK_FIDELITIES)[number];
+export interface StackFrame {
+    readonly location: SourceLocation;
+    /** The frame's original, unparsed text — kept for audit even after structured parsing. */
+    readonly raw: string;
+}
+export interface StackTrace {
+    readonly fidelity: StackFidelity;
+    /**
+     * **Most-recent call first**, always — `frames[0]` is the innermost frame,
+     * the one where execution actually was. Every parser normalises to this;
+     * callers may rely on it.
+     *
+     * This was unstated while TypeScript was the only language, because V8
+     * emits this order natively and nothing had to convert. It is not a
+     * universal convention: a CPython traceback prints **oldest call first**,
+     * with the failing frame last, and so does a Java `printStackTrace` cause
+     * chain read naively. An adapter for such a runtime reverses during
+     * parsing — the ordering decision belongs in the language adapter, which
+     * knows its own runtime's convention, never in a consumer that would have
+     * to ask which language produced the trace to know which end to read.
+     *
+     * Getting this wrong is quiet rather than loud: the trace still has the
+     * right frames and the right count, and root-cause traversal simply
+     * points at whichever end of the call chain happens to be first —
+     * typically the process entry point instead of the failing line.
+     */
+    readonly frames: readonly StackFrame[];
+    /**
+     * Which frame is the **failure site** — the one a developer should be sent
+     * to. Usually `0`; not always, and the exceptions are not exotic.
+     *
+     * ## Why an index and not `frames[0]`
+     *
+     * `frames[0]` is reliably the *innermost* frame. On several runtimes the
+     * innermost frame is the runtime's own, sitting above the application's,
+     * and is therefore innermost and useless. Measured on live still-running
+     * servers (Lane C, RT-120/121):
+     *
+     * | runtime | `frames[0]` | the failure site |
+     * | --- | --- | --- |
+     * | Go, recovered `net/http` handler panic | `net/http.(*conn).serve.func1` at `server.go:1897` | several frames down |
+     * | Rust, threaded server | `__rustc::rust_begin_unwind` at `panicking.rs:698` | after five `std`/`core` frames |
+     *
+     * The JVM's `Caused by:` chains, C#'s `--- End of stack trace from previous
+     * location ---` and Kotlin's coroutine frames are the same shape.
+     *
+     * ## Why this is not a heuristic
+     *
+     * **Each runtime marks the boundary itself**, which is the entire reason
+     * this is expressible as an index rather than as a filter:
+     *
+     * - Go prints a `panic(` frame **only** when the stack was walked through a
+     *   recover — an unrecovered panic has none. Measured both ways.
+     * - Rust's header names the panic site with line *and column*, and exactly
+     *   one frame matches it.
+     *
+     * So the adapter that knows its runtime reads that runtime's own marker.
+     * Nothing above the IR boundary names a language, and nothing anywhere
+     * denylists a stdlib path — a path-shaped filter is the thing this field
+     * exists to make unnecessary, and it would break on any application that
+     * legitimately fails inside a library frame.
+     *
+     * ## Nothing is dropped
+     *
+     * Every frame stays in `frames`, including the unwinding frames above the
+     * failure site. This is a **view**, not a filter, which is what keeps
+     * `adapter-rust`'s standing decision intact — *"std/core frames are kept;
+     * filtering them would be a readability judgment applied to evidence"* —
+     * rather than superseding it. `payload.raw` keeps the verbatim block as
+     * well, as always.
+     *
+     * ## Required, deliberately
+     *
+     * Not optional, for the reason RT-056 records about `processLifecycle`:
+     * **an optional field is one every existing adapter may silently omit**, and
+     * an adapter that never considered the question would keep today's behaviour
+     * with no signal that it never considered it. Where the innermost frame
+     * genuinely is the failure site the answer is `0` — but stated, not
+     * defaulted.
+     *
+     * Consumers must treat an out-of-range value as a fault rather than
+     * clamping to `0`: a silent fallback would reintroduce exactly the defect
+     * this field removes, through the error path instead of the happy one.
+     */
+    readonly primaryFrameIndex: number;
+}
+export interface Evidence {
+    readonly evidenceId: string;
+    readonly executionId: string;
+    readonly timestamp: string;
+    readonly source: EvidenceSource;
+    /** Which owned system this came from (§16.7) — null when not applicable. */
+    readonly service: string | null;
+    /** ProcessHandle.processId, when this evidence is attributable to one process. */
+    readonly process: string | null;
+    readonly eventType: RuntimeEventType;
+    /** Redacted per `redactionStatus` before this is readable by anything upstream (§25) — never raw secrets in transit. */
+    readonly payload: unknown;
+    readonly traceId: string | null;
+    readonly requestId: string | null;
+    /** Set only after the Correlation Engine resolves it (correlation.ts) — never assigned speculatively here. */
+    readonly correlationId: string | null;
+    /** @descryy/ir node ID, set only when resolved via the graph's own identity scheme. This file does not define graph identity. */
+    readonly graphNodeId: string | null;
+    readonly sourceLocation: SourceLocation | null;
+    readonly stackTrace: StackTrace | null;
+    /** Resolution-honesty confidence (§9), 0-1. Independent of environment fidelity level and of a Correlation's own confidence. */
+    readonly confidence: number;
+    readonly redactionStatus: RedactionStatus;
+    /**
+     * The `version` field of the `package.json` that owns the collector which
+     * produced this row (e.g. `@descryhq-wq/runtime-browser`'s own version for
+     * browser-sourced evidence) — read from the package at module load, never
+     * hand-duplicated into a second string that can drift from what actually
+     * shipped. Same idea as `nodeVersion` elsewhere in this repo (`process.version`,
+     * always known, never probed) and as `@descryy/ir`'s `producedBy` (`adapterId@version`,
+     * "drives graph invalidation on adapter upgrade") applied to evidence instead of
+     * IR nodes — see RUNTIME-CHECKLIST.md §3/§19/§23: without this, evidence "cannot
+     * be invalidated by collector version the way IR nodes can."
+     *
+     * Required, not optional, for the same reason `primaryFrameIndex` above is
+     * required: an optional field is one an existing collector can silently omit,
+     * with no signal that it never considered the question.
+     */
+    readonly collectorVersion: string;
+}
+/**
+ * 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
+ *
+ * `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.
+ *
+ * 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`.
+ *
+ * ## 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.
+ */
+export declare function primaryFrameLocation(stackTrace: StackTrace | null): SourceLocation | null;
+/**
+ * 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.
+ */
+export declare function locationNamesNothing(location: SourceLocation): boolean;
+//# sourceMappingURL=evidence.d.ts.map

package/dist/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"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"}

package/dist/evidence.js

@@ -0,0 +1,204 @@
+/**
+ * Evidence contract.
+ *
+ * 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.
+ */
+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.
+    "browser-dom",
+    "browser-console",
+    "browser-network",
+    "backend-log",
+    "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). */
+    "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.
+     */
+    "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"`).
+     */
+    "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"`.
+     */
+    "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
+ * 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
+ *   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.
+ */
+export const SOURCE_LOCATION_RELIABILITIES = [
+    "self-contained",
+    "debug-info-present",
+    "debug-info-stripped",
+    "side-artifact-resolved",
+    "side-artifact-stale",
+    "side-artifact-missing",
+    "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`.
+ */
+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
+ *
+ * `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.
+ *
+ * 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`.
+ *
+ * ## 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.
+ */
+export function primaryFrameLocation(stackTrace) {
+    if (stackTrace === null || stackTrace.frames.length === 0)
+        return null;
+    const index = stackTrace.primaryFrameIndex;
+    if (!Number.isInteger(index) || index < 0 || index >= stackTrace.frames.length) {
+        throw new RangeError(`primaryFrameIndex ${String(index)} is outside the ${stackTrace.frames.length}-frame list it indexes. ` +
+            "The adapter that produced this trace declared a failure site that does not exist; reported rather " +
+            "than clamped to frames[0], which would silently restore the stdlib-frame defect this index removes.");
+    }
+    const location = stackTrace.frames[index]?.location ?? null;
+    if (location === null)
+        return null;
+    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.
+ */
+export function locationNamesNothing(location) {
+    return location.file === null && location.line === null && location.functionName === null;
+}
+//# sourceMappingURL=evidence.js.map

package/dist/evidence.js.map

@@ -0,0 +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"}