@tangle-network/traces 0.11.0 → 0.11.2

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-import { ToolUseMetrics, InMemoryTraceStore } from '@tangle-network/agent-eval';
+import { TraceValidation, SpanKind, Outcome } from '@tangle-network/agent-trace-contract';
+export { Capability, ConformanceFinding, ContractSpan, SpanLink, TraceValidation } from '@tangle-network/agent-trace-contract';
+import { ToolUseMetrics, InMemoryTraceStore, CounterfactualRunner, CounterfactualContext, TraceEmitter, TraceStore } from '@tangle-network/agent-eval';
 import { StuckLoopReport, FailureClusterReport } from '@tangle-network/agent-eval/pipelines';
 import { TraceAnalystDefinition, TraceAnalysisEngine, AnalystRegistry, AnalystFinding, buildDefaultAnalystRegistry, AnalystRunSummary, AnalystRunResult, Analyst } from '@tangle-network/agent-eval/analyst';
 export { Analyst, AnalystContext, AnalystFinding, AnalystRegistry, buildDefaultAnalystRegistry, makeFinding } from '@tangle-network/agent-eval/analyst';
@@ -10,6 +12,194 @@ import { SupervisorRunNodeRole, SupervisorRunReader, SupervisorRunSources } from
 import { TraceSpanEvent } from '@tangle-network/agent-eval/hosted';
 export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-network/agent-eval/hosted';
 
