@tangle-network/agent-eval 0.126.7 → 0.127.0

package/dist/rollout/index.d.ts

@@ -27,19 +27,11 @@ import { DatabaseSync } from 'node:sqlite';
  * flag: a gated line must never export as a positive training example.
  */
 declare const ROLLOUT_SCHEMA = "tangle.rollout.v1";
-/** @deprecated alias kept for consumers of the pre-unification constant name. */
-declare const ROLLOUT_FORMAT = "tangle.rollout.v1";
 /** `agent` = a solo evaluation run (no multi-agent topology). */
 type RolloutRole = 'agent' | 'supervisor' | 'worker' | 'proposer' | 'judge' | 'analyst';
 declare const ROLLOUT_ROLES: readonly RolloutRole[];
-/**
- * Split vocabulary follows `RunRecord.splitTag` ('search' is the pool the
- * optimizer may read — the trainable split), extended with the ledger's
- * 'canary'. 'train' is a legacy alias for 'search' emitted by
- * pre-unification ledgers; it validates and counts as trainable, but new
- * producers must emit 'search'.
- */
-type RolloutSplit = 'search' | 'dev' | 'holdout' | 'canary' | 'train';
+/** Split vocabulary follows `RunRecord.splitTag`, extended with `canary`. */
+type RolloutSplit = 'search' | 'dev' | 'holdout' | 'canary';
 declare const ROLLOUT_SPLITS: readonly RolloutSplit[];
 /** Splits that may ship in training exports. Everything else is fail-closed excluded. */
 declare const TRAINABLE_SPLITS: readonly RolloutSplit[];
