@tangle-network/agent-eval 0.187.2 → 0.188.0

package/dist/index.js

@@ -1,12 +1,12 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
 import { i as JudgeError, o as NotFoundError, r as ConfigError, s as ValidationError, t as AgentEvalError } from "./errors-Dngq5h35.js";
 import { a as hashCanonical, r as canonicalString } from "./canonical-BsZVgBhW.js";
-import { a as CODING_HARNESSES, c as agentProfileId, d as harnessAxisOf, i as verifyCompletion, l as agentProfileModelId, n as completionVerdict, o as HARNESS_NATIVE_MODEL, r as createLlmCorrectnessChecker, s as agentProfileHash, t as extractProducedState, u as expandProfileAxes } from "./produced-state-Cn9ECr4v.js";
+import { a as CODING_HARNESSES, c as agentProfileId, d as harnessAxisOf, i as verifyCompletion, l as agentProfileModelId, n as completionVerdict, o as HARNESS_NATIVE_MODEL, r as createLlmCorrectnessChecker, s as agentProfileHash, t as extractProducedState, u as expandProfileAxes } from "./produced-state-xsMMjYVc.js";
 import { c as groupRunsByAgentProfileCell, d as validateAgentProfileCell, f as verifyAgentProfileCell, h as manifestContentDigest, i as agentProfileCellKey, m as hashJson, r as agentProfileCellHashMaterial, s as buildAgentProfileCell, t as AGENT_PROFILE_KINDS, u as toAgentProfileJson } from "./agent-profile-cell-DcFW4vOc.js";
 import { t as mulberry32 } from "./random-Dn5fPWkt.js";
 import { a as spearmanR, c as weightedMean, i as ranks, n as partialCredit, o as summarizeNumberSeries, r as pearsonR, s as weightedComposite, t as confidenceInterval } from "./descriptive-1V17A-qa.js";
 import { n as calibrateJudgeContinuous, o as verbosityBias, r as continuousAgreement, t as calibrateJudge } from "./judge-calibration-DYmaBtJr.js";
-import { a as budgetBreachView, c as INFRA_FAILURE_BLAMES, d as failureBlame, f as corpusInterRaterAgreement, i as failureClusterView, l as classifyFailure, m as interRaterReliability, n as computeToolUseMetrics, o as DEFAULT_FAILURE_REASON_RULES, p as corpusInterRaterAgreementFromJudgeScores, r as judgeAgreementView, s as FAILURE_BLAME, t as toolWasteView, u as classifyFailureReason } from "./tool-waste-nbHPAxei.js";
+import { a as budgetBreachView, c as interRaterReliability, i as failureClusterView, n as computeToolUseMetrics, o as corpusInterRaterAgreement, r as judgeAgreementView, s as corpusInterRaterAgreementFromJudgeScores, t as toolWasteView } from "./tool-waste-CJDfxH45.js";
 import { i as pairedCohensDz, n as cohensD, r as interpretCliffs, t as cliffsDelta } from "./effect-sizes-DiH8MGOH.js";
 import { a as requiredSampleSize, c as holm, i as requiredPairedSampleSize, n as mcnemarRequiredN, o as benjaminiHochberg, r as pairedMde, s as bonferroni, t as mcnemarPower } from "./power-and-mde-BJOpt6pq.js";
 import { _ as passAtK, a as MANN_WHITNEY_EXACT_MAX_STATES, c as mannWhitneyU, d as isBinaryOutcomeVector, f as mcnemar, g as pairedRiskDifferenceScore, h as pairedRiskDifferenceExact, i as DEFAULT_PERMUTATIONS, l as wilcoxonSignedRank, m as pairedRiskDifference, n as pairArms, o as MANN_WHITNEY_EXACT_MAX_WORK, p as pairedBinaryScale, r as pairRunRecords, s as WILCOXON_EXACT_MAX_N, t as comparePairedArms, v as wilson } from "./paired-arms-JSDcs2zx.js";
@@ -21,44 +21,45 @@ import { r as observedSplitScore, t as isRealnessGated } from "./reward-nw2xZGZG
 import { a as parseRunRecordSafe, c as validateRunRecord, i as modelHasSnapshot, n as UNKNOWN_MODEL, o as roundTripRunRecord, r as isRunRecord, s as runTaskScore, t as RunRecordValidationError } from "./run-record-tg_5H2IK.js";
 import { a as summaryTable, n as gainHistogram, r as paretoChart } from "./summary-report-BMvou2oZ.js";
 import { n as contentHash, r as fileVerdictCache, t as canonicalJson } from "./verdict-cache-BQEsVy9n.js";
-import { B as DEFAULT_RED_TEAM_CORPUS, H as redTeamReport, N as dominates, P as paretoFrontier, U as scoreRedTeamOutput, V as redTeamDataset, W as runCanaries, X as runCampaign, a as transientDispatchFailure, i as quotaExhaustedUntil, o as aggregateRunScore, s as clamp01, t as llmJudge } from "./llm-judge-BVso5x-u.js";
+import { B as DEFAULT_RED_TEAM_CORPUS, H as redTeamReport, N as dominates, P as paretoFrontier, U as scoreRedTeamOutput, V as redTeamDataset, W as runCanaries, X as runCampaign, a as transientDispatchFailure, i as quotaExhaustedUntil, o as aggregateRunScore, s as clamp01, t as llmJudge } from "./llm-judge-DF18J3CR.js";
 import { a as resolveModelPricing, i as isModelPriced, n as estimateCost, r as estimateTokens, t as MODEL_PRICING } from "./metrics-DOMpkoeb.js";
 import { a as CostLedgerPersistenceError, c as costForTokenPricing, i as CostLedger, l as costForUsage, n as CostCallConflictError, o as CostReceiptCaptureError, r as CostCeilingReachedError, s as CostReservationExceededError, t as CostAccountingIncompleteError, u as modelPriceKey } from "./cost-ledger-_IbkejCF.js";
 import { D as parseReflectionResponse, E as buildReflectionPrompt, G as summarizeBackendIntegrity, U as BackendIntegrityError, W as assertRealBackend, c as ATTESTATION_ALGORITHM, l as attest, u as verifyAttestation, z as surfaceContentHash } from "./campaign-evidence-IF1p0oDa.js";
-import { n as REDACTION_VERSION, r as redactString, t as DEFAULT_REDACTION_RULES } from "./redact-7Aq1ukl-.js";
+import { d as redactForShare, f as redactText, n as REDACTION_VERSION, p as shareAllowed, r as assessShareSafety, u as redact } from "./redact-DxwlUAvh.js";
 import { i as makeProposalFinding, n as computeFindingId, r as makeFinding } from "./types-C8VBbiw6.js";
-import { r as selfImprove, t as defineAgentEval } from "./define-agent-eval-C0EqJ9Gz.js";
+import { r as selfImprove, t as defineAgentEval } from "./define-agent-eval-ChtddasD.js";
 import { n as equivalenceVerdict, t as certificationEvidenceDigest } from "./verdict-DhPoXApk.js";
-import { t as TraceEmitter } from "./emitter-DeQHiDMm.js";
+import { t as TraceEmitter } from "./emitter-DbMXUIVP.js";
 import { t as buildTrajectory } from "./trajectory-D_7rLrvE.js";
-import { t as runCounterfactual } from "./counterfactual-Bjq1mlUu.js";
-import { U as DEFAULT_TRACE_ANALYST_OUTPUT_TOKENS, V as parseFindingSubject, l as createBoundedTraceAnalysisStore, m as TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, p as DEFAULT_TRACE_ANALYST_BUDGETS, t as createTraceAnalyst } from "./kind-factory-V79Hw0AU.js";
-import { _ as completedAnalystReviewQuality, b as validateAnalystReviewDecisions, c as FAILURE_MODE_KIND_SPEC, g as assertUniqueFindingIds, h as analystRunDigest, i as DEFAULT_TRACE_ANALYST_KINDS, m as analystFindingDigest, n as AnalystRegistry, t as buildDefaultAnalystRegistry, v as readAnalystReview, y as snapshotAnalystRun } from "./default-registry-Ca2IWH1X.js";
+import { t as runCounterfactual } from "./counterfactual-DtMWvn7D.js";
+import { H as parseFindingSubject, W as DEFAULT_TRACE_ANALYST_OUTPUT_TOKENS, h as TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, m as DEFAULT_TRACE_ANALYST_BUDGETS, t as createTraceAnalyst, u as createBoundedTraceAnalysisStore } from "./kind-factory-g1ROw67A.js";
+import { _ as completedAnalystReviewQuality, b as validateAnalystReviewDecisions, c as FAILURE_MODE_KIND_SPEC, g as assertUniqueFindingIds, h as analystRunDigest, i as DEFAULT_TRACE_ANALYST_KINDS, m as analystFindingDigest, n as AnalystRegistry, t as buildDefaultAnalystRegistry, v as readAnalystReview, y as snapshotAnalystRun } from "./default-registry-BtZ_t-9b.js";
 import { OUTPUT_VALUE } from "./trace-attributes.js";
 import { r as extractUsageFromSse, t as extractUsage } from "./extract-usage-BrQ8mCLX.js";
-import { n as InMemoryRawProviderSink, r as NoopRawProviderSink, t as FileSystemRawProviderSink } from "./raw-provider-sink-BQd7mzyT.js";
-import { D as captureFetchToRawSink, S as exportRunAsOtlp, _ as tokenizeDomainWords, d as inferDomainKeywords, g as scoreTraceInsightReadiness, l as describeTraceInsightScope, n as toolSpansToTraceAnalysisStore, o as buildTraceInsightContext, s as buildTraceInsightPrompt, u as domainEvidencePattern, v as analyzeTraces } from "./store-tool-spans-B1e6Auc2.js";
-import { n as assertRunCaptured, t as RunIntegrityError } from "./integrity-Cy9WHAtb.js";
+import { n as InMemoryRawProviderSink, r as NoopRawProviderSink, t as FileSystemRawProviderSink } from "./raw-provider-sink-C96CcqeG.js";
+import { D as captureFetchToRawSink, S as exportRunAsOtlp, _ as tokenizeDomainWords, d as inferDomainKeywords, g as scoreTraceInsightReadiness, l as describeTraceInsightScope, n as toolSpansToTraceAnalysisStore, o as buildTraceInsightContext, s as buildTraceInsightPrompt, u as domainEvidencePattern, v as analyzeTraces } from "./store-tool-spans-ClPxcvh2.js";
+import { n as assertRunCaptured, t as RunIntegrityError } from "./integrity-BFP4kjGj.js";
 import { n as InMemoryTraceStore, t as FileSystemTraceStore } from "./store-DNe_Uv1Q.js";
 import { t as packageVersion$1 } from "./package-version-D7lQHt_-.js";
+import { a as classifyFailure, i as INFRA_FAILURE_BLAMES, o as classifyFailureReason, r as FAILURE_BLAME, s as failureBlame, t as DEFAULT_FAILURE_REASON_RULES } from "./failure-taxonomy-CjabTATj.js";
 import { n as runBoundedProcess, t as DEFAULT_BOUNDED_PROCESS_TIMEOUT_MS } from "./bounded-process-BBZob7vl.js";
-import { t as runEvalCampaign } from "./eval-campaign-XFHEpN86.js";
-import { i as improvementVerdict, n as computeExperimentStats } from "./experiment-tracker-BKEumQug.js";
+import { t as runEvalCampaign } from "./eval-campaign-CeotQ1ZR.js";
 import "./rollout-C0Ifk3vK.js";
 import { t as mintRolloutRows } from "./mint-B4zgSAJW.js";
 import { n as pairedEvalueSequence, t as evaluateInterimReleaseConfidence } from "./sequential-CzK5DarL.js";
-import { S as judgeFamily, _ as assertServedModels, b as CrossFamilyError, d as stripFencedJson, f as ModelSubstitutionError, h as assertServedModel, i as backoffMs, l as isTransientLlmError, m as assertCrossFamilyServed, o as costReceiptFromLlm, p as ServedCrossFamilyError, r as LlmResponseError, s as costReceiptFromLlmError, t as LlmCallError, u as maximumChargeForLlmRequest, v as checkServedModel, x as assertCrossFamily, y as servedModelAcceptable } from "./llm-client-DDhZ29Vm.js";
-import { n as paidJsonChat } from "./chat-json-call-C-DnDxEy.js";
-import { t as createDspyRlmTraceEngine } from "./dspy-rlm-engine-BE9lCzzL.js";
-import { a as diffFindings, n as runSemanticConceptJudge, o as createChatTraceEngine, r as FindingsStore, t as SEMANTIC_CONCEPT_JUDGE_VERSION } from "./semantic-concept-judge-Cnt0TWp0.js";
+import { S as judgeFamily, _ as assertServedModels, b as CrossFamilyError, d as stripFencedJson, f as ModelSubstitutionError, h as assertServedModel, i as backoffMs, l as isTransientLlmError, m as assertCrossFamilyServed, o as costReceiptFromLlm, p as ServedCrossFamilyError, r as LlmResponseError, s as costReceiptFromLlmError, t as LlmCallError, u as maximumChargeForLlmRequest, v as checkServedModel, x as assertCrossFamily, y as servedModelAcceptable } from "./llm-client-DF9bPNYA.js";
+import { n as paidJsonChat } from "./chat-json-call-JVGbfx95.js";
+import { t as createDspyRlmTraceEngine } from "./dspy-rlm-engine-sPX7B5ac.js";
+import { a as diffFindings, n as runSemanticConceptJudge, o as createChatTraceEngine, r as FindingsStore, t as SEMANTIC_CONCEPT_JUDGE_VERSION } from "./semantic-concept-judge-70LxrCSL.js";
 import { t as analyzeSeries } from "./series-convergence-CjO2QdRW.js";
-import { i as otlpTextToTraceAnalysisStore, n as OtlpFileTraceStore } from "./store-otlp-2gYCy-v0.js";
+import { i as otlpTextToTraceAnalysisStore, n as OtlpFileTraceStore } from "./store-otlp-DPgzSQKS.js";
 import { n as evaluateReleaseConfidence, r as bootstrapCi } from "./release-confidence-RanRUXRW.js";
