@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/evidence/index.ts

@@ -0,0 +1,55 @@
+export type { BuildEvidenceOptions } from "./build.js";
+export { buildEvidence } from "./build.js";
+export type { BuildEvalEvidenceOptions } from "./eval.js";
+export { buildEvalEvidence, evalEvidenceId } from "./eval.js";
+export { FINISH_CONTRACT_EVIDENCE_TAGS, finishContractEvidenceTags } from "./finish-contract-map.js";
+export type { RunEscalationCounts, RunProvenanceView } from "./provenance.js";
+export {
+	extractRunProvenance,
+	hasRunProvenance,
+	PERSONA_HASH_PREFIX_CHARS,
+	provenanceCompactSuffix,
+	provenanceTranscriptLines,
+} from "./provenance.js";
+export type { EvidenceRunProvenance } from "./store.js";
+export {
+	EVIDENCE_FILES,
+	EvidenceNotFoundError,
+	evidenceDirectory,
+	inspectEvidence,
+	listEvidenceOverviews,
+	loadEvidenceGateDecisions,
+	loadEvidenceRunProvenance,
+} from "./store.js";
+export type {
+	EvidenceAuditLinkedRow,
+	EvidenceBuildResult,
+	EvidenceCleanTraceRow,
+	EvidenceEvalCommandTraceRow,
+	EvidenceEvalRawTraceRow,
+	EvidenceEvalTraceRow,
+	EvidenceFinding,
+	EvidenceFindingsFile,
+	EvidenceGateDecisionsFile,
+	EvidenceInspectable,
+	EvidenceLinkConfidence,
+	EvidenceOverview,
+	EvidenceProtectedArtifactEvent,
+	EvidenceProtectedArtifactsFile,
+	EvidenceRawTraceRow,
+	EvidenceReceiptFile,
+	EvidenceRunSource,
+	EvidenceSeverity,
+	EvidenceSource,
+	EvidenceTag,
+	EvidenceToolEvent,
+	EvidenceToolEventSource,
+	EvidenceTotals,
+	FailureCauseTag,
+} from "./types.js";
+export {
+	EVIDENCE_TAGS,
+	EVIDENCE_VERSION,
+	FAILURE_CAUSE_TAG_ORDER,
+	FAILURE_CAUSE_TAGS,
+} from "./types.js";

package/src/domains/evidence/provenance.ts