+/**
+ * The INBOUND path: read OTLP-JSONL that some other system emitted and hand it
+ * to the same analysis pipeline the adapters feed.
+ *
+ * The adapters (`src/adapters/`) exist because Claude Code, Codex, OpenCode and
+ * friends write proprietary session logs we do not control, so somebody has to
+ * translate. A system you DO control should not need one: emit
+ * `@tangle-network/agent-trace-contract` spans and point `--otlp` at the file.
+ *
+ * Two rules govern everything here:
+ *
+ * 1. **Never throw on foreign input.** A tool that crashes on somebody else's
+ *    trace cannot read "any AI system". A malformed line, a missing timestamp, a
+ *    link pointing at nothing — each becomes a counted, named issue and the run
+ *    continues on what is readable.
+ * 2. **Validate what the PRODUCER wrote.** {@link readOtlpInput} runs
+ *    `validateTraceSpans` over the raw rows, before this module normalizes
+ *    anything, so the report tells the producer what to fix rather than
+ *    describing our own repairs back to them.
+ */
+
+/** Why one row of an OTLP file did not become an analyzable span AT ALL. */
+type OtlpIngestIssueKind = 'unparseable-line' | 'not-an-object' | 'missing-span-id' | 'unreadable-timestamp' | 'conflicting-span-id';
+interface OtlpIngestIssue {
+    readonly kind: OtlpIngestIssueKind;
+    readonly file: string;
+    /** 1-indexed line within `file`. */
+    readonly line: number;
+    readonly detail: string;
+}
+/** Which unusable field cost a span one measurement, without costing it its existence. */
+type OtlpWithheldFieldKind = 'negative-duration';
+/**
+ * A row that DID become a span, with one unusable field withheld.
+ *
+ * This is a different event from an {@link OtlpIngestIssue} and the two must
+ * never be merged. A span whose `end_time` precedes its `start_time` has an
+ * unusable INTERVAL — it does not have an unusable identity, name, tool name or
+ * status. Dropping the whole span for it silently deleted a real tool call from
+ * every count in the report, which is a worse failure than the wrong duration
+ * it was avoiding: a wrong number is visible and a missing row is not.
+ *
+ * So the span survives, its interval is withheld rather than repaired (no
+ * synthesized end time enters any total), and the withholding is reported
+ * here. The contract's own `negative-duration` finding independently marks
+ * `latency-analysis` unavailable, so every table that prints a duration is
+ * already gated.
+ */
+interface OtlpFieldWithheld {
+    readonly kind: OtlpWithheldFieldKind;
+    /** The span field that could not be used. */
+    readonly field: string;
+    readonly file: string;
+    /** 1-indexed line within `file`. */
+    readonly line: number;
+    readonly detail: string;
+}
+/**
+ * A span field this package ANALYSES as something other than what the producer
+ * wrote.
+ *
+ * Every one of these is a place the reader has to substitute a value to analyse
+ * the row at all — a trace id to group by, an end time to subtract, a status to
+ * count, a kind to bucket, a link to follow. Substituting is correct; writing
+ * the substitute into the EXPORT is not, because the export is re-validated and
+ * the substitute is by construction more conforming than the source. Every
+ * `missing-trace-id`, `invalid-timestamp`, `invalid-status`, `unknown-span-kind`
+ * and `dangling-link` this package's own re-export ever laundered away was one
+ * of these fields, so they are enumerated in ONE place and the export reads that
+ * list rather than knowing them one at a time — a sixth substitution cannot be
+ * added without the export learning about it.
+ */
+type SubstitutedField = 'trace_id' | 'end_time' | 'status.code' | 'kind' | 'links';
+interface OtlpInputFile {
+    readonly path: string;
+    readonly rows: number;
+    readonly spans: number;
+    /** Rows that re-declared a span already read, byte-identically. */
+    readonly repeats: number;
+    /** Distinct trace ids this file contributed, so a caller can attribute a
+     *  trace back to the file it came from when a directory was ingested. */
+    readonly traceIds: readonly string[];
+}
+/** A `*.jsonl` in the directory that does not hold OTLP spans, and how we know. */
+interface SkippedInputFile {
+    readonly path: string;
+    /** What the first readable line was instead of a span. */
+    readonly reason: string;
+}
+/**
+ * How much of the original source could not be represented as spans, summed
+ * across every export hop that led to this file.
+ *
+ * `rows` is the count and `kinds` names the ingest issues behind it. On a file a
+ * producer wrote, this is just what THIS ingest dropped. On a file
+ * `traces` re-exported, it also carries what earlier hops dropped, read back off
+ * the spans — so a re-export can never present itself as a complete copy of a
+ * source it is missing rows from.
+ */
+interface UnreadableSourceRows {
+    readonly rows: number;
+    readonly kinds: readonly OtlpIngestIssueKind[];
+    /** Rows dropped by EARLIER hops, already absent from the file just read. */
+    readonly inherited: number;
+}
+interface OtlpInput {
+    /** Every file read, in ingest order. */
+    readonly files: readonly OtlpInputFile[];
+    /** JSONL files in the directory that hold something other than OTLP spans. */
+    readonly skipped: readonly SkippedInputFile[];
+    /** Rows exactly as the producer wrote them — the input to `validateTraceSpans`. */
+    readonly rows: readonly unknown[];
+    /** Rows normalized into this package's span model, ready for the pipeline. */
+    readonly spans: readonly OtlpSpan[];
+    /** Conformance of the RAW rows: what this trace can and cannot answer. */
+    readonly validation: TraceValidation;
+    /** Rows that could not become spans, each with its reason. */
+    readonly issues: readonly OtlpIngestIssue[];
+    /** Rows that DID become spans, with one unusable field withheld from them. */
+    readonly withheld: readonly OtlpFieldWithheld[];
+    /** Source rows absent from `spans`, this hop's and every earlier hop's. */
+    readonly unreadable: UnreadableSourceRows;
+}
+/** A file or directory resolved to the OTLP files in it, plus the JSONL that is not OTLP. */
+interface ResolvedOtlpInput {
+    readonly files: readonly string[];
+    readonly skipped: readonly SkippedInputFile[];
+}
+/**
+ * Resolve a file or directory to the OTLP files it names.
+ *
+ * A named FILE is read as OTLP whatever it contains — the caller pointed at it,
+ * and reporting its rows as unreadable is more useful than refusing it. A
+ * DIRECTORY is a guess about which files were meant, so its non-OTLP JSONL is
+ * skipped and named rather than ingested.
+ */
+declare function resolveOtlpInputFiles(path: string): Promise<ResolvedOtlpInput>;
+/**
+ * Classify a span from its EVIDENCE — name and attributes — ignoring whatever
+ * kind it declared. Callers decide whether a declaration wins; this answers the
+ * separate question "what does this span look like".
+ *
+ * The contract's `resolveSpanKind` does the classifying, so a foreign trace
+ * cannot land in one bucket here and another there. What sits on top of it are
+ * only signals the contract deliberately does not read, and only where it
+ * returned `UNKNOWN`:
+ *
+ * - `span.type`, a Tangle-internal marker. Its tool-telemetry values name
+ *   children that DESCRIBE a tool call; counting them as calls doubles every
+ *   tool total, which is why that check runs first.
+ * - the local tool spellings above, and a name that mentions a tool.
+ * - an interaction/agent name, which is the run container this model calls
+ *   AGENT.
+ *
+ * Anything still unrecognised stays `UNKNOWN`. It is not `CHAIN`: CHAIN claims
+ * the span CONTAINS other work, and inventing that relationship is how an
+ * unclassifiable span ends up misreported as a container.
+ */
+declare function inferSpanKind(name: string, attributes: Record<string, unknown>): OtlpSpanKind;
+/**
+ * Exactly one of `span` or `issue`: a usable span, or the named reason there
+ * isn't one. `withheld` accompanies a SPAN — the row was analysable, one field
+ * on it was not.
+ */
+interface OtlpRowConversion {
+    span?: OtlpSpan;
+    issue?: Omit<OtlpIngestIssue, 'file' | 'line'>;
+    withheld?: Omit<OtlpFieldWithheld, 'file' | 'line'>;
+}
+/**
+ * One raw row to one analyzable span, or one named reason it is not analyzable.
+ *
+ * `fallbackTraceId` covers a row with no trace_id: `validateTraceSpans` reports
+ * that as `missing-trace-id`, and grouping still needs SOME key, so the source
+ * file names the anonymous trace instead of each span becoming its own run.
+ */
+declare function otlpRowToSpan(row: unknown, fallbackTraceId: string): OtlpRowConversion;
+/**
+ * Read OTLP-JSONL from a file or a directory of them.
+ *
+ * A directory ingests the OTLP files under it, recursively — every `*.jsonl` /
+ * `*.ndjson` that holds spans, or only the contents of an `otlp/` subdirectory
+ * when the producer made one — so a results directory of per-shot exports
+ * analyses as one body of work while its raw event and stream logs are named
+ * and skipped rather than counted as broken spans.
+ */
+declare function readOtlpInput(path: string): Promise<OtlpInput>;
+
 /**
  * OTLP-flat-line emitter — the canonical normalized trace shape.
  *
@@ -21,7 +211,7 @@ export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-n
  * (which reads the attribute vocabulary), HALO, and any OpenInference tool.
  *
  * Attribute vocabulary the downstream analysts key off:
- *   - `openinference.span.kind`  → span kind (AGENT | LLM | TOOL | CHAIN)
+ *   - `openinference.span.kind`  → span kind ({@link OtlpSpanKind})
  *   - `service.name`             → harness id (claude-code, codex, …)
  *   - `agent.name`               → agent / subagent name
  *   - `llm.model_name`           → model
@@ -29,8 +219,34 @@ export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-n
  *   - `tool.name`                → tool histogram (monoculture / no-verify)
  *   - `step`                     → run order (falls back to start_time)
  */