@@ -136,10 +128,9 @@ interface RolloutOutcome {
     /**
      * Anti-Goodhart flag from `RunRecord.outcome.realness.gated`: the run
      * faked its success signal. Reward is forced to 0 at mint time and the
-     * line never qualifies for SFT. Optional on the wire (absent = false)
-     * so pre-unification ledgers stay readable.
+     * line never qualifies for SFT.
      */
-    realness_gated?: boolean;
+    realness_gated: boolean;
 }
 interface RolloutCostBlock {
     usd: number | null;
@@ -168,11 +159,10 @@ interface RolloutLine {
     /** Spawning invocation within the same episode (worker → supervisor). */
     parent_rollout_id: string | null;
     run_id: string;
-    /** Logical experiment grouping from `RunRecord.experimentId`. Optional on
-     *  the wire (pre-unification ledgers lack it); null = not recorded. */
-    experiment_id?: string | null;
+    /** Logical experiment grouping from `RunRecord.experimentId`; null = not recorded. */
+    experiment_id: string | null;
     /** Stable candidate identity from `RunRecord.candidateId`; null = not recorded. */
-    candidate_id?: string | null;
+    candidate_id: string | null;
     /** Improvement-loop generation (-1 = baseline); null = not an improvement loop. */
     generation: number | null;
     /** Improvement-loop candidate index (-1 = baseline); null = not an improvement loop. */
@@ -207,10 +197,13 @@ declare function isRolloutLine(value: unknown): value is RolloutLine;
  * labels, no joins.
  */
 
-interface SftExportOptions {
-    /** Export only lines with reward ≥ this (default 1 = clean successes only). */
-    minReward?: number;
+interface TrainingExportOptions {
+    /** Include held-out evaluation data in training output. Default false. */
+    allowHeldOutTrainingData?: boolean;
+    /** Require reward to be strictly greater than this value. Default 0. */
+    minimumQualityExclusive?: number;
 }
+type SftExportOptions = TrainingExportOptions;
 interface SftRow {
     messages: ChatMessage[];
     metadata: {
@@ -224,7 +217,7 @@ interface SftRow {
 /**
  * Supervised fine-tune rows: the completed conversation of each qualifying
  * line. Fail-closed filters: trainable split only (never holdout/canary),
- * reward ≥ minReward, realness-gated lines never qualify, gap lines carry
+ * positive reward, realness-gated lines never qualify, gap lines carry
  * no trainable content.
  */
 declare function toSftRows(lines: RolloutLine[], options?: SftExportOptions): SftRow[];
@@ -242,13 +235,9 @@ interface RewardRow {
     };
 }
 /**
- * Reward-labeled rows: every line with a scalar reward, success or
- * failure. Failures are signal here — only the realness-gate zeroing
- * (applied at mint time) touches the reward, never filtering. Lines with
- * no verdict (reward null) are excluded: an unlabeled example is a gap,
- * not a zero.
+ * Reward-labeled rows for completed, positive-quality training runs.
  */
-declare function toRewardRows(lines: RolloutLine[]): RewardRow[];
+declare function toRewardRows(lines: RolloutLine[], options?: TrainingExportOptions): RewardRow[];
 interface VerifiersTokenUsage {
     input_tokens: number | null;
     output_tokens: number | null;
@@ -278,7 +267,7 @@ interface VerifiersRolloutOutput {
     };
 }
 declare function toVerifiersRolloutOutput(line: RolloutLine): VerifiersRolloutOutput;
-declare function toVerifiersRolloutOutputs(lines: RolloutLine[]): VerifiersRolloutOutput[];
+declare function toVerifiersRolloutOutputs(lines: RolloutLine[], options?: TrainingExportOptions): VerifiersRolloutOutput[];
 interface RftItem {
     /** Prompt turns only — the graded completion is re-sampled during RFT. */
     messages: ChatMessage[];
@@ -295,7 +284,7 @@ interface RftItem {
 }
 declare function toRftItem(line: RolloutLine): RftItem;
 /** RFT needs a real prompt: lines whose transcript starts with prompt turns. */
-declare function toRftItems(lines: RolloutLine[]): RftItem[];
+declare function toRftItems(lines: RolloutLine[], options?: TrainingExportOptions): RftItem[];
 declare function toJsonl(rows: ReadonlyArray<unknown>): string;
 
 /**
@@ -531,7 +520,8 @@ type FailureClass = 'success' | 'reasoning_error' | 'tool_selection_error' | 'to
  * researcher loop SHOULD be recorded as a `RunRecord`. The mandatory
  * fields are exactly those the paper "Two Loops, Three Roles" requires
  * for reproducibility: who/what/when/cost/seed/hash, plus the search vs
- * holdout split tag and either a `searchScore` or a `holdoutScore`.
+ * holdout split tag. A task score is optional because execution-only records
+ * must preserve missing labels instead of converting errors into zero quality.
  *
  * This is intentionally NOT a replacement for the rich `Run` /
  * `ProposeReviewReport` / `ScenarioResult` types already in the
@@ -552,6 +542,13 @@ type FailureClass = 'success' | 'reasoning_error' | 'tool_selection_error' | 'to
 /** Search/dev/holdout split tag. 'search' is the paper-grade alias for the
  *  combined train+test pool that the optimizer is allowed to read. */
 type RunSplitTag = 'search' | 'dev' | 'holdout';
+/**
+ * Explicit execution-lifecycle result for a run.
+ *
+ * This is separate from task quality (`outcome`) and failure classification.
+ * Producers set it only from root-run or process evidence.
+ */
+type RunTerminalOutcome = 'succeeded' | 'failed' | 'cancelled' | 'incomplete' | 'unknown';
 interface RunTokenUsage {
     input: number;
     /** All generated tokens charged as output, including reasoning tokens. */
@@ -565,11 +562,6 @@ interface RunTokenUsage {
 }
 /**
  * How a run's USD amount was obtained.
- *
- * `costUsd` remains mandatory for wire compatibility. New producers should
- * always populate this discriminated union so a missing bill is never
- * mistaken for an observed zero-dollar run. For `uncaptured`, `costUsd` uses
- * the legacy `0` sentinel while this field carries the truthful null.
  */
 type RunCostProvenance = {
     kind: 'observed';
@@ -615,8 +607,8 @@ interface JudgeScoresRecord {
     perJudge: Record<string, Record<string, number>>;
     /** Per-dim mean across judges. Convenience — derivable from `perJudge`. */
     perDimMean: Record<string, number>;
-    /** Composite mean across all dims and judges. Mirrors the score
-     *  the gate sees on `outcome.searchScore` / `holdoutScore`. */
+    /** Composite mean across successful judges. Mirrors the task score only
+     *  when `failedJudges` is empty. */
     composite: number;
     /** Judges that errored or returned an unparseable verdict. Recorded
      *  by id (e.g. `['glm-5.1']`) so a partial-failure case is explicit,
@@ -627,11 +619,11 @@ interface JudgeScoresRecord {
     notes?: string;
 }
 interface RunOutcome {
-    /** Score on the search/optimization split. Optional because a
-     *  holdout-only evaluation only fills `holdoutScore`. */
+    /** Score on the search/optimization split. Optional for holdout-only and
+     *  execution-only records. */
     searchScore?: number;
-    /** Score on the held-out split. Optional because a search-only run
-     *  only fills `searchScore`. At least one must be present. */
+    /** Score on the held-out split. Optional for search-only and execution-only
+     *  records. When both scores are absent, the run is explicitly unlabeled. */
     holdoutScore?: number;
     /** Bag of any other metric the run produced — judge dimensions,
      *  pass/fail counters, latency stats, etc. Numeric only — keeps
@@ -695,42 +687,39 @@ interface RunRecord {
     wallMs: number;
     /** Time spent queued before execution started, if known. */
     queueMs?: number;
-    /** Total USD cost. Mandatory — runs without a cost number are
-     *  unbounded by definition and must not be admitted into the gate.
-     *  `0` is retained as the compatibility sentinel for an uncaptured amount;
-     *  inspect `costProvenance` before treating it as observed. */
-    costUsd: number;
-    /** Observed, model-priced estimate, or genuinely uncaptured USD amount.
-     *  Optional only so existing serialized RunRecords remain valid. */
-    costProvenance?: RunCostProvenance;
+    /** Total USD cost, or null when the producer could not capture one. */
+    costUsd: number | null;
+    /** Whether `costUsd` came from billing data, a price calculation, or is unavailable. */
+    costProvenance: RunCostProvenance;
     /** Token usage breakdown. */
     tokenUsage: RunTokenUsage;
+    /** Root-run or process terminal result. Never inferred from a child span. */
+    terminalOutcome: RunTerminalOutcome;
+    /** Root-run or process failure reason. Valid only for a failed, cancelled,
+     *  or incomplete terminal result; never populated from a child span. */
+    terminalFailureReason?: string;
     /** Judge-side metadata, if a judge was used. */
     judgeMetadata?: RunJudgeMetadata;
     /** Per-split scores + raw bag. */
     outcome: RunOutcome;
-    /** Canonical, cross-agent failure class drawn from the shared
+    /** Canonical task-failure class drawn from the shared
      *  `FAILURE_CLASSES` taxonomy. This is the aggregation key that makes
      *  "which failure dominates across the whole fleet" answerable in ONE
      *  vocabulary — every agent classifies against the same enum. Producers
-     *  set it via the substrate classifier; leave unset only when the failure
-     *  genuinely can't be classified. */
+     *  set it only from task-result evidence. Execution errors belong in
+     *  `outcome.raw.execution_error_count`, even when the run later fails. */
     failureClass?: FailureClass;
-    /** Free-form domain-specific failure detail, scoped UNDER `failureClass`
+    /** Free-form task-failure detail, scoped UNDER `failureClass`
      *  (e.g. failureClass='tool_recovery_failure', failureMode='forge_build_unsatisfied').
-     *  The within-agent drill-down; `failureClass` is the cross-agent key. */
+     *  Do not populate this from a child execution error alone. */
     failureMode?: string;
     /** Which split this run was drawn from. */
     splitTag: RunSplitTag;
     /**
-     * Stable scenario identifier the run was scored against. Optional for
-     * backwards compatibility, but **strongly recommended**: every primitive
-     * that pairs runs by scenario (preferences, paired stats, BT tournament)
-     * keys on this. The campaign artifact populates it canonically; legacy
-     * runs without it fall back to inference from `outcome.raw.scenario_id`
-     * or `experimentId`.
+     * Stable scenario identifier the run observed or was scored against.
+     * Comparison primitives match this identity rather than input order.
      */
-    scenarioId?: string;
+    scenarioId: string;
     /**
      * Canonical identity for the agent profile cell that produced this row:
      * profile artifact hash plus optional harness/model/prompt/reporting
@@ -836,7 +825,8 @@ declare function rolloutReward(record: RunRecord): {
 /**
  * Join RunRecords with their traces into canonical rollout lines. Records
  * without spans are emitted as labeled gap lines and reported in
- * `missingTraces` — a capture gap is a finding, not a silent omission.
+ * `missingTraces`. Execution-only records without a task score are rejected
+ * because a missing training label is not a zero reward.
  */
 declare function mintRolloutRows(records: RunRecord[], store: TraceStore, options?: MintRolloutOptions): Promise<MintRolloutResult>;
 
@@ -1058,4 +1048,4 @@ declare function parseRolloutReleaseArgs(argv: string[]): RolloutReleaseCliArgs;
 /** CLI driver for `agent-eval rollout-release`. Returns the process exit code. */
 declare function runRolloutReleaseCli(argv: string[]): Promise<number>;
 
-export { type BuildOptions, type BuildSummary, CHAT_ROLES, type ChatMessage, type ChatRole, type ChatToolCall, type ClaudeTranscript, type ClaudeTranscriptRef, type ClaudeUsageTotals, DEFAULT_CLAUDE_PROJECTS_DIR, DEFAULT_OPENCODE_DB, type DatasetCardInputs, FORMAT_FILES, type MintRolloutOptions, type MintRolloutResult, type OpencodeSessionRow, RELEASE_FORMATS, ROLLOUT_CAPTURES, ROLLOUT_FORMAT, ROLLOUT_RELEASE_USAGE, ROLLOUT_ROLES, ROLLOUT_SCHEMA, ROLLOUT_SPLITS, type ReleaseFormat, type RewardRow, type RftItem, type RolloutArtifacts, type RolloutCapture, type RolloutCostBlock, type RolloutLine, type RolloutOutcome, type RolloutPolicy, type RolloutProvenance, type RolloutReleaseCliArgs, type RolloutRole, type RolloutScrubber, type RolloutSplit, type RolloutStep, type RolloutTask, SCRUB_RULES, type ScrubCounts, type ScrubReport, type ScrubRule, type SftExportOptions, type SftRow, TRAINABLE_SPLITS, type ToolDef, type VerifiersRolloutOutput, type VerifiersTokenUsage, addScrubCounts, appendRolloutLines, assertRolloutLine, buildDatasetCard, buildHfDataset, claudeProjectSlug, defaultRolloutScrubber, emptyScrubCounts, findClaudeTranscripts, findOpencodeSessionById, findOpencodeSessionsByDirectory, isRolloutLine, isTrainableSplit, mintRolloutRows, openOpencodeDb, parseRolloutReleaseArgs, planPushCommand, pushDataset, readClaudeTranscript, readOpencodeSessionMessages, readRolloutLedger, rolloutReward, runRolloutReleaseCli, scrubLines, scrubRolloutLine, scrubText, toJsonl, toRewardRows, toRftItem, toRftItems, toSftRows, toVerifiersRolloutOutput, toVerifiersRolloutOutputs, validateRolloutLine, writeRolloutLedger };
+export { type BuildOptions, type BuildSummary, CHAT_ROLES, type ChatMessage, type ChatRole, type ChatToolCall, type ClaudeTranscript, type ClaudeTranscriptRef, type ClaudeUsageTotals, DEFAULT_CLAUDE_PROJECTS_DIR, DEFAULT_OPENCODE_DB, type DatasetCardInputs, FORMAT_FILES, type MintRolloutOptions, type MintRolloutResult, type OpencodeSessionRow, RELEASE_FORMATS, ROLLOUT_CAPTURES, ROLLOUT_RELEASE_USAGE, ROLLOUT_ROLES, ROLLOUT_SCHEMA, ROLLOUT_SPLITS, type ReleaseFormat, type RewardRow, type RftItem, type RolloutArtifacts, type RolloutCapture, type RolloutCostBlock, type RolloutLine, type RolloutOutcome, type RolloutPolicy, type RolloutProvenance, type RolloutReleaseCliArgs, type RolloutRole, type RolloutScrubber, type RolloutSplit, type RolloutStep, type RolloutTask, SCRUB_RULES, type ScrubCounts, type ScrubReport, type ScrubRule, type SftExportOptions, type SftRow, TRAINABLE_SPLITS, type ToolDef, type VerifiersRolloutOutput, type VerifiersTokenUsage, addScrubCounts, appendRolloutLines, assertRolloutLine, buildDatasetCard, buildHfDataset, claudeProjectSlug, defaultRolloutScrubber, emptyScrubCounts, findClaudeTranscripts, findOpencodeSessionById, findOpencodeSessionsByDirectory, isRolloutLine, isTrainableSplit, mintRolloutRows, openOpencodeDb, parseRolloutReleaseArgs, planPushCommand, pushDataset, readClaudeTranscript, readOpencodeSessionMessages, readRolloutLedger, rolloutReward, runRolloutReleaseCli, scrubLines, scrubRolloutLine, scrubText, toJsonl, toRewardRows, toRftItem, toRftItems, toSftRows, toVerifiersRolloutOutput, toVerifiersRolloutOutputs, validateRolloutLine, writeRolloutLedger };

package/dist/rollout/index.js

@@ -1,7 +1,7 @@
 import {
   mintRolloutRows,
   rolloutReward
-} from "../chunk-M7AH34KV.js";
+} from "../chunk-UTA2TGC4.js";
 import {
   DEFAULT_CLAUDE_PROJECTS_DIR,
   DEFAULT_OPENCODE_DB,
@@ -40,11 +40,10 @@ import {
   toVerifiersRolloutOutput,
   toVerifiersRolloutOutputs,
   writeRolloutLedger
-} from "../chunk-IPYXE555.js";
+} from "../chunk-EJGRPCO3.js";
 import {
   CHAT_ROLES,
   ROLLOUT_CAPTURES,
-  ROLLOUT_FORMAT,
   ROLLOUT_ROLES,
   ROLLOUT_SCHEMA,
   ROLLOUT_SPLITS,
@@ -53,8 +52,12 @@ import {
   isRolloutLine,
   isTrainableSplit,
   validateRolloutLine
-} from "../chunk-MAX3TN3C.js";
+} from "../chunk-UWZZKKU7.js";
 import "../chunk-RZTMDUO7.js";
+import "../chunk-NL33OXEP.js";
+import "../chunk-MA6HLL3S.js";
+import "../chunk-VSMTAMNK.js";
+import "../chunk-ONWEPEDO.js";
 import "../chunk-PZ5AY32C.js";
 export {
   CHAT_ROLES,
@@ -63,7 +66,6 @@ export {
   FORMAT_FILES,
   RELEASE_FORMATS,
   ROLLOUT_CAPTURES,
-  ROLLOUT_FORMAT,
   ROLLOUT_RELEASE_USAGE,
   ROLLOUT_ROLES,
   ROLLOUT_SCHEMA,

package/dist/{run-campaign-FFRM3RH5.js → run-campaign-3A2EBYBE.js}

@@ -1,8 +1,9 @@
 import {
   planCampaignRun,
   runCampaign
-} from "./chunk-ZVCHKKOP.js";
-import "./chunk-PJQFMIOX.js";
+} from "./chunk-WED5KLZQ.js";
+import "./chunk-ZPUEEM5U.js";
+import "./chunk-MHELPNRP.js";
 import "./chunk-WS3NZZQQ.js";
 import "./chunk-VI2UW6B6.js";
 import "./chunk-ONWEPEDO.js";
@@ -11,4 +12,4 @@ export {
   planCampaignRun,
   runCampaign
 };
-//# sourceMappingURL=run-campaign-FFRM3RH5.js.map
+//# sourceMappingURL=run-campaign-3A2EBYBE.js.map

package/dist/supervisor-run/index.d.ts

@@ -27,14 +27,8 @@
 declare const ROLLOUT_SCHEMA = "tangle.rollout.v1";
 /** `agent` = a solo evaluation run (no multi-agent topology). */
 type RolloutRole = 'agent' | 'supervisor' | 'worker' | 'proposer' | 'judge' | 'analyst';
-/**
- * Split vocabulary follows `RunRecord.splitTag` ('search' is the pool the
- * optimizer may read — the trainable split), extended with the ledger's
- * 'canary'. 'train' is a legacy alias for 'search' emitted by
- * pre-unification ledgers; it validates and counts as trainable, but new
- * producers must emit 'search'.
- */
-type RolloutSplit = 'search' | 'dev' | 'holdout' | 'canary' | 'train';
+/** Split vocabulary follows `RunRecord.splitTag`, extended with `canary`. */
+type RolloutSplit = 'search' | 'dev' | 'holdout' | 'canary';
 /** 'mint' = joined live from RunRecord + trace by `mintRolloutRows`. */
 type RolloutCapture = 'mint' | 'settle-time' | 'backfill';
 type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
@@ -125,10 +119,9 @@ interface RolloutOutcome {
     /**
      * Anti-Goodhart flag from `RunRecord.outcome.realness.gated`: the run
      * faked its success signal. Reward is forced to 0 at mint time and the
-     * line never qualifies for SFT. Optional on the wire (absent = false)
-     * so pre-unification ledgers stay readable.
+     * line never qualifies for SFT.
      */
-    realness_gated?: boolean;
+    realness_gated: boolean;
 }
 interface RolloutCostBlock {
     usd: number | null;
@@ -157,11 +150,10 @@ interface RolloutLine {
     /** Spawning invocation within the same episode (worker → supervisor). */
     parent_rollout_id: string | null;
     run_id: string;
-    /** Logical experiment grouping from `RunRecord.experimentId`. Optional on
-     *  the wire (pre-unification ledgers lack it); null = not recorded. */
-    experiment_id?: string | null;
+    /** Logical experiment grouping from `RunRecord.experimentId`; null = not recorded. */
+    experiment_id: string | null;
     /** Stable candidate identity from `RunRecord.candidateId`; null = not recorded. */
-    candidate_id?: string | null;
+    candidate_id: string | null;
     /** Improvement-loop generation (-1 = baseline); null = not an improvement loop. */
     generation: number | null;
     /** Improvement-loop candidate index (-1 = baseline); null = not an improvement loop. */

package/dist/supervisor-run/index.js

@@ -27,9 +27,9 @@ import {
   unavailable,
   writeSupervisorRunReport,
   writeSupervisorRunReportSafe
-} from "../chunk-LKKT3IVV.js";
+} from "../chunk-TSN7JT6D.js";
 import "../chunk-VBQ3CRKH.js";
-import "../chunk-MAX3TN3C.js";
+import "../chunk-UWZZKKU7.js";
 import "../chunk-PZ5AY32C.js";
 export {
   DEFAULT_CANCEL_TOOLS,

package/dist/traces.d.ts

@@ -533,7 +533,8 @@ declare function isSandboxSpan(s: Span): s is SandboxSpan;
  * researcher loop SHOULD be recorded as a `RunRecord`. The mandatory
  * fields are exactly those the paper "Two Loops, Three Roles" requires
  * for reproducibility: who/what/when/cost/seed/hash, plus the search vs
- * holdout split tag and either a `searchScore` or a `holdoutScore`.
+ * holdout split tag. A task score is optional because execution-only records
+ * must preserve missing labels instead of converting errors into zero quality.
  *
  * This is intentionally NOT a replacement for the rich `Run` /
  * `ProposeReviewReport` / `ScenarioResult` types already in the
@@ -554,6 +555,13 @@ declare function isSandboxSpan(s: Span): s is SandboxSpan;
 /** Search/dev/holdout split tag. 'search' is the paper-grade alias for the
  *  combined train+test pool that the optimizer is allowed to read. */
 type RunSplitTag = 'search' | 'dev' | 'holdout';
+/**
+ * Explicit execution-lifecycle result for a run.
+ *
+ * This is separate from task quality (`outcome`) and failure classification.
+ * Producers set it only from root-run or process evidence.
+ */
+type RunTerminalOutcome = 'succeeded' | 'failed' | 'cancelled' | 'incomplete' | 'unknown';
 interface RunTokenUsage {
     input: number;
     /** All generated tokens charged as output, including reasoning tokens. */
@@ -567,11 +575,6 @@ interface RunTokenUsage {
 }
 /**
  * How a run's USD amount was obtained.
- *
- * `costUsd` remains mandatory for wire compatibility. New producers should
- * always populate this discriminated union so a missing bill is never
- * mistaken for an observed zero-dollar run. For `uncaptured`, `costUsd` uses
- * the legacy `0` sentinel while this field carries the truthful null.
  */
 type RunCostProvenance = {
     kind: 'observed';
@@ -617,8 +620,8 @@ interface JudgeScoresRecord {
     perJudge: Record<string, Record<string, number>>;
     /** Per-dim mean across judges. Convenience — derivable from `perJudge`. */
     perDimMean: Record<string, number>;
-    /** Composite mean across all dims and judges. Mirrors the score
-     *  the gate sees on `outcome.searchScore` / `holdoutScore`. */
+    /** Composite mean across successful judges. Mirrors the task score only
+     *  when `failedJudges` is empty. */
     composite: number;
     /** Judges that errored or returned an unparseable verdict. Recorded
      *  by id (e.g. `['glm-5.1']`) so a partial-failure case is explicit,
@@ -629,11 +632,11 @@ interface JudgeScoresRecord {
     notes?: string;
 }
 interface RunOutcome {
-    /** Score on the search/optimization split. Optional because a
-     *  holdout-only evaluation only fills `holdoutScore`. */
+    /** Score on the search/optimization split. Optional for holdout-only and
+     *  execution-only records. */
     searchScore?: number;
-    /** Score on the held-out split. Optional because a search-only run
-     *  only fills `searchScore`. At least one must be present. */
+    /** Score on the held-out split. Optional for search-only and execution-only
+     *  records. When both scores are absent, the run is explicitly unlabeled. */
     holdoutScore?: number;
     /** Bag of any other metric the run produced — judge dimensions,
      *  pass/fail counters, latency stats, etc. Numeric only — keeps
@@ -697,42 +700,39 @@ interface RunRecord {
     wallMs: number;
     /** Time spent queued before execution started, if known. */
     queueMs?: number;
-    /** Total USD cost. Mandatory — runs without a cost number are
-     *  unbounded by definition and must not be admitted into the gate.
-     *  `0` is retained as the compatibility sentinel for an uncaptured amount;
-     *  inspect `costProvenance` before treating it as observed. */
-    costUsd: number;
-    /** Observed, model-priced estimate, or genuinely uncaptured USD amount.
-     *  Optional only so existing serialized RunRecords remain valid. */
-    costProvenance?: RunCostProvenance;
+    /** Total USD cost, or null when the producer could not capture one. */
+    costUsd: number | null;
+    /** Whether `costUsd` came from billing data, a price calculation, or is unavailable. */
+    costProvenance: RunCostProvenance;
     /** Token usage breakdown. */
     tokenUsage: RunTokenUsage;
+    /** Root-run or process terminal result. Never inferred from a child span. */
+    terminalOutcome: RunTerminalOutcome;
+    /** Root-run or process failure reason. Valid only for a failed, cancelled,
+     *  or incomplete terminal result; never populated from a child span. */
+    terminalFailureReason?: string;
     /** Judge-side metadata, if a judge was used. */
     judgeMetadata?: RunJudgeMetadata;
     /** Per-split scores + raw bag. */
     outcome: RunOutcome;
-    /** Canonical, cross-agent failure class drawn from the shared
+    /** Canonical task-failure class drawn from the shared
      *  `FAILURE_CLASSES` taxonomy. This is the aggregation key that makes
      *  "which failure dominates across the whole fleet" answerable in ONE
      *  vocabulary — every agent classifies against the same enum. Producers
-     *  set it via the substrate classifier; leave unset only when the failure
-     *  genuinely can't be classified. */
+     *  set it only from task-result evidence. Execution errors belong in
+     *  `outcome.raw.execution_error_count`, even when the run later fails. */
     failureClass?: FailureClass;
-    /** Free-form domain-specific failure detail, scoped UNDER `failureClass`
+    /** Free-form task-failure detail, scoped UNDER `failureClass`
      *  (e.g. failureClass='tool_recovery_failure', failureMode='forge_build_unsatisfied').
-     *  The within-agent drill-down; `failureClass` is the cross-agent key. */
+     *  Do not populate this from a child execution error alone. */
     failureMode?: string;
     /** Which split this run was drawn from. */
     splitTag: RunSplitTag;
     /**
-     * Stable scenario identifier the run was scored against. Optional for
-     * backwards compatibility, but **strongly recommended**: every primitive
-     * that pairs runs by scenario (preferences, paired stats, BT tournament)
-     * keys on this. The campaign artifact populates it canonically; legacy
-     * runs without it fall back to inference from `outcome.raw.scenario_id`
-     * or `experimentId`.
+     * Stable scenario identifier the run observed or was scored against.
+     * Comparison primitives match this identity rather than input order.
      */
-    scenarioId?: string;
+    scenarioId: string;
     /**
      * Canonical identity for the agent profile cell that produced this row:
      * profile artifact hash plus optional harness/model/prompt/reporting
@@ -1238,6 +1238,19 @@ declare function applyLlmSpanOtlpAttributes(attributes: Record<string, unknown>,
 /** Canonical OpenInference-over-OTLP attribute vocabulary used at the trace boundary. */
 
 type ToolSpanOtlpInput = Pick<ToolSpan, 'toolName' | 'args' | 'argsCaptured' | 'result' | 'latencyMs'>;
+type OtlpSpanRole = 'AGENT' | 'CHAIN' | 'EVALUATOR' | 'GUARDRAIL' | 'LLM' | 'SPAN' | 'TOOL' | 'UNKNOWN';
+interface OtlpSpanRoleInput {
+    name: string;
+    attributes: Record<string, unknown>;
+    kind?: string | null;
+}
+/**
+ * Classify a span once for both measurement and error accounting.
+ * An explicit OpenInference kind wins; untyped spans use the same tool and
+ * model signals in online and offline intake.
+ */
+declare function classifyOtlpSpanRole(input: OtlpSpanRoleInput): OtlpSpanRole;
+declare function isOtlpModelCall(input: OtlpSpanRoleInput): boolean;
 declare function applyToolSpanOtlpAttributes(attributes: Record<string, unknown>, span: ToolSpanOtlpInput): void;
 declare function traceSpanKindToOpenInferenceKind(kind: string): string;
 
@@ -1488,7 +1501,7 @@ declare function convertTraceStoresToOtlp(source: string | TraceStoreSource | re
  * `ViewTraceOversized`.
  */
 /** OTLP span kind (subset we actually use). */
-type TraceAnalystSpanKind = 'AGENT' | 'LLM' | 'TOOL' | 'CHAIN' | 'GUARDRAIL' | 'SPAN' | 'UNKNOWN';
+type TraceAnalystSpanKind = 'AGENT' | 'LLM' | 'TOOL' | 'CHAIN' | 'EVALUATOR' | 'GUARDRAIL' | 'SPAN' | 'UNKNOWN';
 type TraceAnalystSpanStatus = 'OK' | 'ERROR' | 'UNSET';
 /** Subset of OTLP span fields the analyst exposes to the agent. The
  *  store's job is to project upstream's full span shape down to this
@@ -2057,13 +2070,17 @@ declare function firstStringAttr(attrs: Record<string, unknown>, keys: readonly
  *     `opts.priceUsdPerToken` from the aggregated tokens; else 0 with a
  *     loud `raw.cost_unpriced = 1` marker so a missing price is visible, not
  *     a silent zero folded into a gate.
- *   - failureMode: the first `STATUS_CODE_ERROR` span's normalized status
- *     message (carries the real failure signature, not a generic class).
+ *   - terminalFailureReason: the failed root's normalized status message,
+ *     when one unambiguous root supplies terminal failure evidence.
+ *   - terminalOutcome: reduced from root-span status only. Child tool errors
+ *     remain visible in `error_span_count` and `execution_error_count` without
+ *     changing the run outcome. Root, guardrail, evaluator, propagated, and
+ *     unknown errors retain separate counters.
  *   - model: the dominant LLM model in the trace (snapshot-padded to satisfy
  *     `validateRunRecord` when the trace's model is a bare alias).
  *   - outcome score: `opts.scoreForTrace` (AppWorld `world.evaluate()` →
- *     TGC/SGC) when supplied; else 1 when the trace had no error span, 0
- *     when it did — a defensible default the caller can override.
+ *     TGC/SGC) when supplied. Traces without an external task-quality signal
+ *     remain unlabeled; execution errors never become a task score.
  *   - prompt / completion: carried into `raw` as token-count signals and,
  *     when the first/last LLM span exposes `input.value` / `output.value`,
  *     the verbatim text is preserved on the optional `promptText` /
@@ -2119,9 +2136,9 @@ interface OtlpToRunRecordsOptions {
      * Score for a produced run's outcome (AppWorld `world.evaluate()` →
      * TGC/SGC, or
      * any [0,1] task-success signal). Keyed by the logical run id when
-     * `logicalRunIdForTrace` is supplied, otherwise by `trace_id`; falls through to
-     * the error-derived default (1 = no error span, 0 = had one) when the map
-     * has no entry or the function returns undefined.
+     * `logicalRunIdForTrace` is supplied, otherwise by `trace_id`. When the map
+     * has no entry or the function returns undefined, the record remains
+     * unlabeled.
      */
     scoreForTrace?: (runId: string, span: TraceAggregate) => number | undefined;
     /**
@@ -2153,6 +2170,12 @@ interface TraceAggregate {
     toolSpanCount: number;
     agentSpanCount: number;
     errorSpanCount: number;
+    executionErrorCount: number;
+    processErrorCount: number;
+    guardrailErrorCount: number;
+    judgeErrorCount: number;
+    propagatedErrorCount: number;
+    unclassifiedErrorCount: number;
     tokenUsage: RunTokenUsage;
     /** First error span's normalized status message, if any. */
     firstErrorMessage?: string;
@@ -2160,6 +2183,8 @@ interface TraceAggregate {
     startTime: string;
     endTime: string;
     wallMs: number;
+    /** Root-span terminal result. Child span errors do not change this value. */
+    terminalOutcome: RunTerminalOutcome;
 }
 /**
  * Parse + aggregate an OTLP traces.jsonl string into validated
@@ -2340,4 +2365,4 @@ declare function traceAnalystFunctionGroup(opts: BuildTraceAnalystToolsOpts): {
     functions: AxFunction[];
 };
 
-export { type AnalyzeTracesInput, type AnalyzeTracesOptions, type AnalyzeTracesResult, type AnalyzeTracesTurnSnapshot, type Artifact, type BudgetLedgerEntry, type BudgetSpec, type CaptureFetchContext, type CaptureFetchOptions, DEFAULT_REDACTION_RULES, DEFAULT_TRACE_ANALYST_BUDGETS, type DatasetOverview, type ErrorCluster, type EventFilter, type EventKind, type ExportableSpan, type ExtractUsageFromSseOptions, type ExtractedUsage, FAILURE_CLASSES, type FailureClass, FileSystemRawProviderSink, type FileSystemRawProviderSinkOptions, FileSystemTraceStore, type FileSystemTraceStoreOptions, type FlattenOtlpOptions, type GenericSpan, INPUT_VALUE, InMemoryRawProviderSink, type InMemoryRawProviderSinkOptions, InMemoryTraceStore, type JudgeSpan, LLM_CACHED_TOKENS, LLM_CACHED_TOKEN_ATTR_KEYS, LLM_CACHE_WRITE_TOKENS, LLM_CACHE_WRITE_TOKEN_ATTR_KEYS, LLM_CONTEXT_TOKENS, LLM_COST_ATTR_KEYS, LLM_COST_USD, LLM_INPUT_TOKENS, LLM_INPUT_TOKEN_ATTR_KEYS, LLM_MODEL_ATTR_KEYS, LLM_MODEL_NAME, LLM_OUTPUT_TOKENS, LLM_OUTPUT_TOKEN_ATTR_KEYS, LLM_REASONING_TOKENS, LLM_REASONING_TOKEN_ATTR_KEYS, type LlmSpan, type LlmSpanOtlpInput, type Message, NoopRawProviderSink, OPENINFERENCE_SPAN_KIND, OTEL_AGENT_EVAL_SCOPE, OUTPUT_VALUE, type OtelExportConfig, type OtelExporter, type OtlpExport, OtlpFileTraceStore, type OtlpFileTraceStoreOptions, type OtlpFlatLine, type OtlpResourceSpans, type OtlpSpan, type OtlpToRunRecordsOptions, type OtlpTraceRunRecord, type ProjectedOtlpSpan, type ProviderRedactor, type QueryTracesPage, REDACTION_VERSION, RUN_COST_ATTR_KEYS, type RawProviderDirection, type RawProviderEvent, type RawProviderSink, type RawProviderSinkFilter, type RedactionReport, type RedactionRule, ReplayCache, type ReplayCacheEntry, ReplayCacheMissError, type ReplayCacheStats, type ReplayFetchOptions, type RetrievalSpan, type Run, type RunCompleteHook, type RunCompleteHookContext, type RunFilter, RunIntegrityError, type RunIntegrityExpectations, type RunIntegrityIssue, type RunIntegrityIssueCode, type RunIntegrityReport, type RunLayer, type RunOutcome$1 as RunOutcome, type RunStatus, SPAN_KIND_ATTR_KEYS, type SandboxSpan, type SearchSpanResult, type SearchTraceResult, type Span, type SpanBase, type SpanFilter, type SpanHandle, type SpanKind, type SpanMatchRecord, SpanNotFoundError, type SpanStatus, type SseUsageMode, TOOL_ARGS_CAPTURED, TOOL_LATENCY_MS, TOOL_NAME, TOOL_NAME_ATTR_KEYS, TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, TRACE_SCHEMA_VERSION, type ToolSpan, type ToolSpanOtlpInput, type TraceAggregate, type TraceAnalysisStore, type TraceAnalystByteBudgets, type TraceAnalystFilters, type TraceAnalystHookOptions, type TraceAnalystSpan, type TraceAnalystSpanKind, type TraceAnalystSpanStatus, type TraceAnalystTraceSummary, TraceEmitter, type TraceEmitterOptions, type TraceEvent, TraceFileMissingError, type TraceInsightContext, type TraceInsightFinding, type TraceInsightPanelRole, type TraceInsightPromptInput, type TraceInsightQualityGate, type TraceInsightQuestion, type TraceInsightReadiness, type TraceInsightSuite, type TraceInsightTask, TraceNotFoundError, type TraceStore, type TraceStoreSource, type TraceStoreToOtlpOptions, type TracesToOtlpResult, type ViewSpansResult, type ViewTraceOversized, type ViewTraceResult, aggregateLlm, analyzeTraces, applyLlmSpanOtlpAttributes, applyToolSpanOtlpAttributes, argHash, asNumber, asString, assertRunCaptured, buildTraceAnalystTools, buildTraceInsightContext, buildTraceInsightPrompt, captureFetchToRawSink, contextInputTokens, convertTraceStoresToOtlp, createOtelExporter, createOtelTracingStore, createReplayFetch, defaultProviderRedactor, defaultTraceInsightPanel, describeTraceInsightScope, domainEvidencePattern, exportRunAsOtlp, extractOtlpAttributes, extractUsage, extractUsageFromResponse, extractUsageFromSse, firstNumberAttr, firstStringAttr, flattenOtlpExportToNdjson, groupBy, hasCapturedToolArgs, inferDomainKeywords, inferOtlpKind, isJudgeSpan, isLlmSpan, isRetrievalSpan, isSandboxSpan, isToolSpan, iterateRawCalls, judgeSpans, llmSpanFromProvider, llmSpans, otelRunCompleteHook, otlpRowsToRunRecords, otlpRowsToTraceRunRecords, otlpToRunRecords, otlpToTraceRunRecords, planTraceInsightQuestions, projectOtlpFlatLine, providerFromBaseUrl, readOtlpStatus, redactString, redactValue, runFailureClass, runsForScenario, scoreTraceInsightReadiness, stringField, throwIfRunIncomplete, tokenizeDomainWords, toolSpans, traceAnalystFunctionGroup, traceAnalystOnRunComplete, traceSpanKindToOpenInferenceKind };
+export { type AnalyzeTracesInput, type AnalyzeTracesOptions, type AnalyzeTracesResult, type AnalyzeTracesTurnSnapshot, type Artifact, type BudgetLedgerEntry, type BudgetSpec, type CaptureFetchContext, type CaptureFetchOptions, DEFAULT_REDACTION_RULES, DEFAULT_TRACE_ANALYST_BUDGETS, type DatasetOverview, type ErrorCluster, type EventFilter, type EventKind, type ExportableSpan, type ExtractUsageFromSseOptions, type ExtractedUsage, FAILURE_CLASSES, type FailureClass, FileSystemRawProviderSink, type FileSystemRawProviderSinkOptions, FileSystemTraceStore, type FileSystemTraceStoreOptions, type FlattenOtlpOptions, type GenericSpan, INPUT_VALUE, InMemoryRawProviderSink, type InMemoryRawProviderSinkOptions, InMemoryTraceStore, type JudgeSpan, LLM_CACHED_TOKENS, LLM_CACHED_TOKEN_ATTR_KEYS, LLM_CACHE_WRITE_TOKENS, LLM_CACHE_WRITE_TOKEN_ATTR_KEYS, LLM_CONTEXT_TOKENS, LLM_COST_ATTR_KEYS, LLM_COST_USD, LLM_INPUT_TOKENS, LLM_INPUT_TOKEN_ATTR_KEYS, LLM_MODEL_ATTR_KEYS, LLM_MODEL_NAME, LLM_OUTPUT_TOKENS, LLM_OUTPUT_TOKEN_ATTR_KEYS, LLM_REASONING_TOKENS, LLM_REASONING_TOKEN_ATTR_KEYS, type LlmSpan, type LlmSpanOtlpInput, type Message, NoopRawProviderSink, OPENINFERENCE_SPAN_KIND, OTEL_AGENT_EVAL_SCOPE, OUTPUT_VALUE, type OtelExportConfig, type OtelExporter, type OtlpExport, OtlpFileTraceStore, type OtlpFileTraceStoreOptions, type OtlpFlatLine, type OtlpResourceSpans, type OtlpSpan, type OtlpSpanRole, type OtlpSpanRoleInput, type OtlpToRunRecordsOptions, type OtlpTraceRunRecord, type ProjectedOtlpSpan, type ProviderRedactor, type QueryTracesPage, REDACTION_VERSION, RUN_COST_ATTR_KEYS, type RawProviderDirection, type RawProviderEvent, type RawProviderSink, type RawProviderSinkFilter, type RedactionReport, type RedactionRule, ReplayCache, type ReplayCacheEntry, ReplayCacheMissError, type ReplayCacheStats, type ReplayFetchOptions, type RetrievalSpan, type Run, type RunCompleteHook, type RunCompleteHookContext, type RunFilter, RunIntegrityError, type RunIntegrityExpectations, type RunIntegrityIssue, type RunIntegrityIssueCode, type RunIntegrityReport, type RunLayer, type RunOutcome$1 as RunOutcome, type RunStatus, SPAN_KIND_ATTR_KEYS, type SandboxSpan, type SearchSpanResult, type SearchTraceResult, type Span, type SpanBase, type SpanFilter, type SpanHandle, type SpanKind, type SpanMatchRecord, SpanNotFoundError, type SpanStatus, type SseUsageMode, TOOL_ARGS_CAPTURED, TOOL_LATENCY_MS, TOOL_NAME, TOOL_NAME_ATTR_KEYS, TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, TRACE_SCHEMA_VERSION, type ToolSpan, type ToolSpanOtlpInput, type TraceAggregate, type TraceAnalysisStore, type TraceAnalystByteBudgets, type TraceAnalystFilters, type TraceAnalystHookOptions, type TraceAnalystSpan, type TraceAnalystSpanKind, type TraceAnalystSpanStatus, type TraceAnalystTraceSummary, TraceEmitter, type TraceEmitterOptions, type TraceEvent, TraceFileMissingError, type TraceInsightContext, type TraceInsightFinding, type TraceInsightPanelRole, type TraceInsightPromptInput, type TraceInsightQualityGate, type TraceInsightQuestion, type TraceInsightReadiness, type TraceInsightSuite, type TraceInsightTask, TraceNotFoundError, type TraceStore, type TraceStoreSource, type TraceStoreToOtlpOptions, type TracesToOtlpResult, type ViewSpansResult, type ViewTraceOversized, type ViewTraceResult, aggregateLlm, analyzeTraces, applyLlmSpanOtlpAttributes, applyToolSpanOtlpAttributes, argHash, asNumber, asString, assertRunCaptured, buildTraceAnalystTools, buildTraceInsightContext, buildTraceInsightPrompt, captureFetchToRawSink, classifyOtlpSpanRole, contextInputTokens, convertTraceStoresToOtlp, createOtelExporter, createOtelTracingStore, createReplayFetch, defaultProviderRedactor, defaultTraceInsightPanel, describeTraceInsightScope, domainEvidencePattern, exportRunAsOtlp, extractOtlpAttributes, extractUsage, extractUsageFromResponse, extractUsageFromSse, firstNumberAttr, firstStringAttr, flattenOtlpExportToNdjson, groupBy, hasCapturedToolArgs, inferDomainKeywords, inferOtlpKind, isJudgeSpan, isLlmSpan, isOtlpModelCall, isRetrievalSpan, isSandboxSpan, isToolSpan, iterateRawCalls, judgeSpans, llmSpanFromProvider, llmSpans, otelRunCompleteHook, otlpRowsToRunRecords, otlpRowsToTraceRunRecords, otlpToRunRecords, otlpToTraceRunRecords, planTraceInsightQuestions, projectOtlpFlatLine, providerFromBaseUrl, readOtlpStatus, redactString, redactValue, runFailureClass, runsForScenario, scoreTraceInsightReadiness, stringField, throwIfRunIncomplete, tokenizeDomainWords, toolSpans, traceAnalystFunctionGroup, traceAnalystOnRunComplete, traceSpanKindToOpenInferenceKind };