-import { t as createChatClient } from "./chat-client-DqPqWzVV.js";
+import { t as createChatClient } from "./chat-client-C4dg7Ng_.js";
 import { createHash } from "node:crypto";
 import { accessSync, appendFileSync, constants, cpSync, existsSync, mkdirSync, promises, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { INPUT_TOKEN_ATTR_KEYS, MODEL_ATTR_KEYS, OUTPUT_TOKEN_ATTR_KEYS, SPAN_KINDS, TOOL_NAME_ATTR_KEYS, firstNumberAttr, firstStringAttr, resolveSpanKind } from "@tangle-network/agent-trace-contract";
 //#region src/profile/baselines.ts
 /**
 * Strong, generically-useful baseline ROLES — the top zone of an `AgentProfile`
@@ -966,7 +967,7 @@ function stableHash(input) {
 * malformed line never breaks the read. `diffScorecard` compares the latest
 * entry of each cell against its predecessor with Cohen's d + Welch's t-test.
 */
-function median(xs) {
+function median$1(xs) {
 	if (xs.length === 0) return 0;
 	const sorted = [...xs].sort((a, b) => a - b);
 	const mid = Math.floor(sorted.length / 2);
@@ -1024,7 +1025,7 @@ function recordRuns(runs, opts) {
 			commitSha: opts.commitSha,
 			timestamp,
 			scores,
-			composite: median(scores),
+			composite: median$1(scores),
 			runIds: scored.map((s) => s.run.runId)
 		};
 		const perDimension = aggregatePerDimension(scenarioRuns);
@@ -1184,88 +1185,383 @@ function formatScorecardDiff(diff) {
 	return lines.join("\n");
 }
 //#endregion
-//#region src/trace-contracts.ts
+//#region src/trace-contracts/spans.ts
+const EVAL_KIND_TO_CONTRACT_KIND = /* @__PURE__ */ new Map([["judge", "EVALUATOR"], ["retrieval", "RETRIEVER"]]);
+/**
+* The span's contract kind: a declared kind when recognised, else inferred.
+* A top-level `kind` counts as a declaration only when it names a contract
+* kind; OTLP words such as `SPAN_KIND_INTERNAL` and the eval kinds `sandbox`
+* and `custom` fall through to the span-kind attribute and name signals.
+*/
+function contractSpanKind(span) {
+	const raw = typeof span.kind === "string" ? span.kind : void 0;
+	const mapped = raw === void 0 ? void 0 : EVAL_KIND_TO_CONTRACT_KIND.get(raw) ?? raw.toUpperCase();
+	const declared = mapped !== void 0 && SPAN_KINDS.includes(mapped) ? mapped : void 0;
+	return resolveSpanKind({
+		...declared === void 0 ? {} : { kind: declared },
+		name: span.name,
+		attributes: span.attributes ?? {}
+	});
+}
+/**
+* Tool name: `span.toolName` (typed ToolSpan) → the tool-name attributes
+* (`gen_ai.tool.name`, `tool.name`, ..., `toolName`) → `span.name` when the
+* span is a TOOL span (otel-bridge's `ExportableSpan` drops `toolName`).
+*/
+function contractSpanToolName(span) {
+	if (typeof span.toolName === "string") return span.toolName;
+	const attributes = span.attributes ?? {};
+	const fromAttr = firstStringAttr(attributes, TOOL_NAME_ATTR_KEYS) ?? firstStringAttr(attributes, ["toolName"]);
+	if (fromAttr !== void 0) return fromAttr;
+	if (typeof span.name === "string" && contractSpanKind(span) === "TOOL") return span.name;
+}
+function spanModel(span) {
+	if (typeof span.model === "string" && span.model.length > 0) return span.model;
+	return firstStringAttr(span.attributes ?? {}, MODEL_ATTR_KEYS);
+}
+/** Input plus output tokens, or `undefined` when either side is unrecorded. */
+function spanTotalTokens(span) {
+	const attributes = span.attributes ?? {};
+	const input = finite(span.inputTokens) ?? firstNumberAttr(attributes, INPUT_TOKEN_ATTR_KEYS);
+	const output = finite(span.outputTokens) ?? firstNumberAttr(attributes, OUTPUT_TOKEN_ATTR_KEYS);
+	return input === void 0 || output === void 0 ? void 0 : input + output;
+}
+const ARGUMENT_ATTR_KEYS = [
+	"gen_ai.tool.call.arguments",
+	"tool.arguments",
+	"input.value"
+];
+/** The call's arguments: the typed `args` field, else the argument attributes.
+*  JSON strings are parsed; an unparseable string is kept as a string. */
+function spanArguments(span) {
+	if (span.argsCaptured === false || span.attributes?.["tool.args_captured"] === false) return {
+		known: false,
+		reason: "arguments were not captured"
+	};
+	if (span.args !== void 0) return {
+		known: true,
+		value: parseJsonString(span.args)
+	};
+	for (const key of ARGUMENT_ATTR_KEYS) {
+		const value = span.attributes?.[key];
+		if (value !== void 0 && value !== null) return {
+			known: true,
+			value: parseJsonString(value)
+		};
+	}
+	return {
+		known: false,
+		reason: "the span carries no argument evidence"
+	};
+}
+function parseJsonString(value) {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+}
+function finite(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function isSpanError(span) {
+	return typeof span.status === "string" && /^(?:error|status_code_error)$/i.test(span.status);
+}
+//#endregion
+//#region src/trace-contracts/predicates.ts
 function isSerializedRegex(v) {
 	return typeof v === "object" && v !== null && typeof v.$regex === "string" && typeof v.flags === "string";
 }
+function isOneOfMatcher(v) {
+	return typeof v === "object" && v !== null && Array.isArray(v.oneOf);
+}
+function isRegexValue(v) {
+	return v instanceof RegExp || isSerializedRegex(v);
+}
 function matchText(actual, matcher) {
 	if (typeof actual !== "string") return false;
 	if (typeof matcher === "string") return actual === matcher;
 	if (matcher instanceof RegExp) return matcher.test(actual);
+	if (isOneOfMatcher(matcher)) return matcher.oneOf.includes(actual);
 	return new RegExp(matcher.$regex, matcher.flags).test(actual);
 }
-function resolveToolName(span) {
-	if (typeof span.toolName === "string") return span.toolName;
-	const fromAttr = span.attributes?.["tool.name"] ?? span.attributes?.toolName;
-	if (typeof fromAttr === "string") return fromAttr;
-	if (span.kind === "tool" && typeof span.name === "string") return span.name;
+function assertMatcher(m, where) {
+	if (typeof m === "string" || m instanceof RegExp) return;
+	if (isSerializedRegex(m)) {
+		try {
+			new RegExp(m.$regex, m.flags);
+		} catch (error) {
+			throw new ValidationError(`${where}: invalid regex /${m.$regex}/${m.flags}: ${String(error)}`);
+		}
+		return;
+	}
+	if (isOneOfMatcher(m)) {
+		if (m.oneOf.length === 0 || !m.oneOf.every((x) => typeof x === "string")) throw new ValidationError(`${where}: "oneOf" must be a non-empty array of strings`);
+		return;
+	}
+	throw new ValidationError(`${where}: matcher must be string | RegExp | SerializedRegex | { oneOf }`);
 }
 function assertPredicate(value, where) {
-	if (value === null || typeof value !== "object") throw new ValidationError(`${where}: predicate must be an object, got ${typeof value}`);
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new ValidationError(`${where}: predicate must be an object, got ${typeof value}`);
 	const p = value;
-	for (const field of ["name", "tool"]) {
-		const m = p[field];
-		if (m !== void 0 && typeof m !== "string" && !(m instanceof RegExp) && !isSerializedRegex(m)) throw new ValidationError(`${where}: "${field}" must be string | RegExp | SerializedRegex`);
-	}
+	for (const field of [
+		"name",
+		"tool",
+		"model"
+	]) if (p[field] !== void 0) assertMatcher(p[field], `${where} "${field}"`);
+	if (p.kind !== void 0 && !SPAN_KINDS.includes(p.kind)) throw new ValidationError(`${where}: "kind" must be one of ${SPAN_KINDS.join(", ")}`);
 	if (p.attr !== void 0 && (p.attr === null || typeof p.attr !== "object" || Array.isArray(p.attr))) throw new ValidationError(`${where}: "attr" must be a plain object`);
+	for (const [key, expected] of Object.entries(p.attr ?? {})) if (isSerializedRegex(expected)) assertMatcher(expected, `${where} attr "${key}"`);
+	if (p.not !== void 0) assertPredicate(p.not, `${where} "not"`);
 	if (p.requiresCustom && typeof p.custom !== "function") throw new ValidationError(`${where}: rule was built with a custom predicate function, which does not survive JSON serialization — re-attach \`custom\` after deserializing or drop the rule`);
 	const hasAttr = p.attr !== void 0 && Object.keys(p.attr).length > 0;
-	if (p.name === void 0 && p.tool === void 0 && !hasAttr && typeof p.custom !== "function") throw new ValidationError(`${where}: empty predicate would match every span — specify name, tool, attr, or custom`);
-}
-/** Test one span against one predicate. All specified fields must match. */
-function matchSpan(span, predicate) {
-	assertPredicate(predicate, "matchSpan");
-	if (predicate.name !== void 0 && !matchText(span.name, predicate.name)) return false;
-	if (predicate.tool !== void 0 && !matchText(resolveToolName(span), predicate.tool)) return false;
-	if (predicate.attr !== void 0) for (const [key, expected] of Object.entries(predicate.attr)) {
+	if (p.name === void 0 && p.tool === void 0 && p.model === void 0 && p.kind === void 0 && p.not === void 0 && !hasAttr && typeof p.custom !== "function") throw new ValidationError(`${where}: empty predicate would match every span — specify name, tool, model, kind, attr, not, or custom`);
+}
+function predicateMatches(span, p) {
+	if (p.kind !== void 0 && contractSpanKind(span) !== p.kind) return false;
+	if (p.name !== void 0 && !matchText(span.name, p.name)) return false;
+	if (p.tool !== void 0 && !matchText(contractSpanToolName(span), p.tool)) return false;
+	if (p.model !== void 0 && !matchText(spanModel(span), p.model)) return false;
+	if (p.attr !== void 0) for (const [key, expected] of Object.entries(p.attr)) {
 		const actual = span.attributes?.[key];
-		if (expected instanceof RegExp || isSerializedRegex(expected)) {
+		if (isRegexValue(expected)) {
 			if (!matchText(typeof actual === "string" ? actual : void 0, expected)) return false;
 		} else if (actual !== expected) return false;
 	}
-	if (predicate.custom !== void 0 && !predicate.custom(span)) return false;
+	if (p.not !== void 0 && predicateMatches(span, p.not)) return false;
+	if (p.custom !== void 0 && !p.custom(span)) return false;
 	return true;
 }
+function normalizeMatcher(m) {
+	if (m instanceof RegExp) return {
+		$regex: m.source,
+		flags: m.flags
+	};
+	if (isOneOfMatcher(m)) return { oneOf: [...m.oneOf] };
+	return m;
+}
+function normalizePredicate(p, where) {
+	const kind = typeof p?.kind === "string" ? p.kind.toUpperCase() : p?.kind;
+	const withKind = kind === void 0 ? p : {
+		...p,
+		kind
+	};
+	assertPredicate(withKind, where);
+	const out = {};
+	if (withKind.kind !== void 0) out.kind = withKind.kind;
+	if (withKind.name !== void 0) out.name = normalizeMatcher(withKind.name);
+	if (withKind.tool !== void 0) out.tool = normalizeMatcher(withKind.tool);
+	if (withKind.model !== void 0) out.model = normalizeMatcher(withKind.model);
+	if (withKind.attr !== void 0) out.attr = Object.fromEntries(Object.entries(withKind.attr).map(([k, v]) => [k, v instanceof RegExp ? normalizeMatcher(v) : v]));
+	if (withKind.not !== void 0) out.not = normalizePredicate(withKind.not, `${where} "not"`);
+	if (typeof withKind.custom === "function") {
+		out.custom = withKind.custom;
+		out.requiresCustom = true;
+	}
+	return out;
+}
+//#endregion
+//#region src/trace-contracts/types.ts
+const ORDER_MODES = [
+	"start-order",
+	"finish-before-start",
+	"all-occurrences"
+];
+const RUN_STATUSES = [
+	"running",
+	"completed",
+	"failed",
+	"aborted"
+];
+const ARGUMENT_OCCURRENCES = [
+	"first",
+	"last",
+	"any",
+	"all"
+];
+const ARGUMENT_TYPES = [
+	"string",
+	"number",
+	"boolean",
+	"object",
+	"array",
+	"null"
+];
+//#endregion
+//#region src/trace-contracts/validate.ts
+function assertOrder(order, where) {
+	if (order === void 0) return void 0;
+	if (!ORDER_MODES.includes(order)) throw new ValidationError(`${where}: order must be one of ${ORDER_MODES.join(", ")}`);
+	return order;
+}
+function assertCount(max, where) {
+	if (typeof max !== "number" || !Number.isInteger(max) || max < 0) throw new ValidationError(`${where}: max must be a non-negative integer`);
+}
+function assertJsonPointer(pointer, where) {
+	if (typeof pointer !== "string" || pointer !== "" && !pointer.startsWith("/")) throw new ValidationError(`${where}: pointer must be an RFC 6901 JSON Pointer ('' or '/a/b')`);
+	if (/~(?![01])/.test(pointer)) throw new ValidationError(`${where}: pointer has an invalid escape; use ~0 for ~ and ~1 for /`);
+}
+function assertArgumentCheck(check, where) {
+	const c = check;
+	if (c === null || typeof c !== "object") throw new ValidationError(`${where}: check must be an object`);
+	switch (c.op) {
+		case "exists": return;
+		case "equals":
+			if (!("value" in c)) throw new ValidationError(`${where}: equals needs a value`);
+			return;
+		case "oneOf":
+			if (!Array.isArray(c.values) || c.values.length === 0) throw new ValidationError(`${where}: oneOf needs a non-empty values array`);
+			return;
+		case "type":
+			if (!ARGUMENT_TYPES.includes(c.type)) throw new ValidationError(`${where}: type must be one of ${ARGUMENT_TYPES.join(", ")}`);
+			return;
+		default: throw new ValidationError(`${where}: check.op must be exists, equals, oneOf, or type`);
+	}
+}
+function assertRule(rule, where) {
+	switch (rule.kind) {
+		case "always":
+		case "never":
+		case "eventually":
+			assertPredicate(rule.p, `${where} (p)`);
+			return;
+		case "precedes":
+			assertPredicate(rule.a, `${where} (a)`);
+			assertPredicate(rule.b, `${where} (b)`);
+			assertOrder(rule.order, where);
+			return;
+		case "neverUnless":
+			assertPredicate(rule.p, `${where} (p)`);
+			assertPredicate(rule.prior, `${where} (prior)`);
+			assertOrder(rule.order, where);
+			return;
+		case "atMost":
+		case "tokensAtMost":
+			assertPredicate(rule.p, `${where} (p)`);
+			assertCount(rule.max, where);
+			return;
+		case "run":
+			if (rule.requireCompleted === void 0 && rule.allowedStatuses === void 0 && rule.maxDurationMs === void 0) throw new ValidationError(`${where}: run rule checks nothing`);
+			if (rule.requireCompleted !== void 0 && typeof rule.requireCompleted !== "boolean") throw new ValidationError(`${where}: requireCompleted must be a boolean`);
+			if (rule.allowedStatuses !== void 0) {
+				if (!Array.isArray(rule.allowedStatuses) || rule.allowedStatuses.length === 0) throw new ValidationError(`${where}: allowedStatuses must be a non-empty array`);
+				for (const status of rule.allowedStatuses) if (!RUN_STATUSES.includes(status)) throw new ValidationError(`${where}: unknown run status "${String(status)}" — expected one of ${RUN_STATUSES.join(", ")}`);
+			}
+			if (rule.maxDurationMs !== void 0 && (typeof rule.maxDurationMs !== "number" || !Number.isFinite(rule.maxDurationMs) || rule.maxDurationMs <= 0)) throw new ValidationError(`${where}: maxDurationMs must be a positive number`);
+			return;
+		case "argument":
+			assertPredicate(rule.p, `${where} (p)`);
+			assertJsonPointer(rule.pointer, where);
+			assertArgumentCheck(rule.check, where);
+			if (rule.occurrence !== void 0 && !ARGUMENT_OCCURRENCES.includes(rule.occurrence)) throw new ValidationError(`${where}: occurrence must be one of ${ARGUMENT_OCCURRENCES.join(", ")}`);
+			return;
+		default: throw new ValidationError(`${where}: unknown rule kind "${String(rule.kind)}"`);
+	}
+}
+function assertRules(rules, where, allowEmpty = false) {
+	if (!Array.isArray(rules) || rules.length === 0 && !allowEmpty) throw new ValidationError(`${where}: no rules — an empty contract would vacuously pass`);
+	const seen = /* @__PURE__ */ new Set();
+	for (const rule of rules) {
+		const ruleWhere = `${where} rule "${rule?.label ?? "<unlabeled>"}"`;
+		if (typeof rule?.label !== "string" || rule.label.length === 0) throw new ValidationError(`${ruleWhere}: label must be a non-empty string`);
+		if (seen.has(rule.label)) throw new ValidationError(`${ruleWhere}: duplicate label would collapse per-rule scores`);
+		seen.add(rule.label);
+		assertRule(rule, ruleWhere);
+	}
+}
+function assertContract(contract, where) {
+	if (typeof contract?.name !== "string" || contract.name.length === 0) throw new ValidationError(`${where}: contract.name must be a non-empty string`);
+	const at = `${where} "${contract.name}"`;
+	assertRules(contract.rules, at, Array.isArray(contract.alternatives) && contract.alternatives.length > 0);
+	if (contract.scope !== void 0) assertPredicate(contract.scope?.root, `${at} scope.root`);
+	if (contract.alternatives !== void 0) {
+		if (!Array.isArray(contract.alternatives) || contract.alternatives.length === 0) throw new ValidationError(`${at}: alternatives must be a non-empty array`);
+		const ids = /* @__PURE__ */ new Set();
+		for (const alternative of contract.alternatives) {
+			if (typeof alternative?.id !== "string" || alternative.id.length === 0) throw new ValidationError(`${at}: every alternative needs a non-empty id`);
+			if (ids.has(alternative.id)) throw new ValidationError(`${at}: duplicate alternative id "${alternative.id}"`);
+			ids.add(alternative.id);
+			assertRules(alternative.rules, `${at} alternative "${alternative.id}"`);
+		}
+	}
+}
+//#endregion
+//#region src/trace-contracts/explain.ts
 function describeMatcher(m) {
 	if (typeof m === "string") return m;
 	if (m instanceof RegExp) return `/${m.source}/${m.flags}`;
+	if (isOneOfMatcher(m)) return `oneOf(${m.oneOf.join("|")})`;
 	return `/${m.$regex}/${m.flags}`;
 }
 function describePredicate(p) {
 	const parts = [];
+	if (p.kind !== void 0) parts.push(`kind=${p.kind}`);
 	if (p.name !== void 0) parts.push(`name=${describeMatcher(p.name)}`);
 	if (p.tool !== void 0) parts.push(`tool=${describeMatcher(p.tool)}`);
-	if (p.attr !== void 0) for (const [k, v] of Object.entries(p.attr)) parts.push(`attr.${k}=${v instanceof RegExp || isSerializedRegex(v) ? describeMatcher(v) : JSON.stringify(v)}`);
+	if (p.model !== void 0) parts.push(`model=${describeMatcher(p.model)}`);
+	if (p.attr !== void 0) for (const [k, v] of Object.entries(p.attr)) parts.push(`attr.${k}=${isRegexValue(v) ? describeMatcher(v) : JSON.stringify(v)}`);
+	if (p.not !== void 0) parts.push(`not(${describePredicate(p.not)})`);
 	if (typeof p.custom === "function") parts.push(`custom=${p.custom.name || "fn"}`);
 	return parts.join(",");
 }
-function normalizeMatcher(m) {
-	return m instanceof RegExp ? {
-		$regex: m.source,
-		flags: m.flags
-	} : m;
+function describeCheck(check) {
+	switch (check.op) {
+		case "exists": return "exists";
+		case "equals": return `equals ${JSON.stringify(check.value)}`;
+		case "oneOf": return `oneOf ${JSON.stringify(check.values)}`;
+		case "type": return `type ${check.type}`;
+	}
 }
-function normalizePredicate(p, where) {
-	assertPredicate(p, where);
-	const out = {};
-	if (p.name !== void 0) out.name = normalizeMatcher(p.name);
-	if (p.tool !== void 0) out.tool = normalizeMatcher(p.tool);
-	if (p.attr !== void 0) out.attr = Object.fromEntries(Object.entries(p.attr).map(([k, v]) => [k, v instanceof RegExp ? normalizeMatcher(v) : v]));
-	if (typeof p.custom === "function") {
-		out.custom = p.custom;
-		out.requiresCustom = true;
+/** One line per rule, stating what it requires. */
+function describeRule(rule) {
+	switch (rule.kind) {
+		case "always": return `every span matches ${describePredicate(rule.p)}`;
+		case "never": return `no span matches ${describePredicate(rule.p)}`;
+		case "eventually": return `some span matches ${describePredicate(rule.p)}`;
+		case "precedes": return `${describePredicate(rule.a)} and ${describePredicate(rule.b)} both occur, and the first comes before the second (${rule.order ?? "start-order"})`;
+		case "neverUnless": return `every ${describePredicate(rule.p)} has an earlier ${describePredicate(rule.prior)} (${rule.order ?? "start-order"})`;
+		case "atMost": return `at most ${rule.max} span(s) match ${describePredicate(rule.p)}`;
+		case "tokensAtMost": return `spans matching ${describePredicate(rule.p)} use at most ${rule.max} tokens in total`;
+		case "run": {
+			const parts = [];
+			if (rule.requireCompleted) parts.push("the run reached a terminal status");
+			if (rule.allowedStatuses) parts.push(`its status is one of ${rule.allowedStatuses.join(", ")}`);
+			if (rule.maxDurationMs !== void 0) parts.push(`it took at most ${rule.maxDurationMs} ms`);
+			return parts.join("; ");
+		}
+		case "argument": return `${rule.occurrence ?? "all"} call(s) matching ${describePredicate(rule.p)} have argument ${rule.pointer || "(whole value)"} that ${describeCheck(rule.check)}`;
+	}
+}
+/** Plain-language statement of everything a contract checks, one rule per line. */
+function explainTraceContract(contract) {
+	assertContract(contract, "explainTraceContract");
+	const lines = [`Contract "${contract.name}"${contract.description ? ` — ${contract.description}` : ""}`];
+	if (contract.scope) lines.push(`Scope: only the span matching ${describePredicate(contract.scope.root)} and its descendants; exactly one span must match.`);
+	lines.push("Every rule must pass:");
+	for (const rule of contract.rules) lines.push(`  - ${rule.label}: ${describeRule(rule)}`);
+	if (contract.alternatives) {
+		lines.push("And at least one alternative must pass completely:");
+		for (const alternative of contract.alternatives) {
+			lines.push(`  ${alternative.id}:`);
+			for (const rule of alternative.rules) lines.push(`    - ${rule.label}: ${describeRule(rule)}`);
+		}
 	}
-	return out;
+	return lines.join("\n");
 }
-var TraceContractBuilder = class {
+//#endregion
+//#region src/trace-contracts/builder.ts
+var TraceContractBuilder = class TraceContractBuilder {
 	name;
 	rules = [];
+	alternativeList = [];
+	scopeRoot;
 	constructor(name) {
 		this.name = name;
 	}
 	/** Every span in the trace must satisfy `p`. */
 	always(p, label) {
-		const np = normalizePredicate(p, `traceContract("${this.name}").always`);
+		const np = normalizePredicate(p, this.where("always"));
 		return this.add({
 			kind: "always",
 			label: label ?? `always(${describePredicate(np)})`,
@@ -1274,7 +1570,7 @@ var TraceContractBuilder = class {
 	}
 	/** No span in the trace may satisfy `p`. */
 	never(p, label) {
-		const np = normalizePredicate(p, `traceContract("${this.name}").never`);
+		const np = normalizePredicate(p, this.where("never"));
 		return this.add({
 			kind: "never",
 			label: label ?? `never(${describePredicate(np)})`,
@@ -1283,41 +1579,114 @@ var TraceContractBuilder = class {
 	}
 	/** At least one span in the trace must satisfy `p`. */
 	eventually(p, label) {
-		const np = normalizePredicate(p, `traceContract("${this.name}").eventually`);
+		const np = normalizePredicate(p, this.where("eventually"));
 		return this.add({
 			kind: "eventually",
 			label: label ?? `eventually(${describePredicate(np)})`,
 			p: np
 		});
 	}
-	/** Every `b`-match must have a strictly earlier `a`-match. */
-	precedes(a, b, label) {
-		const na = normalizePredicate(a, `traceContract("${this.name}").precedes (a)`);
-		const nb = normalizePredicate(b, `traceContract("${this.name}").precedes (b)`);
+	/** Both `a` and `b` must occur, with `a` first under `options.order`
+	*  (default `start-order`). For "every `b` needs an earlier `a`, and a run
+	*  without `b` passes", use {@link neverUnless}. */
+	precedes(a, b, label, options = {}) {
+		const na = normalizePredicate(a, this.where("precedes (a)"));
+		const nb = normalizePredicate(b, this.where("precedes (b)"));
+		const order = assertOrder(options.order, this.where("precedes"));
 		return this.add({
 			kind: "precedes",
 			label: label ?? `precedes(${describePredicate(na)} -> ${describePredicate(nb)})`,
 			a: na,
-			b: nb
+			b: nb,
+			...order === void 0 ? {} : { order }
 		});
 	}
-	/** Every `p`-match is a violation unless a strictly earlier `prior`-match exists. */
-	neverUnless(p, prior, label) {
-		const np = normalizePredicate(p, `traceContract("${this.name}").neverUnless (p)`);
-		const nprior = normalizePredicate(prior, `traceContract("${this.name}").neverUnless (prior)`);
+	/** Every `p`-match needs an earlier `prior`-match; a run without `p` passes. */
+	neverUnless(p, prior, label, options = {}) {
+		const np = normalizePredicate(p, this.where("neverUnless (p)"));
+		const nprior = normalizePredicate(prior, this.where("neverUnless (prior)"));
+		const order = assertOrder(options.order, this.where("neverUnless"));
 		return this.add({
 			kind: "neverUnless",
 			label: label ?? `neverUnless(${describePredicate(np)} unless ${describePredicate(nprior)})`,
 			p: np,
-			prior: nprior
+			prior: nprior,
+			...order === void 0 ? {} : { order }
 		});
 	}
+	/** At most `max` spans may satisfy `p`. */
+	atMost(p, max, label) {
+		const np = normalizePredicate(p, this.where("atMost"));
+		assertCount(max, this.where("atMost"));
+		return this.add({
+			kind: "atMost",
+			label: label ?? `atMost(${describePredicate(np)}, ${max})`,
+			p: np,
+			max
+		});
+	}
+	/** Spans satisfying `p` may use at most `max` input+output tokens in total. */
+	tokensAtMost(p, max, label) {
+		const np = normalizePredicate(p, this.where("tokensAtMost"));
+		assertCount(max, this.where("tokensAtMost"));
+		return this.add({
+			kind: "tokensAtMost",
+			label: label ?? `tokensAtMost(${describePredicate(np)}, ${max})`,
+			p: np,
+			max
+		});
+	}
+	/** Terminal status and duration of the run. */
+	run(checks, label = "run") {
+		const rule = {
+			kind: "run",
+			label,
+			...checks
+		};
+		assertRule(rule, this.where("run"));
+		return this.add(rule);
+	}
+	/** A JSON Pointer check on the arguments of calls matching `p`. */
+	argument(p, options, label) {
+		const np = normalizePredicate(p, this.where("argument"));
+		const rule = {
+			kind: "argument",
+			label: label ?? `argument(${describePredicate(np)}, ${options.pointer || "(whole value)"} ${describeCheck(options.check)})`,
+			p: np,
+			pointer: options.pointer,
+			check: options.check,
+			...options.occurrence === void 0 ? {} : { occurrence: options.occurrence }
+		};
+		assertRule(rule, this.where("argument"));
+		return this.add(rule);
+	}
+	/** Evaluate only the subtree rooted at the one span matching `root`. */
+	scope(root) {
+		this.scopeRoot = normalizePredicate(root, this.where("scope"));
+		return this;
+	}
+	/** A named alternate path; at least one alternative must pass completely. */
+	alternative(id, define) {
+		const branch = define(new TraceContractBuilder(`${this.name}/${id}`));
+		if (branch.scopeRoot !== void 0 || branch.alternativeList.length > 0) throw new ValidationError(`${this.where("alternative")}: alternatives cannot nest scope or alternatives`);
+		this.alternativeList.push({
+			id,
+			rules: [...branch.rules]
+		});
+		return this;
+	}
 	build() {
-		if (this.rules.length === 0) throw new ValidationError(`traceContract("${this.name}").build(): no rules — an empty contract would vacuously pass`);
-		return {
+		const contract = {
 			name: this.name,
-			rules: [...this.rules]
+			...this.scopeRoot === void 0 ? {} : { scope: { root: this.scopeRoot } },
+			rules: [...this.rules],
+			...this.alternativeList.length === 0 ? {} : { alternatives: [...this.alternativeList] }
 		};
+		assertContract(contract, `traceContract("${this.name}").build()`);
+		return contract;
+	}
+	where(op) {
+		return `traceContract("${this.name}").${op}`;
 	}
 	add(rule) {
 		let label = rule.label;
@@ -1337,144 +1706,378 @@ function traceContract(name) {
 	if (typeof name !== "string" || name.length === 0) throw new ValidationError("traceContract: name must be a non-empty string");
 	return new TraceContractBuilder(name);
 }
-function assertContract(contract) {
-	if (typeof contract?.name !== "string" || contract.name.length === 0) throw new ValidationError("evaluateTraceContract: contract.name must be a non-empty string");
-	if (!Array.isArray(contract.rules) || contract.rules.length === 0) throw new ValidationError(`evaluateTraceContract: contract "${contract.name}" has no rules — an empty contract would vacuously pass`);
-	const seen = /* @__PURE__ */ new Set();
-	for (const rule of contract.rules) {
-		const where = `contract "${contract.name}" rule "${rule?.label ?? "<unlabeled>"}"`;
-		if (typeof rule?.label !== "string" || rule.label.length === 0) throw new ValidationError(`${where}: label must be a non-empty string`);
-		if (seen.has(rule.label)) throw new ValidationError(`${where}: duplicate label would collapse per-rule scores`);
-		seen.add(rule.label);
-		switch (rule.kind) {
-			case "always":
-			case "never":
-			case "eventually":
-				assertPredicate(rule.p, `${where} (p)`);
-				break;
-			case "precedes":
-				assertPredicate(rule.a, `${where} (a)`);
-				assertPredicate(rule.b, `${where} (b)`);
-				break;
-			case "neverUnless":
-				assertPredicate(rule.p, `${where} (p)`);
-				assertPredicate(rule.prior, `${where} (prior)`);
-				break;
-			default: throw new ValidationError(`${where}: unknown rule kind "${String(rule.kind)}"`);
-		}
-	}
+//#endregion
+//#region src/trace-contracts/rules.ts
+function spanRef(span, index) {
+	return span.spanId ?? `#${index}`;
+}
+function indexed(spans, p) {
+	const out = [];
+	spans.forEach((span, i) => {
+		if (predicateMatches(span, p)) out.push({
+			span,
+			ref: spanRef(span, i)
+		});
+	});
+	return out;
 }
 /**
-* Order spans for temporal evaluation: by `startedAt` when EVERY span carries
-* one (stable — ties keep array order), by array order when NONE does. Mixed
-* timestamps throw: neither time order nor array order is a trustworthy total
-* order over a partially-stamped sequence, and guessing would corrupt
-* `precedes` / `neverUnless` verdicts.
+* Is guarded span `b` preceded by the guard spans under `order`? A span never
+* witnesses itself. Missing timestamps fail: the checker cannot prove an
+* order it cannot see.
 */
-function orderSpans(spans) {
-	const timed = spans.filter((s) => typeof s.startedAt === "number" && Number.isFinite(s.startedAt)).length;
-	if (timed === spans.length) return spans.map((span, i) => ({
-		span,
-		i
-	})).sort((x, y) => x.span.startedAt - y.span.startedAt || x.i - y.i).map((x) => x.span);
-	if (timed === 0) return [...spans];
-	throw new ValidationError(`evaluateTraceContract: ${timed}/${spans.length} spans carry a finite startedAt — mixed timestamps make ordering ambiguous; stamp every span or none`);
+function witnessed(b, guards, order) {
+	const bStart = finite(b.span.startedAt);
+	if (bStart === void 0) return {
+		ok: false,
+		detail: `span ${b.ref} has no startedAt, so its order cannot be proven`
+	};
+	const candidates = guards.filter((a) => a.span !== b.span);
+	if (candidates.length === 0) return {
+		ok: false,
+		detail: `span ${b.ref} has no earlier match`
+	};
+	const boundary = order === "start-order" ? "startedAt" : "endedAt";
+	const untimed = candidates.find((a) => finite(a.span[boundary]) === void 0);
+	if (order === "all-occurrences") {
+		if (untimed) return {
+			ok: false,
+			detail: `span ${untimed.ref} has no endedAt, so its order cannot be proven`
+		};
+		const late = candidates.find((a) => a.span.endedAt > bStart);
+		return late ? {
+			ok: false,
+			detail: `span ${late.ref} ends after span ${b.ref} starts`
+		} : { ok: true };
+	}
+	if (candidates.some((a) => {
+		const t = finite(a.span[boundary]);
+		return t !== void 0 && (order === "start-order" ? t < bStart : t <= bStart);
+	})) return { ok: true };
+	if (untimed) return {
+		ok: false,
+		detail: `span ${untimed.ref} has no ${boundary}, so its order cannot be proven`
+	};
+	return {
+		ok: false,
+		detail: order === "start-order" ? `span ${b.ref} has no match that started before it` : `span ${b.ref} has no match that finished before it started`
+	};
 }
-function spanRef(span, index) {
-	return span.spanId ?? `#${index}`;
+function orderViolations(label, guards, guarded, order, describe) {
+	const out = [];
+	for (const b of guarded) {
+		const w = witnessed(b, guards, order);
+		if (!w.ok) out.push({
+			rule: label,
+			spanId: b.span.spanId,
+			detail: `${describe}: ${w.detail}`
+		});
+	}
+	return out;
+}
+/** RFC 6901 resolution. `found: false` when any reference token is absent. */
+function resolveJsonPointer(value, pointer) {
+	if (pointer === "") return {
+		found: true,
+		value
+	};
+	let current = value;
+	for (const raw of pointer.slice(1).split("/")) {
+		const token = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+		if (Array.isArray(current)) {
+			if (!/^(?:0|[1-9]\d*)$/.test(token) || Number(token) >= current.length) return { found: false };
+			current = current[Number(token)];
+		} else if (current !== null && typeof current === "object" && Object.hasOwn(current, token)) current = current[token];
+		else return { found: false };
+	}
+	return {
+		found: true,
+		value: current
+	};
 }
-function checkGuarded(args) {
+function jsonType(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	const t = typeof value;
+	return t === "string" || t === "number" || t === "boolean" || t === "object" ? t : "undefined";
+}
+function jsonEqual(a, b) {
+	if (a === b) return true;
+	const ta = jsonType(a);
+	if (ta !== jsonType(b)) return false;
+	if (ta === "array") {
+		const x = a;
+		const y = b;
+		return x.length === y.length && x.every((v, i) => jsonEqual(v, y[i]));
+	}
+	if (ta === "object") {
+		const x = a;
+		const y = b;
+		const keys = Object.keys(x);
+		return keys.length === Object.keys(y).length && keys.every((k) => Object.hasOwn(y, k) && jsonEqual(x[k], y[k]));
+	}
+	return false;
+}
+/** Why `value` fails `check`, or `undefined` when it passes. Never echoes the
+*  actual argument value: arguments can carry customer data. */
+function argumentFailure(evidence, pointer, check) {
+	if (!evidence.known) return evidence.reason;
+	const resolved = resolveJsonPointer(evidence.value, pointer);
+	if (!resolved.found) return `argument ${pointer || "(whole value)"} is absent`;
+	switch (check.op) {
+		case "exists": return;
+		case "equals": return jsonEqual(resolved.value, check.value) ? void 0 : `argument ${pointer || "(whole value)"} (a ${jsonType(resolved.value)}) does not equal the expected value`;
+		case "oneOf": return check.values.some((v) => jsonEqual(resolved.value, v)) ? void 0 : `argument ${pointer || "(whole value)"} (a ${jsonType(resolved.value)}) is not one of the expected values`;
+		case "type": return jsonType(resolved.value) === check.type ? void 0 : `argument ${pointer || "(whole value)"} is a ${jsonType(resolved.value)}, not a ${check.type}`;
+	}
+}
+function checkArgument(rule, spans) {
+	const matches = indexed(spans, rule.p);
+	if (matches.length === 0) return [{
+		rule: rule.label,
+		detail: `no span matches ${describePredicate(rule.p)}, so there is no argument evidence to check`
+	}];
+	const occurrence = rule.occurrence ?? "all";
+	let selected = matches;
+	if ((occurrence === "first" || occurrence === "last") && matches.length > 1) {
+		const untimed = matches.find((m) => finite(m.span.startedAt) === void 0);
+		if (untimed) return [{
+			rule: rule.label,
+			spanId: untimed.span.spanId,
+			detail: `span ${untimed.ref} has no startedAt, so the ${occurrence} call cannot be chosen`
+		}];
+		const sorted = [...matches].sort((x, y) => x.span.startedAt - y.span.startedAt);
+		selected = [occurrence === "first" ? sorted[0] : sorted[sorted.length - 1]];
+	}
+	const failures = selected.map((m) => ({
+		m,
+		why: argumentFailure(spanArguments(m.span), rule.pointer, rule.check)
+	}));
+	const failed = failures.filter((f) => f.why !== void 0);
+	if (occurrence === "any" ? failed.length < failures.length : failed.length === 0) return [];
+	return failed.map((f) => ({
+		rule: rule.label,
+		spanId: f.m.span.spanId,
+		detail: `span ${f.m.ref}: ${f.why}`
+	}));
+}
+function checkRun(rule, context) {
+	if ("unknown" in context) return [{
+		rule: rule.label,
+		detail: `run record unavailable: ${context.unknown}`
+	}];
+	const run = context.run;
 	const out = [];
-	let guardSeen = false;
-	for (let i = 0; i < args.ordered.length; i++) {
-		const span = args.ordered[i];
-		if (!guardSeen && matchSpan(span, args.guarded)) out.push({
-			rule: args.label,
-			spanId: span.spanId,
-			detail: args.detail(spanRef(span, i))
+	if (rule.requireCompleted && (run.status === void 0 || run.status === "running" || finite(run.endedAt) === void 0)) out.push({
+		rule: rule.label,
+		detail: `run did not reach a terminal status (status ${run.status ?? "unknown"})`
+	});
+	if (rule.allowedStatuses && !rule.allowedStatuses.includes(run.status ?? "")) out.push({
+		rule: rule.label,
+		detail: `run status ${run.status ?? "unknown"} is not one of ${rule.allowedStatuses.join(", ")}`
+	});
+	if (rule.maxDurationMs !== void 0) {
+		const start = finite(run.startedAt);
+		const end = finite(run.endedAt);
+		if (start === void 0 || end === void 0) out.push({
+			rule: rule.label,
+			detail: "run duration is unknown: start or end time is missing"
+		});
+		else if (end - start > rule.maxDurationMs) out.push({
+			rule: rule.label,
+			detail: `run took ${end - start} ms, over ${rule.maxDurationMs} ms`
 		});
-		if (matchSpan(span, args.guard)) guardSeen = true;
 	}
 	return out;
 }
-function checkRule(rule, ordered) {
+function checkRule(rule, ctx) {
+	const { spans } = ctx;
 	switch (rule.kind) {
-		case "always": {
+		case "always": return spans.flatMap((span, i) => predicateMatches(span, rule.p) ? [] : [{
+			rule: rule.label,
+			spanId: span.spanId,
+			detail: `span ${spanRef(span, i)} ("${span.name ?? ""}") fails always(${describePredicate(rule.p)})`
+		}]);
+		case "never": return indexed(spans, rule.p).map(({ span, ref }) => ({
+			rule: rule.label,
+			spanId: span.spanId,
+			detail: `span ${ref} ("${span.name ?? ""}") matches never(${describePredicate(rule.p)})`
+		}));
+		case "eventually": return spans.some((span) => predicateMatches(span, rule.p)) ? [] : [{
+			rule: rule.label,
+			detail: `no span matches eventually(${describePredicate(rule.p)}) over ${spans.length} span(s)`
+		}];
+		case "precedes": {
+			const as = indexed(spans, rule.a);
+			const bs = indexed(spans, rule.b);
 			const out = [];
-			for (let i = 0; i < ordered.length; i++) {
-				const span = ordered[i];
-				if (!matchSpan(span, rule.p)) out.push({
-					rule: rule.label,
-					spanId: span.spanId,
-					detail: `span ${spanRef(span, i)} ("${span.name ?? ""}") fails always(${describePredicate(rule.p)})`
-				});
-			}
-			return out;
+			if (as.length === 0) out.push({
+				rule: rule.label,
+				detail: `required predecessor ${describePredicate(rule.a)} never occurred`
+			});
+			if (bs.length === 0) out.push({
+				rule: rule.label,
+				detail: `required successor ${describePredicate(rule.b)} never occurred`
+			});
+			if (out.length > 0) return out;
+			return orderViolations(rule.label, as, bs, rule.order ?? "start-order", `${describePredicate(rule.b)} is not preceded by ${describePredicate(rule.a)}`);
 		}
-		case "never": {
-			const out = [];
-			for (let i = 0; i < ordered.length; i++) {
-				const span = ordered[i];
-				if (matchSpan(span, rule.p)) out.push({
-					rule: rule.label,
-					spanId: span.spanId,
-					detail: `span ${spanRef(span, i)} ("${span.name ?? ""}") matches never(${describePredicate(rule.p)})`
-				});
-			}
-			return out;
+		case "neverUnless": return orderViolations(rule.label, indexed(spans, rule.prior), indexed(spans, rule.p), rule.order ?? "start-order", `${describePredicate(rule.p)} without an earlier ${describePredicate(rule.prior)}`);
+		case "atMost": {
+			const matches = indexed(spans, rule.p);
+			return matches.length <= rule.max ? [] : [{
+				rule: rule.label,
+				spanId: matches[rule.max]?.span.spanId,
+				detail: `${matches.length} span(s) match ${describePredicate(rule.p)}, over the limit of ${rule.max}`
+			}];
 		}
-		case "eventually": return ordered.some((span) => matchSpan(span, rule.p)) ? [] : [{
-			rule: rule.label,
-			detail: `no span matches eventually(${describePredicate(rule.p)}) over ${ordered.length} span(s)`
-		}];
-		case "precedes": return checkGuarded({
-			label: rule.label,
-			ordered,
-			guard: rule.a,
-			guarded: rule.b,
-			detail: (ref) => `span ${ref} matches ${describePredicate(rule.b)} with no earlier ${describePredicate(rule.a)} match`
-		});
-		case "neverUnless": return checkGuarded({
-			label: rule.label,
-			ordered,
-			guard: rule.prior,
-			guarded: rule.p,
-			detail: (ref) => `span ${ref} matches ${describePredicate(rule.p)} with no earlier ${describePredicate(rule.prior)} match`
-		});
+		case "tokensAtMost": {
+			const matches = indexed(spans, rule.p);
+			const unknown = matches.find((m) => spanTotalTokens(m.span) === void 0);
+			if (unknown) return [{
+				rule: rule.label,
+				spanId: unknown.span.spanId,
+				detail: `span ${unknown.ref} has no recorded input and output token counts, so the total is unknown`
+			}];
+			const total = matches.reduce((sum, m) => sum + spanTotalTokens(m.span), 0);
+			return total <= rule.max ? [] : [{
+				rule: rule.label,
+				detail: `${total} tokens across ${matches.length} span(s) matching ${describePredicate(rule.p)}, over the limit of ${rule.max}`
+			}];
+		}
+		case "run": return checkRun(rule, ctx.run);
+		case "argument": return checkArgument(rule, spans);
+	}
+}
+function executeRule(rule, ctx) {
+	try {
+		const violations = checkRule(rule, ctx);
+		return {
+			status: violations.length === 0 ? "pass" : "fail",
+			violations
+		};
+	} catch (error) {
+		return {
+			status: "error",
+			violations: [],
+			error: error instanceof Error ? error.message : String(error)
+		};
 	}
 }
+//#endregion
+//#region src/trace-contracts/evaluate.ts
 /**
-* Evaluate one contract over a span sequence. Pure and synchronous — works
-* on `Span[]` from a TraceStore, `ExportableSpan[]` from the otel-bridge
-* flattening, or any array satisfying `ContractSpan`.
+* A run derived from one span: the `run.status` attribute a run-anchor span
+* carries (store-to-otlp writes it), else failed on an error status, else
+* completed once the span ended.
 */
-function evaluateTraceContract(contract, spans) {
-	assertContract(contract);
-	const ordered = orderSpans(spans);
-	const scores = {};
-	const violations = [];
-	for (const rule of contract.rules) {
-		const ruleViolations = checkRule(rule, ordered);
-		scores[rule.label] = ruleViolations.length === 0 ? 1 : 0;
-		violations.push(...ruleViolations);
+function runOfSpan(span) {
+	const declared = span.attributes?.["run.status"];
+	return {
+		status: typeof declared === "string" && RUN_STATUSES.includes(declared) ? declared : isSpanError(span) ? "failed" : finite(span.endedAt) !== void 0 ? "completed" : "running",
+		...finite(span.startedAt) === void 0 ? {} : { startedAt: span.startedAt },
+		...finite(span.endedAt) === void 0 ? {} : { endedAt: span.endedAt }
+	};
+}
+function rootsOf(spans) {
+	const ids = new Set(spans.map((s) => s.spanId).filter((id) => typeof id === "string"));
+	return spans.filter((s) => !s.parentSpanId || !ids.has(s.parentSpanId));
+}
+function subtree(spans, root) {
+	if (typeof root.spanId !== "string") return [root];
+	const children = /* @__PURE__ */ new Map();
+	for (const span of spans) if (typeof span.parentSpanId === "string") {
+		const list = children.get(span.parentSpanId) ?? [];
+		list.push(span);
+		children.set(span.parentSpanId, list);
+	}
+	const members = /* @__PURE__ */ new Set([root]);
+	const queue = [root];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		for (const child of typeof current.spanId === "string" && children.get(current.spanId) || []) if (!members.has(child)) {
+			members.add(child);
+			queue.push(child);
+		}
+	}
+	return spans.filter((s) => members.has(s));
+}
+function statusOf(outcomes) {
+	if (outcomes.some((o) => o.status === "error")) return "error";
+	return outcomes.every((o) => o.status === "pass") ? "pass" : "fail";
+}
+/**
+* Evaluate one contract over a span sequence. Pure and synchronous — works on
+* `Span[]` from a TraceStore, `ExportableSpan[]` from the otel-bridge
+* flattening, or any array satisfying `ContractSpan`. Throws
+* `ValidationError` for a malformed contract; a rule that cannot be evaluated
+* is reported as `error` in the verdict instead.
+*/
+function evaluateTraceContract(contract, spans, options = {}) {
+	assertContract(contract, "evaluateTraceContract");
+	if (!Array.isArray(spans)) throw new ValidationError(`evaluateTraceContract: spans must be an array, got ${typeof spans}`);
+	let subject = spans;
+	let run;
+	let scopeError;
+	if (contract.scope) {
+		const roots = spans.filter((s) => predicateMatches(s, contract.scope.root));
+		if (roots.length === 1) {
+			subject = subtree(spans, roots[0]);
+			run = { run: runOfSpan(roots[0]) };
+		} else {
+			scopeError = `scope root ${describePredicate(contract.scope.root)} matched ${roots.length} spans; exactly one is required`;
+			run = { unknown: scopeError };
+		}
+	} else if (options.run) run = { run: options.run };
+	else {
+		const roots = rootsOf(spans);
+		run = roots.length === 1 ? { run: runOfSpan(roots[0]) } : { unknown: `the trace has ${roots.length} root spans and no run record was passed` };
 	}
-	const ruleCount = contract.rules.length;
+	const ctx = {
+		spans: subject,
+		run
+	};
+	const execute = (rule) => scopeError === void 0 ? executeRule(rule, ctx) : {
+		status: "error",
+		violations: [],
+		error: scopeError
+	};
+	const base = contract.rules.map(execute);
+	const branches = (contract.alternatives ?? []).map((alternative) => ({
+		alternative,
+		outcomes: alternative.rules.map(execute)
+	}));
+	const passedBranch = branches.find((b) => statusOf(b.outcomes) === "pass");
+	const baseStatus = statusOf(base);
+	let status = baseStatus;
+	if (baseStatus === "pass" && branches.length > 0 && !passedBranch) status = branches.some((b) => statusOf(b.outcomes) === "error") ? "error" : "fail";
+	const ruleExecutions = [...contract.rules.map((rule, i) => execution(rule.label, void 0, base[i])), ...branches.flatMap((b) => b.alternative.rules.map((rule, i) => execution(rule.label, b.alternative.id, b.outcomes[i])))];
+	const violations = base.flatMap((o) => o.violations);
+	if (branches.length > 0 && !passedBranch) for (const b of branches) for (const o of b.outcomes) violations.push(...o.violations.map((v) => ({
+		...v,
+		rule: `${b.alternative.id}/${v.rule}`
+	})));
+	const errors = ruleExecutions.filter((e) => e.status === "error").map((e) => `${e.alternative ? `${e.alternative}/` : ""}${e.rule}: ${e.error}`);
+	const scores = {};
+	contract.rules.forEach((rule, i) => {
+		const s = base[i].status;
+		if (s !== "error") scores[rule.label] = s === "pass" ? 1 : 0;
+	});
+	if (branches.length > 0 && (passedBranch || status !== "error")) scores.anyOf = passedBranch ? 1 : 0;
+	const total = contract.rules.length + (branches.length > 0 ? 1 : 0);
 	const passCount = Object.values(scores).filter((s) => s === 1).length;
 	const assumptions = [];
-	if (spans.length > 0 && ordered.every((s) => typeof s.startedAt !== "number")) assumptions.push("spans ordered by array position — no startedAt timestamps to order by");
-	for (const rule of contract.rules) if ([
-		rule.p,
-		rule.a,
-		rule.b,
-		rule.prior
-	].some((p) => p !== void 0 && typeof p.custom === "function")) assumptions.push(`rule '${rule.label}' rests on a custom predicate function`);
+	for (const rule of [...contract.rules, ...branches.flatMap((b) => b.alternative.rules)]) if (rulePredicates(rule).some(usesCustom)) assumptions.push(`rule '${rule.label}' rests on a custom predicate function`);
 	return {
 		contract: contract.name,
-		valid: passCount === ruleCount,
-		score: passCount / ruleCount,
+		status,
+		valid: status === "pass",
+		score: passCount / total,
 		scores,
 		violations,
-		notes: `${passCount}/${ruleCount} rules passed`,
+		ruleExecutions,
+		errors,
+		notes: `${passCount}/${total} rules passed` + (errors.length > 0 ? `; ${errors.length} could not be evaluated` : ""),
 		certification: {
 			strategy: "invariant",
 			checker: {
@@ -1484,25 +2087,573 @@ function evaluateTraceContract(contract, spans) {
 			assumptions,
 			evidenceDigest: certificationEvidenceDigest({
 				contract: contract.name,
+				status,
 				scores,
-				violations
+				violations,
+				ruleExecutions
 			})
 		}
 	};
 }
+function execution(rule, alternative, outcome) {
+	return {
+		rule,
+		...alternative === void 0 ? {} : { alternative },
+		status: outcome.status,
+		violations: outcome.violations.length,
+		...outcome.error === void 0 ? {} : { error: outcome.error }
+	};
+}
+function rulePredicates(rule) {
+	switch (rule.kind) {
+		case "precedes": return [rule.a, rule.b];
+		case "neverUnless": return [rule.p, rule.prior];
+		case "run": return [];
+		default: return [rule.p];
+	}
+}
+function usesCustom(p) {
+	return typeof p.custom === "function" || p.not !== void 0 && usesCustom(p.not);
+}
 /**
 * Evaluate many contracts over one span sequence. Throws on an empty
 * contract list — `allValid: true` over zero contracts is a silent pass.
 */
-function checkTraceContracts(spans, contracts) {
+function checkTraceContracts(spans, contracts, options = {}) {
 	if (contracts.length === 0) throw new ValidationError("checkTraceContracts: empty contract list would vacuously pass — supply at least one contract");
-	const verdicts = contracts.map((c) => evaluateTraceContract(c, spans));
+	const verdicts = contracts.map((c) => evaluateTraceContract(c, spans, options));
+	const status = verdicts.some((v) => v.status === "error") ? "error" : verdicts.every((v) => v.status === "pass") ? "pass" : "fail";
 	return {
 		verdicts,
-		allValid: verdicts.every((v) => v.valid)
+		status,
+		allValid: status === "pass"
 	};
 }
 //#endregion
+//#region src/trace-contracts/spec.ts
+/**
+* The declarative contract form: a JSON document that names tools, model
+* calls, and run limits, compiled onto the temporal operators.
+*
+* ```json
+* {
+*   "name": "refund-agent",
+*   "run": { "requireCompleted": true, "maxDurationMs": 120000 },
+*   "tools": {
+*     "required": ["lookup_order", "issue_refund"],
+*     "forbidden": ["delete_account"],
+*     "allowed": ["lookup_order", "issue_refund", "send_email"],
+*     "maxCalls": 20,
+*     "requiredOrder": ["lookup_order", "issue_refund"],
+*     "arguments": [{ "tool": "issue_refund", "pointer": "/amount", "type": "number" }]
+*   },
+*   "llm": { "maxCalls": 10, "maxTotalTokens": 50000, "allowedModels": ["claude-sonnet-4-5"] },
+*   "alternatives": { "anyOf": [{ "id": "cache-hit", "tools": { "required": ["read_cache"] } }] }
+* }
+* ```
+*
+* Parsing is strict: an unknown key anywhere is an error that names the
+* closest known key, so a typo never silently drops a check. Tool rules match
+* TOOL spans only and model rules match LLM spans only, so an LLM span that
+* shares a tool's name never satisfies a tool rule. `rules` accepts the
+* low-level operators for checks the declarative keys cannot state.
+*/
+const PATH_KEYS = [
+	"run",
+	"tools",
+	"llm",
+	"rules"
+];
+const SPEC_KEYS = [
+	"name",
+	"description",
+	"scope",
+	"alternatives",
+	...PATH_KEYS
+];
+const ALTERNATIVE_KEYS = ["id", ...PATH_KEYS];
+const RUN_KEYS = [
+	"requireCompleted",
+	"allowedStatuses",
+	"maxDurationMs"
+];
+const TOOLS_KEYS = [
+	"required",
+	"forbidden",
+	"allowed",
+	"maxCalls",
+	"maxCallsPerTool",
+	"requiredOrder",
+	"orderMode",
+	"arguments"
+];
+const LLM_KEYS = [
+	"maxCalls",
+	"maxTotalTokens",
+	"allowedModels"
+];
+const ARGUMENT_KEYS = [
+	"tool",
+	"pointer",
+	"occurrence",
+	"exists",
+	"equals",
+	"oneOf",
+	"type"
+];
+const ARGUMENT_CHECK_KEYS = [
+	"exists",
+	"equals",
+	"oneOf",
+	"type"
+];
+const PREDICATE_KEYS = [
+	"name",
+	"tool",
+	"model",
+	"kind",
+	"attr",
+	"not"
+];
+const MATCHER_KEYS = [
+	"$regex",
+	"flags",
+	"oneOf"
+];
+const RULE_KEYS = {
+	always: [
+		"kind",
+		"label",
+		"p"
+	],
+	never: [
+		"kind",
+		"label",
+		"p"
+	],
+	eventually: [
+		"kind",
+		"label",
+		"p"
+	],
+	precedes: [
+		"kind",
+		"label",
+		"a",
+		"b",
+		"order"
+	],
+	neverUnless: [
+		"kind",
+		"label",
+		"p",
+		"prior",
+		"order"
+	],
+	atMost: [
+		"kind",
+		"label",
+		"p",
+		"max"
+	],
+	tokensAtMost: [
+		"kind",
+		"label",
+		"p",
+		"max"
+	],
+	run: [
+		"kind",
+		"label",
+		...RUN_KEYS
+	],
+	argument: [
+		"kind",
+		"label",
+		"p",
+		"pointer",
+		"check",
+		"occurrence"
+	]
+};
+/**
+* Parse and compile a declarative contract. Throws `ValidationError` naming
+* the path of the first problem: an unknown key, a wrong type, an unknown
+* status, or a contract that checks nothing.
+*/
+function compileTraceContractSpec(input) {
+	const spec = parseSpec(input);
+	const scope = spec.scope ? { root: normalizePredicate(spec.scope.root, "scope.root") } : void 0;
+	const alternatives = spec.alternatives?.anyOf.map((alt) => ({
+		id: alt.id,
+		rules: compilePath(alt, "")
+	}));
+	const contract = {
+		name: spec.name,
+		...spec.description === void 0 ? {} : { description: spec.description },
+		...scope === void 0 ? {} : { scope },
+		rules: compilePath(spec, ""),
+		...alternatives === void 0 ? {} : { alternatives }
+	};
+	assertContract(contract, `contract spec "${spec.name}"`);
+	return contract;
+}
+const toolCall = (tool) => ({
+	kind: "TOOL",
+	tool
+});
+const ANY_TOOL = { kind: "TOOL" };
+const ANY_LLM = { kind: "LLM" };
+function compilePath(path, prefix) {
+	const at = (key) => prefix ? `${prefix}.${key}` : key;
+	const rules = [];
+	if (path.run) rules.push({
+		kind: "run",
+		label: at("run"),
+		...path.run
+	});
+	const tools = path.tools;
+	if (tools) {
+		for (const tool of tools.required ?? []) rules.push({
+			kind: "eventually",
+			label: at(`tools.required[${tool}]`),
+			p: toolCall(tool)
+		});
+		for (const tool of tools.forbidden ?? []) rules.push({
+			kind: "never",
+			label: at(`tools.forbidden[${tool}]`),
+			p: toolCall(tool)
+		});
+		if (tools.allowed) rules.push({
+			kind: "never",
+			label: at("tools.allowed"),
+			p: {
+				kind: "TOOL",
+				not: { tool: { oneOf: [...tools.allowed] } }
+			}
+		});
+		if (tools.maxCalls !== void 0) rules.push({
+			kind: "atMost",
+			label: at("tools.maxCalls"),
+			p: ANY_TOOL,
+			max: tools.maxCalls
+		});
+		for (const [tool, max] of Object.entries(tools.maxCallsPerTool ?? {})) rules.push({
+			kind: "atMost",
+			label: at(`tools.maxCallsPerTool[${tool}]`),
+			p: toolCall(tool),
+			max
+		});
+		const order = tools.requiredOrder ?? [];
+		for (let i = 1; i < order.length; i++) rules.push({
+			kind: "precedes",
+			label: at(`tools.requiredOrder[${order[i - 1]}->${order[i]}]`),
+			a: toolCall(order[i - 1]),
+			b: toolCall(order[i]),
+			...tools.orderMode === void 0 ? {} : { order: tools.orderMode }
+		});
+		if (order.length === 1) rules.push({
+			kind: "eventually",
+			label: at(`tools.requiredOrder[${order[0]}]`),
+			p: toolCall(order[0])
+		});
+		tools.arguments?.forEach((arg, i) => {
+			const check = argumentCheck(arg);
+			rules.push({
+				kind: "argument",
+				label: at(`tools.arguments[${i}] ${arg.tool} ${arg.pointer || "(whole value)"} ${describeCheck(check)}`),
+				p: toolCall(arg.tool),
+				pointer: arg.pointer,
+				check,
+				...arg.occurrence === void 0 ? {} : { occurrence: arg.occurrence }
+			});
+		});
+	}
+	const llm = path.llm;
+	if (llm) {
+		if (llm.maxCalls !== void 0) rules.push({
+			kind: "atMost",
+			label: at("llm.maxCalls"),
+			p: ANY_LLM,
+			max: llm.maxCalls
+		});
+		if (llm.maxTotalTokens !== void 0) rules.push({
+			kind: "tokensAtMost",
+			label: at("llm.maxTotalTokens"),
+			p: ANY_LLM,
+			max: llm.maxTotalTokens
+		});
+		if (llm.allowedModels) rules.push({
+			kind: "never",
+			label: at("llm.allowedModels"),
+			p: {
+				kind: "LLM",
+				not: { model: { oneOf: [...llm.allowedModels] } }
+			}
+		});
+	}
+	for (const rule of path.rules ?? []) rules.push({ ...rule });
+	return rules;
+}
+function argumentCheck(arg) {
+	if (arg.exists) return { op: "exists" };
+	if ("equals" in arg) return {
+		op: "equals",
+		value: arg.equals
+	};
+	if (arg.oneOf) return {
+		op: "oneOf",
+		values: arg.oneOf
+	};
+	return {
+		op: "type",
+		type: arg.type
+	};
+}
+function parseSpec(input) {
+	const spec = object(input, "contract");
+	strictKeys(spec, SPEC_KEYS, "contract");
+	const name = nonEmptyString(spec.name, "name");
+	if (spec.description !== void 0) nonEmptyString(spec.description, "description");
+	if (spec.scope !== void 0) {
+		const scope = object(spec.scope, "scope");
+		strictKeys(scope, ["root"], "scope");
+		predicate(scope.root, "scope.root");
+	}
+	parsePath(spec, "");
+	if (spec.alternatives !== void 0) {
+		const alternatives = object(spec.alternatives, "alternatives");
+		strictKeys(alternatives, ["anyOf"], "alternatives");
+		nonEmptyArray(alternatives.anyOf, "alternatives.anyOf").forEach((alt, i) => {
+			const where = `alternatives.anyOf[${i}]`;
+			const a = object(alt, where);
+			strictKeys(a, ALTERNATIVE_KEYS, where);
+			nonEmptyString(a.id, `${where}.id`);
+			parsePath(a, where);
+		});
+	}
+	return {
+		...spec,
+		name
+	};
+}
+function parsePath(path, prefix) {
+	const at = (key) => prefix ? `${prefix}.${key}` : key;
+	if (path.run !== void 0) {
+		const run = object(path.run, at("run"));
+		strictKeys(run, RUN_KEYS, at("run"));
+		if (Array.isArray(run.allowedStatuses)) run.allowedStatuses.forEach((status, i) => {
+			oneOfValues(status, RUN_STATUSES, at(`run.allowedStatuses[${i}]`));
+		});
+		assertRule({
+			kind: "run",
+			label: "run",
+			...run
+		}, at("run"));
+	}
+	if (path.tools !== void 0) {
+		const tools = object(path.tools, at("tools"));
+		strictKeys(tools, TOOLS_KEYS, at("tools"));
+		for (const key of [
+			"required",
+			"forbidden",
+			"allowed",
+			"requiredOrder"
+		]) if (tools[key] !== void 0) toolNames(tools[key], at(`tools.${key}`));
+		if (tools.maxCalls !== void 0) count(tools.maxCalls, at("tools.maxCalls"));
+		if (tools.maxCallsPerTool !== void 0) {
+			const perTool = object(tools.maxCallsPerTool, at("tools.maxCallsPerTool"));
+			for (const [tool, max] of Object.entries(perTool)) {
+				nonEmptyString(tool, at("tools.maxCallsPerTool key"));
+				count(max, at(`tools.maxCallsPerTool.${tool}`));
+			}
+		}
+		if (tools.orderMode !== void 0) oneOfValues(tools.orderMode, ORDER_MODES, at("tools.orderMode"));
+		if (tools.orderMode !== void 0 && tools.requiredOrder === void 0) throw new ValidationError(`${at("tools.orderMode")}: set only with requiredOrder`);
+		if (tools.arguments !== void 0) nonEmptyArray(tools.arguments, at("tools.arguments")).forEach((arg, i) => {
+			const where = at(`tools.arguments[${i}]`);
+			const a = object(arg, where);
+			strictKeys(a, ARGUMENT_KEYS, where);
+			nonEmptyString(a.tool, `${where}.tool`);
+			const checks = ARGUMENT_CHECK_KEYS.filter((k) => k in a);
+			if (checks.length !== 1) throw new ValidationError(`${where}: set exactly one of ${ARGUMENT_CHECK_KEYS.join(", ")} (found ${checks.length})`);
+			if (a.exists !== void 0 && a.exists !== true) throw new ValidationError(`${where}.exists: must be true`);
+			if (a.oneOf !== void 0) nonEmptyArray(a.oneOf, `${where}.oneOf`);
+			if (a.type !== void 0) oneOfValues(a.type, ARGUMENT_TYPES, `${where}.type`);
+			if (a.occurrence !== void 0) oneOfValues(a.occurrence, ARGUMENT_OCCURRENCES, `${where}.occurrence`);
+			assertRule({
+				kind: "argument",
+				label: "argument",
+				p: toolCall(a.tool),
+				pointer: a.pointer,
+				check: argumentCheck(a)
+			}, where);
+		});
+	}
+	if (path.llm !== void 0) {
+		const llm = object(path.llm, at("llm"));
+		strictKeys(llm, LLM_KEYS, at("llm"));
+		if (llm.maxCalls !== void 0) count(llm.maxCalls, at("llm.maxCalls"));
+		if (llm.maxTotalTokens !== void 0) count(llm.maxTotalTokens, at("llm.maxTotalTokens"));
+		if (llm.allowedModels !== void 0) toolNames(llm.allowedModels, at("llm.allowedModels"));
+	}
+	if (path.rules !== void 0) nonEmptyArray(path.rules, at("rules")).forEach((raw, i) => {
+		const where = at(`rules[${i}]`);
+		const rule = object(raw, where);
+		const kind = oneOfValues(rule.kind, Object.keys(RULE_KEYS), `${where}.kind`);
+		strictKeys(rule, RULE_KEYS[kind], where);
+		for (const key of [
+			"p",
+			"a",
+			"b",
+			"prior"
+		]) if (rule[key] !== void 0) predicate(rule[key], `${where}.${key}`);
+		if (kind === "argument" && rule.check !== void 0) strictKeys(object(rule.check, `${where}.check`), [
+			"op",
+			"value",
+			"values",
+			"type"
+		], `${where}.check`);
+		assertRule(rule, where);
+	});
+}
+function predicate(value, where) {
+	const p = object(value, where);
+	strictKeys(p, PREDICATE_KEYS, where);
+	for (const key of [
+		"name",
+		"tool",
+		"model"
+	]) {
+		const m = p[key];
+		if (m !== null && typeof m === "object" && !Array.isArray(m)) strictKeys(m, MATCHER_KEYS, `${where}.${key}`);
+	}
+	if (p.kind !== void 0) oneOfValues(p.kind, SPAN_KINDS, `${where}.kind`);
+	if (p.not !== void 0) predicate(p.not, `${where}.not`);
+}
+function strictKeys(value, allowed, where) {
+	for (const key of Object.keys(value)) {
+		if (allowed.includes(key)) continue;
+		const hint = closest(key, allowed);
+		throw new ValidationError(`${where}: unknown key "${key}"${hint ? ` — did you mean "${hint}"?` : ""} (allowed: ${allowed.join(", ")})`);
+	}
+}
+function object(value, where) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new ValidationError(`${where}: must be an object`);
+	return value;
+}
+function nonEmptyString(value, where) {
+	if (typeof value !== "string" || value.trim().length === 0) throw new ValidationError(`${where}: must be a non-empty string`);
+	return value;
+}
+function nonEmptyArray(value, where) {
+	if (!Array.isArray(value) || value.length === 0) throw new ValidationError(`${where}: must be a non-empty array`);
+	return value;
+}
+function toolNames(value, where) {
+	const names = nonEmptyArray(value, where).map((v, i) => nonEmptyString(v, `${where}[${i}]`));
+	const dup = names.find((n, i) => names.indexOf(n) !== i);
+	if (dup !== void 0) throw new ValidationError(`${where}: "${dup}" is listed twice`);
+	return names;
+}
+function count(value, where) {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throw new ValidationError(`${where}: must be a non-negative integer`);
+}
+function oneOfValues(value, allowed, where) {
+	if (typeof value === "string" && allowed.includes(value)) return value;
+	const hint = typeof value === "string" ? closest(value, allowed) : void 0;
+	throw new ValidationError(`${where}: ${JSON.stringify(value)} is not one of ${allowed.join(", ")}${hint ? ` — did you mean "${hint}"?` : ""}`);
+}
+/** The allowed word within edit distance 2 (or a case-insensitive match). */
+function closest(word, allowed) {
+	let best;
+	for (const candidate of allowed) {
+		const d = candidate.toLowerCase() === word.toLowerCase() ? 0 : editDistance(word.toLowerCase(), candidate.toLowerCase());
+		if (d <= 2 && (!best || d < best.d)) best = {
+			word: candidate,
+			d
+		};
+	}
+	return best?.word;
+}
+function editDistance(a, b) {
+	let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+	for (let i = 1; i <= a.length; i++) {
+		const cur = [i];
+		for (let j = 1; j <= b.length; j++) cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+		prev = cur;
+	}
+	return prev[b.length];
+}
+/**
+* Find contradictions and likely mistakes in a declarative contract. Parses
+* strictly first, so a malformed spec throws instead of linting.
+*/
+function lintTraceContractSpec(input) {
+	const spec = parseSpec(input);
+	const findings = [];
+	lintPath(spec, "", findings);
+	for (const [i, alt] of (spec.alternatives?.anyOf ?? []).entries()) lintPath(alt, `alternatives.anyOf[${i}]`, findings);
+	if (spec.alternatives?.anyOf.length === 1) findings.push({
+		level: "warning",
+		code: "alternatives.single",
+		path: "alternatives.anyOf",
+		message: "one alternative is the same as base checks; move its checks to the base or add another path"
+	});
+	const ids = spec.alternatives?.anyOf.map((a) => a.id) ?? [];
+	const dupId = ids.find((id, i) => ids.indexOf(id) !== i);
+	if (dupId !== void 0) findings.push({
+		level: "error",
+		code: "alternatives.duplicate-id",
+		path: "alternatives.anyOf",
+		message: `alternative id "${dupId}" is used twice`
+	});
+	return findings;
+}
+function lintPath(path, prefix, out) {
+	const at = (key) => prefix ? `${prefix}.${key}` : key;
+	const error = (code, key, message) => out.push({
+		level: "error",
+		code,
+		path: at(key),
+		message
+	});
+	const warn = (code, key, message) => out.push({
+		level: "warning",
+		code,
+		path: at(key),
+		message
+	});
+	const t = path.tools ?? {};
+	const forbidden = new Set(t.forbidden ?? []);
+	const allowed = t.allowed ? new Set(t.allowed) : void 0;
+	const needed = [...t.required ?? [], ...t.requiredOrder ?? []];
+	for (const tool of needed) {
+		if (forbidden.has(tool)) error("tools.required-and-forbidden", "tools", `"${tool}" is both required and forbidden`);
+		if (allowed && !allowed.has(tool)) error("tools.required-not-allowed", "tools.allowed", `"${tool}" is required but not in allowed`);
+		if (t.maxCallsPerTool?.[tool] === 0) error("tools.required-capped-at-zero", "tools.maxCallsPerTool", `"${tool}" is required but capped at 0 calls`);
+	}
+	if (t.maxCalls === 0 && needed.length > 0) error("tools.required-but-no-calls", "tools.maxCalls", "tools are required but maxCalls is 0");
+	const distinctNeeded = new Set(needed).size;
+	if (t.maxCalls !== void 0 && t.maxCalls > 0 && distinctNeeded > t.maxCalls) error("tools.max-below-required", "tools.maxCalls", `${distinctNeeded} distinct tools are required but maxCalls is ${t.maxCalls}`);
+	for (const tool of forbidden) {
+		if (allowed?.has(tool)) error("tools.allowed-and-forbidden", "tools", `"${tool}" is both allowed and forbidden`);
+		if (t.maxCallsPerTool?.[tool] !== void 0) warn("tools.cap-on-forbidden", "tools.maxCallsPerTool", `"${tool}" is forbidden, so its call cap never applies`);
+	}
+	for (const tool of Object.keys(t.maxCallsPerTool ?? {})) if (allowed && !allowed.has(tool)) warn("tools.cap-on-disallowed", "tools.maxCallsPerTool", `"${tool}" has a cap but is not in allowed`);
+	for (const [i, arg] of (t.arguments ?? []).entries()) {
+		if (forbidden.has(arg.tool)) error("tools.argument-on-forbidden", `tools.arguments[${i}]`, `"${arg.tool}" is forbidden, so its arguments can never be checked`);
+		if (!needed.includes(arg.tool)) warn("tools.argument-without-required", `tools.arguments[${i}]`, `"${arg.tool}" is not required; a run that never calls it fails this check for missing evidence`);
+	}
+	const order = t.requiredOrder ?? [];
+	const repeated = order.find((tool, i) => order.indexOf(tool) !== i);
+	if (repeated !== void 0) error("tools.order-repeats", "tools.requiredOrder", `"${repeated}" appears twice, so the order contradicts itself`);
+	if (order.length > 1 && t.orderMode === void 0) warn("tools.order-default-mode", "tools.orderMode", "start-order passes when calls overlap; set finish-before-start if each step must finish first");
+	const run = path.run;
+	if (run?.requireCompleted && run.allowedStatuses?.includes("running")) error("run.running-and-completed", "run", "requireCompleted contradicts allowedStatuses containing \"running\"");
+	if (path.llm?.maxCalls === 0 && (path.llm.maxTotalTokens !== void 0 || path.llm.allowedModels)) warn("llm.no-calls", "llm", "maxCalls is 0, so the token and model limits never apply");
+}
+//#endregion
 //#region src/active-learning.ts
 async function proposeSynthesisTargets(dataset, traceStore, options = {}) {
 	const minPerBand = options.minPerBand ?? 5;
@@ -2108,7 +3259,7 @@ async function runAgentControlLoop(config) {
 	const started = Date.now();
 	const wallTimer = budget.maxWallMs ? setTimeout(() => controller.abort(/* @__PURE__ */ new Error("control runtime wall timeout")), budget.maxWallMs) : void 0;
 	const history = [];
-	const emitter = config.store ? new TraceEmitter(config.store) : void 0;
+	const emitter = config.store ? new TraceEmitter(config.store, { onCaptureError: () => void 0 }) : void 0;
 	let spentCostUsd = 0;
 	const runtimeErrors = [];
 	const repeatedDetector = repeatedActionDetector({ maxRepeated: config.stopPolicies?.maxRepeatedActions ?? 0 });
@@ -2117,7 +3268,7 @@ async function runAgentControlLoop(config) {
 		minScoreDelta: config.stopPolicies?.minScoreDelta ?? .001
 	});
 	try {
-		if (emitter) await runTrace(runtimeErrors, 0, () => emitter.startRun({
+		if (emitter) await runTrace(emitter, runtimeErrors, 0, () => emitter.startRun({
 			scenarioId: config.scenarioId ?? "agent-control-loop",
 			projectId: config.projectId,
 			variantId: config.variantId,
@@ -2322,7 +3473,7 @@ async function runAgentControlLoop(config) {
 			const evalsBefore = evals;
 			const scoreBefore = averageScore(evals);
 			const actionStarted = Date.now();
-			const stepHandle = emitter ? await runTrace(runtimeErrors, stepIndex, () => emitter.tool({
+			const stepHandle = emitter ? await runTrace(emitter, runtimeErrors, stepIndex, () => emitter.tool({
 				name: `control-step-${stepIndex}`,
 				toolName: "agent-control-action",
 				args: decision.action,
@@ -2360,7 +3511,7 @@ async function runAgentControlLoop(config) {
 					durationMs: Date.now() - actionStarted
 				};
 				if (actionFailure === "stop") {
-					await runTrace(runtimeErrors, stepIndex, () => stepHandle?.fail(actionOutcome.error ?? "action failed"));
+					await runTrace(emitter, runtimeErrors, stepIndex, () => stepHandle?.fail(actionOutcome.error ?? "action failed"));
 					const step = {
 						index: stepIndex,
 						decision,
@@ -2411,7 +3562,7 @@ async function runAgentControlLoop(config) {
 					endedAt: (/* @__PURE__ */ new Date()).toISOString()
 				};
 				history.push(step);
-				await runTrace(runtimeErrors, stepIndex, () => stepHandle?.fail(runtimeErrors[runtimeErrors.length - 1].message));
+				await runTrace(emitter, runtimeErrors, stepIndex, () => stepHandle?.fail(runtimeErrors[runtimeErrors.length - 1].message));
 				await runOnStep(config.onStep, step, runtimeErrors);
 				return finish(emitter, {
 					intent: config.intent,
@@ -2452,7 +3603,7 @@ async function runAgentControlLoop(config) {
 					endedAt: (/* @__PURE__ */ new Date()).toISOString()
 				};
 				history.push(step);
-				await runTrace(runtimeErrors, stepIndex, () => stepHandle?.fail(runtimeErrors[runtimeErrors.length - 1].message));
+				await runTrace(emitter, runtimeErrors, stepIndex, () => stepHandle?.fail(runtimeErrors[runtimeErrors.length - 1].message));
 				await runOnStep(config.onStep, step, runtimeErrors);
 				return finish(emitter, {
 					intent: config.intent,
@@ -2490,14 +3641,14 @@ async function runAgentControlLoop(config) {
 				endedAt: (/* @__PURE__ */ new Date()).toISOString()
 			};
 			history.push(step);
-			if (actionOutcome.ok) await runTrace(runtimeErrors, stepIndex, () => stepHandle?.end({ attributes: {
+			if (actionOutcome.ok) await runTrace(emitter, runtimeErrors, stepIndex, () => stepHandle?.end({ attributes: {
 				actionCostUsd: actionOutcome.costUsd ?? null,
 				spentCostUsd,
 				scoreBefore: scoreBefore ?? null,
 				scoreAfter: scoreAfter ?? null,
 				noProgressStreak
 			} }));
-			else await runTrace(runtimeErrors, stepIndex, () => stepHandle?.fail(actionOutcome.error ?? "action failed", { attributes: {
+			else await runTrace(emitter, runtimeErrors, stepIndex, () => stepHandle?.fail(actionOutcome.error ?? "action failed", { attributes: {
 				spentCostUsd,
 				noProgressStreak
 			} }));
@@ -2703,7 +3854,7 @@ function budgetStopDecision(budget, spentCostUsd) {
 async function recordCostBudget(emitter, budget, spentCostUsd, handle, runtimeErrors, stepIndex) {
 	if (!emitter || budget.maxCostUsd === void 0) return;
 	const maxCostUsd = budget.maxCostUsd;
-	await runTrace(runtimeErrors, stepIndex, () => emitter.recordBudget({
+	await runTrace(emitter, runtimeErrors, stepIndex, () => emitter.recordBudget({
 		dimension: "usd",
 		limit: maxCostUsd,
 		consumed: spentCostUsd,
@@ -2714,7 +3865,7 @@ async function recordCostBudget(emitter, budget, spentCostUsd, handle, runtimeEr
 }
 async function recordEvalSpans(emitter, evals, phase, runtimeErrors, stepIndex, targetSpanId) {
 	if (!emitter) return;
-	for (const result of evals) await runTrace(runtimeErrors, stepIndex, () => emitter.recordJudge({
+	for (const result of evals) await runTrace(emitter, runtimeErrors, stepIndex, () => emitter.recordJudge({
 		judgeId: result.objective ? "objective-validator" : "subjective-judge",
 		targetSpanId: targetSpanId ?? emitter.runId,
 		name: `control-eval/${result.id}`,
@@ -2738,13 +3889,24 @@ async function runOnStep(onStep, step, runtimeErrors) {
 		runtimeErrors.push(runtimeError("on-step", step.index, err));
 	}
 }
-async function runTrace(runtimeErrors, stepIndex, write) {
+/**
+* Run trace writes and record a `trace` runtime error when any of them was
+* dropped. The emitter never throws a failed store write; it counts it, so the
+* count is what this reads. A throw from building the write is recorded too.
+*/
+async function runTrace(emitter, runtimeErrors, stepIndex, write) {
+	if (!emitter) return void 0;
+	const droppedBefore = emitter.captureStats().dropped;
+	let value;
 	try {
-		return await write();
+		value = await write();
 	} catch (err) {
 		runtimeErrors.push(runtimeError("trace", stepIndex, err));
 		return;
 	}
+	const after = emitter.captureStats();
+	if (after.dropped > droppedBefore) runtimeErrors.push(runtimeError("trace", stepIndex, after.lastError ?? "trace write dropped"));
+	return value;
 }
 function fingerprintState(state, policies) {
 	if (policies?.stateFingerprint) return policies.stateFingerprint(state);
@@ -2778,7 +3940,7 @@ function runtimeError(phase, stepIndex, err) {
 	};
 }
 async function finish(emitter, result) {
-	await runTrace(result.runtimeErrors, result.steps.length, () => emitter?.endRun({
+	await runTrace(emitter, result.runtimeErrors, result.steps.length, () => emitter?.endRun({
 		pass: result.pass,
 		score: result.score ?? averageScore(result.finalEvals),
 		failureClass: result.failureClass,
@@ -2836,6 +3998,119 @@ async function discoverPersonas(dir, opts = {}) {
 	return results;
 }
 //#endregion
+//#region src/improvement-verdict.ts
+const DEFAULTS = {
+	keepThreshold: 5,
+	regressionThreshold: 5,
+	iqrUnstableAbove: 10,
+	stddevUnstableAbove: Number.POSITIVE_INFINITY,
+	minRepsForVerdict: 3
+};
+function resolveThresholds(t) {
+	const r = {
+		...DEFAULTS,
+		...t ?? {}
+	};
+	if (r.keepThreshold < 0) throw new ValidationError(`improvement-verdict: keepThreshold must be >= 0, got ${r.keepThreshold}`);
+	if (r.regressionThreshold < 0) throw new ValidationError(`improvement-verdict: regressionThreshold must be >= 0, got ${r.regressionThreshold}`);
+	if (r.minRepsForVerdict < 1) throw new ValidationError(`improvement-verdict: minRepsForVerdict must be >= 1, got ${r.minRepsForVerdict}`);
+	return r;
+}
+function median(sorted) {
+	const n = sorted.length;
+	if (n === 0) return 0;
+	const mid = Math.floor(n / 2);
+	return n % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+/** Population standard deviation (÷n). 0 for fewer than 2 values. */
+function stddev(values, mean) {
+	if (values.length < 2) return 0;
+	const variance = values.reduce((acc, v) => acc + (v - mean) ** 2, 0) / values.length;
+	return Math.sqrt(variance);
+}
+/**
+* Compute the N-rep statistics for a set of reps. Pure — no I/O. The `stable`
+* flag is the trust gate the verdict depends on: a sample whose spread exceeds
+* the configured bounds can't distinguish a real delta from run-to-run noise.
+*/
+function computeExperimentStats(reps, thresholds) {
+	const t = resolveThresholds(thresholds);
+	const n = reps.length;
+	if (n === 0) return {
+		median: 0,
+		mean: 0,
+		min: 0,
+		max: 0,
+		iqr: 0,
+		stddev: 0,
+		passRate: null,
+		n: 0,
+		stable: false
+	};
+	const scores = reps.map((r) => {
+		if (!Number.isFinite(r.score)) throw new ValidationError(`improvement-verdict: rep ${r.rep} has non-finite score ${r.score}`);
+		return r.score;
+	});
+	const sorted = [...scores].sort((a, b) => a - b);
+	const mean = scores.reduce((s, v) => s + v, 0) / n;
+	const sd = stddev(scores, mean);
+	const spread = iqr(scores);
+	const rated = reps.filter((r) => typeof r.passed === "boolean");
+	const passRate = rated.length === 0 ? null : rated.filter((r) => r.passed).length / rated.length;
+	const stable = spread < t.iqrUnstableAbove && sd < t.stddevUnstableAbove;
+	return {
+		median: median(sorted),
+		mean,
+		min: sorted[0],
+		max: sorted[n - 1],
+		iqr: spread,
+		stddev: sd,
+		passRate,
+		n,
+		stable
+	};
+}
+/**
+* Verdict for a candidate against its parent. Pure — operates on already-computed
+* stats. KEEP/REGRESSION require both sides to have `>= minRepsForVerdict` reps
+* AND the candidate to be `stable`; otherwise the result is NOISE (unstable) or
+* ITERATE (not enough reps / no parent).
+*/
+function improvementVerdict(candidate, parent, thresholds) {
+	const t = resolveThresholds(thresholds);
+	if (!parent) return {
+		verdict: "ITERATE",
+		medianDelta: null,
+		reason: "no parent experiment to compare against"
+	};
+	if (candidate.n < t.minRepsForVerdict || parent.n < t.minRepsForVerdict) return {
+		verdict: "ITERATE",
+		medianDelta: null,
+		reason: `need >= ${t.minRepsForVerdict} reps on both sides (candidate n=${candidate.n}, parent n=${parent.n})`
+	};
+	if (!candidate.stable) return {
+		verdict: "NOISE",
+		medianDelta: candidate.median - parent.median,
+		reason: `candidate unstable (iqr=${candidate.iqr}, stddev=${candidate.stddev.toFixed(2)})`
+	};
+	const medianDelta = candidate.median - parent.median;
+	if (medianDelta > t.keepThreshold) return {
+		verdict: "KEEP",
+		medianDelta,
+		reason: `median +${medianDelta} > +${t.keepThreshold}`
+	};
+	if (medianDelta < -t.regressionThreshold) return {
+		verdict: "REGRESSION",
+		medianDelta,
+		reason: `median ${medianDelta} < -${t.regressionThreshold}`
+	};
+	return {
+		verdict: "NOISE",
+		medianDelta,
+		reason: `median delta ${medianDelta} inside noise band [-${t.regressionThreshold}, +${t.keepThreshold}]`
+	};
+}
+//#endregion
 //#region src/propose-review.ts
 /**
 * Propose / Verify / Review — the core multi-shot primitive.
@@ -8311,6 +9586,6 @@ function rankRows(rows, weights) {
 	})).sort((a, b) => b.mean - a.mean);
 }
 //#endregion
-export { AGENT_PROFILE_KINDS, ATTESTATION_ALGORITHM, AgentEvalError, AnalystRegistry, BOOTSTRAP_GATE_MIN_N, BackendIntegrityError, BudgetBreachError, BudgetGuard, CODING_HARNESSES, ConfigError, CostAccountingIncompleteError, CostCallConflictError, CostCeilingReachedError, CostLedger, CostLedgerPersistenceError, CostReceiptCaptureError, CostReservationExceededError, CostTracker, CrossFamilyError, DECISION_PAIRED_DELTA_STATISTIC, DEFAULT_BOUNDED_PROCESS_TIMEOUT_MS, DEFAULT_FAILURE_REASON_RULES, DEFAULT_PERMUTATIONS, DEFAULT_REDACTION_RULES, DEFAULT_RED_TEAM_CORPUS, DEFAULT_TRACE_ANALYST_BUDGETS, DEFAULT_TRACE_ANALYST_KINDS, DEFAULT_TRACE_ANALYST_OUTPUT_TOKENS, ERROR_COUNT_PATTERNS, EquivalenceProtocolError, FAILURE_BLAME, FAILURE_CLASSES, FAILURE_MODE_KIND_SPEC, FileSystemFeedbackTrajectoryStore, FileSystemRawProviderSink, FileSystemTraceStore, FindingsStore, HARNESS_NATIVE_MODEL, HeldOutGate, INFRA_FAILURE_BLAMES, InMemoryFeedbackTrajectoryStore, InMemoryRawProviderSink, InMemoryTraceStore, JudgeError, LOCAL_COMMAND_RUNNER_DEFAULT_CAP_MS, LlmCallError, LlmResponseError, MANN_WHITNEY_EXACT_MAX_STATES, MANN_WHITNEY_EXACT_MAX_WORK, MODEL_PRICING, ModelSubstitutionError, MultiLayerVerifier, NoopRawProviderSink, NotFoundError, OUTPUT_VALUE, OtlpFileTraceStore, POLICY_EDIT_AXES, POLICY_EDIT_CANDIDATE_RECORD_SCHEMA, POLICY_EDIT_TARGET_SURFACES, PairwiseSteeringOptimizer, PolicyEditValidationError, ProductClient, PromptRegistry, REDACTION_VERSION, RunIntegrityError, RunRecordValidationError, SEMANTIC_CONCEPT_JUDGE_VERSION, ServedCrossFamilyError, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, TraceEmitter, UNKNOWN_MODEL, VERIFICATION_STRATEGIES, VERIFICATION_STRATEGY_SOURCES, ValidationError, WILCOXON_EXACT_MAX_N, acquisitionPlansForKnowledgeGaps, admitPolicyEdit, agentProfileCellHashMaterial, agentProfileCellKey, agentProfileHash, agentProfileId, aggregateJudgeVerdicts, aggregateRunScore, analystFindingDigest, analystRunDigest, analystRunToFeedbackTrajectory, analystRunToReviewRequests, analyzeAntiSlop, analyzeRuns, analyzeSeries, analyzeTraces, applyPolicyEditToSurface, argHash, assertCapabilityHeadroom, assertCrossFamily, assertCrossFamilyServed, assertNoHiddenLeak, assertNoJudgeVerdict, assertProductBenchmarkRun, assertRealBackend, assertRunCaptured, assertServedModel, assertServedModels, assertSingleBackend, assignFeedbackSplit, attest, benjaminiHochberg, blendHeldout, blockingKnowledgeEval, bonferroni, bootstrapCi, budgetBreachView, buildAgentProfileCell, buildDefaultAnalystRegistry, buildEquivalenceRecord, buildReflectionPrompt, buildTraceInsightContext, buildTraceInsightPrompt, buildTrajectory, calibrateJudge, calibrateJudgeContinuous, canonicalJson, capabilityHeadroom, captureFetchToRawSink, certificationEvidenceDigest, checkCanaries, checkServedModel, checkTraceContracts, clamp01, classifyFailure, classifyFailureReason, cliffsDelta, cohensD, comparePairedArms, completionVerdict, computeExperimentStats, computeFindingId, computePolicyEditId, computeToolUseMetrics, confidenceInterval, contentHash, continuousAgreement, controlRunToFeedbackTrajectory, corpusInterRaterAgreement, corpusInterRaterAgreementFromJudgeScores, costForTokenPricing, costForUsage, costReceiptFromLlm, costReceiptFromLlmError, createAntiSlopJudge, createBoundedTraceAnalysisStore, createChatClient, createChatTraceEngine, createDspyRlmTraceEngine, createFeedbackTrajectory, createLlmCorrectnessChecker, createLlmReviewer, createTraceAnalyst, decidePairedPromotion, defaultBlendWeights, defineAgentEval, defineEquivalenceCheck, deployGateLayer, describeTraceInsightScope, diffFindings, diffScorecard, discoverPersonas, domainEvidencePattern, dominates, eProcess, ensembleJudge, equivalenceVerdict, errorStreakDetector, estimateCost, estimateTokens, evaluateActionPolicy, evaluateInterimReleaseConfidence, evaluateOracles, evaluateReleaseConfidence, expandProfileAxes, exportProductBenchmark, exportProductBenchmarkRuns, exportRunAsOtlp, extractErrorCount, extractProducedState, extractUsage, extractUsageFromSse, failureBlame, failureClusterView, feedbackTrajectoriesToDatasetScenarios, feedbackTrajectoriesToOptimizerRows, feedbackTrajectoryToOptimizerRow, fileVerdictCache, formatScorecardDiff, gainHistogram, gateTreatmentApplied, gradeOnHidden, gradeSemanticStatus, groupRunsByAgentProfileCell, harnessAxisOf, hashContent, hashJson, hiddenGrade, holm, improvementVerdict, inMemoryReviewStore, inferDomainKeywords, interRaterReliability, interpretCliffs, iqr, isBinaryOutcomeVector, isJudgeSpan, isLlmSpan, isModelPriced, isPolicyEdit, isRunRecord, isToolSpan, isTransientLlmError, jsonShape, jsonlReviewStore, jsonlRunRecordBackend, judgeAgreementView, judgeFamily, judgeSpans, knowledgeReadinessTracePayload, leaderboard, llmJudge, loadScorecard, localCommandRunner, makeFinding, makePolicyEdit, makePolicyEditCandidateRecord, makeProposalFinding, manifestContentDigest, mannWhitneyU, maximumChargeForLlmRequest, mcnemar, mcnemarPower, mcnemarRequiredN, minimumPairsForPairedDeltaTest, mintRolloutRows, modelHasSnapshot, modelPriceKey, mulberry32, notBlocked, objectiveEval, observeAll, otlpTextToTraceAnalysisStore, pairArms, pairRunRecords, pairedBinaryScale, pairedBootstrap, pairedCohensDz, pairedDeltaTest, pairedDeltaTieFraction, pairedEvalueSequence, pairedMde, pairedPromotionPower, pairedRiskDifference, pairedRiskDifferenceExact, pairedRiskDifferenceScore, pairedSignTest, pairedTTest, paretoChart, paretoFrontier, parseReflectionResponse, parseRunRecordSafe, partialCredit, partitionHeldOut, partitionTrainSelectionTest, passAtK, pearsonR, policyEditFromFinding, policyEditsFromFindings, preflightModels, productBenchmarkRepoIdentity, profile_exports as profile, projectRuntimeTrajectoryEvidence, proposeSynthesisTargets, quotaExhaustedUntil, ranks, readProductBenchmarkManifest, recordRuns, recordRunsToScorecard, redTeamDataset, redTeamReport, redactString, regexMatches, renderPreferenceMemoryMarkdown, repeatedActionDetector, requiredPairedSampleSize, requiredPairsForPairedPromotion, requiredSampleSize, resolveModelPricing, resolveSeat, roundTripRunRecord, routeFields, runAgentControlLoop, runBoundedProcess, runCampaign, runCanaries, runCounterfactual, runEquivalenceCheck, runEvalCampaign, runIntentMatchJudge, runKeywordCoverageJudge, runKeywordCoverageJudgeUrl, runProposeReview, runProposeReviewAsControlLoop, runSemanticConceptJudge, runTaskScore, runsForScenario, scoreKnowledgeReadiness, scorePolicyEditReadiness, scoreRedTeamOutput, scoreTraceInsightReadiness, seatPresets, selfImprove, servedModelAcceptable, spearmanR, stripFencedJson, subjectiveEval, summarizeBackendIntegrity, summarizeNumberSeries, summarizePreferenceMemory, summaryTable, textInSnapshot, toAgentProfileJson, tokenizeDomainWords, toolSpansToTraceAnalysisStore, toolWasteView, traceContract, transientDispatchFailure, urlContains, userQuestionsForKnowledgeGaps, validatePolicyEdit, validatePolicyEditCandidateRecord, validateRunRecord, verbosityBias, verifyAgentProfileCell, verifyAttestation, verifyCompletion, viteDeployRunner, weightedComposite, weightedMean, wilcoxonSignedRank, wilson, withAssignedFeedbackSplit, withHeldoutBlend, withJudgeRetry, wranglerDeployRunner };
+export { AGENT_PROFILE_KINDS, ATTESTATION_ALGORITHM, AgentEvalError, AnalystRegistry, BOOTSTRAP_GATE_MIN_N, BackendIntegrityError, BudgetBreachError, BudgetGuard, CODING_HARNESSES, ConfigError, CostAccountingIncompleteError, CostCallConflictError, CostCeilingReachedError, CostLedger, CostLedgerPersistenceError, CostReceiptCaptureError, CostReservationExceededError, CostTracker, CrossFamilyError, DECISION_PAIRED_DELTA_STATISTIC, DEFAULT_BOUNDED_PROCESS_TIMEOUT_MS, DEFAULT_FAILURE_REASON_RULES, DEFAULT_PERMUTATIONS, DEFAULT_RED_TEAM_CORPUS, DEFAULT_TRACE_ANALYST_BUDGETS, DEFAULT_TRACE_ANALYST_KINDS, DEFAULT_TRACE_ANALYST_OUTPUT_TOKENS, ERROR_COUNT_PATTERNS, EquivalenceProtocolError, FAILURE_BLAME, FAILURE_CLASSES, FAILURE_MODE_KIND_SPEC, FileSystemFeedbackTrajectoryStore, FileSystemRawProviderSink, FileSystemTraceStore, FindingsStore, HARNESS_NATIVE_MODEL, HeldOutGate, INFRA_FAILURE_BLAMES, InMemoryFeedbackTrajectoryStore, InMemoryRawProviderSink, InMemoryTraceStore, JudgeError, LOCAL_COMMAND_RUNNER_DEFAULT_CAP_MS, LlmCallError, LlmResponseError, MANN_WHITNEY_EXACT_MAX_STATES, MANN_WHITNEY_EXACT_MAX_WORK, MODEL_PRICING, ModelSubstitutionError, MultiLayerVerifier, NoopRawProviderSink, NotFoundError, OUTPUT_VALUE, OtlpFileTraceStore, POLICY_EDIT_AXES, POLICY_EDIT_CANDIDATE_RECORD_SCHEMA, POLICY_EDIT_TARGET_SURFACES, PairwiseSteeringOptimizer, PolicyEditValidationError, ProductClient, PromptRegistry, REDACTION_VERSION, RunIntegrityError, RunRecordValidationError, SEMANTIC_CONCEPT_JUDGE_VERSION, ServedCrossFamilyError, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, TraceEmitter, UNKNOWN_MODEL, VERIFICATION_STRATEGIES, VERIFICATION_STRATEGY_SOURCES, ValidationError, WILCOXON_EXACT_MAX_N, acquisitionPlansForKnowledgeGaps, admitPolicyEdit, agentProfileCellHashMaterial, agentProfileCellKey, agentProfileHash, agentProfileId, aggregateJudgeVerdicts, aggregateRunScore, analystFindingDigest, analystRunDigest, analystRunToFeedbackTrajectory, analystRunToReviewRequests, analyzeAntiSlop, analyzeRuns, analyzeSeries, analyzeTraces, applyPolicyEditToSurface, argHash, assertCapabilityHeadroom, assertCrossFamily, assertCrossFamilyServed, assertNoHiddenLeak, assertNoJudgeVerdict, assertProductBenchmarkRun, assertRealBackend, assertRunCaptured, assertServedModel, assertServedModels, assertSingleBackend, assessShareSafety, assignFeedbackSplit, attest, benjaminiHochberg, blendHeldout, blockingKnowledgeEval, bonferroni, bootstrapCi, budgetBreachView, buildAgentProfileCell, buildDefaultAnalystRegistry, buildEquivalenceRecord, buildReflectionPrompt, buildTraceInsightContext, buildTraceInsightPrompt, buildTrajectory, calibrateJudge, calibrateJudgeContinuous, canonicalJson, capabilityHeadroom, captureFetchToRawSink, certificationEvidenceDigest, checkCanaries, checkServedModel, checkTraceContracts, clamp01, classifyFailure, classifyFailureReason, cliffsDelta, cohensD, comparePairedArms, compileTraceContractSpec, completionVerdict, computeExperimentStats, computeFindingId, computePolicyEditId, computeToolUseMetrics, confidenceInterval, contentHash, continuousAgreement, controlRunToFeedbackTrajectory, corpusInterRaterAgreement, corpusInterRaterAgreementFromJudgeScores, costForTokenPricing, costForUsage, costReceiptFromLlm, costReceiptFromLlmError, createAntiSlopJudge, createBoundedTraceAnalysisStore, createChatClient, createChatTraceEngine, createDspyRlmTraceEngine, createFeedbackTrajectory, createLlmCorrectnessChecker, createLlmReviewer, createTraceAnalyst, decidePairedPromotion, defaultBlendWeights, defineAgentEval, defineEquivalenceCheck, deployGateLayer, describeTraceInsightScope, diffFindings, diffScorecard, discoverPersonas, domainEvidencePattern, dominates, eProcess, ensembleJudge, equivalenceVerdict, errorStreakDetector, estimateCost, estimateTokens, evaluateActionPolicy, evaluateInterimReleaseConfidence, evaluateOracles, evaluateReleaseConfidence, evaluateTraceContract, expandProfileAxes, explainTraceContract, exportProductBenchmark, exportProductBenchmarkRuns, exportRunAsOtlp, extractErrorCount, extractProducedState, extractUsage, extractUsageFromSse, failureBlame, failureClusterView, feedbackTrajectoriesToDatasetScenarios, feedbackTrajectoriesToOptimizerRows, feedbackTrajectoryToOptimizerRow, fileVerdictCache, formatScorecardDiff, gainHistogram, gateTreatmentApplied, gradeOnHidden, gradeSemanticStatus, groupRunsByAgentProfileCell, harnessAxisOf, hashContent, hashJson, hiddenGrade, holm, improvementVerdict, inMemoryReviewStore, inferDomainKeywords, interRaterReliability, interpretCliffs, iqr, isBinaryOutcomeVector, isJudgeSpan, isLlmSpan, isModelPriced, isPolicyEdit, isRunRecord, isToolSpan, isTransientLlmError, jsonShape, jsonlReviewStore, jsonlRunRecordBackend, judgeAgreementView, judgeFamily, judgeSpans, knowledgeReadinessTracePayload, leaderboard, lintTraceContractSpec, llmJudge, loadScorecard, localCommandRunner, makeFinding, makePolicyEdit, makePolicyEditCandidateRecord, makeProposalFinding, manifestContentDigest, mannWhitneyU, maximumChargeForLlmRequest, mcnemar, mcnemarPower, mcnemarRequiredN, minimumPairsForPairedDeltaTest, mintRolloutRows, modelHasSnapshot, modelPriceKey, mulberry32, notBlocked, objectiveEval, observeAll, otlpTextToTraceAnalysisStore, pairArms, pairRunRecords, pairedBinaryScale, pairedBootstrap, pairedCohensDz, pairedDeltaTest, pairedDeltaTieFraction, pairedEvalueSequence, pairedMde, pairedPromotionPower, pairedRiskDifference, pairedRiskDifferenceExact, pairedRiskDifferenceScore, pairedSignTest, pairedTTest, paretoChart, paretoFrontier, parseReflectionResponse, parseRunRecordSafe, partialCredit, partitionHeldOut, partitionTrainSelectionTest, passAtK, pearsonR, policyEditFromFinding, policyEditsFromFindings, preflightModels, productBenchmarkRepoIdentity, profile_exports as profile, projectRuntimeTrajectoryEvidence, proposeSynthesisTargets, quotaExhaustedUntil, ranks, readProductBenchmarkManifest, recordRuns, recordRunsToScorecard, redTeamDataset, redTeamReport, redact, redactForShare, redactText, regexMatches, renderPreferenceMemoryMarkdown, repeatedActionDetector, requiredPairedSampleSize, requiredPairsForPairedPromotion, requiredSampleSize, resolveModelPricing, resolveSeat, roundTripRunRecord, routeFields, runAgentControlLoop, runBoundedProcess, runCampaign, runCanaries, runCounterfactual, runEquivalenceCheck, runEvalCampaign, runIntentMatchJudge, runKeywordCoverageJudge, runKeywordCoverageJudgeUrl, runProposeReview, runProposeReviewAsControlLoop, runSemanticConceptJudge, runTaskScore, runsForScenario, scoreKnowledgeReadiness, scorePolicyEditReadiness, scoreRedTeamOutput, scoreTraceInsightReadiness, seatPresets, selfImprove, servedModelAcceptable, shareAllowed, spearmanR, stripFencedJson, subjectiveEval, summarizeBackendIntegrity, summarizeNumberSeries, summarizePreferenceMemory, summaryTable, textInSnapshot, toAgentProfileJson, tokenizeDomainWords, toolSpansToTraceAnalysisStore, toolWasteView, traceContract, transientDispatchFailure, urlContains, userQuestionsForKnowledgeGaps, validatePolicyEdit, validatePolicyEditCandidateRecord, validateRunRecord, verbosityBias, verifyAgentProfileCell, verifyAttestation, verifyCompletion, viteDeployRunner, weightedComposite, weightedMean, wilcoxonSignedRank, wilson, withAssignedFeedbackSplit, withHeldoutBlend, withJudgeRetry, wranglerDeployRunner };
 
 //# sourceMappingURL=index.js.map