@tangle-network/agent-eval 0.187.2 → 0.188.0

package/dist/diagnosis/index.d.ts

@@ -1,6 +1,8 @@
-import { n as ExecutionReport } from "../analyze-runs-DapYZz02.js";
-import { l as PrimeRawUsage } from "../prime-protocol-CDBcL9NM.js";
+import { o as FailureBlame, s as FailureClassification } from "../failure-cluster-CbgEDcFJ.js";
+import { n as ExecutionReport } from "../analyze-runs-CLz5O01x.js";
+import { l as PrimeRawUsage } from "../prime-protocol-CF8Z43Fj.js";
 import { i as nodeHttpPrimeBridgeTransport, n as PrimeBridgeTransportRequest, r as PrimeBridgeTransportResult, t as PrimeBridgeTransport } from "../prime-bridge-transport-6feEglLf.js";
+import { a as isContentAttribute, i as ingestSpans, n as IngestReport, r as epochMillis, t as DiagnosisSpan } from "../spans-W0o8pbEg.js";
 import { SpanKind, TraceValidation } from "@tangle-network/agent-trace-contract";
 //#region src/diagnosis/findings.d.ts
 /**
@@ -72,105 +74,43 @@ declare function validateDiagnosisFindings(document: unknown, options?: {
   spanIds?: ReadonlySet<string>;
 }): string[];
 //#endregion
-//#region src/diagnosis/secret-filter.d.ts
-/**
- * The secret filter every diagnosis input passes through before any model or
- * report reads it.
- *
- * Two layers:
- *   - `secret-assignment` is the line-anchored credential-assignment pattern
- *     trace-archive uses to keep plaintext-secret files out of the archive
- *     (`holds_secret` in tangle-tools trace-archive/archive.py). It is ported
- *     here verbatim so both the archive and the miner refuse the same lines.
- *     That pattern is line-anchored on purpose, so a secret quoted inside a
- *     JSON record or a prose line passes it;
- *   - the token-shape rules close that gap: they match the credential itself
- *     wherever it appears (`sk-`, `sk-ant-`, GitHub, Slack, AWS, Google, JWT,
- *     bearer headers, URL passwords, PEM blocks, and JSON `"...key": "..."`).
- *
- * A redacted value becomes `[REDACTED:<rule id>]`, so a report can state what
- * was removed by class without carrying any of it. The filter never throws on
- * input shape: non-string leaves pass through unchanged.
- */
-interface SecretRule {
-  id: string;
-  pattern: RegExp;
-  /** Rebuilds the match with the secret replaced; receives the regex groups. */
-  replace: (match: string, ...groups: string[]) => string;
-}
-interface SecretFilterReport {
-  redactionCount: number;
-  byRule: Record<string, number>;
-}
-/**
- * The trace-archive `SECRET_ASSIGNMENT` pattern (tangle-tools
- * trace-archive/archive.py), with the prefix captured so the key name survives
- * and only the value is replaced.
- */
-declare const SECRET_ASSIGNMENT_PATTERN: RegExp;
-declare const DIAGNOSIS_SECRET_RULES: readonly SecretRule[];
-/** Redact one string, adding the per-rule counts to `report`. */
-declare function redactSecrets(input: string, report?: SecretFilterReport, rules?: readonly SecretRule[]): string;
-/** Whether any rule matches: the miner's equivalent of trace-archive `holds_secret`. */
-declare function holdsSecret(input: string, rules?: readonly SecretRule[]): boolean;
-/** Redact every string leaf of a JSON-like value. Keys are kept; values are filtered. */
-declare function redactSecretsDeep(value: unknown, report: SecretFilterReport): unknown;
-//#endregion
-//#region src/diagnosis/spans.d.ts
-type DiagnosisSpanStatus = 'OK' | 'ERROR' | 'UNSET';
-interface DiagnosisSpan {
+//#region src/diagnosis/first-failure.d.ts
+/** Span ids listed beside a result; the count carries the rest. */
+declare const MAX_FIRST_FAILURE_IDS = 8;
+type FirstFailureStage = 'error-span' | 'failed-outcome';
+interface FirstFailureFound {
+  status: 'found';
   traceId: string;
+  stage: FirstFailureStage;
   spanId: string;
-  parentSpanId: string | null;
   name: string;
   kind: SpanKind;
-  startMs: number | null;
-  endMs: number | null;
-  status: DiagnosisSpanStatus;
-  statusMessage: string | null;
-  toolName: string | null;
-  model: string | null;
-  /**
-   * Keyed fingerprint of the tool call's input, taken before redaction so calls
-   * that differ only in secret material stay distinct. The key is random per
-   * ingest, so the fingerprint cannot be matched against a guessed payload or
-   * joined across diagnoses. Null when the span carries no input.
-   */
-  inputDigest: string | null;
-  attributes: Record<string, unknown>;
+  /** The span's status message after secret filtering; null when absent or withheld. */
+  message: string | null;
+  /** The taxonomy's reading of `message`; null for a failed outcome, which has none. */
+  classification: FailureClassification | null;
+  blame: FailureBlame;
+  /** Other candidates at the same stage, in rank order, capped at {@link MAX_FIRST_FAILURE_IDS}. */
+  later: string[];
+  laterCount: number;
 }
-interface IngestReport {
-  received: number;
-  accepted: number;
-  /** Lines without a trace id or span id, which no evidence could ever cite. */
-  unreadable: number;
-  /** Identical (trace id, span id) pairs seen again; the first occurrence is kept. */
-  duplicateSpans: number;
-  /** Span ids that occur in more than one trace, which evidence cannot cite unambiguously. */
-  ambiguousSpanIds: string[];
-  secrets: SecretFilterReport;
-  /** Attribute keys removed because content was not included. */
-  droppedAttributes: string[];
+interface FirstFailureAmbiguous {
+  status: 'ambiguous';
+  traceId: string;
+  stage: FirstFailureStage;
+  /** The candidates the rank could not order, capped at {@link MAX_FIRST_FAILURE_IDS}. */
+  candidates: string[];
+  candidateCount: number;
+  reason: string;
 }
-declare function isContentAttribute(key: string): boolean;
-/**
- * Filter secrets from every string, drop content attributes unless content is
- * included, and normalize each span. Order matters: the input fingerprint is
- * keyed and taken before redaction and the content drop, so repeated-call
- * detection works on metadata-only runs without the payload itself surviving.
- */
-declare function ingestSpans(raw: readonly unknown[], options: {
-  contentIncluded: boolean;
-}): {
-  spans: DiagnosisSpan[];
-  report: IngestReport;
-};
-/**
- * Epoch milliseconds from OTLP nanoseconds, epoch milliseconds, epoch seconds,
- * or ISO-8601. Digit strings are classified by length: 17 or more digits are
- * nanoseconds, 15-16 microseconds, 12-14 milliseconds, and fewer are seconds.
- */
-declare function epochMillis(value: unknown): number | null;
+interface FirstFailureNone {
+  status: 'none';
+  traceId: string;
+  reason: string;
+}
+type FirstFailure = FirstFailureFound | FirstFailureAmbiguous | FirstFailureNone;
+/** Rank the first failure of one trace. Throws when the spans belong to more than one trace. */
+declare function rankFirstFailure(spans: readonly DiagnosisSpan[]): FirstFailure;
 //#endregion
 //#region src/diagnosis/deterministic.d.ts
 interface ExecutionFacts {
@@ -180,6 +120,8 @@ interface ExecutionFacts {
   errorSpans: number;
   toolCalls: number;
   models: string[];
+  /** The first failure of each run, in trace id order. See `rankFirstFailure`. */
+  firstFailures: FirstFailure[];
   /** agent-eval execution summary; null with a reason when it could not be computed. */
   execution: ExecutionReport | null;
   executionError?: string;
@@ -315,5 +257,5 @@ interface DiagnosisResult {
 declare const DEFAULT_MAX_MODEL_TRACES = 6;
 declare function diagnoseSpans(spans: readonly unknown[], context: DiagnosisContext, options: DiagnosisOptions): Promise<DiagnosisResult>;
 //#endregion
-export { DEFAULT_MAX_MODEL_TRACES, DIAGNOSIS_FINDINGS_SCHEMA_ID, DIAGNOSIS_SECRET_RULES, type DiagnosisCapability, type DiagnosisConfidence, type DiagnosisContext, type DiagnosisFinding, type DiagnosisFindingsDocument, type DiagnosisMeasure, type DiagnosisModelOptions, type DiagnosisOptions, type DiagnosisRedaction, type DiagnosisResult, type DiagnosisSeverity, type DiagnosisSkippedAnalysis, type DiagnosisSpan, type DiagnosisUsage, type ExecutionFacts, type IngestReport, type ModelQuestion, type ModelRejection, type ModelRowNote, type ModelRunRecord, type PrimeBridgeTransport, type PrimeBridgeTransportRequest, type PrimeBridgeTransportResult, SECRET_ASSIGNMENT_PATTERN, type SecretFilterReport, type SecretRule, diagnoseSpans, epochMillis, holdsSecret, ingestSpans, isContentAttribute, nodeHttpPrimeBridgeTransport, redactSecrets, redactSecretsDeep, validateDiagnosisFindings };
+export { DEFAULT_MAX_MODEL_TRACES, DIAGNOSIS_FINDINGS_SCHEMA_ID, type DiagnosisCapability, type DiagnosisConfidence, type DiagnosisContext, type DiagnosisFinding, type DiagnosisFindingsDocument, type DiagnosisMeasure, type DiagnosisModelOptions, type DiagnosisOptions, type DiagnosisRedaction, type DiagnosisResult, type DiagnosisSeverity, type DiagnosisSkippedAnalysis, type DiagnosisSpan, type DiagnosisUsage, type ExecutionFacts, type FirstFailure, type FirstFailureAmbiguous, type FirstFailureFound, type FirstFailureNone, type FirstFailureStage, type IngestReport, MAX_FIRST_FAILURE_IDS, type ModelQuestion, type ModelRejection, type ModelRowNote, type ModelRunRecord, type PrimeBridgeTransport, type PrimeBridgeTransportRequest, type PrimeBridgeTransportResult, diagnoseSpans, epochMillis, ingestSpans, isContentAttribute, nodeHttpPrimeBridgeTransport, rankFirstFailure, validateDiagnosisFindings };
 //# sourceMappingURL=index.d.ts.map

package/dist/diagnosis/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/diagnosis/findings.ts","../../src/diagnosis/secret-filter.ts","../../src/diagnosis/spans.ts","../../src/diagnosis/deterministic.ts","../../src/diagnosis/model-pass.ts","../../src/diagnosis/engine.ts"],"mappings":";;;;;;;;;;;;;cASa;KAGD;;KAGA;UAEK;EACf;EACA;EACA;;EAEA;;UAGe;EACf;EACA,UAAU;EACV;EACA;EACA,UAAU;;EAEV;EACA;EACA,YAAY;EACZ;;UAGe;EACf;EACA;;UAGe;EACf;EACA;;UAGe;EACf;EACA,QAAQ;EACR;;UAGe;EACf;EACA;IACE;IACA;IACA;IACA;;EAEF;IACE,cAAc,eAAe;IAC7B,SAAS;IACT,YAAY;;EAEd,UAAU;;;;;;;;iBAiBI,0BACd,mBACA;EAAW,UAAU;;;;;;;;;;;;;;;;;;;;;;;UClEN;EACf;EACA,SAAS;;EAET,UAAU,kBAAkB;;UAGb;EACf;EACA,QAAQ;;;;;;;cAWG,2BAAyB;cAGzB,iCAAiC;;iBA8D9B,cACd,eACA,SAAQ,oBACR,iBAAgB;;iBAwBF,YACd,eACA,iBAAgB;;iBAWF,kBAAkB,gBAAgB,QAAQ;;;KC1H9C;UAEK;EACf;EACA;EACA;EACA;EACA,MAAM;EACN;EACA;EACA,QAAQ;EACR;EACA;EACA;;;;;;;EAOA;EACA,YAAY;;UAGG;EACf;EACA;;EAEA;;EAEA;;EAEA;EACA,SAAS;;EAET;;iBA0Bc,mBAAmB;;;;;;;iBAUnB,YACd,yBACA;EAAW;;EACR,OAAO;EAAiB,QAAQ;;;;;;;iBA+GrB,YAAY;;;UC3JX;EACf;EACA;EACA,aAAa;EACb;EACA;EACA;;EAEA,WAAW;EACX;;UAGe;EACf,YAAY;EACZ,cAAc,eAAe;EAC7B,SAAS;EACT,OAAO;EACP,UAAU;EACV;;;;UC/Ce;;EAEf,WAAW;;EAEX;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;IAAY;IAA4B;;;UAGzB;EACf;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;;UAGe;EACf;EACA;;UAGe;EACf;EACA;EACA;EACA;IAAa;IAAiB;IAAkB;;EAChD,OAAO;EACP;;;;UC/Be;;EAEf;;EAEA;;EAEA;;;;;EAKA;;EAEA;;EAEA;IAAa,MAAM;MAAQ;QAAe;MAA6B;;KAG7D;EACN;EAAuB;EAAiB,SAAS;;EACjD;EAAe,OAAO;EAAuB,SAAS;;UAE3C;EACf;EACA;EACA;EACA;;UAGe;;EAEf,UAAU;;EAEV,WAAW;;EAEX,OAAO;;EAEP,WAAW;IAAQ;IAAiB;;EACpC,OAAO;EACP,aAAa;EACb,QAAQ;;EAER,UAAU;EACV;IACE;IACA;IACA,MAAM;IACN;IACA,OAAO;;EAET;IAAU;IAA8B;;;cAG7B;iBAIS,cACpB,2BACA,SAAS,kBACT,SAAS,mBACR,QAAQ"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/diagnosis/findings.ts","../../src/diagnosis/first-failure.ts","../../src/diagnosis/deterministic.ts","../../src/diagnosis/model-pass.ts","../../src/diagnosis/engine.ts"],"mappings":";;;;;;;;;;;;;;;cASa;KAGD;;KAGA;UAEK;EACf;EACA;EACA;;EAEA;;UAGe;EACf;EACA,UAAU;EACV;EACA;EACA,UAAU;;EAEV;EACA;EACA,YAAY;EACZ;;UAGe;EACf;EACA;;UAGe;EACf;EACA;;UAGe;EACf;EACA,QAAQ;EACR;;UAGe;EACf;EACA;IACE;IACA;IACA;IACA;;EAEF;IACE,cAAc,eAAe;IAC7B,SAAS;IACT,YAAY;;EAEd,UAAU;;;;;;;;iBAiBI,0BACd,mBACA;EAAW,UAAU;;;;;cCnDV;KAID;UAEK;EACf;EACA;EACA,OAAO;EACP;EACA;EACA,MAAM;;EAEN;;EAEA,gBAAgB;EAChB,OAAO;;EAEP;EACA;;UAGe;EACf;EACA;EACA,OAAO;;EAEP;EACA;EACA;;UAGe;EACf;EACA;EACA;;KAGU,eAAe,oBAAoB,wBAAwB;;iBAGvD,iBAAiB,gBAAgB,kBAAkB;;;UCvBlD;EACf;EACA;EACA,aAAa;EACb;EACA;EACA;;EAEA,eAAe;;EAEf,WAAW;EACX;;UAGe;EACf,YAAY;EACZ,cAAc,eAAe;EAC7B,SAAS;EACT,OAAO;EACP,UAAU;EACV;;;;UClDe;;EAEf,WAAW;;EAEX;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;IAAY;IAA4B;;;UAGzB;EACf;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;;UAGe;EACf;EACA;;UAGe;EACf;EACA;EACA;EACA;IAAa;IAAiB;IAAkB;;EAChD,OAAO;EACP;;;;UC/Be;;EAEf;;EAEA;;EAEA;;;;;EAKA;;EAEA;;EAEA;IAAa,MAAM;MAAQ;QAAe;MAA6B;;KAG7D;EACN;EAAuB;EAAiB,SAAS;;EACjD;EAAe,OAAO;EAAuB,SAAS;;UAE3C;EACf;EACA;EACA;EACA;;UAGe;;EAEf,UAAU;;EAEV,WAAW;;EAEX,OAAO;;EAEP,WAAW;IAAQ;IAAiB;;EACpC,OAAO;EACP,aAAa;EACb,QAAQ;;EAER,UAAU;EACV;IACE;IACA;IACA,MAAM;IACN;IACA,OAAO;;EAET;IAAU;IAA8B;;;cAG7B;iBAIS,cACpB,2BACA,SAAS,kBACT,SAAS,mBACR,QAAQ"}

package/dist/diagnosis/index.js

@@ -1,137 +1,88 @@
 import { n as summarizeExecution } from "../analyze-runs-DCY7LMt4.js";
+import { c as emptyRedactionReport, f as redactText, u as redact } from "../redact-DxwlUAvh.js";
 import { t as packageVersion } from "../package-version-D7lQHt_-.js";
+import { o as classifyFailureReason } from "../failure-taxonomy-CjabTATj.js";
 import { c as primeProtocolSha256, d as runPrimeExchange, n as buildPrimePrompt } from "../prime-protocol-DcAK9pC8.js";
 import { t as nodeHttpPrimeBridgeTransport } from "../prime-bridge-transport-Z3cpKGoV.js";
 import { t as fromOtelSpans } from "../otel-spans-CQY1pNiN.js";
 import { createHash, createHmac, randomBytes } from "node:crypto";
 import { MODEL_ATTR_KEYS, SPAN_KINDS, TOOL_NAME_ATTR_KEYS, resolveSpanKind, validateTraceSpans } from "@tangle-network/agent-trace-contract";
-//#region src/diagnosis/secret-filter.ts
-const marker = (id) => `[REDACTED:${id}]`;
-const whole = (id) => () => marker(id);
-/**
-* The trace-archive `SECRET_ASSIGNMENT` pattern (tangle-tools
-* trace-archive/archive.py), with the prefix captured so the key name survives
-* and only the value is replaced.
-*/
-const SECRET_ASSIGNMENT_PATTERN = /^([ \t]*(?:export[ \t]+)?["']?(?:[A-Za-z_][A-Za-z0-9_.-]*)?(?:key|token|secret|password|passwd|passphrase|credentials?)[A-Za-z0-9_]*["']?[ \t]*[=:][ \t]*["']?)(?!encrypted:)(?![$`])(?=[^\s"'#,]*[0-9])(?=[^\s"'#,]*[A-Za-z])[^\s"'#,]{16,}(["']?[ \t]*,?[ \t]*(?:#.*)?\r?)$/gim;
-const DIAGNOSIS_SECRET_RULES = [
-	{
-		id: "pem-block",
-		pattern: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g,
-		replace: whole("pem-block")
-	},
-	{
-		id: "secret-assignment",
-		pattern: SECRET_ASSIGNMENT_PATTERN,
-		replace: (_match, prefix, suffix) => `${prefix}${marker("secret-assignment")}${suffix}`
-	},
-	{
-		id: "json-secret",
-		pattern: /("[A-Za-z0-9_.-]*(?:key|token|secret|password|passwd|passphrase|credentials?)[A-Za-z0-9_]*"[ \t]*:[ \t]*")(?!encrypted:)(?![$`])(?=[^"\s]*[0-9])(?=[^"\s]*[A-Za-z])[^"\s]{16,}(")/gi,
-		replace: (_match, prefix, suffix) => `${prefix}${marker("json-secret")}${suffix}`
-	},
-	{
-		id: "inline-assignment",
-		pattern: /\b([A-Za-z0-9_.-]*(?:key|token|secret|password|passwd|passphrase|credentials?)[A-Za-z0-9_]*["']?[ \t]*[=:][ \t]*["']?)(?!encrypted:)(?![$`[])(?=[^\s"'#,&;]*[0-9])(?=[^\s"'#,&;]*[A-Za-z])[^\s"'#,&;]{16,}/gi,
-		replace: (_match, prefix) => `${prefix}${marker("inline-assignment")}`
-	},
-	{
-		id: "anthropic-key",
-		pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/g,
-		replace: whole("anthropic-key")
-	},
-	{
-		id: "openai-key",
-		pattern: /\bsk-[A-Za-z0-9_-]{20,}/g,
-		replace: whole("openai-key")
-	},
-	{
-		id: "github-token",
-		pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,})/g,
-		replace: whole("github-token")
-	},
-	{
-		id: "slack-token",
-		pattern: /\bxox[abeoprs]-[A-Za-z0-9-]{10,}/g,
-		replace: whole("slack-token")
-	},
-	{
-		id: "aws-access-key",
-		pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
-		replace: whole("aws-access-key")
-	},
-	{
-		id: "google-api-key",
-		pattern: /\bAIza[0-9A-Za-z_-]{35}/g,
-		replace: whole("google-api-key")
-	},
-	{
-		id: "jwt",
-		pattern: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
-		replace: whole("jwt")
-	},
-	{
-		id: "bearer",
-		pattern: /\b(Bearer)[ \t]+[A-Za-z0-9._~+/=-]{16,}/gi,
-		replace: (_match, word) => `${word} ${marker("bearer")}`
-	},
-	{
-		id: "url-credentials",
-		pattern: /\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)[^\s@/]+@/gi,
-		replace: (_match, prefix) => `${prefix}${marker("url-credentials")}@`
+//#region src/diagnosis/first-failure.ts
+/** Span ids listed beside a result; the count carries the rest. */
+const MAX_FIRST_FAILURE_IDS = 8;
+const OUTCOME_ATTR = "agent.outcome";
+/** Rank the first failure of one trace. Throws when the spans belong to more than one trace. */
+function rankFirstFailure(spans) {
+	const traceId = spans[0]?.traceId;
+	if (traceId === void 0) throw new TypeError("rankFirstFailure: no spans");
+	if (spans.some((span) => span.traceId !== traceId)) throw new TypeError("rankFirstFailure: spans belong to more than one trace");
+	const errors = spans.filter(isErrorSpan);
+	if (errors.length > 0) {
+		const innermost = withoutFailingDescendants(spans, errors);
+		if (innermost.length === 0) return ambiguous(traceId, "error-span", errors, "every failing span contains another failing span, so containment is cyclic");
+		return rank(traceId, "error-span", innermost);
 	}
-];
-/** Redact one string, adding the per-rule counts to `report`. */
-function redactSecrets(input, report = emptySecretFilterReport(), rules = DIAGNOSIS_SECRET_RULES) {
-	let output = input;
-	for (const rule of rules) {
-		let hits = 0;
-		rule.pattern.lastIndex = 0;
-		output = output.replace(rule.pattern, (match, ...rest) => {
-			hits += 1;
-			const captured = rest.slice(0, countGroups(rule.pattern)).map((value) => typeof value === "string" ? value : "");
-			return rule.replace(match, ...captured);
-		});
-		if (hits > 0) {
-			report.redactionCount += hits;
-			report.byRule[rule.id] = (report.byRule[rule.id] ?? 0) + hits;
-		}
-	}
-	return output;
+	const failed = spans.filter((span) => span.attributes[OUTCOME_ATTR] === "fail");
+	if (failed.length > 0) return rank(traceId, "failed-outcome", failed);
+	return {
+		status: "none",
+		traceId,
+		reason: `none of ${spans.length} spans has status ERROR or an agent.outcome of error or fail`
+	};
 }
-/** Whether any rule matches: the miner's equivalent of trace-archive `holds_secret`. */
-function holdsSecret(input, rules = DIAGNOSIS_SECRET_RULES) {
-	return rules.some((rule) => {
-		rule.pattern.lastIndex = 0;
-		const found = rule.pattern.test(input);
-		rule.pattern.lastIndex = 0;
-		return found;
-	});
+function isErrorSpan(span) {
+	return span.status === "ERROR" || span.attributes[OUTCOME_ATTR] === "error";
 }
-/** Redact every string leaf of a JSON-like value. Keys are kept; values are filtered. */
-function redactSecretsDeep(value, report) {
-	if (typeof value === "string") return redactSecrets(value, report);
-	if (Array.isArray(value)) return value.map((item) => redactSecretsDeep(item, report));
-	if (value !== null && typeof value === "object") {
-		const next = {};
-		for (const [key, item] of Object.entries(value)) next[key] = redactSecretsDeep(item, report);
-		return next;
+/** The failing spans with no failing span beneath them. */
+function withoutFailingDescendants(spans, failing) {
+	const parentOf = new Map(spans.map((span) => [span.spanId, span.parentSpanId]));
+	const explained = /* @__PURE__ */ new Set();
+	for (const span of failing) {
+		const seen = /* @__PURE__ */ new Set([span.spanId]);
+		let parent = span.parentSpanId;
+		while (parent !== null && parentOf.has(parent) && !seen.has(parent)) {
+			explained.add(parent);
+			seen.add(parent);
+			parent = parentOf.get(parent) ?? null;
+		}
 	}
-	return value;
+	return failing.filter((span) => !explained.has(span.spanId));
 }
-function emptySecretFilterReport() {
+function rank(traceId, stage, candidates) {
+	if (candidates.length > 1) {
+		const untimed = candidates.filter((span) => span.endMs === null);
+		if (untimed.length > 0) return ambiguous(traceId, stage, candidates, `${untimed.length} of ${candidates.length} candidates have no end time, so their order is unknown`);
+	}
+	const ordered = [...candidates].sort((a, b) => (a.endMs ?? 0) - (b.endMs ?? 0) || a.spanId.localeCompare(b.spanId));
+	const first = ordered[0];
+	const tied = ordered.filter((span) => span.endMs === first.endMs);
+	if (tied.length > 1) return ambiguous(traceId, stage, tied, `${tied.length} candidates ended at the same instant, so none ranks first`);
+	const classification = stage === "error-span" ? classifyFailureReason(first.statusMessage) : null;
+	const later = ordered.slice(1);
 	return {
-		redactionCount: 0,
-		byRule: {}
+		status: "found",
+		traceId,
+		stage,
+		spanId: first.spanId,
+		name: first.name,
+		kind: first.kind,
+		message: first.statusMessage,
+		classification,
+		blame: classification?.blame ?? "agent",
+		later: later.slice(0, 8).map((span) => span.spanId),
+		laterCount: later.length
 	};
 }
-const groupCounts = /* @__PURE__ */ new WeakMap();
-function countGroups(pattern) {
-	const cached = groupCounts.get(pattern);
-	if (cached !== void 0) return cached;
-	const count = (new RegExp(`${pattern.source}|`).exec("")?.length ?? 1) - 1;
-	groupCounts.set(pattern, count);
-	return count;
+function ambiguous(traceId, stage, candidates, reason) {
+	const ids = candidates.map((span) => span.spanId).sort();
+	return {
+		status: "ambiguous",
+		traceId,
+		stage,
+		candidates: ids.slice(0, 8),
+		candidateCount: ids.length,
+		reason
+	};
 }
 //#endregion
 //#region src/diagnosis/spans.ts
@@ -175,10 +126,7 @@ function isContentAttribute(key) {
 * detection works on metadata-only runs without the payload itself surviving.
 */
 function ingestSpans(raw, options) {
-	const secrets = {
-		redactionCount: 0,
-		byRule: {}
-	};
+	const secrets = emptyRedactionReport();
 	const dropped = /* @__PURE__ */ new Set();
 	const seen = /* @__PURE__ */ new Set();
 	const spans = [];
@@ -210,7 +158,7 @@ function ingestSpans(raw, options) {
 		else if (firstTrace !== traceId) ambiguous.add(spanId);
 		const merged = mergedAttributes(record);
 		const inputDigest = digestInput(merged, digestKey);
-		const attributes = redactSecretsDeep(merged, secrets);
+		const attributes = redact(merged, { report: secrets }).value;
 		if (!options.contentIncluded) {
 			for (const [key, value] of Object.entries(attributes)) if (isContentAttribute(key) || value !== null && typeof value === "object") {
 				delete attributes[key];
@@ -218,10 +166,10 @@ function ingestSpans(raw, options) {
 			}
 		}
 		const status = readStatus(record);
-		const statusMessage = status.message === null ? null : redactSecrets(status.message, secrets);
+		const statusMessage = status.message === null ? null : redactText(status.message, { report: secrets });
 		const toolName = firstString(attributes, TOOL_NAME_ATTR_KEYS);
 		const model = firstString(attributes, MODEL_ATTR_KEYS);
-		const name = redactSecrets(stringOr(record.name, "unknown"), secrets);
+		const name = redactText(stringOr(record.name, "unknown"), { report: secrets });
 		spans.push({
 			traceId,
 			spanId,
@@ -413,7 +361,7 @@ function runDeterministicPass(spans) {
 		validation,
 		capabilities,
 		skipped,
-		facts: executionFacts(spans, traces.size),
+		facts: executionFacts(spans, traces),
 		findings,
 		window: timeWindow(spans)
 	};
@@ -524,7 +472,7 @@ function failedRunFindings(traces) {
 		recommendation: "Group the failed runs by their root status message and fix the largest group first."
 	}];
 }
-function executionFacts(spans, runs) {
+function executionFacts(spans, traces) {
 	const spansByKind = {};
 	const models = /* @__PURE__ */ new Set();
 	let errorSpans = 0;
@@ -536,12 +484,13 @@ function executionFacts(spans, runs) {
 		if (span.model) models.add(span.model);
 	}
 	const facts = {
-		runs,
+		runs: traces.size,
 		spans: spans.length,
 		spansByKind,
 		errorSpans,
 		toolCalls,
 		models: [...models].sort(),
+		firstFailures: [...traces.keys()].sort().map((traceId) => rankFirstFailure(traces.get(traceId))),
 		execution: null
 	};
 	try {
@@ -1169,7 +1118,7 @@ async function diagnoseSpans(spans, context, options) {
 	if (context.subject === "customer" && context.topology !== void 0) throw new TypeError("diagnoseSpans: topology analysis is internal only; a customer context must not carry one");
 	const contentIncluded = context.contentIncluded === true;
 	const { spans: filtered, report: ingest } = ingestSpans(spans, { contentIncluded });
-	const focus = context.focus === void 0 ? void 0 : redactSecrets(context.focus, ingest.secrets);
+	const focus = context.focus === void 0 ? void 0 : redactText(context.focus, { report: ingest.secrets });
 	const deterministic = runDeterministicPass(filtered);
 	const skipped = [...deterministic.skipped];
 	const ambiguous = new Set(ingest.ambiguousSpanIds);
@@ -1224,7 +1173,7 @@ async function diagnoseSpans(spans, context, options) {
 			reason: run.failure ?? "failed"
 		});
 		if (context.subject === "internal" && context.topology) {
-			const topology = redactSecretsDeep(context.topology, ingest.secrets);
+			const topology = redact(context.topology, { report: ingest.secrets }).value;
 			const reading = await runTopologyPass(topology, new Set((topology.runs ?? []).map((run) => run.id).filter((id) => typeof id === "string")), options.model, options.signal);
 			notes.push(...reading.notes);
 			questions.push(...reading.questions);
@@ -1241,7 +1190,7 @@ async function diagnoseSpans(spans, context, options) {
 	const document = {
 		schemaVersion: 1,
 		subject: {
-			label: redactSecrets(context.label, ingest.secrets),
+			label: redactText(context.label, { report: ingest.secrets }),
 			runCount: traces.size,
 			window: deterministic.window,
 			contentIncluded
@@ -1251,7 +1200,7 @@ async function diagnoseSpans(spans, context, options) {
 			skipped,
 			redaction: {
 				redactionCount: ingest.secrets.redactionCount,
-				byRule: { ...ingest.secrets.byRule },
+				byRule: { ...ingest.secrets.byDetector },
 				droppedAttributes: ingest.droppedAttributes
 			}
 		},
@@ -1328,6 +1277,6 @@ function totalUsage(runs, pricing) {
 	};
 }
 //#endregion
-export { DEFAULT_MAX_MODEL_TRACES, DIAGNOSIS_FINDINGS_SCHEMA_ID, DIAGNOSIS_SECRET_RULES, SECRET_ASSIGNMENT_PATTERN, diagnoseSpans, epochMillis, holdsSecret, ingestSpans, isContentAttribute, nodeHttpPrimeBridgeTransport, redactSecrets, redactSecretsDeep, validateDiagnosisFindings };
+export { DEFAULT_MAX_MODEL_TRACES, DIAGNOSIS_FINDINGS_SCHEMA_ID, MAX_FIRST_FAILURE_IDS, diagnoseSpans, epochMillis, ingestSpans, isContentAttribute, nodeHttpPrimeBridgeTransport, rankFirstFailure, validateDiagnosisFindings };
 
 //# sourceMappingURL=index.js.map