-type OtlpSpanKind = 'AGENT' | 'LLM' | 'TOOL' | 'CHAIN' | 'SPAN';
+
+/**
+ * The span-kind vocabulary, which is exactly
+ * `@tangle-network/agent-trace-contract`'s — AGENT, CHAIN, LLM, TOOL,
+ * EVALUATOR, RETRIEVER, UNKNOWN.
+ *
+ * It is an alias, not a copy, because the two vocabularies MUST NOT drift: a
+ * narrower local union silently re-typed every kind it did not list, so a
+ * producer's EVALUATOR verdict span came back out as CHAIN and the re-exported
+ * file no longer said what the original did.
+ */
+type OtlpSpanKind = SpanKind;
 type OtlpStatusCode = 'OK' | 'ERROR' | 'UNSET';
+/**
+ * A causal edge that is NOT containment. `parent_span_id` says "this span
+ * happened INSIDE that one"; a link says "that one CAUSED this one" — round N's
+ * verdict steering round N+1, a retry pointing at the attempt it replaces.
+ * Encoding those as a parent would claim a nesting that never existed, so OTLP
+ * gives them their own edge and this model keeps it.
+ *
+ * Matches `SpanLink` in `@tangle-network/agent-trace-contract`.
+ */
+interface OtlpSpanLink {
+    trace_id: string;
+    span_id: string;
+    /** e.g. `{ 'agent.link.kind': 'steered_by' }`. */
+    attributes?: Record<string, unknown>;
+}
 interface OtlpSpan {
     trace_id: string;
     span_id: string;
@@ -43,6 +259,8 @@ interface OtlpSpan {
         message?: string;
     };
     attributes: Record<string, unknown>;
+    /** Causal edges to other spans. Absent when the producer recorded none. */
+    links?: OtlpSpanLink[];
 }
 interface SpanInput {
     traceId: string;
@@ -70,6 +288,8 @@ interface SpanInput {
     step?: number;
     /** Verbatim content the agentic analysts read via regex search. */
     content?: string | null;
+    /** Causal edges (steered-by / graded-by / retry-of), not containment. */
+    links?: readonly OtlpSpanLink[];
     /** Extra attributes merged last (escape hatch for harness-specific signal). */
     extra?: Record<string, unknown>;
 }
@@ -79,11 +299,43 @@ interface SpanInput {
  * so the behavioral analyst's "no LLM data" case stays honest.
  */
 declare function span(input: SpanInput): OtlpSpan;
-/** Project an in-memory span to a COMPLETE OpenInference span: the standard shape
- *  OTel/OpenInference consumers (and HALO) expect — top-level `kind`, `resource`,
- *  `scope`, and a string `parent_span_id` ("" at the root) — while keeping the
- *  attribute vocabulary (incl. `openinference.span.kind`) our own analysts read.
- *  One artifact feeds our pipeline, HALO, and any OpenInference tool. */
+/** The three things an export can write for a substituted field, and nothing else. */
+type ExportRule = 'faithful' | 'declared-or-analysed' | 'analysed';
+/**
+ * What the export writes for a field this package substituted. One rule per
+ * field, in one table, because the difference between them is not a style choice
+ * — each `analysed` entry is a consumer that HARD-REQUIRES the field, named.
+ *
+ * The table is EXPORTED because it is a guarantee, not documentation:
+ * `tests/otlp-export-rule.test.ts` reads it and derives, per field, the checks
+ * the declared word promises — the exact value written in each of the two
+ * producer states, that a `faithful` field erases no finding its source earned,
+ * and that the artifact stays readable by the consumer whose hard requirement is
+ * the only reason `analysed` exists. A field could be declared `faithful` here
+ * while nothing implemented it (`status.code` was, and the finding vanished from
+ * every re-export); a table that reads as a guarantee and is not one is worse
+ * than no table.
+ *
+ * - `faithful` — the producer's value, or NO field at all when they wrote none.
+ *   This is the default and the only rule that reproduces the source's finding
+ *   exactly.
+ * - `declared-or-analysed` — the producer's word when they wrote one, else this
+ *   package's. A kind is what every consumer buckets by, and a span with none is
+ *   re-derived differently by each of them (the tool-execution demotion that
+ *   stops a tool call being counted twice is one such re-derivation), so the
+ *   export always declares one. Writing the producer's word when there is one is
+ *   what keeps `unknown-span-kind` alive across the trip.
+ * - `analysed` — this package's value regardless. `trace_id` is the one field
+ *   here, and it is not a choice: `analyze --otlp-out` hands the artifact
+ *   straight to `agent-eval`'s `OtlpFileTraceStore`, whose `projectOtlpFlatLine`
+ *   drops any row with a falsy `trace_id` and then throws `TraceFileMalformed`
+ *   on the drop. A faithful (absent) trace id makes the artifact unreadable by
+ *   the tool that reads it, so `missing-trace-id` CANNOT survive the trip. The
+ *   substitution is disclosed instead — the span carries the pairing, and
+ *   `renderConformance` states it above the findings so a reader of the artifact
+ *   is told the id was minted here rather than left to assume the source had one.
+ */
+declare const EXPORT_RULE: Readonly<Record<SubstitutedField, ExportRule>>;
 declare function toOpenInferenceSpan(s: OtlpSpan): Record<string, unknown>;
 /** Serialize spans to OpenInference JSONL (one complete span per line). This is a
  *  standard OpenInference representation: it feeds our analysts, HALO, and other
@@ -209,6 +461,226 @@ interface HarnessTraceAdapter {
     resolveParentTask?(ref: SessionRef, childSessionId: string, options?: Pick<ParseOptions, 'corruptionMode' | 'signal'>): Promise<ParentTaskResolution>;
 }
 
+/**
+ * What a trace can and cannot answer, said out loud.
+ *
+ * `@tangle-network/agent-trace-contract` decides conformance: it reports
+ * findings (what is wrong, and the consequence) and capabilities (what a
+ * consumer can compute, and why not when it cannot). That package is
+ * deliberately generic. This module adds the one thing it cannot know — which
+ * section of THIS report each missing capability empties — so a thin report
+ * explains its own thinness instead of reading as "the agent did nothing".
+ */
+
+/**
+ * Capabilities the trace cannot support, mapped to the trace's own reason.
+ *
+ * This is what makes the conformance section GATE rather than narrate: the
+ * renderer takes it and marks every section whose inputs are incomplete, at the
+ * table, so a number and the reason it is wrong cannot end up forty lines
+ * apart.
+ */
+type UnavailableCapabilities = ReadonlyMap<string, string>;
+/** The trace's unavailable capabilities, each mapped to the validator's own reason. */
+declare function unavailableCapabilities(validation: TraceValidation): UnavailableCapabilities;
+/**
+ * The inline marker a section carries when its inputs are incomplete. Empty
+ * when the capability is available — the caller concatenates unconditionally,
+ * so a section can never be marked in one place and silently not in another.
+ */
+declare function incompleteInputsNote(unavailable: UnavailableCapabilities | undefined, capability: string): string;
+interface SpanStructure {
+    readonly spans: number;
+    readonly traces: number;
+    /** Spans carrying no `parent_span_id` at all. */
+    readonly rootless: number;
+    /**
+     * Rootless spans BEYOND the one root each trace is supposed to have. This,
+     * not `rootless`, is the number of spans that attribute to nothing: a
+     * textbook-correct trace has exactly one root, so `rootless === traces` with
+     * one root each is a conforming shape and must read as one.
+     */
+    readonly extraRoots: number;
+    /** Traces where every span names a parent, so the trace has no top at all. */
+    readonly tracesWithoutRoot: number;
+    /** Spans naming a parent that is absent from the export. */
+    readonly orphans: number;
+    readonly links: number;
+}
+/**
+ * How much of the span tree actually attaches.
+ *
+ * The contract's `flat-hierarchy` finding is per-trace and all-or-nothing: one
+ * parented span anywhere in a trace suppresses it for every other span. A trace
+ * where the overwhelming majority of spans have no parent is not flat by that
+ * definition and is entirely flat in practice, so this reports the DEGREE the
+ * binary finding cannot express. It measures, it does not re-implement — the
+ * finding still comes from the validator.
+ *
+ * Roots are counted PER TRACE, because "has no parent" is the definition of a
+ * root, not of a defect. Counting every rootless span as unattributed made a
+ * correct one-root trace narrate itself as broken.
+ */
+declare function summarizeSpanStructure(spans: readonly OtlpSpan[]): SpanStructure;
+interface SkippedAnalysis {
+    readonly capability: string;
+    /** The analysis in this report that the missing capability empties. */
+    readonly analysis: string;
+    /** The trace's own reason, from the contract validator. */
+    readonly reason: string;
+}
+/**
+ * Conformance of spans this package produced (adapters, importers), measured on
+ * the same OpenInference projection that gets written to disk — so the report
+ * grades the artifact a consumer would actually receive, not an in-memory shape
+ * nobody sees. For spans read from a foreign OTLP file, validate the RAW rows
+ * instead (`readOtlpInput` does): that tells the producer what to fix rather
+ * than describing our own normalization back to them.
+ */
+declare function conformanceOfSpans(spans: readonly OtlpSpan[]): TraceValidation;
+/** Unavailable capabilities, paired with the analysis each one empties. */
+declare function skippedAnalyses(validation: TraceValidation): SkippedAnalysis[];
+interface ConformanceRenderOptions {
+    /** What was validated, e.g. a file path or "spans emitted by the claude-code adapter". */
+    readonly subject: string;
+    /** Files read, when the source was an OTLP file or directory. */
+    readonly files?: readonly OtlpInputFile[];
+    /** JSONL files in the directory that hold something other than OTLP spans. */
+    readonly skipped?: readonly SkippedInputFile[];
+    /** Rows that never became spans, when the source was an OTLP file or directory. */
+    readonly issues?: readonly OtlpIngestIssue[];
+    /** Rows that DID become spans, with one field withheld from them. */
+    readonly withheld?: readonly OtlpFieldWithheld[];
+    /** Source rows absent from this file — this ingest's, and any earlier export's. */
+    readonly unreadable?: UnreadableSourceRows;
+    /** The spans that were analysed, for the hierarchy summary. */
+    readonly spans?: readonly OtlpSpan[];
+    /** Markdown heading level for the section title (default 2). */
+    readonly headingLevel?: number;
+}
+/**
+ * The conformance section of an analysis report: findings, the capability
+ * table, and — the part that makes a thin report honest — the named analyses
+ * that produced nothing and why.
+ */
+declare function renderConformance(validation: TraceValidation, opts: ConformanceRenderOptions): string;
+/**
+ * The `traces validate` report. Same body, plus a verdict line a reader (or a
+ * CI job reading the exit code) can act on.
+ *
+ * The three verdicts are the three answers `@tangle-network/agent-trace-contract`
+ * can give, in its own terms — `ok` says whether the input is a trace AT ALL, and
+ * `capabilities` says what a trace can answer. Nothing here re-derives either.
+ */
+declare function renderValidation(validation: TraceValidation, opts: ConformanceRenderOptions): string;
+/**
+ * Exit code for `traces validate`, which is read by CI.
+ *
+ * Non-zero on exactly one condition: the input is not a trace. That is what
+ * `TraceValidation.ok` means and the contract's severities are defined to match
+ * it — `error` is "nothing readable", `warn` is "readable but degraded", `info`
+ * is "nothing lost" — so a severity scan here would only be a second, driftable
+ * copy of the same rule.
+ *
+ * A degraded trace exits 0 deliberately. Failing on degradation is failing on
+ * thinness, and every real-world trace is thin somewhere: a gate that red-lights
+ * `flat-hierarchy` or `no-usage` is one a producer learns to ignore. What a
+ * missing field costs is stated per capability, in the table, where it can be
+ * acted on.
+ */
+declare function validationExitCode(validation: TraceValidation): number;
+
+/**
+ * The two questions a LOOP trace exists to answer, and that a flat event list
+ * cannot: **did round N+1 improve on round N**, and **which verdict caused
+ * which retry**.
+ *
+ * Both are read from the contract's own vocabulary and nothing else:
+ *
+ * - `agent.loop.id` / `agent.loop.iteration` group and order the rounds.
+ * - `agent.outcome` / `agent.outcome.score` carry the verdict. A round rarely
+ *   grades itself — the grade lives on an EVALUATOR span underneath it — so the
+ *   verdict is taken from the shallowest descendant that has one, which is the
+ *   round's own verdict rather than one of its per-layer sub-verdicts.
+ * - `links` carry causality. `parent_span_id` says round N+1 happened INSIDE
+ *   round N, which is false; the link says round N's verdict CAUSED it, which
+ *   is the edge a steering chain is made of.
+ *
+ * Nothing here throws on malformed input, and nothing is inferred where the
+ * trace is silent: a loop with no scores reports `unscored`, not a flat trend.
+ */
+
+/** Whether the rounds got better, stayed put, or got worse — and on what basis. */
+type LoopTrend = 'improved' | 'plateaued' | 'regressed' | 'mixed' | 'unscored';
+/** What the trend was computed from, so a reader can tell a score series from
+ *  a pass/fail series from nothing at all. */
+type LoopTrendBasis = 'score' | 'outcome' | 'none';
+interface LoopIteration {
+    readonly iteration: number;
+    readonly spanId: string;
+    readonly name: string;
+    /** Terminal verdict for the round, from the round or its shallowest graded descendant. */
+    readonly outcome: Outcome | null;
+    readonly score: number | null;
+    /** Span the verdict was read from; equals `spanId` when the round graded itself. */
+    readonly verdictSpanId: string | null;
+    readonly startTime: string;
+    readonly durationMs: number | null;
+}
+interface LoopConvergence {
+    readonly loopId: string;
+    readonly traceId: string;
+    readonly iterations: readonly LoopIteration[];
+    readonly trend: LoopTrend;
+    readonly basis: LoopTrendBasis;
+    /** The trend in the trace's own numbers, e.g. "score 0.4 → 0.9 over 4 rounds". */
+    readonly detail: string;
+}
+interface LoopConvergenceReport {
+    readonly loops: readonly LoopConvergence[];
+    /** Spans carrying `agent.loop.iteration` — 0 means the trace records no rounds. */
+    readonly iterationSpans: number;
+}
+/** One causal edge: a graded span, and the work it caused. */
+interface SteeringEdge {
+    /** The span that CAUSED the work — a verdict, an earlier attempt. */
+    readonly causeSpanId: string;
+    readonly causeName: string | null;
+    readonly causeOutcome: Outcome | null;
+    readonly causeScore: number | null;
+    /** The span the link was recorded on: the work that was caused. */
+    readonly effectSpanId: string;
+    readonly effectName: string;
+    readonly effectIteration: number | null;
+    /** `agent.link.kind`, or `unspecified` when the producer recorded none. */
+    readonly linkKind: string;
+    /** False when the cause is absent from this export, so the chain breaks here. */
+    readonly resolved: boolean;
+}
+interface SteeringChainReport {
+    readonly edges: readonly SteeringEdge[];
+    readonly links: number;
+    readonly dangling: number;
+    readonly byKind: Readonly<Record<string, number>>;
+}
+/**
+ * Round-over-round convergence, per loop.
+ *
+ * Rounds are ordered by `agent.loop.iteration`, not by time: a resumed or
+ * re-run round is written later than the round it replaces, and time order
+ * would report the replacement as a new round.
+ */
+declare function analyzeLoopConvergence(spans: readonly OtlpSpan[]): LoopConvergenceReport;
+/**
+ * The steering chain: which graded span caused which subsequent unit of work.
+ *
+ * A link is recorded on the EFFECT and points at the CAUSE, so the edge is read
+ * backwards from the span that carries it. A link whose target is absent from
+ * the export is kept and marked unresolved — dropping it would report a shorter
+ * chain than the producer recorded, which is the opposite of the truth.
+ */
+declare function analyzeSteeringChain(spans: readonly OtlpSpan[]): SteeringChainReport;
+
 interface CodeTraceBenchFileRef {
     readonly path: string;
     readonly line_start: number;
@@ -1849,6 +2321,24 @@ interface TraceInvestigationOptions {
     readonly analyzerPrompt?: string;
     readonly otlpOutPath?: string;
     readonly generatedAt?: string;
+    /**
+     * Conformance of the SOURCE the spans were read from. Supply it when the
+     * source was a foreign OTLP file, so the report grades what the producer
+     * wrote; omitted, it is computed from the spans themselves.
+     */
+    readonly conformance?: TraceValidation;
+    /** What was validated, named in the conformance section (default: the harness). */
+    readonly conformanceSubject?: string;
+    /** OTLP files read, when the spans came from `--otlp`. */
+    readonly conformanceFiles?: readonly OtlpInputFile[];
+    /** JSONL files that were not OTLP, when the spans came from `--otlp` on a directory. */
+    readonly conformanceSkipped?: readonly SkippedInputFile[];
+    /** Rows that never became spans, when the spans came from `--otlp`. */
+    readonly conformanceIssues?: readonly OtlpIngestIssue[];
+    /** Rows analysed with one field withheld, when the spans came from `--otlp`. */
+    readonly conformanceWithheld?: readonly OtlpFieldWithheld[];
+    /** Source rows absent from the file read, including any earlier export's. */
+    readonly conformanceUnreadable?: UnreadableSourceRows;
     readonly signal?: AbortSignal;
     readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
 }
@@ -1881,12 +2371,22 @@ interface TraceInvestigationResult {
     readonly workflow?: SessionWorkflowSummary;
     readonly spanCount: number;
     readonly otlpPath: string;
+    /**
+     * What these spans can and cannot answer. Every report carries it: a thin
+     * report that does not explain its own thinness reads as "the agent did
+     * nothing" when the truth is "the trace never recorded it".
+     */
+    readonly conformance: TraceValidation;
     readonly execution: ExecutionReport;
     readonly analystResult: AnalystRunResult;
     readonly findings: readonly AnalystFinding[];
     readonly pipelines: PipelineReport;
     readonly reactions: ReactionReport;
     readonly adoption: AdoptionReport;
+    /** Did round N+1 improve on round N, per loop. */
+    readonly loopConvergence: LoopConvergenceReport;
+    /** Which verdict caused which subsequent round. */
+    readonly steeringChain: SteeringChainReport;
     /** Deterministic routing record for the agentic trace-analysis pass. */
     readonly agenticRoute?: TraceAgenticRoute;
     /**
@@ -2618,6 +3118,206 @@ interface SessionBatch {
 /** Select + parse (+ redact) sessions into per-session span batches. */
 declare function collectSessions(opts?: CollectOptions): Promise<SessionBatch[]>;
 
+/**
+ * Execution-replay verification for CodeTraceBench-style shell trajectories.
+ *
+ * Turns a cited analyst finding ("step k is the error-critical step") into an
+ * executed proof: replay steps 1..k-1 inside a real sandbox on the
+ * trajectory's own docker image, then
+ *   arm A — run the recorded step k and check the recorded failure signature
+ *           reproduces (returncode + a stable output substring), and
+ *   arm B — run a corrected step k and check the failure vanishes.
+ *
+ * Built on the agent-eval counterfactual scaffold: the trajectory is ingested
+ * into a TraceStore, each arm is a `runCounterfactual` meta-run, and the
+ * sandbox-backed `CounterfactualRunner` here supplies the `executeFrom`
+ * callback that scaffold deliberately leaves to consumers.
+ *
+ * Honest limits:
+ * - Only SWE-style trajectories carry `docker_config.base_image`; tasks whose
+ *   environment needs external compose peers cannot be replayed this way.
+ * - Copy-on-write forks (`box.branch()`) are firecracker-only; on the docker
+ *   driver each arm replays the prefix in its own fresh sandbox instead.
+ * - Prefix divergence (recorded vs replayed returncode) is recorded per step
+ *   and surfaced in the verdict, never hidden: a high divergence count is a
+ *   finding about replayability, not an error of the harness.
+ */
+
+/** Recorded returncode from a mini-SWE observation, or null when absent
+ *  (terminal submit steps carry no returncode tag). */
+declare function parseRecordedReturncode(observation: string | null): number | null;
+/** Text between the observation's <output> tags, or the raw observation when
+ *  the tags are absent. */
+declare function parseObservationOutput(observation: string | null): string;
+/**
+ * Stable failure-signature candidate: the first line of the recorded output
+ * that contains the word "error". Null when no such line exists — the verdict
+ * then falls back to returncode-only matching and says so.
+ * Pass an explicit signature to override (compiler quote glyphs vary with
+ * locale, so a hand-picked ASCII substring is often more robust).
+ */
+declare function deriveFailureSignature(observation: string | null): string | null;
+interface IngestedTrajectory {
+    runId: string;
+    stepCount: number;
+}
+/**
+ * Emit one tool span per trajectory step, in order, with a monotonic
+ * injected clock so `buildTrajectory` ordering is deterministic even when
+ * two spans would share a Date.now() millisecond.
+ */
+declare function ingestCodeTraceBenchSteps(store: TraceStore, steps: readonly CodeTraceBenchStep[], caseId: string): Promise<IngestedTrajectory>;
+interface ReplayExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface ReplayExecSession {
+    exec(command: string, timeoutMs: number): Promise<ReplayExecResult>;
+    close(): Promise<void>;
+}
+interface ReplayExecBackend {
+    open(): Promise<ReplayExecSession>;
+}
+interface SandboxReplayBackendOptions {
+    image: string;
+    apiKey: string;
+    baseUrl: string;
+    maxLifetimeSeconds?: number;
+    /**
+     * The local SDK-adapter test harness does not translate `agent: false`
+     * into the platform-control-runtime marker the way the production
+     * sandbox API does, so images without node need the marker passed as
+     * container env. Harmless against the production API path. Default true.
+     */
+    platformRuntimeEnvMarker?: boolean;
+}
+/** One fresh sandbox per open(); close() deletes it. */
+declare function sandboxReplayBackend(options: SandboxReplayBackendOptions): ReplayExecBackend;
+/**
+ * mini-SWE runs every action as a fresh /bin/sh subshell from a fixed
+ * workdir. Reproduce that exactly — and stay quote-proof for arbitrary
+ * recorded actions — by piping the base64 of the action into `sh` after
+ * cd-ing to the workdir. Exit code is sh's, i.e. the action's.
+ */
+declare function wrapActionForExec(action: string, cwd: string): string;
+interface PrefixDivergence {
+    step: number;
+    expectedReturncode: number | null;
+    actualExit: number;
+}
+interface PrefixReplayResult {
+    prefixExecuted: number;
+    prefixDivergences: PrefixDivergence[];
+    wallMs: number;
+}
+interface ArmExecutionResult {
+    command: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    wallMs: number;
+}
+interface SandboxCounterfactualRunnerOptions {
+    cwd: string;
+    stepTimeoutMs: number;
+    /** Execute at most this many prefix steps (from the start). Fast-iteration
+     *  knob; a truncated prefix weakens state fidelity and the verdict says so. */
+    prefixLimit?: number;
+    onProgress?: (message: string) => void;
+}
+/**
+ * Replays `ctx.prefix` in a fresh sandbox session, then executes the mutated
+ * step. Divergences are recorded and never abort the replay. Results land on
+ * `lastPrefix` / `lastArm` for the caller; spans for every exec land in the
+ * counterfactual meta-run.
+ */
+declare class SandboxCounterfactualRunner implements CounterfactualRunner {
+    private readonly backend;
+    private readonly options;
+    lastPrefix: PrefixReplayResult | null;
+    lastArm: ArmExecutionResult | null;
+    constructor(backend: ReplayExecBackend, options: SandboxCounterfactualRunnerOptions);
+    executeFrom(ctx: CounterfactualContext, emitter: TraceEmitter): Promise<void>;
+}
+interface ReplayVerifyOptions {
+    stepsPath: string;
+    image: string;
+    /** 1-based step_id of the error-critical step (matches CodeTraceBench). */
+    at: number;
+    /** Corrected command for arm B. Omit to run arm A only. */
+    fixCommand?: string;
+    cwd: string;
+    out: string;
+    caseId?: string;
+    /** Override the auto-derived failure signature substring. */
+    signature?: string;
+    stepTimeoutMs?: number;
+    prefixLimit?: number;
+    /** Label of the orchestrator driver backing the sandbox (reported, not probed). */
+    driverLabel?: string;
+    /** Injectable for tests; defaults to sandboxReplayBackend(). */
+    backend?: ReplayExecBackend;
+    apiKey?: string;
+    baseUrl?: string;
+    maxLifetimeSeconds?: number;
+    onProgress?: (message: string) => void;
+}
+interface ReplayArmVerdict {
+    command: string;
+    exitCode: number;
+    wallMs: number;
+    prefix: PrefixReplayResult;
+}
+interface ReplayVerdict {
+    case: string;
+    image: string;
+    driver: string;
+    k: number;
+    cwd: string;
+    recordedReturncode: number | null;
+    signature: string | null;
+    signatureBasis: 'returncode+output-substring' | 'returncode-only';
+    prefixExecuted: number;
+    prefixDivergences: PrefixDivergence[];
+    armA: ReplayArmVerdict & {
+        failureSignatureMatch: boolean;
+    };
+    armB: (ReplayArmVerdict & {
+        failureVanished: boolean;
+    }) | null;
+    timings: {
+        armAMs: number;
+        armBMs: number | null;
+        totalMs: number;
+    };
+    runIds: {
+        original: string;
+        armA: string;
+        armB: string | null;
+    };
+}
+declare function replayVerify(options: ReplayVerifyOptions): Promise<ReplayVerdict>;
+interface ReplayVerifyCliArgs {
+    stepsPath: string;
+    image: string;
+    at: number;
+    fixCommand?: string;
+    cwd: string;
+    out: string;
+    caseId?: string;
+    signature?: string;
+    stepTimeoutMs?: number;
+    prefixLimit?: number;
+    driverLabel?: string;
+    baseUrl: string;
+    apiKeyEnv: string;
+    maxLifetimeSeconds?: number;
+}
+declare function parseReplayVerifyArgs(argv: readonly string[]): ReplayVerifyCliArgs | 'help';
+declare function replayVerifyUsage(): string;
+declare function cmdReplayVerify(argv: readonly string[]): Promise<void>;
+
 /**
  * Local upload-dedup state.
  *
@@ -2720,4 +3420,4 @@ interface ExecuteOptions {
 /** Send the final, new outbound items (or write their dry-run OTLP). */
 declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
 
-export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, DEFAULT_HARNESS, EMPTY_SPAN_RUN_SNAPSHOT, EmptySessionError, type ExecuteOptions, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FactoryAdapter, type FileRunContextReaderOptions, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, RESULT_FILE, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SPAWN_JOURNAL_FILE, STATUS_MARK, type ScanOptions, type ScannedSession, type SessionBatch, type SessionCorruptionReceipt, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SpanInput, type SpanNodeStatus, type SpanRedaction, type SpanRunNode, type SpanRunSnapshot, type SpendRoll, TRACES_REDACTION_RULES, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, type WatchRunTargetOptions, ZERO_ROLL, addSpend, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, connectors, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, describeSessionRelationship, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, fileRunContextSupervisorRunReader, findSpanSourceFiles, forEachTreeNode, haloAnalyzer, hodoscopeAnalyzer, importCodeTraceBench, indexSessionIdsByTrace, inferRole, inspectSessionIndex, int, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, knownHarnesses, listAdapters, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeRemote, outboundHash, parseIsoToEpochMs, parseSession, parseSince, planTraceAgenticRoute, planUpload, readCoordinationLog, readFileRunContext, readJsonFile, readJsonl, readRunContextJournal, readRunContextSnapshot, readRunWatchSnapshot, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderInspectionReport, renderRunContextSnapshot, renderRunWatchSnapshot, renderSpanRunSnapshot, resolveAdapter, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, span, spanRunTotals, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, traceAgenticKinds, traceStreamEventsFromSpans, uploadKey, usd, userPromptSpan, validateOtlpSpans, watchRunTarget, watchSessions, wrap, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, zeroPricedCost };
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type ArmExecutionResult, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type ConformanceRenderOptions, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, DEFAULT_HARNESS, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type ExecuteOptions, type ExportRule, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FactoryAdapter, type FileRunContextReaderOptions, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, type IngestedTrajectory, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type LoopConvergence, type LoopConvergenceReport, type LoopIteration, type LoopTrend, type LoopTrendBasis, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpIngestIssue, type OtlpIngestIssueKind, type OtlpInput, type OtlpInputFile, type OtlpRowConversion, type OtlpSpan, type OtlpSpanKind, type OtlpSpanLink, type OtlpStatusCode, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, type PrefixDivergence, type PrefixReplayResult, QwenAdapter, REACTIONS, RESULT_FILE, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type ReplayArmVerdict, type ReplayExecBackend, type ReplayExecResult, type ReplayExecSession, type ReplayVerdict, type ReplayVerifyCliArgs, type ReplayVerifyOptions, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SPAWN_JOURNAL_FILE, STATUS_MARK, SandboxCounterfactualRunner, type SandboxCounterfactualRunnerOptions, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionCorruptionReceipt, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SkippedAnalysis, type SkippedInputFile, type SpanInput, type SpanNodeStatus, type SpanRedaction, type SpanRunNode, type SpanRunSnapshot, type SpanStructure, type SpendRoll, type SteeringChainReport, type SteeringEdge, TRACES_REDACTION_RULES, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UnavailableCapabilities, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, type WatchRunTargetOptions, ZERO_ROLL, addSpend, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyLiveActions, classifyReaction, claudeActor, cmdReplayVerify, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, conformanceOfSpans, connectors, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, deriveFailureSignature, describeSessionRelationship, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, fileRunContextSupervisorRunReader, findSpanSourceFiles, forEachTreeNode, haloAnalyzer, hodoscopeAnalyzer, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, ingestCodeTraceBenchSteps, inspectSessionIndex, int, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, knownHarnesses, listAdapters, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeRemote, otlpRowToSpan, outboundHash, parseIsoToEpochMs, parseObservationOutput, parseRecordedReturncode, parseReplayVerifyArgs, parseSession, parseSince, planTraceAgenticRoute, planUpload, readCoordinationLog, readFileRunContext, readJsonFile, readJsonl, readOtlpInput, readRunContextJournal, readRunContextSnapshot, readRunWatchSnapshot, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunWatchSnapshot, renderSpanRunSnapshot, renderValidation, replayVerify, replayVerifyUsage, resolveAdapter, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, skippedAnalyses, span, spanRunTotals, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, summarizeSpanStructure, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, traceAgenticKinds, traceStreamEventsFromSpans, unavailableCapabilities, uploadKey, usd, userPromptSpan, validateOtlpSpans, validationExitCode, watchRunTarget, watchSessions, wrap, wrapActionForExec, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, zeroPricedCost };