@@ -0,0 +1,200 @@
+import type {
+	RunPersonaOverride,
+	RunPipelineProvenance,
+	RunReceipt,
+	RunReceiptAutonomyEnforcement,
+} from "../dispatch/types.js";
+
+/**
+ * Worker permission-escalation counters projected from sealed receipt
+ * provenance. Renderers omit this view when no escalation was requested.
+ * Optional outcome counters default to zero until the receipt schema makes
+ * every escalation counter required.
+ */
+export interface RunEscalationCounts {
+	requested: number;
+	approved: number;
+	denied: number;
+	timedOut: number;
+}
+
+/**
+ * The sealed receipt provenance that evidence and dispatch surfaces render.
+ * Each field is present only when the receipt carries it. Renderers omit
+ * provenance output when none of these fields are present.
+ */
+export interface RunProvenanceView {
+	pipeline?: RunPipelineProvenance;
+	personaOverride?: RunPersonaOverride;
+	escalation?: RunEscalationCounts;
+	autonomyEnforcement?: RunReceiptAutonomyEnforcement;
+}
+
+/** The receipt fields the provenance view reads; a narrow slice of RunReceipt. */
+type ProvenanceReceipt = Pick<RunReceipt, "pipeline" | "personaOverride" | "safety" | "autonomyEnforcement">;
+
+/** Number of leading hash characters shown as a persona-override prompt-hash prefix. */
+export const PERSONA_HASH_PREFIX_CHARS = 12;
+
+/**
+ * Read provenance from a sealed receipt shape. This reads optional fields
+ * without mutating the receipt and returns an empty view when none are present.
+ */
+export function extractRunProvenance(receipt: ProvenanceReceipt): RunProvenanceView {
+	const view: RunProvenanceView = {};
+	if (receipt.pipeline !== undefined) view.pipeline = receipt.pipeline;
+	if (receipt.personaOverride !== undefined) view.personaOverride = receipt.personaOverride;
+	const escalation = escalationCountsFrom(receipt.safety);
+	if (escalation !== null) view.escalation = escalation;
+	if (receipt.autonomyEnforcement !== undefined) view.autonomyEnforcement = receipt.autonomyEnforcement;
+	return view;
+}
+
+/** True when at least one provenance field set is present. */
+export function hasRunProvenance(view: RunProvenanceView): boolean {
+	return (
+		view.pipeline !== undefined ||
+		view.personaOverride !== undefined ||
+		view.escalation !== undefined ||
+		view.autonomyEnforcement !== undefined
+	);
+}
+
+/**
+ * Defensively read a provenance view off a raw receipt JSON value (a
+ * `receipt.json` bundle entry). Unlike {@link extractRunProvenance}, this
+ * validates each field so a malformed or partial receipt yields an empty view
+ * instead of throwing. Used by CLI surfaces that read the bundle back.
+ */
+export function runProvenanceFromUnknown(value: unknown): RunProvenanceView {
+	if (!isRecord(value)) return {};
+	const view: RunProvenanceView = {};
+	const pipeline = pipelineFromUnknown(value.pipeline);
+	if (pipeline !== null) view.pipeline = pipeline;
+	const personaOverride = personaOverrideFromUnknown(value.personaOverride);
+	if (personaOverride !== null) view.personaOverride = personaOverride;
+	const escalation = escalationFromUnknown(value.safety);
+	if (escalation !== null) view.escalation = escalation;
+	const autonomyEnforcement = autonomyEnforcementFromUnknown(value.autonomyEnforcement);
+	if (autonomyEnforcement !== null) view.autonomyEnforcement = autonomyEnforcement;
+	return view;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function finiteNumber(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function pipelineFromUnknown(value: unknown): RunPipelineProvenance | null {
+	if (!isRecord(value)) return null;
+	const position = finiteNumber(value.position);
+	const inputBytes = finiteNumber(value.inputBytes);
+	if (position === null || inputBytes === null) return null;
+	const fromRunId = typeof value.fromRunId === "string" ? value.fromRunId : null;
+	return { fromRunId, position, inputBytes, inputTruncated: value.inputTruncated === true };
+}
+
+function personaOverrideFromUnknown(value: unknown): RunPersonaOverride | null {
+	if (!isRecord(value) || typeof value.promptHash !== "string" || value.promptHash.length === 0) return null;
+	return { promptHash: value.promptHash };
+}
+
+function autonomyEnforcementFromUnknown(value: unknown): RunReceiptAutonomyEnforcement | null {
+	if (!isRecord(value)) return null;
+	if (value.grade !== "mediated" && value.grade !== "approximated" && value.grade !== "bypassed") return null;
+	if (typeof value.autonomy !== "string" || value.autonomy.length === 0) return null;
+	const view: RunReceiptAutonomyEnforcement = { grade: value.grade, autonomy: value.autonomy };
+	if (typeof value.externalMode === "string" && value.externalMode.length > 0) view.externalMode = value.externalMode;
+	if (typeof value.dangerousBypass === "boolean") view.dangerousBypass = value.dangerousBypass;
+	return view;
+}
+
+function escalationFromUnknown(safety: unknown): RunEscalationCounts | null {
+	if (!isRecord(safety)) return null;
+	const decisions = safety.decisions;
+	if (!isRecord(decisions)) return null;
+	const requested = finiteNumber(decisions.escalationRequested);
+	if (requested === null) return null;
+	return {
+		requested,
+		approved: finiteNumber(decisions.escalationApproved) ?? 0,
+		denied: finiteNumber(decisions.escalationDenied) ?? 0,
+		timedOut: finiteNumber(decisions.escalationTimedOut) ?? 0,
+	};
+}
+
+function escalationCountsFrom(safety: RunReceipt["safety"]): RunEscalationCounts | null {
+	const decisions = safety?.decisions;
+	if (decisions === undefined || decisions.escalationRequested === undefined) return null;
+	return {
+		requested: decisions.escalationRequested,
+		approved: decisions.escalationApproved ?? 0,
+		denied: decisions.escalationDenied ?? 0,
+		timedOut: decisions.escalationTimedOut ?? 0,
+	};
+}
+
+/** Leading prefix of a persona-override prompt hash, with an ellipsis when clipped. */
+function formatPersonaHashPrefix(promptHash: string): string {
+	if (promptHash.length <= PERSONA_HASH_PREFIX_CHARS) return promptHash;
+	return `${promptHash.slice(0, PERSONA_HASH_PREFIX_CHARS)}...`;
+}
+
+/**
+ * Human transcript sentences for each present provenance field set.
+ * An empty view adds no lines to the transcript run section.
+ */
+export function provenanceTranscriptLines(view: RunProvenanceView): string[] {
+	const lines: string[] = [];
+	if (view.pipeline !== undefined) {
+		const { fromRunId, position, inputBytes, inputTruncated } = view.pipeline;
+		const source = fromRunId ?? "unknown";
+		const truncation = inputTruncated ? "input truncated" : "not truncated";
+		lines.push(`pipeline: step ${position}, input ${inputBytes} bytes from ${source} (${truncation})`);
+	}
+	if (view.personaOverride !== undefined) {
+		lines.push(`persona override: prompt hash ${formatPersonaHashPrefix(view.personaOverride.promptHash)}`);
+	}
+	if (view.escalation !== undefined) {
+		const { requested, approved, denied, timedOut } = view.escalation;
+		lines.push(`escalations: ${requested} requested, ${approved} approved, ${denied} denied, ${timedOut} timed out`);
+	}
+	if (view.autonomyEnforcement !== undefined) {
+		const { grade, autonomy, externalMode, dangerousBypass } = view.autonomyEnforcement;
+		const mode = externalMode !== undefined ? ` mode=${externalMode}` : "";
+		const bypass = dangerousBypass === true ? " dangerousBypass=true" : "";
+		lines.push(`autonomy enforcement: ${grade} autonomy=${autonomy}${mode}${bypass}`);
+	}
+	return lines;
+}
+
+/**
+ * Compact ` key=value` suffix for the dispatch tool's per-run and CLI lines.
+ * The leading space lets callers append it directly. An empty provenance view
+ * returns an empty string.
+ */
+export function provenanceCompactSuffix(view: RunProvenanceView): string {
+	const parts: string[] = [];
+	if (view.pipeline !== undefined) {
+		const { fromRunId, position, inputBytes, inputTruncated } = view.pipeline;
+		const from = fromRunId ?? "unknown";
+		parts.push(`pipeline=step${position} from=${from} in=${inputBytes}b${inputTruncated ? " truncated" : ""}`);
+	}
+	if (view.personaOverride !== undefined) {
+		parts.push(`persona=${formatPersonaHashPrefix(view.personaOverride.promptHash)}`);
+	}
+	if (view.escalation !== undefined) {
+		const { requested, approved, denied, timedOut } = view.escalation;
+		parts.push(`escalations=${requested}req/${approved}appr/${denied}deny/${timedOut}timeout`);
+	}
+	if (view.autonomyEnforcement !== undefined) {
+		const { grade, autonomy, externalMode, dangerousBypass } = view.autonomyEnforcement;
+		const mode = externalMode !== undefined ? `/${externalMode}` : "";
+		const bypass = dangerousBypass === true ? "/bypass" : "";
+		parts.push(`enforcement=${grade}:${autonomy}${mode}${bypass}`);
+	}
+	return parts.length === 0 ? "" : ` ${parts.join(" ")}`;
+}

package/src/domains/evidence/redact.ts

@@ -0,0 +1,81 @@
+/**
+ * Export-boundary secret redaction. Applied when an evidence bundle is built
+ * (cold path), never during live turns: previews, transcript text, and
+ * receipt payloads are scrubbed before serialization so a leaked value stops
+ * at the machine boundary. Raw session files stay untouched; the bundle is
+ * the boundary, and its overview records how much was filtered so the bundle
+ * stays truthful about its own redaction.
+ */
+
+export interface RedactionTally {
+	count: number;
+}
+
+export function createRedactionTally(): RedactionTally {
+	return { count: 0 };
+}
+
+interface SecretPattern {
+	kind: string;
+	re: RegExp;
+}
+
+/**
+ * Value-shaped secrets, matched on content alone. Deliberately conservative:
+ * each pattern targets a documented credential format, plus one generic
+ * key/token/secret/password assignment shape. Audit rows already get
+ * key-name-based redaction at write time; this pass catches values that
+ * escaped into free text, command output, or tool arguments.
+ */
+const SECRET_PATTERNS: ReadonlyArray<SecretPattern> = [
+	{
+		kind: "pem",
+		re: /-----BEGIN [A-Z0-9 ]*(?:PRIVATE KEY|PRIVATE KEY BLOCK)-----[\s\S]*?(?:-----END [A-Z0-9 ]*(?:PRIVATE KEY|PRIVATE KEY BLOCK)-----|$)/g,
+	},
+	{ kind: "aws-access-key", re: /\bAKIA[0-9A-Z]{16}\b/g },
+	{ kind: "github-token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g },
+	{ kind: "github-token", re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g },
+	{ kind: "sk-key", re: /\bsk-(?:[A-Za-z0-9_-]{2,20}-)?[A-Za-z0-9_-]{16,}\b/g },
+	{ kind: "slack-token", re: /\bxox[bpars]-[A-Za-z0-9-]{8,}\b/g },
+	{ kind: "google-api-key", re: /\bAIza[0-9A-Za-z_-]{30,}\b/g },
+	{ kind: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}\b/g },
+	{
+		kind: "assignment",
+		// KEY=value / key: value / "api_key": "value" shapes where the key name
+		// is secret-flavored and the value is long enough to be a credential.
+		re: /\b((?:[A-Za-z0-9_-]*(?:api[_-]?key|apikey|secret|token|passwd|password|credential)[A-Za-z0-9_-]*)\s*["']?\s*[:=]\s*["']?)([^\s"'`;,&|<>]{8,})/gi,
+	},
+];
+
+/** Replace every secret-shaped value in `text`, tallying replacements. */
+export function redactSecretsText(text: string, tally: RedactionTally): string {
+	let out = text;
+	for (const pattern of SECRET_PATTERNS) {
+		out = out.replace(pattern.re, (...match: unknown[]) => {
+			tally.count += 1;
+			if (pattern.kind === "assignment") {
+				// Keep the key and separator; replace only the value.
+				return `${String(match[1])}[redacted:${pattern.kind}]`;
+			}
+			return `[redacted:${pattern.kind}]`;
+		});
+	}
+	return out;
+}
+
+/**
+ * Deep-redact every string in a JSON-shaped value. Arrays and plain objects
+ * are walked; other object types (dates, buffers) pass through untouched.
+ */
+export function redactSecretsDeep<T>(value: T, tally: RedactionTally): T {
+	if (typeof value === "string") return redactSecretsText(value, tally) as unknown as T;
+	if (Array.isArray(value)) return value.map((item) => redactSecretsDeep(item, tally)) as unknown as T;
+	if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+		const out: Record<string, unknown> = {};
+		for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+			out[key] = redactSecretsDeep(item, tally);
+		}
+		return out as unknown as T;
+	}
+	return value;
+}

package/src/domains/evidence/store.ts

@@ -0,0 +1,291 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { assertSafeId } from "../../core/safe-id.js";
+import { type GateDecisionArtifact, verifyGateDecisionArtifact } from "../dispatch/index.js";
+import { hasRunProvenance, type RunProvenanceView, runProvenanceFromUnknown } from "./provenance.js";
+import type { EvidenceFinding, EvidenceFindingsFile, EvidenceInspectable, EvidenceOverview } from "./types.js";
+
+export const EVIDENCE_FILES = [
+	"overview.json",
+	"transcript.md",
+	"trace.raw.jsonl",
+	"trace.cleaned.jsonl",
+	"tool-events.jsonl",
+	"audit-linked.jsonl",
+	"receipt.json",
+	"gate-decisions.json",
+	"protected-artifacts.json",
+	"findings.json",
+	"findings.md",
+] as const;
+
+function evidenceRoot(dataDir: string): string {
+	return join(dataDir, "evidence");
+}
+
+export function evidenceDirectory(dataDir: string, evidenceId: string): string {
+	assertSafeId(evidenceId, "evidence");
+	return join(evidenceRoot(dataDir), evidenceId);
+}
+
+/**
+ * Thrown when a bundle id resolves to no bundle. Callers hold an id, not a
+ * path, so the store names the id; the CLI adds the listing command that shows
+ * which ids exist.
+ */
+export class EvidenceNotFoundError extends Error {
+	constructor(readonly evidenceId: string) {
+		super(`evidence artifact not found: ${evidenceId}`);
+		this.name = "EvidenceNotFoundError";
+	}
+}
+
+function isMissingFile(error: unknown): boolean {
+	return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+async function loadEvidenceOverview(dataDir: string, evidenceId: string): Promise<EvidenceOverview> {
+	let raw: string;
+	try {
+		raw = await readFile(join(evidenceDirectory(dataDir, evidenceId), "overview.json"), "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) throw new EvidenceNotFoundError(evidenceId);
+		throw error;
+	}
+	const parsed = parseJson(raw, `${evidenceId}/overview.json`);
+	return parseOverview(parsed, `${evidenceId}/overview.json`);
+}
+
+export async function inspectEvidence(dataDir: string, evidenceId: string): Promise<EvidenceInspectable> {
+	const overview = await loadEvidenceOverview(dataDir, evidenceId);
+	let findingsRaw: string;
+	try {
+		findingsRaw = await readFile(join(evidenceDirectory(dataDir, evidenceId), "findings.json"), "utf8");
+	} catch (error) {
+		// The overview above read, so the bundle exists and this one member of it
+		// does not. That is a different fault from a missing bundle and says so.
+		if (isMissingFile(error)) throw new Error(`evidence artifact ${evidenceId} is missing findings.json`);
+		throw error;
+	}
+	const findingsParsed = parseJson(findingsRaw, `${evidenceId}/findings.json`);
+	const findings = parseFindingsFile(findingsParsed, `${evidenceId}/findings.json`);
+	return { overview, findings };
+}
+
+/** A bundle run whose receipt carries at least one provenance field set. */
+export interface EvidenceRunProvenance {
+	runId: string;
+	view: RunProvenanceView;
+}
+
+/**
+ * Read per-run provenance views from a bundle's `receipt.json`. Only runs whose
+ * receipt carries at least one provenance field set are returned. A missing
+ * receipt file produces an empty provenance list.
+ */
+export async function loadEvidenceRunProvenance(dataDir: string, evidenceId: string): Promise<EvidenceRunProvenance[]> {
+	let raw: string;
+	try {
+		raw = await readFile(join(evidenceDirectory(dataDir, evidenceId), "receipt.json"), "utf8");
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return [];
+		throw error;
+	}
+	const parsed = parseJson(raw, `${evidenceId}/receipt.json`);
+	if (!isRecord(parsed) || !Array.isArray(parsed.receipts)) return [];
+	const out: EvidenceRunProvenance[] = [];
+	for (const entry of parsed.receipts) {
+		if (!isRecord(entry) || typeof entry.runId !== "string") continue;
+		const view = runProvenanceFromUnknown(entry);
+		if (hasRunProvenance(view)) out.push({ runId: entry.runId, view });
+	}
+	return out;
+}
+
+/** Load only integrity-valid coordinator decisions linked into an evidence bundle. */
+export async function loadEvidenceGateDecisions(dataDir: string, evidenceId: string): Promise<GateDecisionArtifact[]> {
+	let raw: string;
+	try {
+		raw = await readFile(join(evidenceDirectory(dataDir, evidenceId), "gate-decisions.json"), "utf8");
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return [];
+		throw error;
+	}
+	const parsed = parseJson(raw, `${evidenceId}/gate-decisions.json`);
+	if (!isRecord(parsed) || !Array.isArray(parsed.decisions)) return [];
+	return parsed.decisions.filter((entry): entry is GateDecisionArtifact => {
+		if (!isRecord(entry)) return false;
+		return verifyGateDecisionArtifact(entry as unknown as GateDecisionArtifact).ok;
+	});
+}
+
+export async function listEvidenceOverviews(dataDir: string): Promise<EvidenceOverview[]> {
+	let entries: string[];
+	try {
+		entries = await readdir(evidenceRoot(dataDir));
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return [];
+		throw error;
+	}
+	const overviews: EvidenceOverview[] = [];
+	for (const entry of entries.sort(compareStrings)) {
+		try {
+			overviews.push(await loadEvidenceOverview(dataDir, entry));
+		} catch {
+			// Ignore incomplete evidence directories so list stays scriptable.
+		}
+	}
+	return overviews;
+}
+
+function parseOverview(value: unknown, source: string): EvidenceOverview {
+	if (!isRecord(value)) throw new Error(`${source}: expected object`);
+	if (value.version !== 1) throw new Error(`${source}: expected version 1`);
+	const evidenceId = readString(value, source, "evidenceId");
+	const sourceValue = readSource(value.source, `${source}.source`);
+	const generatedAt = readString(value, source, "generatedAt");
+	const runIds = readStringArray(value, source, "runIds");
+	const sessionId = readNullableString(value, source, "sessionId");
+	const statuses = readStringArray(value, source, "statuses");
+	const startedAt = readNullableString(value, source, "startedAt");
+	const endedAt = readNullableString(value, source, "endedAt");
+	const tasks = readStringArray(value, source, "tasks");
+	const cwds = readStringArray(value, source, "cwds");
+	const agentIds = readStringArray(value, source, "agentIds");
+	const targetIds = readStringArray(value, source, "targetIds");
+	const runtimeIds = readStringArray(value, source, "runtimeIds");
+	const modelIds = readStringArray(value, source, "modelIds");
+	const totals = readTotals(value.totals, `${source}.totals`);
+	const tags = readStringArray(value, source, "tags") as EvidenceOverview["tags"];
+	const files = readStringArray(value, source, "files");
+	return {
+		version: 1,
+		evidenceId,
+		source: sourceValue,
+		generatedAt,
+		runIds,
+		sessionId,
+		statuses,
+		startedAt,
+		endedAt,
+		tasks,
+		cwds,
+		agentIds,
+		targetIds,
+		runtimeIds,
+		modelIds,
+		totals,
+		tags,
+		files,
+	};
+}
+
+function parseFindingsFile(value: unknown, source: string): EvidenceFinding[] {
+	if (!isRecord(value)) throw new Error(`${source}: expected object`);
+	if (value.version !== 1) throw new Error(`${source}: expected version 1`);
+	if (!Array.isArray(value.findings)) throw new Error(`${source}.findings: expected array`);
+	return value.findings.map((entry, index) => parseFinding(entry, `${source}.findings[${index}]`));
+}
+
+function parseFinding(value: unknown, source: string): EvidenceFinding {
+	if (!isRecord(value)) throw new Error(`${source}: expected object`);
+	const severity = readString(value, source, "severity");
+	if (severity !== "info" && severity !== "warn") throw new Error(`${source}.severity: expected info or warn`);
+	const tag = readString(value, source, "tag") as EvidenceFinding["tag"];
+	return {
+		id: readString(value, source, "id"),
+		severity,
+		tag,
+		runId: readNullableString(value, source, "runId"),
+		message: readString(value, source, "message"),
+	};
+}
+
+function readSource(value: unknown, source: string): EvidenceOverview["source"] {
+	if (!isRecord(value)) throw new Error(`${source}: expected object`);
+	if (value.kind === "run") return { kind: "run", runId: readString(value, source, "runId") };
+	if (value.kind === "session") return { kind: "session", sessionId: readString(value, source, "sessionId") };
+	if (value.kind === "eval") return { kind: "eval", evalId: readString(value, source, "evalId") };
+	throw new Error(`${source}.kind: expected run, session, or eval`);
+}
+
+function readTotals(value: unknown, source: string): EvidenceOverview["totals"] {
+	if (!isRecord(value)) throw new Error(`${source}: expected object`);
+	return {
+		runs: readNumber(value, source, "runs"),
+		receipts: readNumber(value, source, "receipts"),
+		toolCalls: readNumber(value, source, "toolCalls"),
+		toolErrors: readNumber(value, source, "toolErrors"),
+		blockedToolCalls: readNumber(value, source, "blockedToolCalls"),
+		sessionEntries: readOptionalNumber(value, source, "sessionEntries", 0),
+		auditRows: readOptionalNumber(value, source, "auditRows", 0),
+		toolEvents: readOptionalNumber(value, source, "toolEvents", 0),
+		linkedToolEvents: readOptionalNumber(value, source, "linkedToolEvents", 0),
+		protectedArtifacts: readOptionalNumber(value, source, "protectedArtifacts", 0),
+		tokens: readNumber(value, source, "tokens"),
+		costUsd: readNumber(value, source, "costUsd"),
+		wallTimeMs: readNumber(value, source, "wallTimeMs"),
+	};
+}
+
+function readString(record: Record<string, unknown>, source: string, field: string): string {
+	const value = record[field];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${source}.${field}: expected string`);
+	return value;
+}
+
+function readNullableString(record: Record<string, unknown>, source: string, field: string): string | null {
+	const value = record[field];
+	if (value === null) return null;
+	if (typeof value !== "string") throw new Error(`${source}.${field}: expected string or null`);
+	return value;
+}
+
+function readStringArray(record: Record<string, unknown>, source: string, field: string): string[] {
+	const value = record[field];
+	if (!Array.isArray(value)) throw new Error(`${source}.${field}: expected string array`);
+	const out: string[] = [];
+	for (let index = 0; index < value.length; index += 1) {
+		const item = value[index];
+		if (typeof item !== "string") throw new Error(`${source}.${field}[${index}]: expected string`);
+		out.push(item);
+	}
+	return out;
+}
+
+function readNumber(record: Record<string, unknown>, source: string, field: string): number {
+	const value = record[field];
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${source}.${field}: expected number`);
+	return value;
+}
+
+function readOptionalNumber(record: Record<string, unknown>, source: string, field: string, fallback: number): number {
+	const value = record[field];
+	if (value === undefined) return fallback;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${source}.${field}: expected number`);
+	return value;
+}
+
+function parseJson(raw: string, source: string): unknown {
+	try {
+		return JSON.parse(raw) as unknown;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`${source}: invalid JSON: ${message}`);
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function compareStrings(a: string, b: string): number {
+	return a.localeCompare(b);
+}
+
+export function findingsFile(evidenceId: string, findings: EvidenceFinding[]): EvidenceFindingsFile {
+	return { version: 1, evidenceId, findings };
+}