@tangle-network/agent-eval 0.138.0 → 0.139.0

package/dist/kind-factory-CFxA0JQX.js

@@ -0,0 +1,2133 @@
+import { a as LimitExceededError, c as ValidationError, n as CaptureIntegrityError, o as NotFoundError, t as AgentEvalError } from "./errors-D-LKuDhb.js";
+import { i as CostLedger } from "./cost-ledger-CZ9diLxY.js";
+import { INPUT_VALUE, LLM_MODEL_ATTR_KEYS, OUTPUT_VALUE, SPAN_KIND_ATTR_KEYS, TOOL_ARGS_CAPTURED, TOOL_LATENCY_MS, TOOL_NAME, TOOL_NAME_ATTR_KEYS } from "./trace-attributes.js";
+import { i as validateUsageSettlementTimeout, n as settleUsageReceiptFromCostLedger, o as makeFinding } from "./usage-receipt-CgxMEBZq.js";
+import { i as hashCanonical, r as canonicalString } from "./canonical-D011XM8r.js";
+import { z } from "zod";
+import { RE2JS } from "re2js";
+//#region src/trace/otlp-attributes.ts
+/** Canonical OpenInference-over-OTLP attribute vocabulary used at the trace boundary. */
+const TOOL_SPAN_ATTRIBUTE_KEYS = [
+	TOOL_NAME,
+	TOOL_ARGS_CAPTURED,
+	TOOL_LATENCY_MS,
+	INPUT_VALUE,
+	OUTPUT_VALUE
+];
+const EXPLICIT_SPAN_ROLES = /* @__PURE__ */ new Set([
+	"AGENT",
+	"CHAIN",
+	"EVALUATOR",
+	"GUARDRAIL",
+	"LLM",
+	"SPAN",
+	"TOOL"
+]);
+/**
+* Classify a span once for both measurement and error accounting.
+* An explicit OpenInference kind wins; untyped spans use the same tool and
+* model signals in online and offline intake.
+*/
+function classifyOtlpSpanRole(input) {
+	const explicitKind = input.kind ?? firstStringAttribute(input.attributes, SPAN_KIND_ATTR_KEYS);
+	if (explicitKind) {
+		const normalized = explicitKind.toUpperCase();
+		if (EXPLICIT_SPAN_ROLES.has(normalized)) return normalized;
+	}
+	if (firstStringAttribute(input.attributes, TOOL_NAME_ATTR_KEYS) !== void 0 || /^(?:function|tool)[.:/]/i.test(input.name)) return "TOOL";
+	const spanType = input.attributes["span.type"];
+	if (typeof spanType === "string" && spanType.toLowerCase() === "llm_request" || /(?:^|[.:/_-])(?:chat[._-]?completions?|llm)(?:$|[.:/_-])/i.test(input.name) || firstStringAttribute(input.attributes, LLM_MODEL_ATTR_KEYS) !== void 0 || typeof input.attributes["gen_ai.operation.name"] === "string") return "LLM";
+	return "UNKNOWN";
+}
+function isOtlpModelCall(input) {
+	return classifyOtlpSpanRole(input) === "LLM";
+}
+function toolSpanOtlpAttributes(span) {
+	const argsCaptured = span.argsCaptured !== false;
+	const attributes = {
+		[TOOL_NAME]: span.toolName,
+		[TOOL_ARGS_CAPTURED]: argsCaptured
+	};
+	if (span.latencyMs !== void 0) attributes[TOOL_LATENCY_MS] = span.latencyMs;
+	if (argsCaptured) attributes[INPUT_VALUE] = stringifyTraceValue(span.args);
+	if (span.result !== void 0) attributes[OUTPUT_VALUE] = stringifyTraceValue(span.result);
+	return attributes;
+}
+function applyToolSpanOtlpAttributes(attributes, span) {
+	for (const key of TOOL_SPAN_ATTRIBUTE_KEYS) delete attributes[key];
+	Object.assign(attributes, toolSpanOtlpAttributes(span));
+}
+function traceSpanKindToOpenInferenceKind(kind) {
+	switch (kind) {
+		case "llm": return "LLM";
+		case "tool": return "TOOL";
+		case "retrieval": return "CHAIN";
+		case "judge": return "EVALUATOR";
+		case "sandbox": return "CHAIN";
+		case "agent": return "AGENT";
+		default: return "SPAN";
+	}
+}
+function firstStringAttribute(attributes, keys) {
+	for (const key of keys) {
+		const value = attributes[key];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+}
+function stringifyTraceValue(value) {
+	if (value === void 0) return "null";
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+//#region src/trace-analyst/otlp-span.ts
+/**
+* Canonical OTLP-flat-line readers shared by every consumer of the
+* OTLP-JSONL wire shape (one OTLP span per line; the form
+* `flattenOtlpExportToNdjson` produces and the form AppWorld / HALO
+* emit via their OpenInference OTLP exporter).
+*
+* `OtlpFileTraceStore` indexes spans with these; `otlpToRunRecords`
+* aggregates spans into `RunRecord`s with the same readers. One parser,
+* one vocabulary — a divergence between the analyst's view of a trace and
+* the RunRecord projected from it is a class of bug this consolidation
+* removes by construction.
+*
+* Vocabulary. The readers understand BOTH dialects that appear in the
+* wild:
+*   - the substrate's own `llm.*` / `tool.*` / `span.kind` attributes
+*     (`flattenSpanAttributes` in `trace/otel.ts`), and
+*   - the OpenInference / inference-export attributes AppWorld / HALO
+*     emit (`openinference.span.kind`, `inference.observation_kind`,
+*     `inference.llm.input_tokens`, `llm.token_count.prompt`, …).
+*
+* Pure, no I/O.
+*/
+/**
+* Project one parsed OTLP-JSONL object to `ProjectedOtlpSpan`, or `null`
+* when the line is missing the mandatory `trace_id` + `span_id`.
+*/
+function projectOtlpFlatLine(raw) {
+	const trace_id = stringField(raw, "trace_id") ?? stringField(raw, "traceId");
+	const span_id = stringField(raw, "span_id") ?? stringField(raw, "spanId");
+	if (!trace_id || !span_id) return null;
+	const parent_id = normalizeParentSpanId(trace_id, span_id, stringField(raw, "parent_span_id") ?? stringField(raw, "parentSpanId") ?? null);
+	const name = stringField(raw, "name") ?? "unknown";
+	const start_time = stringField(raw, "start_time") ?? stringField(raw, "startTime") ?? "";
+	const end_time = stringField(raw, "end_time") ?? stringField(raw, "endTime") ?? start_time;
+	const status = readOtlpStatus(raw);
+	const attributes = extractOtlpAttributes(raw);
+	const service_name = asString(attributes["service.name"]) ?? asString(attributes["resource.attributes.service.name"]) ?? null;
+	const agent_name = asString(attributes["agent.name"]) ?? asString(attributes["inference.agent.name"]) ?? asString(attributes["inference.agent_name"]) ?? null;
+	const model_name = firstStringAttr(attributes, LLM_MODEL_ATTR_KEYS);
+	const tool_name = firstStringAttr(attributes, TOOL_NAME_ATTR_KEYS);
+	const kind = inferOtlpKind(attributes);
+	let duration_ms = 0;
+	if (start_time && end_time) {
+		const a = spanEpochMillis(start_time);
+		const b = spanEpochMillis(end_time);
+		if (a !== null && b !== null) duration_ms = Math.max(0, b - a);
+	}
+	return {
+		trace_id,
+		span_id,
+		parent_span_id: parent_id && parent_id.length > 0 ? parent_id : null,
+		name,
+		kind,
+		start_time,
+		end_time,
+		duration_ms,
+		status: status.code,
+		status_message: status.message,
+		service_name,
+		agent_name,
+		model_name,
+		tool_name,
+		attributes
+	};
+}
+function normalizeParentSpanId(traceId, spanId, parentId) {
+	if (!parentId) return null;
+	const prefix = `${traceId}:`;
+	return spanId.startsWith(prefix) && !parentId.startsWith(prefix) ? `${prefix}${parentId}` : parentId;
+}
+function readOtlpStatus(raw) {
+	const status = raw.status;
+	if (status && typeof status === "object" && !Array.isArray(status)) {
+		const codeRaw = status.code;
+		const code = codeRaw === "STATUS_CODE_OK" || codeRaw === "OK" ? "OK" : codeRaw === "STATUS_CODE_ERROR" || codeRaw === "ERROR" ? "ERROR" : "UNSET";
+		const messageRaw = status.message;
+		return {
+			code,
+			message: typeof messageRaw === "string" && messageRaw.length > 0 ? messageRaw : void 0
+		};
+	}
+	return {
+		code: "UNSET",
+		message: void 0
+	};
+}
+function inferOtlpKind(attrs) {
+	const opik = firstStringAttr(attrs, SPAN_KIND_ATTR_KEYS);
+	if (opik) {
+		const upper = opik.toUpperCase();
+		if (upper === "AGENT" || upper === "LLM" || upper === "TOOL" || upper === "CHAIN" || upper === "EVALUATOR" || upper === "GUARDRAIL" || upper === "SPAN") return upper;
+	}
+	return "UNKNOWN";
+}
+/**
+* Flatten OTLP `attributes` + `resource.attributes` into a single
+* dotted-key map. Span attributes override resource attributes when keys
+* overlap. Nested objects/arrays are preserved as-is.
+*/
+function extractOtlpAttributes(raw) {
+	const out = {};
+	const resource = raw.resource;
+	if (resource && typeof resource === "object" && !Array.isArray(resource)) {
+		const ra = resource.attributes;
+		if (ra && typeof ra === "object" && !Array.isArray(ra)) for (const [k, v] of Object.entries(ra)) out[k] = v;
+	}
+	const spanAttrs = raw.attributes;
+	if (spanAttrs && typeof spanAttrs === "object" && !Array.isArray(spanAttrs)) for (const [k, v] of Object.entries(spanAttrs)) out[k] = v;
+	return out;
+}
+function stringField(raw, key) {
+	const v = raw[key];
+	return typeof v === "string" ? v : void 0;
+}
+function asString(v) {
+	return typeof v === "string" && v.length > 0 ? v : null;
+}
+/** First non-empty string value across a list of candidate attribute keys. */
+function firstStringAttr(attrs, keys) {
+	for (const k of keys) {
+		const s = asString(attrs[k]);
+		if (s !== null) return s;
+	}
+	return null;
+}
+/**
+* Parse a span timestamp to epoch millis, or null when empty/unparseable. The
+* OTLP readers accept BOTH ISO-8601 and epoch-millis-string dialects, so raw
+* string comparison (`<`, `localeCompare`) mis-orders across dialects and
+* `Date.parse` returns NaN for a bare epoch-millis string.
+*/
+function spanEpochMillis(ts) {
+	if (!ts) return null;
+	if (/^\d+$/.test(ts)) return Number(ts);
+	const n = Date.parse(ts);
+	return Number.isNaN(n) ? null : n;
+}
+/**
+* Order comparator for span timestamps across mixed ISO/epoch dialects.
+* Unparseable timestamps sort as epoch 0 (earliest), never NaN (which would
+* make the sort non-deterministic).
+*/
+function compareSpanTime(a, b) {
+	return (spanEpochMillis(a) ?? 0) - (spanEpochMillis(b) ?? 0);
+}
+//#endregion
+//#region src/analyst/engine.ts
+const DEFAULT_TRACE_ANALYST_LIMITS = {
+	maxIterations: 12,
+	maxLlmCalls: 8,
+	maxToolCalls: 48,
+	maxOutputChars: 1e4
+};
+function resolveTraceAnalystLimits(limits) {
+	const resolved = {
+		...DEFAULT_TRACE_ANALYST_LIMITS,
+		...limits
+	};
+	for (const [name, value] of Object.entries(resolved)) if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`trace analyst ${name} must be a positive safe integer`);
+	return resolved;
+}
+//#endregion
+//#region src/ledger-core/deep-freeze.ts
+/** Freeze a detached canonical-JSON graph. Canonicalization has already ruled out cycles.
+*
+* Lives outside canonical.ts so the analyst-benchmark implementation digest,
+* which covers canonical.ts, stays bound to the published benchmark evidence. */
+function deepFreezeCanonicalJson(value) {
+	if (value && typeof value === "object" && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const nested of Object.values(value)) deepFreezeCanonicalJson(nested);
+	}
+	return value;
+}
+//#endregion
+//#region src/analyst/exact-types.ts
+/** Canonical identity for any live component admitted to an exact run. */
+function snapshotExactExecutionComponentIdentity(value, context) {
+	let detached;
+	try {
+		detached = JSON.parse(canonicalString(value));
+	} catch (cause) {
+		throw new TypeError(`${context} must have a canonical JSON representation`, { cause });
+	}
+	const parsed = componentIdentitySchema.safeParse(detached);
+	if (!parsed.success) throw new TypeError(`${context} requires non-empty id/version and object config`);
+	return deepFreezeCanonicalJson({
+		id: parsed.data.id,
+		version: parsed.data.version,
+		config_digest: hashCanonical(parsed.data.config)
+	});
+}
+const nonEmptyString = z.string().min(1);
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const finiteNonnegative = z.number().finite().nonnegative();
+const nonnegativeSafeInteger = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const positiveTimeout = z.number().int().positive().max(2147483647);
+const componentSnapshotSchema = z.strictObject({
+	id: nonEmptyString,
+	version: nonEmptyString,
+	config_digest: digest
+});
+const componentIdentitySchema = z.strictObject({
+	id: nonEmptyString,
+	version: nonEmptyString,
+	config: z.record(z.string(), z.unknown())
+});
+const deterministicCostSchema = z.strictObject({
+	kind: z.literal("deterministic"),
+	est_usd_per_run: finiteNonnegative.optional(),
+	models: z.array(nonEmptyString).optional()
+});
+const llmCostSchema = z.strictObject({
+	kind: z.literal("llm"),
+	est_usd_per_run: finiteNonnegative.optional(),
+	models: z.array(nonEmptyString).optional(),
+	settlement_timeout_ms: nonnegativeSafeInteger.optional()
+});
+const requirementsSchema = z.strictObject({
+	min_shots: nonnegativeSafeInteger.optional(),
+	capabilities: z.array(nonEmptyString).optional()
+}).nullable();
+const analystSnapshotSchema = z.strictObject({
+	id: nonEmptyString,
+	version: nonEmptyString,
+	input_kind: z.enum([
+		"trace-store",
+		"artifact-dir",
+		"run-record",
+		"judge-input",
+		"custom"
+	]),
+	cost: z.discriminatedUnion("kind", [deterministicCostSchema, llmCostSchema]),
+	requirements: requirementsSchema,
+	execution_config_digest: digest
+});
+const allocationsSchema = z.record(nonEmptyString, z.union([finiteNonnegative, z.null()]));
+const weightsSchema = z.record(nonEmptyString, finiteNonnegative);
+const budgetSnapshotSchema = z.discriminatedUnion("kind", [
+	z.strictObject({ kind: z.literal("none") }),
+	z.strictObject({
+		kind: z.literal("equal"),
+		total_usd: finiteNonnegative,
+		allocations_usd: allocationsSchema
+	}),
+	z.strictObject({
+		kind: z.literal("weighted"),
+		total_usd: finiteNonnegative,
+		weights: weightsSchema,
+		allocations_usd: allocationsSchema
+	})
+]);
+const priorFindingsSchema = z.discriminatedUnion("kind", [
+	z.strictObject({ kind: z.literal("none") }),
+	z.strictObject({
+		kind: z.literal("ordered"),
+		count: nonnegativeSafeInteger,
+		digest
+	}),
+	z.strictObject({
+		kind: z.literal("by_analyst"),
+		keys: z.array(nonEmptyString),
+		count: nonnegativeSafeInteger,
+		digest
+	})
+]);
+const exactRunPolicySchema = z.strictObject({
+	budget: budgetSnapshotSchema,
+	total_timeout_ms: positiveTimeout.nullable(),
+	signal_provided: z.boolean(),
+	cost_ledger: componentSnapshotSchema.nullable(),
+	cost_phase: nonEmptyString.nullable(),
+	tags: z.record(z.string(), z.string()).nullable(),
+	prior_findings: priorFindingsSchema,
+	chain_findings: z.boolean(),
+	missing_input_mode: z.enum(["skip", "abort"]),
+	registry_hooks: componentSnapshotSchema.nullable(),
+	registry_chat: componentSnapshotSchema.nullable()
+});
+const exactExecutionPlanSchema = z.strictObject({
+	schema_version: z.literal("1.0.0"),
+	analysts: z.array(analystSnapshotSchema).min(1),
+	policy: exactRunPolicySchema,
+	digest
+}).superRefine((plan, context) => {
+	const issue = (path, message) => context.addIssue({
+		code: "custom",
+		path,
+		message
+	});
+	const analystIds = plan.analysts.map((analyst) => analyst.id);
+	if (new Set(analystIds).size !== analystIds.length) issue(["analysts"], "analyst ids must be unique");
+	if (plan.policy.cost_ledger === null && plan.policy.cost_phase !== null) issue(["policy", "cost_phase"], "cost phase requires a cost ledger");
+	if (plan.policy.prior_findings.kind === "by_analyst" && plan.policy.prior_findings.keys.some((key, index, keys) => index > 0 && key <= keys[index - 1])) issue([
+		"policy",
+		"prior_findings",
+		"keys"
+	], "keys must be sorted and unique");
+	const budget = plan.policy.budget;
+	if (budget.kind === "none") return;
+	const allocationIds = Object.keys(budget.allocations_usd).sort();
+	const selectedIds = [...analystIds].sort();
+	if (allocationIds.length !== selectedIds.length || allocationIds.some((id, index) => id !== selectedIds[index])) {
+		issue([
+			"policy",
+			"budget",
+			"allocations_usd"
+		], "allocations must name every analyst and no others");
+		return;
+	}
+	const runnableIds = analystIds.filter((id) => budget.allocations_usd[id] !== null);
+	const epsilon = Math.max(1, budget.total_usd) * Number.EPSILON * 8;
+	if (runnableIds.length === 0) return;
+	if (budget.kind === "weighted") {
+		const weightIds = Object.keys(budget.weights).sort();
+		if (weightIds.length !== selectedIds.length || weightIds.some((id, index) => id !== selectedIds[index])) {
+			issue([
+				"policy",
+				"budget",
+				"weights"
+			], "weights must name every analyst and no others");
+			return;
+		}
+		const totalWeight = runnableIds.reduce((sum, id) => sum + (budget.weights[id] ?? 0), 0);
+		if (totalWeight === 0) {
+			issue([
+				"policy",
+				"budget",
+				"weights"
+			], "runnable analysts must have positive total weight");
+			return;
+		}
+		for (const id of runnableIds) {
+			const expected = budget.total_usd * (budget.weights[id] ?? 0) / totalWeight;
+			if (Math.abs((budget.allocations_usd[id] ?? 0) - expected) > epsilon) issue([
+				"policy",
+				"budget",
+				"allocations_usd",
+				id
+			], "allocation does not match the weighted policy");
+		}
+		return;
+	}
+	const expected = budget.total_usd / runnableIds.length;
+	for (const id of runnableIds) if (Math.abs((budget.allocations_usd[id] ?? 0) - expected) > epsilon) issue([
+		"policy",
+		"budget",
+		"allocations_usd",
+		id
+	], "allocation does not match the equal policy");
+});
+/**
+* Canonicalize and validate the one exact-plan representation shared by execution and archival.
+* Unknown fields fail at every level; the returned graph is detached and deeply frozen.
+*/
+function snapshotExactExecutionPlan(value, context = "exact analyst execution plan") {
+	let detached;
+	try {
+		detached = JSON.parse(canonicalString(value));
+	} catch (cause) {
+		throw new TypeError(`${context} must have a canonical JSON representation`, { cause });
+	}
+	const parsed = exactExecutionPlanSchema.safeParse(detached);
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		const path = issue?.path.length ? ` ${issue.path.join(".")}` : "";
+		throw new TypeError(`${context}${path}: ${issue?.message ?? "is invalid"}`);
+	}
+	const expectedDigest = hashCanonical({
+		schema_version: parsed.data.schema_version,
+		analysts: parsed.data.analysts,
+		policy: parsed.data.policy
+	});
+	if (parsed.data.digest !== expectedDigest) throw new TypeError(`${context} digest does not match its content`);
+	return deepFreezeCanonicalJson(parsed.data);
+}
+//#endregion
+//#region src/analyst/finding-subject.ts
+/**
+* Typed `FindingSubject` — the canonical grammar every analyst kind emits.
+*
+* Background: kind actor prompts have always documented a subject grammar
+* (e.g. `system-prompt:<section>`, `agent-knowledge:wiki:<slug>`) but the
+* LLM was unconstrained — it could emit `subject: "fix the prompt"`
+* (prose) and downstream adapters routed on `startsWith(...)` would
+* silently skip it. Every per-vertical `ImprovementAdapter` had a
+* routing table that mostly caught nothing.
+*
+* This module fixes that:
+*   - `parseFindingSubject(raw)` — returns the typed `FindingSubject`
+*     when `raw` matches the grammar, else `null`. Used at the
+*     `RawAnalystFindingSchema` boundary so malformed subjects are
+*     rejected loudly instead of silently lifted into the registry.
+*   - `FindingSubjectKind` — the union of valid locus categories. Each
+*     variant carries the typed components downstream adapters resolve
+*     against the agent's surface manifest (no string parsing in the
+*     adapter).
+*   - `FINDING_SUBJECT_GRAMMAR_PROMPT` — single source of truth for the
+*     grammar string embedded in kind actor prompts. Drift between
+*     prompt and parser is impossible if every kind imports this.
+*
+* The grammar is intentionally NARROW — only loci the substrate's
+* default `ImprovementAdapter` / `KnowledgeAdapter` can act on. A
+* finding with a subject outside this set fails the parser; the kind
+* author either extends the grammar here (and adds adapter routing)
+* or rephrases the prompt to map onto an existing variant.
+*
+* `failure-mode` is the one exception — its subjects are free-form
+* cluster labels, not loci. The schema preserves them as
+* `{ kind: 'cluster', label }` and the adapters skip them (cluster
+* findings are evidence, not actionable mutations).
+*/
+const FINDING_SUBJECT_KINDS = [
+	"knowledge.wiki",
+	"knowledge.claim",
+	"knowledge.raw",
+	"knowledge.stale",
+	"system-prompt",
+	"skill",
+	"tool-doc",
+	"new-tool",
+	"mcp",
+	"hook",
+	"subagent",
+	"workflow",
+	"rollout-policy",
+	"agent-profile",
+	"code",
+	"rag",
+	"memory",
+	"scaffolding",
+	"output-schema",
+	"websearch.outdated",
+	"prior-run-summary",
+	"cluster"
+];
+/**
+* Parse a raw subject string emitted by an analyst kind's actor.
+*
+* Returns the typed `FindingSubject` when `raw` matches the grammar,
+* else `null`. Callers use the `null` return as a signal to either
+* (a) reject the finding at parse time (kinds that emit typed loci —
+* knowledge-gap, improvement, knowledge-poisoning) or (b) lift it as
+* a cluster label (failure-mode).
+*
+* Slugs are constrained to `[a-z0-9-]+` (lowercase kebab) to keep file
+* paths sane downstream. Topics / keys / sections allow any non-empty
+* string (free-form for the LLM's voice) but get trimmed.
+*
+* Empty / whitespace-only inputs return `null`. `undefined` returns
+* `null`. Both are surfaced by the caller as a rejected subject.
+*/
+function parseFindingSubject(raw) {
+	if (raw === null || raw === void 0) return null;
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return null;
+	const wiki = trimmed.match(/^agent-knowledge:wiki:([a-z0-9][a-z0-9-]*)(?:#([a-z0-9][a-z0-9-]*))?$/);
+	if (wiki) return {
+		kind: "knowledge.wiki",
+		slug: wiki[1],
+		...wiki[2] ? { heading: wiki[2] } : {}
+	};
+	const claim = trimmed.match(/^agent-knowledge:claim:(.+)$/);
+	if (claim && claim[1].trim().length > 0) return {
+		kind: "knowledge.claim",
+		topic: claim[1].trim()
+	};
+	const raw_ = trimmed.match(/^agent-knowledge:raw:(.+)$/);
+	if (raw_ && raw_[1].trim().length > 0) return {
+		kind: "knowledge.raw",
+		sourceId: raw_[1].trim()
+	};
+	const stale = trimmed.match(/^agent-knowledge:stale:([a-z0-9][a-z0-9-]*)$/);
+	if (stale) return {
+		kind: "knowledge.stale",
+		slug: stale[1]
+	};
+	const sp = trimmed.match(/^system-prompt:(.+)$/);
+	if (sp && sp[1].trim().length > 0) return {
+		kind: "system-prompt",
+		section: sp[1].trim()
+	};
+	const skill = trimmed.match(/^skill:([a-z0-9][a-z0-9_.-]*)$/);
+	if (skill) return {
+		kind: "skill",
+		name: skill[1]
+	};
+	const tdAspect = trimmed.match(/^tool-doc:([a-z0-9][a-z0-9_-]*):(.+)$/);
+	if (tdAspect && tdAspect[2].trim().length > 0) return {
+		kind: "tool-doc",
+		tool: tdAspect[1],
+		aspect: tdAspect[2].trim()
+	};
+	const td = trimmed.match(/^tool-doc:([a-z0-9][a-z0-9_-]*)$/);
+	if (td) return {
+		kind: "tool-doc",
+		tool: td[1]
+	};
+	const nt = trimmed.match(/^new-tool:([a-z0-9][a-z0-9_-]*)$/);
+	if (nt) return {
+		kind: "new-tool",
+		name: nt[1]
+	};
+	const mcp = trimmed.match(/^mcp:([a-z0-9][a-z0-9_.-]*)(?::([a-z0-9][a-z0-9_.-]*))?$/);
+	if (mcp) return {
+		kind: "mcp",
+		server: mcp[1],
+		...mcp[2] ? { tool: mcp[2] } : {}
+	};
+	const hook = trimmed.match(/^hook:([a-z0-9][a-z0-9_.-]*)$/);
+	if (hook) return {
+		kind: "hook",
+		name: hook[1]
+	};
+	const subagent = trimmed.match(/^subagent:([a-z0-9][a-z0-9_.-]*)$/);
+	if (subagent) return {
+		kind: "subagent",
+		name: subagent[1]
+	};
+	const workflow = trimmed.match(/^workflow:([a-z0-9][a-z0-9_.-]*)$/);
+	if (workflow) return {
+		kind: "workflow",
+		name: workflow[1]
+	};
+	const rolloutPolicy = trimmed.match(/^rollout-policy:(.+)$/);
+	if (rolloutPolicy && rolloutPolicy[1].trim().length > 0) return {
+		kind: "rollout-policy",
+		field: rolloutPolicy[1].trim()
+	};
+	const agentProfile = trimmed.match(/^agent-profile:(.+)$/);
+	if (agentProfile && agentProfile[1].trim().length > 0) return {
+		kind: "agent-profile",
+		field: agentProfile[1].trim()
+	};
+	const code = trimmed.match(/^code:(.+)$/);
+	if (code && code[1].trim().length > 0) return {
+		kind: "code",
+		path: code[1].trim()
+	};
+	const rag = trimmed.match(/^rag:([a-z0-9][a-z0-9_-]*):(.+)$/);
+	if (rag && rag[2].trim().length > 0) return {
+		kind: "rag",
+		corpus: rag[1],
+		docId: rag[2].trim()
+	};
+	const mem = trimmed.match(/^memory:(.+)$/);
+	if (mem && mem[1].trim().length > 0) return {
+		kind: "memory",
+		key: mem[1].trim()
+	};
+	const sc = trimmed.match(/^scaffolding:(.+)$/);
+	if (sc && sc[1].trim().length > 0) return {
+		kind: "scaffolding",
+		concern: sc[1].trim()
+	};
+	const os = trimmed.match(/^output-schema:(.+)$/);
+	if (os && os[1].trim().length > 0) return {
+		kind: "output-schema",
+		field: os[1].trim()
+	};
+	const ws = trimmed.match(/^websearch:outdated:(.+)$/);
+	if (ws && ws[1].trim().length > 0) return {
+		kind: "websearch.outdated",
+		topic: ws[1].trim()
+	};
+	const prs = trimmed.match(/^prior-run-summary:(.+)$/);
+	if (prs && prs[1].trim().length > 0) return {
+		kind: "prior-run-summary",
+		topic: prs[1].trim()
+	};
+	if (/^[a-z0-9][a-z0-9._-]*$/.test(trimmed) && trimmed.length <= 80) return {
+		kind: "cluster",
+		label: trimmed
+	};
+	return null;
+}
+/**
+* Render the parsed subject back to its canonical string form. Inverse
+* of `parseFindingSubject`; useful when the substrate constructs new
+* findings programmatically (e.g. for tests, replays, or
+* `id_basis` carry-forward).
+*/
+function renderFindingSubject(s) {
+	switch (s.kind) {
+		case "knowledge.wiki": return s.heading ? `agent-knowledge:wiki:${s.slug}#${s.heading}` : `agent-knowledge:wiki:${s.slug}`;
+		case "knowledge.claim": return `agent-knowledge:claim:${s.topic}`;
+		case "knowledge.raw": return `agent-knowledge:raw:${s.sourceId}`;
+		case "knowledge.stale": return `agent-knowledge:stale:${s.slug}`;
+		case "system-prompt": return `system-prompt:${s.section}`;
+		case "skill": return `skill:${s.name}`;
+		case "tool-doc": return s.aspect ? `tool-doc:${s.tool}:${s.aspect}` : `tool-doc:${s.tool}`;
+		case "new-tool": return `new-tool:${s.name}`;
+		case "mcp": return s.tool ? `mcp:${s.server}:${s.tool}` : `mcp:${s.server}`;
+		case "hook": return `hook:${s.name}`;
+		case "subagent": return `subagent:${s.name}`;
+		case "workflow": return `workflow:${s.name}`;
+		case "rollout-policy": return `rollout-policy:${s.field}`;
+		case "agent-profile": return `agent-profile:${s.field}`;
+		case "code": return `code:${s.path}`;
+		case "rag": return `rag:${s.corpus}:${s.docId}`;
+		case "memory": return `memory:${s.key}`;
+		case "scaffolding": return `scaffolding:${s.concern}`;
+		case "output-schema": return `output-schema:${s.field}`;
+		case "websearch.outdated": return `websearch:outdated:${s.topic}`;
+		case "prior-run-summary": return `prior-run-summary:${s.topic}`;
+		case "cluster": return s.label;
+	}
+}
+/**
+* The grammar text embedded into kind actor prompts. Kinds opt into
+* the subset of variants they emit (e.g. `improvement` excludes the
+* cluster variant; `failure-mode` includes ONLY the cluster variant).
+*
+* Drift between prompt and parser is impossible: every kind imports
+* this constant + the matching `expects` set, and the unit tests below
+* lock the table to the parser.
+*/
+const FINDING_SUBJECT_SYNTAX = {
+	"knowledge.wiki": "agent-knowledge:wiki:<slug>[#<heading>]",
+	"knowledge.claim": "agent-knowledge:claim:<topic>",
+	"knowledge.raw": "agent-knowledge:raw:<source-id>",
+	"knowledge.stale": "agent-knowledge:stale:<slug>",
+	"system-prompt": "system-prompt:<section>",
+	skill: "skill:<name>",
+	"tool-doc": "tool-doc:<tool>[:<aspect>]",
+	"new-tool": "new-tool:<name>",
+	mcp: "mcp:<server>[:<tool>]",
+	hook: "hook:<name>",
+	subagent: "subagent:<name>",
+	workflow: "workflow:<name>",
+	"rollout-policy": "rollout-policy:<field>",
+	"agent-profile": "agent-profile:<field>",
+	code: "code:<path>",
+	rag: "rag:<corpus>:<doc-id>",
+	memory: "memory:<key>",
+	scaffolding: "scaffolding:<concern>",
+	"output-schema": "output-schema:<field>",
+	"websearch.outdated": "websearch:outdated:<topic>",
+	"prior-run-summary": "prior-run-summary:<topic>",
+	cluster: "<lowercase-cluster-label>"
+};
+const FINDING_SUBJECT_PURPOSE = {
+	"knowledge.wiki": "create or update a wiki page",
+	"knowledge.claim": "draft a claim or relation",
+	"knowledge.raw": "curate a raw source",
+	"knowledge.stale": "mark a stale page",
+	"system-prompt": "revise a system-prompt section",
+	skill: "create or revise a skill",
+	"tool-doc": "revise a tool contract",
+	"new-tool": "propose a new tool",
+	mcp: "revise an MCP server or tool",
+	hook: "revise a lifecycle hook",
+	subagent: "revise a delegated agent",
+	workflow: "revise an orchestration workflow",
+	"rollout-policy": "revise budget, sampling, or stop policy",
+	"agent-profile": "revise another AgentProfile field",
+	code: "revise an implementation path",
+	rag: "ingest or correct a RAG document",
+	memory: "invalidate or set memory",
+	scaffolding: "revise preconditions, retries, or verification",
+	"output-schema": "constrain the output shape",
+	"websearch.outdated": "identify a stale web result",
+	"prior-run-summary": "identify a stale prior-run summary",
+	cluster: "name one failure cluster"
+};
+function renderFindingSubjectGrammar(kinds) {
+	return [
+		"Subjects MUST match one of these forms — anything else is rejected at parse time:",
+		...kinds.map((kind) => `  ${FINDING_SUBJECT_SYNTAX[kind]} — ${FINDING_SUBJECT_PURPOSE[kind]}`),
+		"Runtime ids are lowercase [a-z0-9_.-]+. Topics, keys, paths, and sections are free-form and trimmed."
+	].join("\n");
+}
+const FINDING_SUBJECT_GRAMMAR_PROMPT = renderFindingSubjectGrammar(FINDING_SUBJECT_KINDS);
+/**
+* The variants each kind is allowed to emit. Used at the kind factory
+* boundary so a knowledge-gap finding can't sneak in a `system-prompt:*`
+* subject (the improvement-analyst's job) and vice versa.
+*
+* `failure-mode` is restricted to `cluster` — the only kind that emits
+* a non-locus subject.
+*/
+const KIND_EXPECTED_SUBJECTS = {
+	"failure-mode": ["cluster"],
+	"knowledge-gap": [
+		"knowledge.wiki",
+		"knowledge.claim",
+		"knowledge.raw",
+		"knowledge.stale",
+		"tool-doc",
+		"system-prompt",
+		"skill",
+		"mcp",
+		"subagent",
+		"workflow",
+		"memory",
+		"websearch.outdated",
+		"prior-run-summary"
+	],
+	"knowledge-poisoning": [
+		"knowledge.wiki",
+		"knowledge.claim",
+		"knowledge.raw",
+		"tool-doc",
+		"system-prompt",
+		"skill",
+		"mcp",
+		"hook",
+		"memory",
+		"websearch.outdated",
+		"prior-run-summary"
+	],
+	improvement: [
+		"system-prompt",
+		"skill",
+		"tool-doc",
+		"new-tool",
+		"mcp",
+		"hook",
+		"subagent",
+		"workflow",
+		"rollout-policy",
+		"agent-profile",
+		"code",
+		"rag",
+		"memory",
+		"scaffolding",
+		"output-schema",
+		"knowledge.wiki",
+		"knowledge.claim"
+	]
+};
+/** Render only the subject forms one analyst kind is permitted to emit. */
+function findingSubjectGrammarPromptFor(kindId) {
+	const kinds = KIND_EXPECTED_SUBJECTS[kindId];
+	if (!kinds) throw new Error(`unknown analyst kind: ${kindId}`);
+	return renderFindingSubjectGrammar(kinds);
+}
+/**
+* Zod schema that validates a raw subject string and returns the parsed
+* `FindingSubject`. Embedded in `RawAnalystFindingSchema` via
+* `transform`, so `subject` arrives at the kind factory either as a
+* typed locus or as a parse error attached to a single Zod issue.
+*
+* Optionality is preserved: subjects ARE optional on the wire (some
+* findings are descriptive, not actionable). When present, they MUST
+* parse — emitting a malformed subject is a contract violation, not a
+* soft signal.
+*/
+const FindingSubjectStringSchema = z.string().refine((s) => parseFindingSubject(s) !== null, { message: "subject does not match the finding-subject grammar" });
+//#endregion
+//#region src/analyst/parse-tolerant.ts
+/**
+* Forgiving pre-parse for analyst findings. Weak models routinely emit
+* schema-correct content in an unusable wrapper — fenced ```json blocks, a
+* single object where an array is expected, trailing commas. Measured: GPT-4o
+* drops to 0% usable output purely from markdown-fence wrapping
+* (arXiv:2605.02363). A five-line de-fence recovers most of it. This module is
+* the de-fence/coerce step that runs BEFORE Zod, so a recoverable finding is
+* repaired, not dropped.
+*
+* Pure + deterministic. No model, no network.
+*/
+/** Strip a ```lang ... ``` (or bare ``` ... ```) code fence, if the string is one. */
+function stripCodeFences(text) {
+	const t = text.trim();
+	const m = t.match(/^```[a-zA-Z0-9]*\s*\n?([\s\S]*?)\n?```$/);
+	return m ? m[1].trim() : t;
+}
+/** Remove trailing commas before } or ] — the most common near-JSON defect. */
+function dropTrailingCommas(s) {
+	return s.replace(/,(\s*[}\]])/g, "$1");
+}
+/**
+* Best-effort parse of a string into JSON. De-fences, drops trailing commas,
+* then `JSON.parse`. Returns `undefined` (never throws) when unrecoverable.
+*/
+function coerceJson(text) {
+	const candidate = dropTrailingCommas(stripCodeFences(text));
+	try {
+		return JSON.parse(candidate);
+	} catch {
+		return;
+	}
+}
+/**
+* Coerce arbitrary actor/structurer output into an array of candidate finding
+* rows: a JSON string → parse; a single object → 1-element array; an array →
+* as-is; anything else → []. Callers still run each row through Zod
+* (`parseRawFinding`) — this only fixes the shape and never invents fields.
+*/
+function coerceToFindingRows(raw) {
+	let value = raw;
+	if (typeof value === "string") {
+		const parsed = coerceJson(value);
+		if (parsed === void 0) return [];
+		value = parsed;
+	}
+	if (Array.isArray(value)) return value;
+	if (value && typeof value === "object") {
+		const inner = value.findings;
+		if (Array.isArray(inner)) return inner;
+		return [value];
+	}
+	return [];
+}
+//#endregion
+//#region src/analyst/finding-signature.ts
+/**
+* Engine-neutral structured output for trace-analyst findings.
+*
+* Every recursive engine returns this shape. The TypeScript boundary validates
+* it before a finding can enter a registry or benchmark.
+*/
+const ANALYST_SEVERITIES = [
+	"critical",
+	"high",
+	"medium",
+	"low",
+	"info"
+];
+const RawAnalystEvidenceSchema = z.object({
+	uri: z.string().trim().min(1).max(2e3),
+	excerpt: z.string().max(2e3).optional()
+}).strict();
+const RawAnalystFindingBaseShape = {
+	severity: z.enum(ANALYST_SEVERITIES),
+	claim: z.string().min(1).max(2e3),
+	subject: z.string().max(400).refine((subject) => parseFindingSubject(subject) !== null, { message: "subject does not match the finding-subject grammar" }).optional(),
+	confidence: z.number().min(0).max(1),
+	rationale: z.string().max(4e3).optional(),
+	recommended_action: z.string().max(2e3).optional()
+};
+const RawAnalystFindingSchema = z.object({
+	...RawAnalystFindingBaseShape,
+	evidence: z.array(RawAnalystEvidenceSchema).min(1)
+}).strict();
+/**
+* Description embedded into the actor prompt so the LLM knows what
+* shape to emit. Kept here so kinds share one source of truth rather
+* than restating the schema in every prompt.
+*/
+const RAW_FINDING_SCHEMA_PROMPT = `Each finding MUST be a strict JSON object with:
+  - severity: "critical" | "high" | "medium" | "low" | "info"
+  - claim: one-sentence statement (max 2000 chars)
+  - subject?: one exact subject form listed by this kind; omit rather than guess
+  - evidence: REQUIRED non-empty array of {"uri": string, "excerpt"?: string}. Use trace://<URL-encoded-trace-id>/span/<URL-encoded-span-id> for trace evidence or finding://<finding-id> for supplied prior findings. URL encoding means percent encoding, never base64. Include a short exact quote in excerpt when available. If nothing is citable, do not emit the finding.
+  - confidence: number 0..1 (0.9+ exact evidence; 0.6-0.8 inferred pattern; <0.5 speculative)
+  - rationale?: one or two reasoning sentences
+  - recommended_action?: concrete imperative change; omit for descriptive findings
+
+Unknown fields are rejected. Do not emit area; the factory assigns it. Emit [] when there are no findings. Never fabricate evidence.`;
+/** Convert raw citations into the public finding evidence envelope. */
+function evidenceRefsFromRawFinding(finding) {
+	return finding.evidence.map(({ uri, excerpt }) => ({
+		kind: evidenceKindFromUri(uri),
+		uri,
+		excerpt
+	}));
+}
+function parseRawFinding(row, log) {
+	return parseFindingWithSchema(RawAnalystFindingSchema, row, log);
+}
+function parseFindingWithSchema(schema, row, log) {
+	const result = schema.safeParse(row);
+	if (result.success) return result.data;
+	if (typeof row === "string") {
+		const coerced = coerceJson(row);
+		if (coerced !== void 0) {
+			const retry = schema.safeParse(coerced);
+			if (retry.success) return retry.data;
+		}
+	}
+	log?.("finding rejected: schema failure", { issues: result.error.issues.map((i) => ({
+		path: i.path.join("."),
+		code: i.code,
+		message: i.message
+	})) });
+	return null;
+}
+function evidenceKindFromUri(uri) {
+	if (parseTraceSpanEvidenceUri(uri)) return "span";
+	if (uri.startsWith("finding://")) return "finding";
+	return "artifact";
+}
+function parseTraceSpanEvidenceUri(uri) {
+	const match = /^trace:\/\/([^/]+)\/span\/([^/]+)$/.exec(uri);
+	if (!match) return null;
+	try {
+		const traceId = decodeURIComponent(match[1]);
+		const spanId = decodeURIComponent(match[2]);
+		return traceId && spanId ? {
+			traceId,
+			spanId
+		} : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/trace-analyst/errors.ts
+/** Invalid trace-tool arguments, including malformed filters and regexes. */
+var TraceAnalysisValidationError = class extends ValidationError {};
+/** A trace read cannot fit within a documented count or byte limit. */
+var TraceAnalysisLimitError = class extends LimitExceededError {
+	operation;
+	actual;
+	limit;
+	constructor(operation, actual, limit, message) {
+		super(message ?? `${operation} produced ${actual}, over the limit of ${limit}`);
+		this.operation = operation;
+		this.actual = actual;
+		this.limit = limit;
+	}
+};
+/** A supplied store returned a shape that violates the trace read contract. */
+var TraceAnalysisStoreContractError = class extends AgentEvalError {
+	operation;
+	constructor(operation, message, options) {
+		super("backend_integrity", `${operation}: ${message}`, options);
+		this.operation = operation;
+	}
+};
+var TraceFileMissingError = class extends NotFoundError {
+	path;
+	constructor(path) {
+		super(`trace file not found: ${path}`);
+		this.path = path;
+	}
+};
+var TraceFileTooLargeError = class extends TraceAnalysisLimitError {
+	path;
+	size_bytes;
+	max_bytes;
+	constructor(path, size_bytes, max_bytes) {
+		super("OtlpFileTraceStore.readBuffer", size_bytes, max_bytes, `trace file ${path} is ${size_bytes} bytes, over the ${max_bytes}-byte limit; raise OtlpFileTraceStoreOptions.maxFileBytes or pre-split the file`);
+		this.path = path;
+		this.size_bytes = size_bytes;
+		this.max_bytes = max_bytes;
+	}
+};
+var TraceFileMalformedError = class extends CaptureIntegrityError {
+	path;
+	line_number;
+	byte_offset;
+	constructor(path, line_number, byte_offset, cause) {
+		super(`malformed trace row in ${path} at line ${line_number}, byte ${byte_offset}`, { cause });
+		this.path = path;
+		this.line_number = line_number;
+		this.byte_offset = byte_offset;
+	}
+};
+var TraceNotFoundError = class extends NotFoundError {
+	trace_id;
+	constructor(trace_id) {
+		super(`trace not found: ${trace_id}`);
+		this.trace_id = trace_id;
+	}
+};
+var SpanNotFoundError = class extends NotFoundError {
+	trace_id;
+	span_id;
+	constructor(trace_id, span_id) {
+		super(`span ${span_id} not found in trace ${trace_id}`);
+		this.trace_id = trace_id;
+		this.span_id = span_id;
+	}
+};
+//#endregion
+//#region src/trace-analyst/store-contract.ts
+const TRACE_ANALYSIS_LIMITS = {
+	sampleTraceIds: 20,
+	queryTraces: 200,
+	viewSpans: 100,
+	searchMatches: 500,
+	filterValues: 100,
+	identifierCharacters: 256,
+	regexCharacters: 4096,
+	minimumTextBudget: 64
+};
+//#endregion
+//#region src/trace-analyst/types.ts
+const DEFAULT_TRACE_ANALYST_BUDGETS = {
+	perCallByteCeiling: 15e4,
+	perAttributeViewBudget: 4096,
+	perAttributeSpanBudget: 16384,
+	perMatchTextBudget: 1024
+};
+/** Marker substituted in place of truncated string payloads. Callers
+*  parsing tool output can detect it deterministically. */
+const TRACE_ANALYST_TRUNCATION_MARKER_PREFIX = "[trace-analyst truncated:";
+//#endregion
+//#region src/trace-analyst/store-bounds.ts
+function resolveTraceBudgets(overrides) {
+	const budgets = {
+		...DEFAULT_TRACE_ANALYST_BUDGETS,
+		...overrides
+	};
+	validateInteger(budgets.perCallByteCeiling, "perCallByteCeiling", 1);
+	for (const name of [
+		"perAttributeViewBudget",
+		"perAttributeSpanBudget",
+		"perMatchTextBudget"
+	]) validateInteger(budgets[name], name, TRACE_ANALYSIS_LIMITS.minimumTextBudget);
+	return budgets;
+}
+function boundOverview(result, byteCeiling) {
+	if (result.sample_trace_ids.length > result.total_traces) throw contractError("getOverview", "sample_trace_ids contains more entries than total_traces");
+	if (result.errors.trace_count > result.total_traces) throw contractError("getOverview", "errors.trace_count exceeds total_traces");
+	return withinByteCeiling("getOverview", result, byteCeiling);
+}
+function boundTracePage(result, input, byteCeiling) {
+	if (result.traces.length > input.limit) throw contractError("queryTraces", `store returned ${result.traces.length} traces for limit ${input.limit}`);
+	if (result.total < input.offset + result.traces.length) throw contractError("queryTraces", `total ${result.total} is smaller than the returned page ending at ${input.offset + result.traces.length}`);
+	if (result.has_more !== input.offset + result.traces.length < result.total) throw contractError("queryTraces", "has_more does not match the returned page position and total");
+	if (result.has_more && result.traces.length === 0) throw contractError("queryTraces", "store reported more traces without returning any progress");
+	const traces = [];
+	for (const trace of result.traces) {
+		if (encodedBytes("queryTraces", {
+			traces: [...traces, trace],
+			total: result.total,
+			has_more: true
+		}) > byteCeiling) break;
+		traces.push(trace);
+	}
+	if (result.traces.length > 0 && traces.length === 0) throw responseItemTooLarge("queryTraces", {
+		traces: [result.traces[0]],
+		total: result.total,
+		has_more: true
+	}, byteCeiling);
+	return withinByteCeiling("queryTraces", {
+		traces,
+		total: result.total,
+		has_more: result.has_more || traces.length < result.traces.length
+	}, byteCeiling);
+}
+function boundTraceView(result, expectedTraceId, perAttributeCap, byteCeiling) {
+	requireEqual("viewTrace", "trace_id", result.trace_id, expectedTraceId);
+	if (result.oversized) return withinByteCeiling("viewTrace", result, byteCeiling);
+	const spans = result.spans.map((span) => {
+		requireEqual("viewTrace", "span.trace_id", span.trace_id, expectedTraceId);
+		return truncateSpanAttributes("viewTrace", span, perAttributeCap).span;
+	});
+	const full = {
+		trace_id: expectedTraceId,
+		spans
+	};
+	if (encodedBytes("viewTrace", full) <= byteCeiling) return full;
+	return withinByteCeiling("viewTrace", {
+		trace_id: expectedTraceId,
+		oversized: oversizedFromSpans(spans)
+	}, byteCeiling);
+}
+function boundSpansView(result, expectedTraceId, requested, existingSpanIds, perAttributeCap, byteCeiling) {
+	requireEqual("viewSpans", "trace_id", result.trace_id, expectedTraceId);
+	const requestedSet = new Set(requested);
+	const missing = checkedAccountingIds("missing_span_ids", result.missing_span_ids, requestedSet);
+	const omitted = checkedAccountingIds("omitted_span_ids", result.omitted_span_ids, requestedSet);
+	const missingSet = new Set(missing);
+	const omittedSet = new Set(omitted);
+	const expectedMissing = requested.filter((id) => !existingSpanIds.has(id));
+	if (expectedMissing.length !== missing.length || expectedMissing.some((id) => !missingSet.has(id))) throw contractError("viewSpans", "missing_span_ids does not match the store existence checks");
+	if (result.has_more !== omitted.length > 0) throw contractError("viewSpans", "has_more must be true exactly when omitted_span_ids is non-empty");
+	if (result.spans.length === 0 && requested.some((id) => existingSpanIds.has(id) && omittedSet.has(id))) throw contractError("viewSpans", "store omitted every existing requested span instead of returning progress or throwing a size error");
+	const projected = /* @__PURE__ */ new Map();
+	for (const span of result.spans) {
+		requireEqual("viewSpans", "span.trace_id", span.trace_id, expectedTraceId);
+		if (!requestedSet.has(span.span_id)) throw contractError("viewSpans", `store returned unrequested span ${JSON.stringify(span.span_id)}`);
+		if (missingSet.has(span.span_id) || omittedSet.has(span.span_id)) throw contractError("viewSpans", `span ${JSON.stringify(span.span_id)} is both returned and unavailable`);
+		if (projected.has(span.span_id)) throw contractError("viewSpans", `store returned duplicate span ${JSON.stringify(span.span_id)}`);
+		projected.set(span.span_id, truncateSpanAttributes("viewSpans", span, perAttributeCap));
+	}
+	for (const id of requested) if (!missingSet.has(id) && !omittedSet.has(id) && !projected.has(id)) throw contractError("viewSpans", `store did not account for requested span ${JSON.stringify(id)}`);
+	const spans = [];
+	let addedTruncations = 0;
+	const build = () => ({
+		trace_id: expectedTraceId,
+		spans,
+		missing_span_ids: requested.filter((id) => missingSet.has(id)),
+		omitted_span_ids: requested.filter((id) => omittedSet.has(id)),
+		has_more: omittedSet.size > 0,
+		truncated_attribute_count: result.truncated_attribute_count + addedTruncations
+	});
+	withinByteCeiling("viewSpans", build(), byteCeiling);
+	for (const id of requested) {
+		const item = projected.get(id);
+		if (!item) continue;
+		spans.push(item.span);
+		omittedSet.delete(id);
+		addedTruncations += item.truncations;
+		if (encodedBytes("viewSpans", build()) <= byteCeiling) continue;
+		spans.pop();
+		omittedSet.add(id);
+		addedTruncations -= item.truncations;
+	}
+	if (projected.size > 0 && spans.length === 0) {
+		const first = projected.values().next().value;
+		if (first) throw responseItemTooLarge("viewSpans", {
+			trace_id: expectedTraceId,
+			spans: [first.span],
+			missing_span_ids: [],
+			omitted_span_ids: [],
+			has_more: false,
+			truncated_attribute_count: result.truncated_attribute_count + first.truncations
+		}, byteCeiling);
+	}
+	return withinByteCeiling("viewSpans", build(), byteCeiling);
+}
+function boundTraceSearch(result, expectedTraceId, maxMatches, budgets) {
+	requireEqual("searchTrace", "trace_id", result.trace_id, expectedTraceId);
+	return {
+		trace_id: expectedTraceId,
+		...boundSearchHits("searchTrace", result, maxMatches, budgets, (hit) => {
+			requireEqual("searchTrace", "hit.trace_id", hit.trace_id, expectedTraceId);
+		})
+	};
+}
+function boundSpanSearch(result, expectedTraceId, expectedSpanId, maxMatches, budgets) {
+	requireEqual("searchSpan", "trace_id", result.trace_id, expectedTraceId);
+	requireEqual("searchSpan", "span_id", result.span_id, expectedSpanId);
+	return {
+		trace_id: expectedTraceId,
+		span_id: expectedSpanId,
+		...boundSearchHits("searchSpan", result, maxMatches, budgets, (hit) => {
+			requireEqual("searchSpan", "hit.trace_id", hit.trace_id, expectedTraceId);
+			requireEqual("searchSpan", "hit.span_id", hit.span_id, expectedSpanId);
+		})
+	};
+}
+function boundSearchHits(operation, result, maxMatches, budgets, validateHit) {
+	if (result.hits.length > maxMatches) throw contractError(operation, `store returned ${result.hits.length} hits for max_matches ${maxMatches}`);
+	if (result.has_more && result.hits.length === 0) throw contractError(operation, "store reported more matches without returning any progress");
+	const hits = [];
+	for (const raw of result.hits) {
+		validateHit(raw);
+		const hit = truncateMatchRecord(raw, budgets.perMatchTextBudget);
+		if (encodedBytes(operation, {
+			hits: [...hits, hit],
+			has_more: true
+		}) > budgets.perCallByteCeiling) break;
+		hits.push(hit);
+	}
+	if (result.hits.length > 0 && hits.length === 0) throw responseItemTooLarge(operation, {
+		hits: [truncateMatchRecord(result.hits[0], budgets.perMatchTextBudget)],
+		has_more: true
+	}, budgets.perCallByteCeiling);
+	return withinByteCeiling(operation, {
+		hits,
+		has_more: result.has_more || hits.length < result.hits.length
+	}, budgets.perCallByteCeiling);
+}
+function checkedAccountingIds(label, ids, requested) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const id of ids) {
+		if (!requested.has(id)) throw contractError("viewSpans", `${label} contains unrequested id ${JSON.stringify(id)}`);
+		if (seen.has(id)) throw contractError("viewSpans", `${label} contains duplicate id ${JSON.stringify(id)}`);
+		seen.add(id);
+	}
+	return [...ids];
+}
+function truncateMatchRecord(record, cap) {
+	return {
+		...record,
+		span_name: truncateForBudget(record.span_name, cap),
+		attribute_path: truncateForBudget(record.attribute_path, cap),
+		matched_text: truncateForBudget(record.matched_text, cap),
+		context_before: truncateForBudget(record.context_before, cap),
+		context_after: truncateForBudget(record.context_after, cap)
+	};
+}
+function truncateSpanAttributes(operation, span, cap) {
+	const attributes = {};
+	let truncations = 0;
+	for (const [key, value] of Object.entries(span.attributes)) {
+		if (typeof value === "string") {
+			const truncated = truncateForBudget(value, cap);
+			if (truncated !== value) truncations += 1;
+			attributes[key] = truncated;
+			continue;
+		}
+		if (value !== null && typeof value === "object") {
+			let json;
+			try {
+				json = JSON.stringify(value);
+			} catch (cause) {
+				throw new TraceAnalysisStoreContractError(operation, `span attribute ${JSON.stringify(key)} is not JSON-serializable`, { cause });
+			}
+			const truncated = truncateForBudget(json, cap);
+			if (truncated !== json) {
+				truncations += 1;
+				attributes[key] = truncated;
+			} else attributes[key] = value;
+			continue;
+		}
+		attributes[key] = value;
+	}
+	return {
+		span: {
+			...span,
+			attributes
+		},
+		truncations
+	};
+}
+function oversizedFromSpans(spans) {
+	const names = /* @__PURE__ */ new Map();
+	let maxBytes = 0;
+	let errors = 0;
+	for (const span of spans) {
+		names.set(span.name, (names.get(span.name) ?? 0) + 1);
+		maxBytes = Math.max(maxBytes, encodedBytes("viewTrace", span));
+		if (span.status === "ERROR") errors += 1;
+	}
+	return {
+		span_count: spans.length,
+		top_span_names: [...names.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 20),
+		span_response_bytes_max: maxBytes,
+		error_span_count: errors
+	};
+}
+function compileSearchRegex(pattern) {
+	if (typeof pattern !== "string" || pattern.length === 0) throw new TraceAnalysisValidationError("regex_pattern must be a non-empty string");
+	let source = pattern;
+	let flags = RE2JS.MULTILINE;
+	if (source.startsWith("(?i)")) {
+		source = source.slice(4);
+		flags |= RE2JS.CASE_INSENSITIVE;
+	}
+	try {
+		return RE2JS.compile(source, flags);
+	} catch (cause) {
+		throw new TraceAnalysisValidationError(`regex_pattern is invalid: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+}
+function truncateForBudget(value, byteCap) {
+	validateInteger(byteCap, "byteCap", TRACE_ANALYSIS_LIMITS.minimumTextBudget);
+	const original = Buffer.byteLength(value, "utf8");
+	if (original <= byteCap) return value;
+	const marker = `\n[trace-analyst truncated: original ${original} bytes]`;
+	const contentCap = byteCap - Buffer.byteLength(marker, "utf8");
+	let cut = Math.max(0, Math.floor(value.length * contentCap / original));
+	while (cut > 0 && Buffer.byteLength(value.slice(0, cut), "utf8") > contentCap) cut -= 1;
+	return `${value.slice(0, cut)}${marker}`;
+}
+function validateInteger(value, label, minimum, maximum = Number.MAX_SAFE_INTEGER) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new TraceAnalysisValidationError(`${label} must be an integer ${minimum}..${maximum}, got ${String(value)}`);
+	return value;
+}
+function requireEqual(operation, label, actual, expected) {
+	if (actual !== expected) throw contractError(operation, `${label} ${JSON.stringify(actual)} does not match ${JSON.stringify(expected)}`);
+}
+function encodedBytes(operation, value) {
+	try {
+		const encoded = JSON.stringify(value);
+		if (encoded === void 0) throw new TypeError("JSON.stringify returned undefined");
+		return Buffer.byteLength(encoded, "utf8");
+	} catch (cause) {
+		if (cause instanceof TraceAnalysisStoreContractError) throw cause;
+		throw new TraceAnalysisStoreContractError(operation, "store result is not JSON-serializable", { cause });
+	}
+}
+function withinByteCeiling(operation, value, ceiling) {
+	const actual = encodedBytes(operation, value);
+	if (actual > ceiling) throw new TraceAnalysisLimitError(operation, actual, ceiling, `${operation} metadata requires ${actual} bytes, over the ${ceiling}-byte response limit`);
+	return value;
+}
+function responseItemTooLarge(operation, value, ceiling) {
+	return new TraceAnalysisLimitError(operation, encodedBytes(operation, value), ceiling, `${operation} cannot fit one result item in the ${ceiling}-byte response limit`);
+}
+function contractError(operation, message) {
+	return new TraceAnalysisStoreContractError(operation, message);
+}
+//#endregion
+//#region src/trace-analyst/store-schemas.ts
+const identifier = z.string().min(1).max(TRACE_ANALYSIS_LIMITS.identifierCharacters);
+const timestamp = z.iso.datetime({ offset: true });
+const nonNegativeInteger = z.number().int().nonnegative();
+const nonNegativeNumber = z.number().nonnegative();
+const nullableString = z.string().nullable();
+const nullableIdentifier = identifier.nullable();
+const stringArray = z.array(z.string());
+const filterValues = z.array(identifier).max(TRACE_ANALYSIS_LIMITS.filterValues);
+const traceFiltersSchema = z.object({
+	has_errors: z.boolean().optional(),
+	service_names: filterValues.optional(),
+	agent_names: filterValues.optional(),
+	model_names: filterValues.optional(),
+	tool_names: filterValues.optional(),
+	start_time_after: timestamp.optional(),
+	start_time_before: timestamp.optional(),
+	regex_pattern: z.string().min(1).max(TRACE_ANALYSIS_LIMITS.regexCharacters).optional()
+}).strict();
+const byteCap = z.number().int().min(TRACE_ANALYSIS_LIMITS.minimumTextBudget);
+const searchPattern = z.string().min(1).max(TRACE_ANALYSIS_LIMITS.regexCharacters);
+const traceStoreInputSchemas = {
+	hasTrace: z.object({ trace_id: identifier }).strict(),
+	hasSpans: z.object({
+		trace_id: identifier,
+		span_ids: z.array(identifier).min(1).max(TRACE_ANALYSIS_LIMITS.viewSpans)
+	}).strict(),
+	getOverview: z.object({ filters: traceFiltersSchema.optional() }).strict(),
+	queryTraces: z.object({
+		filters: traceFiltersSchema.optional(),
+		limit: z.number().int().min(1).max(TRACE_ANALYSIS_LIMITS.queryTraces),
+		offset: z.number().int().nonnegative().optional()
+	}).strict(),
+	countTraces: z.object({ filters: traceFiltersSchema.optional() }).strict(),
+	viewTrace: z.object({
+		trace_id: identifier,
+		per_attribute_byte_cap: byteCap.optional()
+	}).strict(),
+	viewSpans: z.object({
+		trace_id: identifier,
+		span_ids: z.array(identifier).min(1).max(TRACE_ANALYSIS_LIMITS.viewSpans),
+		per_attribute_byte_cap: byteCap.optional()
+	}).strict(),
+	searchTrace: z.object({
+		trace_id: identifier,
+		regex_pattern: searchPattern,
+		max_matches: z.number().int().min(1).max(TRACE_ANALYSIS_LIMITS.searchMatches).default(50)
+	}).strict(),
+	searchSpan: z.object({
+		trace_id: identifier,
+		span_id: identifier,
+		regex_pattern: searchPattern,
+		max_matches: z.number().int().min(1).max(TRACE_ANALYSIS_LIMITS.searchMatches).default(50)
+	}).strict()
+};
+const spanKind = z.enum([
+	"AGENT",
+	"LLM",
+	"TOOL",
+	"CHAIN",
+	"EVALUATOR",
+	"GUARDRAIL",
+	"SPAN",
+	"UNKNOWN"
+]);
+const spanStatus = z.enum([
+	"OK",
+	"ERROR",
+	"UNSET"
+]);
+const traceSpan = z.object({
+	trace_id: identifier,
+	span_id: identifier,
+	parent_span_id: nullableIdentifier,
+	name: z.string(),
+	kind: spanKind,
+	start_time: timestamp,
+	end_time: timestamp,
+	duration_ms: nonNegativeNumber,
+	status: spanStatus,
+	status_message: z.string().optional(),
+	service_name: nullableString,
+	agent_name: nullableString,
+	model_name: nullableString,
+	tool_name: nullableString,
+	attributes: z.record(z.string(), z.json())
+}).strict();
+const traceSummary = z.object({
+	trace_id: identifier,
+	service_name: nullableString,
+	agent_name: nullableString,
+	span_count: nonNegativeInteger,
+	has_errors: z.boolean(),
+	start_time: timestamp,
+	end_time: timestamp,
+	duration_ms: nonNegativeNumber,
+	raw_jsonl_bytes: nonNegativeInteger,
+	models: stringArray,
+	tools: stringArray
+}).strict();
+const errorCluster = z.object({
+	signature: z.string(),
+	status_message_sample: z.string(),
+	span_name: nullableString,
+	tool_name: nullableString,
+	trace_count: nonNegativeInteger,
+	span_count: nonNegativeInteger,
+	prevalence: z.number().min(0).max(1),
+	exemplar_trace_ids: z.array(identifier),
+	exemplar_span_ids: z.array(identifier)
+}).strict();
+const overview = z.object({
+	total_traces: nonNegativeInteger,
+	raw_jsonl_bytes: nonNegativeInteger,
+	services: stringArray,
+	agents: stringArray,
+	models: stringArray,
+	tool_names: stringArray,
+	sample_trace_ids: z.array(identifier).max(TRACE_ANALYSIS_LIMITS.sampleTraceIds),
+	errors: z.object({
+		trace_count: nonNegativeInteger,
+		span_count: nonNegativeInteger
+	}).strict(),
+	error_clusters: z.array(errorCluster),
+	time_range: z.object({
+		earliest: timestamp,
+		latest: timestamp
+	}).strict().nullable()
+}).strict();
+const tracePage = z.object({
+	traces: z.array(traceSummary),
+	total: nonNegativeInteger,
+	has_more: z.boolean()
+}).strict();
+const oversizedTrace = z.object({
+	span_count: nonNegativeInteger,
+	top_span_names: z.array(z.tuple([z.string(), nonNegativeInteger])).max(20),
+	span_response_bytes_max: nonNegativeInteger,
+	error_span_count: nonNegativeInteger
+}).strict();
+const traceView = z.object({
+	trace_id: identifier,
+	spans: z.array(traceSpan).optional(),
+	oversized: oversizedTrace.optional()
+}).strict().refine((value) => value.spans === void 0 !== (value.oversized === void 0), { message: "exactly one of spans or oversized is required" });
+const spansView = z.object({
+	trace_id: identifier,
+	spans: z.array(traceSpan),
+	missing_span_ids: z.array(identifier),
+	omitted_span_ids: z.array(identifier),
+	has_more: z.boolean(),
+	truncated_attribute_count: nonNegativeInteger
+}).strict();
+const matchRecord = z.object({
+	trace_id: identifier,
+	span_id: identifier,
+	span_name: z.string(),
+	span_kind: spanKind,
+	attribute_path: z.string(),
+	matched_text: z.string(),
+	context_before: z.string(),
+	context_after: z.string(),
+	match_offset: nonNegativeInteger
+}).strict();
+const traceSearch = z.object({
+	trace_id: identifier,
+	hits: z.array(matchRecord),
+	has_more: z.boolean()
+}).strict();
+const spanSearch = traceSearch.extend({ span_id: identifier }).strict();
+const traceStoreOutputSchemas = {
+	hasTrace: z.boolean(),
+	hasSpans: z.array(identifier).max(TRACE_ANALYSIS_LIMITS.viewSpans),
+	getOverview: overview,
+	queryTraces: tracePage,
+	countTraces: nonNegativeInteger,
+	viewTrace: traceView,
+	viewSpans: spansView,
+	searchTrace: traceSearch,
+	searchSpan: spanSearch
+};
+function parseTraceInput(operation, schema, value) {
+	try {
+		return schema.parse(value);
+	} catch (cause) {
+		throw new TraceAnalysisValidationError(`${operation}: invalid arguments: ${cause instanceof z.ZodError ? z.prettifyError(cause) : String(cause)}`, { cause });
+	}
+}
+function parseStoreOutput(operation, schema, value) {
+	try {
+		return schema.parse(value);
+	} catch (cause) {
+		throw new TraceAnalysisStoreContractError(operation, `invalid store result: ${cause instanceof z.ZodError ? z.prettifyError(cause) : String(cause)}`, { cause });
+	}
+}
+function toTraceJsonSchema(schema) {
+	return z.toJSONSchema(schema, { target: "draft-7" });
+}
+//#endregion
+//#region src/trace-analyst/store-boundary.ts
+/** Apply the public validation, cancellation, not-found, and size rules to any adapter. */
+function createBoundedTraceAnalysisStore(source, options = {}) {
+	const budgets = resolveTraceBudgets(options.budgets);
+	return {
+		async hasTrace(traceId, context) {
+			throwIfAborted(context);
+			const { trace_id } = parseTraceInput("hasTrace", traceStoreInputSchemas.hasTrace, { trace_id: traceId });
+			const result = await source.hasTrace(trace_id, context);
+			throwIfAborted(context);
+			return parseStoreOutput("hasTrace", traceStoreOutputSchemas.hasTrace, result);
+		},
+		async hasSpans(input, context) {
+			throwIfAborted(context);
+			const parsed = parseTraceInput("hasSpans", traceStoreInputSchemas.hasSpans, input);
+			assertUniqueIds(parsed.span_ids, "hasSpans.span_ids");
+			const result = await source.hasSpans(parsed, context);
+			throwIfAborted(context);
+			return validateExistingSpanIds(parseStoreOutput("hasSpans", traceStoreOutputSchemas.hasSpans, result), parsed.span_ids);
+		},
+		async getOverview(filters, context) {
+			throwIfAborted(context);
+			const input = parseTraceInput("getOverview", traceStoreInputSchemas.getOverview, { filters });
+			const result = await source.getOverview(input.filters, context);
+			throwIfAborted(context);
+			return boundOverview(parseStoreOutput("getOverview", traceStoreOutputSchemas.getOverview, result), budgets.perCallByteCeiling);
+		},
+		async queryTraces(input, context) {
+			throwIfAborted(context);
+			const parsed = parseTraceInput("queryTraces", traceStoreInputSchemas.queryTraces, input);
+			const offset = parsed.offset ?? 0;
+			const result = await source.queryTraces({
+				...parsed,
+				offset
+			}, context);
+			throwIfAborted(context);
+			return boundTracePage(parseStoreOutput("queryTraces", traceStoreOutputSchemas.queryTraces, result), {
+				limit: parsed.limit,
+				offset
+			}, budgets.perCallByteCeiling);
+		},
+		async countTraces(filters, context) {
+			throwIfAborted(context);
+			const input = parseTraceInput("countTraces", traceStoreInputSchemas.countTraces, { filters });
+			const result = await source.countTraces(input.filters, context);
+			throwIfAborted(context);
+			return parseStoreOutput("countTraces", traceStoreOutputSchemas.countTraces, result);
+		},
+		async viewTrace(input, context) {
+			throwIfAborted(context);
+			const parsed = parseTraceInput("viewTrace", traceStoreInputSchemas.viewTrace, input);
+			await requireTrace(source, parsed.trace_id, context);
+			const perAttributeCap = parsed.per_attribute_byte_cap ?? budgets.perAttributeViewBudget;
+			const result = await source.viewTrace({
+				...parsed,
+				per_attribute_byte_cap: perAttributeCap
+			}, context);
+			throwIfAborted(context);
+			return boundTraceView(parseStoreOutput("viewTrace", traceStoreOutputSchemas.viewTrace, result), parsed.trace_id, perAttributeCap, budgets.perCallByteCeiling);
+		},
+		async viewSpans(input, context) {
+			throwIfAborted(context);
+			const parsed = parseTraceInput("viewSpans", traceStoreInputSchemas.viewSpans, input);
+			assertUniqueIds(parsed.span_ids, "viewSpans.span_ids");
+			await requireTrace(source, parsed.trace_id, context);
+			const existingSpanIds = new Set(validateExistingSpanIds(parseStoreOutput("hasSpans", traceStoreOutputSchemas.hasSpans, await source.hasSpans({
+				trace_id: parsed.trace_id,
+				span_ids: parsed.span_ids
+			}, context)), parsed.span_ids));
+			throwIfAborted(context);
+			const perAttributeCap = parsed.per_attribute_byte_cap ?? budgets.perAttributeSpanBudget;
+			const result = await source.viewSpans({
+				...parsed,
+				per_attribute_byte_cap: perAttributeCap
+			}, context);
+			throwIfAborted(context);
+			return boundSpansView(parseStoreOutput("viewSpans", traceStoreOutputSchemas.viewSpans, result), parsed.trace_id, parsed.span_ids, existingSpanIds, perAttributeCap, budgets.perCallByteCeiling);
+		},
+		async searchTrace(input, context) {
+			throwIfAborted(context);
+			const parsed = parseTraceInput("searchTrace", traceStoreInputSchemas.searchTrace, input);
+			compileSearchRegex(parsed.regex_pattern);
+			await requireTrace(source, parsed.trace_id, context);
+			const result = await source.searchTrace(parsed, context);
+			throwIfAborted(context);
+			return boundTraceSearch(parseStoreOutput("searchTrace", traceStoreOutputSchemas.searchTrace, result), parsed.trace_id, parsed.max_matches, budgets);
+		},
+		async searchSpan(input, context) {
+			throwIfAborted(context);
+			const parsed = parseTraceInput("searchSpan", traceStoreInputSchemas.searchSpan, input);
+			compileSearchRegex(parsed.regex_pattern);
+			await requireTrace(source, parsed.trace_id, context);
+			await requireSpan(source, parsed.trace_id, parsed.span_id, context);
+			const result = await source.searchSpan(parsed, context);
+			throwIfAborted(context);
+			return boundSpanSearch(parseStoreOutput("searchSpan", traceStoreOutputSchemas.searchSpan, result), parsed.trace_id, parsed.span_id, parsed.max_matches, budgets);
+		}
+	};
+}
+async function requireTrace(source, traceId, context) {
+	throwIfAborted(context);
+	const exists = await source.hasTrace(traceId, context);
+	throwIfAborted(context);
+	if (!parseStoreOutput("hasTrace", traceStoreOutputSchemas.hasTrace, exists)) throw new TraceNotFoundError(traceId);
+}
+async function requireSpan(source, traceId, spanId, context) {
+	throwIfAborted(context);
+	const existing = await source.hasSpans({
+		trace_id: traceId,
+		span_ids: [spanId]
+	}, context);
+	throwIfAborted(context);
+	if (validateExistingSpanIds(parseStoreOutput("hasSpans", traceStoreOutputSchemas.hasSpans, existing), [spanId]).length === 0) throw new SpanNotFoundError(traceId, spanId);
+}
+function validateExistingSpanIds(found, requested) {
+	const requestedSet = new Set(requested);
+	const seen = /* @__PURE__ */ new Set();
+	for (const id of found) {
+		if (!requestedSet.has(id)) throw new TraceAnalysisStoreContractError("hasSpans", `hasSpans returned unrequested span id ${JSON.stringify(id)}`);
+		if (seen.has(id)) throw new TraceAnalysisStoreContractError("hasSpans", `hasSpans returned duplicate span id ${JSON.stringify(id)}`);
+		seen.add(id);
+	}
+	return [...found];
+}
+function assertUniqueIds(ids, label) {
+	if (new Set(ids).size !== ids.length) throw new TraceAnalysisValidationError(`${label} must not contain duplicates`);
+}
+function throwIfAborted(context) {
+	context?.signal?.throwIfAborted();
+}
+//#endregion
+//#region src/trace-analyst/tools.ts
+const TRACE_ANALYST_TOOL_NAMESPACE = "traces";
+/** Bind all seven trace reads without exposing an agent framework type. */
+function buildTraceAnalysisToolDescriptors(options) {
+	const store = createBoundedTraceAnalysisStore(options.store, { budgets: options.budgets });
+	return [
+		{
+			namespace: TRACE_ANALYST_TOOL_NAMESPACE,
+			name: "getDatasetOverview",
+			description: "Dataset rollup: total traces, raw_jsonl_bytes, services, agents, models, tools, and sample_trace_ids. Always call this first without a regex_pattern.",
+			parameters: toTraceJsonSchema(traceStoreInputSchemas.getOverview),
+			handler: async (args, context) => {
+				const { filters } = parseTraceInput("getDatasetOverview", traceStoreInputSchemas.getOverview, args ?? {});
+				return store.getOverview(filters, context);
+			}
+		},
+		{
+			namespace: TRACE_ANALYST_TOOL_NAMESPACE,
+			name: "queryTraces",
+			description: `Paginated trace summaries, at most ${TRACE_ANALYSIS_LIMITS.queryTraces} per call. Each summary carries raw_jsonl_bytes; narrow with indexed filters before regex_pattern.`,
+			parameters: toTraceJsonSchema(traceStoreInputSchemas.queryTraces),
+			handler: async (args, context) => {
+				const input = parseTraceInput("queryTraces", traceStoreInputSchemas.queryTraces, args);
+				return store.queryTraces(input, context);
+			}
+		},
+		{
+			namespace: TRACE_ANALYST_TOOL_NAMESPACE,
+			name: "countTraces",
+			description: "Count traces matching filters. Use as a cheap pre-flight before a regex_pattern scan.",
+			parameters: toTraceJsonSchema(traceStoreInputSchemas.countTraces),
+			handler: async (args, context) => {
+				const { filters } = parseTraceInput("countTraces", traceStoreInputSchemas.countTraces, args ?? {});
+				return store.countTraces(filters, context);
+			}
+		},
+		{
+			namespace: TRACE_ANALYST_TOOL_NAMESPACE,
+			name: "viewTrace",
+			description: "Return all spans for one trace with bounded attributes. Oversized responses carry an oversized summary instead of spans; continue with searchTrace or viewSpans.",
+			parameters: toTraceJsonSchema(traceStoreInputSchemas.viewTrace.omit({ per_attribute_byte_cap: true })),
+			handler: async (args, context) => {
+				const input = parseTraceInput("viewTrace", traceStoreInputSchemas.viewTrace.omit({ per_attribute_byte_cap: true }), args);
+				return store.viewTrace(input, context);
+			}
+		},
+		{
+			namespace: TRACE_ANALYST_TOOL_NAMESPACE,
+			name: "viewSpans",
+			description: `Read 1..${TRACE_ANALYSIS_LIMITS.viewSpans} specific spans. Every requested id is accounted for in spans, missing_span_ids, or omitted_span_ids; retry omitted ids.`,
+			parameters: toTraceJsonSchema(traceStoreInputSchemas.viewSpans.omit({ per_attribute_byte_cap: true })),
+			handler: async (args, context) => {
+				const input = parseTraceInput("viewSpans", traceStoreInputSchemas.viewSpans.omit({ per_attribute_byte_cap: true }), args);
+				return store.viewSpans(input, context);
+			}
+		},
+		{
+			namespace: TRACE_ANALYST_TOOL_NAMESPACE,
+			name: "searchTrace",
+			description: `Regex search across one trace, bounded to ${TRACE_ANALYSIS_LIMITS.searchMatches} hits. When has_more is true, refine the regex instead of treating the result as complete.`,
+			parameters: toTraceJsonSchema(traceStoreInputSchemas.searchTrace),
+			handler: async (args, context) => {
+				const input = parseTraceInput("searchTrace", traceStoreInputSchemas.searchTrace, args);
+				return store.searchTrace(input, context);
+			}
+		},
+		{
+			namespace: TRACE_ANALYST_TOOL_NAMESPACE,
+			name: "searchSpan",
+			description: `Regex search inside one span, bounded to ${TRACE_ANALYSIS_LIMITS.searchMatches} hits. Use after viewSpans omits or truncates a large span payload.`,
+			parameters: toTraceJsonSchema(traceStoreInputSchemas.searchSpan),
+			handler: async (args, context) => {
+				const input = parseTraceInput("searchSpan", traceStoreInputSchemas.searchSpan, args);
+				return store.searchSpan(input, context);
+			}
+		}
+	];
+}
+function traceAnalystFunctionGroup(options) {
+	return {
+		namespace: TRACE_ANALYST_TOOL_NAMESPACE,
+		title: "Trace Analysis",
+		selectionCriteria: "Use for any inspection of OTLP-shaped trace data.",
+		description: "Discovery, narrowing, and bounded deep reads over a JSONL trace dataset. Always call getDatasetOverview first.",
+		functions: buildTraceAnalysisToolDescriptors(options)
+	};
+}
+//#endregion
+//#region src/analyst/tool-groups.ts
+const TOOL_NAMES_BY_GROUP = {
+	all: /* @__PURE__ */ new Set(),
+	discovery: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"queryTraces",
+		"countTraces"
+	]),
+	discoveryAndRead: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"queryTraces",
+		"countTraces",
+		"viewTrace",
+		"viewSpans"
+	]),
+	discoveryAndSearch: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"queryTraces",
+		"countTraces",
+		"searchTrace",
+		"searchSpan"
+	]),
+	targeted: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"queryTraces",
+		"viewSpans",
+		"searchSpan"
+	]),
+	singleTrace: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"viewTrace",
+		"viewSpans",
+		"searchTrace",
+		"searchSpan"
+	])
+};
+/**
+* Build the tool set for a named group bound to a specific trace store.
+*
+* `all` returns every tool. Other groups filter the canonical descriptors
+* by name to the documented subset. An unrecognised group name throws —
+* silently returning all tools would defeat the cost-control point.
+*/
+function buildTraceToolsForGroup(group, store) {
+	const all = buildTraceAnalysisToolDescriptors({ store });
+	if (group === "all") return all;
+	const allow = TOOL_NAMES_BY_GROUP[group];
+	if (!allow) throw new Error(`unknown trace tool group: ${group}`);
+	return all.filter((tool) => allow.has(tool.name));
+}
+//#endregion
+//#region src/analyst/kind-factory.ts
+/** Run one definition and retain its answer, findings, and full investigation record. */
+async function runTraceAnalyst(args) {
+	const { definition, context } = args;
+	validateDefinition(definition);
+	const minimumEvidenceCitations = definition.minimumEvidenceCitations ?? 1;
+	const settlementTimeoutMs = validateUsageSettlementTimeout(args.settlementTimeoutMs);
+	const costLedger = context.costLedger ?? new CostLedger(context.budgetUsd);
+	const costTags = {
+		...context.tags ?? {},
+		analystId: definition.id,
+		...context.correlationId ? { analystRunId: context.correlationId } : {}
+	};
+	try {
+		const preparedContext = await definition.prepareContext?.(args.store, context);
+		if (preparedContext !== void 0 && typeof preparedContext !== "string") throw new TypeError(`trace analyst '${definition.id}' prepareContext must return a string`);
+		const instructions = [
+			definition.instructions.trim(),
+			renderPriorFindings(context.priorFindings),
+			renderUpstreamFindings(context.upstreamFindings),
+			RAW_FINDING_SCHEMA_PROMPT,
+			minimumEvidenceCitations > 1 ? `Every finding requires at least ${minimumEvidenceCitations} distinct evidence citations.` : "",
+			preparedContext ? `PREPARED CONTEXT:\n${preparedContext}` : "",
+			"Return a direct prose answer and a strict findings array. Use trace tools to investigate. Do not infer trace facts from the question alone."
+		].filter(Boolean).join("\n\n");
+		const completed = await args.engine.analyze({
+			analystId: definition.id,
+			question: deriveQuestion(context, definition),
+			instructions,
+			tools: buildTraceToolsForGroup(definition.toolGroup, args.store),
+			limits: resolveTraceAnalystLimits(definition.limits),
+			costLedger,
+			costPhase: context.costPhase ?? "trace-analysis",
+			costTags,
+			...context.signal ? { signal: context.signal } : {},
+			...context.log ? { log: context.log } : {}
+		});
+		const findings = await acceptFindings(definition, completed.findings, args.store, context, minimumEvidenceCitations);
+		if (definition.requireStructuredFindings && findings.length === 0) throw new Error(`trace analyst '${definition.id}' returned no valid structured findings: ${truncateForContext(completed.answer, 600)}`);
+		context.log?.(`trace analyst ${definition.id} completed`, {
+			engine: args.engine.id,
+			model_calls: completed.modelCalls,
+			tool_calls: completed.toolCalls,
+			submitted_findings: completed.findings.length,
+			accepted_findings: findings.length
+		});
+		return {
+			...completed,
+			findings
+		};
+	} finally {
+		const usage = await settleUsageReceiptFromCostLedger(costLedger, {
+			channel: "analyst",
+			tags: costTags,
+			timeoutMs: settlementTimeoutMs
+		});
+		if (!usage.settled) context.log?.(`trace analyst ${definition.id} provider settlement timed out`, {
+			pending_calls: usage.pendingCalls,
+			timeout_ms: settlementTimeoutMs
+		});
+		context.recordUsage?.(usage.receipt);
+	}
+}
+/** Adapt a research definition to the common Analyst registry contract. */
+function createTraceAnalyst(definition, options) {
+	validateDefinition(definition);
+	const version = options.versionSuffix ? `${definition.version}+${options.versionSuffix}` : definition.version;
+	const settlementTimeoutMs = validateUsageSettlementTimeout(options.settlementTimeoutMs);
+	const limits = resolveTraceAnalystLimits(definition.limits);
+	const engineIdentity = snapshotExactExecutionComponentIdentity({
+		id: options.engine.id,
+		version: options.engine.version,
+		config: options.engine.executionConfig
+	}, "createTraceAnalyst engine");
+	return {
+		id: definition.id,
+		description: definition.description,
+		inputKind: "trace-store",
+		cost: {
+			kind: "llm",
+			...options.engine.model ? { models: [options.engine.model] } : {},
+			settlement_timeout_ms: settlementTimeoutMs
+		},
+		version,
+		executionConfig: {
+			kind: "trace-analyst",
+			model: options.engine.model ?? null,
+			engine: options.engine.id,
+			engine_identity: engineIdentity,
+			instructions_digest: hashCanonical(definition.instructions.trim()),
+			question: typeof definition.question === "string" ? hashCanonical(definition.question.trim()) : definition.question === void 0 ? "context-derived" : "version-bound",
+			tool_group: definition.toolGroup,
+			max_iterations: limits.maxIterations,
+			max_llm_calls: limits.maxLlmCalls,
+			max_tool_calls: limits.maxToolCalls,
+			max_output_chars: limits.maxOutputChars,
+			minimum_evidence_citations: definition.minimumEvidenceCitations ?? 1,
+			require_structured_findings: definition.requireStructuredFindings ?? false,
+			prepare_context: definition.prepareContext === void 0 ? "disabled" : "version-bound",
+			post_process: definition.postProcess === void 0 ? "disabled" : "version-bound",
+			evidence_verification: EVIDENCE_VERIFICATION_VERSION,
+			settlement_timeout_ms: settlementTimeoutMs
+		},
+		async analyze(store, context) {
+			const completed = await runTraceAnalyst({
+				definition,
+				engine: options.engine,
+				store,
+				context,
+				settlementTimeoutMs: options.settlementTimeoutMs
+			});
+			return completed.findings.map((finding) => toAnalystFinding(definition, version, finding, {
+				analysis_engine: options.engine.id,
+				analysis_model: options.engine.model,
+				analysis_model_calls: completed.modelCalls,
+				analysis_tool_calls: completed.toolCalls,
+				analysis_runtime: completed.runtime
+			}));
+		}
+	};
+}
+async function acceptFindings(definition, submitted, store, context, minimumEvidenceCitations) {
+	const expectedSubjects = KIND_EXPECTED_SUBJECTS[definition.id];
+	const accepted = [];
+	for (const row of submitted) {
+		const parsed = parseRawFinding(row, context.log);
+		if (!parsed) continue;
+		const processed = definition.postProcess ? definition.postProcess(parsed, context) : parsed;
+		if (!processed) continue;
+		const validated = parseRawFinding(processed, context.log);
+		if (!validated) continue;
+		if (expectedSubjects && validated.subject !== void 0) {
+			const subject = parseFindingSubject(validated.subject);
+			if (subject === null || !expectedSubjects.includes(subject.kind)) {
+				context.log?.("finding rejected: subject is not valid for analyst", {
+					analyst_id: definition.id,
+					subject: validated.subject,
+					allowed: expectedSubjects
+				});
+				continue;
+			}
+		}
+		const distinctEvidence = new Set(validated.evidence.map((citation) => citation.uri.trim())).size;
+		if (distinctEvidence < minimumEvidenceCitations) {
+			context.log?.("finding rejected: insufficient evidence citations", {
+				analyst_id: definition.id,
+				required: minimumEvidenceCitations,
+				distinct: distinctEvidence
+			});
+			continue;
+		}
+		if (!await evidenceIsResolvable(validated, store, context)) continue;
+		accepted.push(validated);
+	}
+	return accepted;
+}
+async function evidenceIsResolvable(finding, store, context) {
+	const knownFindings = new Map([...context.priorFindings ?? [], ...context.upstreamFindings ?? []].map((entry) => [entry.finding_id, entry]));
+	for (const citation of finding.evidence) {
+		if (citation.excerpt !== void 0 && citation.excerpt.trim().length < MINIMUM_EXCERPT_LENGTH) {
+			rejectEvidence(context, citation.uri, "excerpt is too short to verify");
+			return false;
+		}
+		const traceLocation = parseTraceSpanEvidenceUri(citation.uri);
+		if (traceLocation) {
+			const storeContext = context.signal ? { signal: context.signal } : void 0;
+			if (!(await store.hasSpans({
+				trace_id: traceLocation.traceId,
+				span_ids: [traceLocation.spanId]
+			}, storeContext)).includes(traceLocation.spanId)) {
+				rejectEvidence(context, citation.uri, "trace span does not exist");
+				return false;
+			}
+			if (citation.excerpt !== void 0) {
+				const span = (await store.viewSpans({
+					trace_id: traceLocation.traceId,
+					span_ids: [traceLocation.spanId]
+				}, storeContext)).spans.find((entry) => entry.span_id === traceLocation.spanId);
+				if (!span || !containsExactText([span.attributes, span.status_message], citation.excerpt)) {
+					rejectEvidence(context, citation.uri, "excerpt is not present in the cited span content");
+					return false;
+				}
+			}
+			continue;
+		}
+		const findingId = parseFindingEvidenceUri(citation.uri);
+		const referenced = findingId ? knownFindings.get(findingId) : void 0;
+		if (!referenced) {
+			rejectEvidence(context, citation.uri, "citation is not a supplied finding or trace span");
+			return false;
+		}
+		if (citation.excerpt !== void 0 && !containsExactText([
+			referenced.claim,
+			referenced.rationale,
+			referenced.recommended_action,
+			referenced.validation_plan,
+			referenced.evidence_refs?.map((evidence) => evidence.excerpt)
+		], citation.excerpt)) {
+			rejectEvidence(context, citation.uri, "excerpt is not present in the cited finding content");
+			return false;
+		}
+	}
+	return true;
+}
+function parseFindingEvidenceUri(uri) {
+	const match = /^finding:\/\/([^/?#]+)$/.exec(uri);
+	if (!match) return null;
+	try {
+		return decodeURIComponent(match[1]) || null;
+	} catch {
+		return null;
+	}
+}
+/** Excerpts must quote enough content to be checkable evidence, not an
+*  incidental substring of an id, status, or timestamp. */
+const MINIMUM_EXCERPT_LENGTH = 8;
+/** Bumped whenever the evidence-acceptance rules change, so two differently
+*  strict builds cannot seal identical execution plans. */
+const EVIDENCE_VERIFICATION_VERSION = "resolvable-excerpt-v1";
+/** Matches only within the passed content-bearing values — callers must not
+*  hand this whole spans or findings, or identifier fields become quotable. */
+function containsExactText(value, expected, depth = 0) {
+	if (!expected || depth > 20) return false;
+	if (typeof value === "string") return value.includes(expected);
+	if (Array.isArray(value)) return value.some((entry) => containsExactText(entry, expected, depth + 1));
+	if (typeof value === "object" && value !== null) return Object.values(value).some((entry) => containsExactText(entry, expected, depth + 1));
+	return false;
+}
+function rejectEvidence(context, uri, reason) {
+	context.log?.("finding rejected: unresolved evidence", {
+		uri,
+		reason
+	});
+}
+function validateDefinition(definition) {
+	for (const [name, value] of [
+		["id", definition.id],
+		["description", definition.description],
+		["area", definition.area],
+		["version", definition.version],
+		["instructions", definition.instructions]
+	]) if (typeof value !== "string" || !value.trim()) throw new TypeError(`trace analyst ${name} must be a non-empty string`);
+	const minimumEvidenceCitations = definition.minimumEvidenceCitations ?? 1;
+	if (!Number.isSafeInteger(minimumEvidenceCitations) || minimumEvidenceCitations < 1) throw new TypeError("minimumEvidenceCitations must be a positive safe integer");
+	resolveTraceAnalystLimits(definition.limits);
+}
+function deriveQuestion(context, definition) {
+	const base = (typeof definition.question === "function" ? definition.question(context) : definition.question)?.trim() || `Analyze this trace dataset and report ${definition.area} findings. ${definition.description}`;
+	const focus = context.tags?.focus?.trim();
+	return focus ? `${base}\nFocus: ${focus}` : base;
+}
+function toAnalystFinding(definition, version, raw, metadata) {
+	return makeFinding({
+		analyst_id: definition.id,
+		area: definition.area,
+		subject: raw.subject,
+		claim: raw.claim,
+		rationale: raw.rationale,
+		severity: raw.severity,
+		confidence: raw.confidence,
+		evidence_refs: evidenceRefsFromRawFinding(raw),
+		recommended_action: raw.recommended_action,
+		metadata: {
+			definition_version: version,
+			...metadata
+		}
+	});
+}
+function renderPriorFindings(prior) {
+	if (!prior || prior.length === 0) return "";
+	const maxRows = 40;
+	const rows = prior.slice(0, maxRows).map((finding) => {
+		const subject = finding.subject ? ` [${finding.subject}]` : "";
+		return `- id=${finding.finding_id} ${finding.severity}${subject} ${truncateForContext(finding.claim, 160)}`;
+	});
+	if (prior.length > maxRows) rows.push(`- ${prior.length - maxRows} older findings omitted`);
+	return [
+		"PRIOR FINDINGS:",
+		"Reuse a matching finding id through id_basis and raise confidence only when current evidence confirms recurrence.",
+		...rows
+	].join("\n");
+}
+function renderUpstreamFindings(upstream) {
+	if (!upstream || upstream.length === 0) return "";
+	const maxRows = 40;
+	const rows = upstream.slice(0, maxRows).map((finding) => {
+		const subject = finding.subject ? ` [${finding.subject}]` : "";
+		const evidence = finding.evidence_refs[0]?.uri ? ` evidence=${truncateForContext(finding.evidence_refs[0].uri, 120)}` : "";
+		return `- id=${finding.finding_id} source=${finding.analyst_id} ${finding.severity}${subject} claim=${truncateForContext(finding.claim, 160)}${evidence}`;
+	});
+	if (upstream.length > maxRows) rows.push(`- ${upstream.length - maxRows} additional upstream findings omitted`);
+	return [
+		"UPSTREAM FINDINGS:",
+		"Build on these findings instead of repeating them. Cite dependencies as finding://<id>.",
+		...rows
+	].join("\n");
+}
+function truncateForContext(value, max) {
+	if (value.length <= max) return value;
+	return `${value.slice(0, max - 3).trimEnd()}...`;
+}
+//#endregion
+export { spanEpochMillis as $, coerceJson as A, renderFindingSubject as B, TraceNotFoundError as C, RawAnalystFindingSchema as D, RawAnalystEvidenceSchema as E, FINDING_SUBJECT_SYNTAX as F, resolveTraceAnalystLimits as G, snapshotExactExecutionPlan as H, FindingSubjectStringSchema as I, extractOtlpAttributes as J, asString as K, KIND_EXPECTED_SUBJECTS as L, stripCodeFences as M, FINDING_SUBJECT_GRAMMAR_PROMPT as N, evidenceRefsFromRawFinding as O, FINDING_SUBJECT_KINDS as P, readOtlpStatus as Q, findingSubjectGrammarPromptFor as R, TraceFileTooLargeError as S, RAW_FINDING_SCHEMA_PROMPT as T, deepFreezeCanonicalJson as U, snapshotExactExecutionComponentIdentity as V, DEFAULT_TRACE_ANALYST_LIMITS as W, inferOtlpKind as X, firstStringAttr as Y, projectOtlpFlatLine as Z, TraceAnalysisLimitError as _, buildTraceToolsForGroup as a, TraceFileMalformedError as b, traceAnalystFunctionGroup as c, truncateForBudget as d, stringField as et, validateInteger as f, SpanNotFoundError as g, TRACE_ANALYSIS_LIMITS as h, runTraceAnalyst as i, traceSpanKindToOpenInferenceKind as it, coerceToFindingRows as j, parseRawFinding as k, createBoundedTraceAnalysisStore as l, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX as m, renderPriorFindings as n, classifyOtlpSpanRole as nt, TRACE_ANALYST_TOOL_NAMESPACE as o, DEFAULT_TRACE_ANALYST_BUDGETS as p, compareSpanTime as q, renderUpstreamFindings as r, isOtlpModelCall as rt, buildTraceAnalysisToolDescriptors as s, createTraceAnalyst as t, applyToolSpanOtlpAttributes as tt, compileSearchRegex as u, TraceAnalysisStoreContractError as v, ANALYST_SEVERITIES as w, TraceFileMissingError as x, TraceAnalysisValidationError as y, parseFindingSubject as z };
+
+//# sourceMappingURL=kind-factory-CFxA0JQX.js.map