@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/dispatch/receipt-findings.ts

@@ -0,0 +1,255 @@
+/**
+ * Cheap, pure findings classifier for the durable receipt summary (v0.2.7
+ * Slice 3). It maps the signals already present on a receipt draft and its
+ * ledger envelope -- outcome, outcomeDetail, exitCode, toolStats, toolActivity
+ * -- to a conservative subset of the canonical EvidenceTag taxonomy.
+ *
+ * This is deliberately NOT buildEvidence. The forensic aggregator reads the
+ * persisted receipt, so calling it at record time would create a cycle. This
+ * classifier only inspects in-memory draft fields, emits a tag only when the
+ * data justifies it, and keeps the result JSON-clean (stably ordered tag array,
+ * boolean firstPassSuccess, finite findingCount) so the v3 integrity digest can
+ * fold it without hitting a non-finite or undefined value.
+ */
+
+import { createHash } from "node:crypto";
+import { type EvidenceTag, FAILURE_CAUSE_TAG_ORDER, FAILURE_CAUSE_TAGS } from "../evidence/index.js";
+import type {
+	RunEnvelope,
+	RunReceiptDraft,
+	RunReceiptFindingsSummary,
+	RunReceiptQuality,
+	RunReceiptResultContractFact,
+	RunReceiptTypedValidationFact,
+	RunReceiptVerification,
+} from "./types.js";
+
+function lower(value: string | null | undefined): string {
+	return (value ?? "").toLowerCase();
+}
+
+function canonicalJson(value: unknown): string {
+	if (value === null) return "null";
+	if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error("response schema digest requires finite numbers");
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		return `{${Object.keys(record)
+			.sort()
+			.map((key) => {
+				if (record[key] === undefined) throw new Error("response schema digest cannot contain undefined");
+				return `${JSON.stringify(key)}:${canonicalJson(record[key])}`;
+			})
+			.join(",")}}`;
+	}
+	throw new Error(`response schema digest cannot represent ${typeof value}`);
+}
+
+export function canonicalResponseSchemaDigest(schema: Record<string, unknown>): string {
+	return createHash("sha256").update(canonicalJson(schema), "utf8").digest("hex");
+}
+
+export interface CreateRunReceiptQualityInput {
+	responseSchema?: Record<string, unknown>;
+	runtimeEnforceable: boolean;
+	enforcementPassed: boolean | null;
+	typedValidations?: ReadonlyArray<RunReceiptTypedValidationFact>;
+	resultContract?: RunReceiptResultContractFact | null;
+}
+
+/**
+ * `verify` is Clio's typed verifier tool. Its sealed aggregate records the
+ * tool identity and pass/fail result; generic process exit and shell commands
+ * never enter this channel.
+ */
+export function typedValidationFactsFromToolStats(
+	toolStats: ReadonlyArray<Pick<RunReceiptDraft["toolStats"][number], "tool" | "count" | "ok" | "errors" | "blocked">>,
+): RunReceiptTypedValidationFact[] {
+	return toolStats
+		.filter((stat) => stat.tool === "verify" && stat.count > 0)
+		.map((stat) => ({
+			sourceId: "tool:verify",
+			validatorDigest: createHash("sha256").update(canonicalJson(stat), "utf8").digest("hex"),
+			passed: stat.ok === stat.count && stat.errors === 0 && stat.blocked === 0,
+		}));
+}
+
+/** Create the required, JSON-clean quality block for one receipt finalization. */
+export function createRunReceiptQuality(input: CreateRunReceiptQualityInput): RunReceiptQuality {
+	const schemaDigest = input.responseSchema === undefined ? null : canonicalResponseSchemaDigest(input.responseSchema);
+	return {
+		version: 1,
+		typedValidations: [...(input.typedValidations ?? [])]
+			.map((fact) => ({ ...fact }))
+			.sort(
+				(left, right) =>
+					left.sourceId.localeCompare(right.sourceId) || left.validatorDigest.localeCompare(right.validatorDigest),
+			),
+		responseSchema: {
+			sourceId: schemaDigest === null ? null : `dispatch.response-schema:${schemaDigest}`,
+			schemaDigest,
+			runtimeEnforceable: input.responseSchema === undefined ? false : input.runtimeEnforceable,
+			enforcementPassed: input.responseSchema === undefined ? null : input.enforcementPassed,
+		},
+		resultContract: input.resultContract ?? null,
+	};
+}
+
+function toolNamesLower(draft: RunReceiptDraft): string[] {
+	return draft.toolStats.map((stat) => stat.tool.toLowerCase());
+}
+
+function anyToolMatches(toolNames: string[], needles: readonly string[]): boolean {
+	return toolNames.some((name) => needles.some((needle) => name.includes(needle)));
+}
+
+function blockedCount(draft: RunReceiptDraft): number {
+	const fromStats = draft.toolStats.reduce((total, stat) => total + stat.blocked, 0);
+	const fromActivity = draft.toolActivity?.blocked ?? 0;
+	return Math.max(fromStats, fromActivity);
+}
+
+const TEST_TOOL_NEEDLES = ["pytest", "ctest", "jest", "vitest", "test", "lint", "typecheck"] as const;
+const BUILD_TOOL_NEEDLES = ["build", "compile", "make", "cmake", "cargo", "gradle", "ninja", "tsc"] as const;
+const VALIDATION_TOOL_NEEDLES = [
+	"pytest",
+	"ctest",
+	"jest",
+	"vitest",
+	"test",
+	"lint",
+	"typecheck",
+	"check",
+	"ci",
+	"validate",
+	"verify",
+] as const;
+
+/**
+ * Emit the conservative failure-cause tags justified by the draft + envelope.
+ * Only signals that are unambiguous in the available data produce a tag.
+ */
+function classifyTags(draft: RunReceiptDraft, envelope: RunEnvelope): Set<EvidenceTag> {
+	const tags = new Set<EvidenceTag>();
+	const outcome = draft.outcome ?? envelope.outcome ?? null;
+	const detail = lower(draft.outcomeDetail ?? envelope.outcomeDetail);
+	const failureText = `${lower(draft.failureMessage)} ${detail}`;
+	const exitCode = draft.exitCode;
+	const nonzeroExit = Number.isFinite(exitCode) && exitCode !== 0;
+	const toolNames = toolNamesLower(draft);
+
+	// Timeout: an explicit timed_out/stalled outcome, or timeout language in the
+	// detail/failure text.
+	if (outcome === "timed_out" || outcome === "stalled") {
+		tags.add("timeout");
+	} else if (failureText.includes("timed out") || failureText.includes("timeout")) {
+		tags.add("timeout");
+	}
+
+	// Auth failure: credential/api-key/auth language in the failure text.
+	if (
+		failureText.includes("auth") ||
+		failureText.includes("api key") ||
+		failureText.includes("credential") ||
+		failureText.includes("unauthorized")
+	) {
+		tags.add("auth-failure");
+	}
+
+	// Missing dependency: explicit dependency/module-not-found language.
+	if (
+		failureText.includes("module not found") ||
+		failureText.includes("missing package") ||
+		failureText.includes("missing dependency")
+	) {
+		tags.add("missing-dependency");
+	}
+
+	// Blocked tool: any blocked attempt recorded in stats or activity totals.
+	if (blockedCount(draft) > 0) {
+		tags.add("blocked-tool");
+	}
+
+	// Build/test failure: a nonzero exit paired with a build/test command in the
+	// tool stats. Build takes precedence when both appear, matching the forensic
+	// classifier's ordering.
+	if (nonzeroExit) {
+		if (anyToolMatches(toolNames, BUILD_TOOL_NEEDLES)) {
+			tags.add("build-failure");
+		} else if (anyToolMatches(toolNames, TEST_TOOL_NEEDLES)) {
+			tags.add("test-failure");
+		}
+	}
+
+	return tags;
+}
+
+function hasValidationEvidence(draft: Pick<RunReceiptDraft, "toolStats">): boolean {
+	return draft.toolStats.some((stat) => {
+		if (stat.ok <= 0 || stat.errors > 0) return false;
+		const tool = stat.tool.toLowerCase();
+		return VALIDATION_TOOL_NEEDLES.some((needle) => tool.includes(needle));
+	});
+}
+
+/**
+ * Derive the receipt's descriptive evidence-confidence marker without
+ * changing execution semantics. ACP agents may validate externally, so lack
+ * of Clio-observed validation is unknown rather than a negative assertion.
+ */
+export function deriveReceiptVerification(
+	draft: Pick<RunReceiptDraft, "toolStats">,
+	context: { capabilityClass?: string | null; acpDelegation?: boolean } = {},
+): RunReceiptVerification {
+	if (context.capabilityClass === "read-only") {
+		return { state: "not_applicable", basis: "read-only-agent" };
+	}
+	if (hasValidationEvidence(draft)) {
+		return { state: "verified", basis: "validation-tool" };
+	}
+	if (context.acpDelegation === true) {
+		return { state: "unknown", basis: "acp-external-unobserved" };
+	}
+	return { state: "unverified", basis: "no-validation-tool" };
+}
+
+/**
+ * Evidence confidence when no sealed receipt can be read: the run has none, or
+ * its integrity check failed, so nothing it claims may be reported as verified.
+ */
+export const UNVERIFIABLE_RECEIPT_VERIFICATION: RunReceiptVerification = {
+	state: "unknown",
+	basis: "receipt-unavailable",
+};
+
+/**
+ * Compute the durable findings summary for a receipt draft. Pure and cheap:
+ * inspects only in-memory fields, never reads disk or calls buildEvidence.
+ *
+ * firstPassSuccess (per spec section 7) requires a succeeded outcome, zero
+ * dispatch retries (lineage.attempt === 0), a cheap positive validation signal
+ * in the receipt stats, and no failure-cause tag. Absent draft lineage falls
+ * back to the envelope before treating the run as attempt 0.
+ */
+export function computeReceiptFindingsSummary(
+	draft: RunReceiptDraft,
+	envelope: RunEnvelope,
+): RunReceiptFindingsSummary {
+	const detected = classifyTags(draft, envelope);
+	const tags = FAILURE_CAUSE_TAG_ORDER.filter((tag) => detected.has(tag));
+
+	const outcome = draft.outcome ?? envelope.outcome ?? null;
+	const attempt = draft.lineage?.attempt ?? envelope.lineage?.attempt ?? 0;
+	const hasFailureCause = tags.some((tag) => FAILURE_CAUSE_TAGS.has(tag));
+	const firstPassSuccess = outcome === "succeeded" && attempt === 0 && hasValidationEvidence(draft) && !hasFailureCause;
+
+	return {
+		tags,
+		firstPassSuccess,
+		findingCount: tags.length,
+	};
+}

package/src/domains/dispatch/receipt-integrity.ts

@@ -0,0 +1,378 @@
+import { createHash } from "node:crypto";
+import { isExecutionRole } from "./execution-role.js";
+import { isRouteDecisionAgentSelection } from "./route-decision.js";
+import { ROUTE_POLICY_VERSION } from "./route-policy.js";
+import { isRoutingIntent } from "./routing-intent.js";
+import type { RunEnvelope, RunReceipt, RunReceiptDraft, RunReceiptIntegrity, RunReceiptQuality } from "./types.js";
+
+/**
+ * The single receipt integrity contract. Clio is pre-1.0 with no installed
+ * base, so there are no historical receipts to keep verifying: a receipt is
+ * either this version or it is not a receipt.
+ */
+export const RUN_RECEIPT_INTEGRITY_VERSION: RunReceiptIntegrity["version"] = 15;
+export type ReceiptIntegrityVersion = RunReceiptIntegrity["version"];
+export type ReceiptIntegrityField = keyof RunReceiptDraft;
+export const RUN_RECEIPT_INTEGRITY_ALGORITHM = "sha256";
+
+export type ReceiptIntegrityResult = { ok: true } | { ok: false; reason: string };
+
+function sha256(input: string): string {
+	return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+function canonicalJson(value: unknown): string {
+	return serializeCanonical(value);
+}
+
+function serializeCanonical(value: unknown): string {
+	if (value === null) return "null";
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			throw new Error(`receipt integrity: non-finite number ${String(value)} is not representable`);
+		}
+		return JSON.stringify(value);
+	}
+	if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+	if (typeof value === "bigint") throw new Error("receipt integrity: bigint is not representable");
+	if (typeof value === "symbol" || typeof value === "function") {
+		throw new Error(`receipt integrity: ${typeof value} is not representable`);
+	}
+	if (value === undefined) throw new Error("receipt integrity: undefined is not representable at root");
+	if (Array.isArray(value)) {
+		const parts: string[] = [];
+		for (let i = 0; i < value.length; i++) {
+			if (!(i in value) || value[i] === undefined) {
+				parts.push("null");
+				continue;
+			}
+			parts.push(serializeCanonical(value[i]));
+		}
+		return `[${parts.join(",")}]`;
+	}
+	if (typeof value === "object") {
+		const obj = value as Record<string, unknown>;
+		const keys = Object.keys(obj).sort();
+		const parts: string[] = [];
+		for (const key of keys) {
+			const child = obj[key];
+			if (child === undefined) continue;
+			parts.push(`${JSON.stringify(key)}:${serializeCanonical(child)}`);
+		}
+		return `{${parts.join(",")}}`;
+	}
+	throw new Error(`receipt integrity: unsupported value of type ${typeof value}`);
+}
+
+/**
+ * Every public draft field enters the digest. This map is deliberately
+ * exhaustive: adding a receipt field without registering it here is a compile
+ * error, so a new field can never ship outside integrity coverage.
+ */
+export const RECEIPT_INTEGRITY_FIELD_COVERAGE = {
+	runId: true,
+	agentId: true,
+	executionRole: true,
+	agentAudience: true,
+	requestOrigin: true,
+	task: true,
+	targetId: true,
+	wireModelId: true,
+	runtimeId: true,
+	runtimeKind: true,
+	startedAt: true,
+	endedAt: true,
+	outcome: true,
+	outcomeDetail: true,
+	lineage: true,
+	identity: true,
+	node: true,
+	attestation: true,
+	reroutes: true,
+	pipeline: true,
+	gate: true,
+	plan: true,
+	personaOverride: true,
+	projectContext: true,
+	exitCode: true,
+	failureMessage: true,
+	tokenCount: true,
+	inputTokenCount: true,
+	outputTokenCount: true,
+	cacheReadTokenCount: true,
+	cacheWriteTokenCount: true,
+	reasoningTokenCount: true,
+	upstreamResponses: true,
+	output: true,
+	costUsd: true,
+	costProvenance: true,
+	compiledPromptHash: true,
+	staticCompositionHash: true,
+	staticShellHash: true,
+	sessionShellHash: true,
+	dynamicHash: true,
+	promptSignature: true,
+	toolSignature: true,
+	clioVersion: true,
+	piMonoVersion: true,
+	platform: true,
+	nodeVersion: true,
+	toolCalls: true,
+	toolStats: true,
+	toolActivity: true,
+	verification: true,
+	routingIntent: true,
+	quality: true,
+	skillActivations: true,
+	autonomyEnforcement: true,
+	safety: true,
+	reproducibility: true,
+	runtimeResolution: true,
+	delegation: true,
+	findingsSummary: true,
+	// Both are optional and absent unless the run produced the condition they
+	// name, so a receipt that carries neither digests exactly as it did before
+	// they existed and the integrity version stays where it is.
+	validationGrounding: true,
+	capabilityMismatch: true,
+	// Same reasoning: absent unless the run had an agent ledger, so a receipt
+	// without one digests byte-identically to one produced before it existed.
+	ledgerContribution: true,
+	sessionId: true,
+	briefing: true,
+	outcomeCode: true,
+	steering: true,
+	routeDecision: true,
+} as const satisfies Record<ReceiptIntegrityField, true>;
+
+const RECEIPT_FIELDS = Object.keys(RECEIPT_INTEGRITY_FIELD_COVERAGE) as ReceiptIntegrityField[];
+
+function selectedReceiptFields(
+	receipt: RunReceipt | RunReceiptDraft,
+	fields: ReadonlyArray<string>,
+): Record<string, unknown> {
+	const source = receipt as unknown as Record<string, unknown>;
+	const result: Record<string, unknown> = {};
+	for (const field of fields) {
+		const value = source[field];
+		if (value !== undefined) result[field] = value;
+	}
+	return result;
+}
+
+function receiptDigestFields(receipt: RunReceipt | RunReceiptDraft): Record<string, unknown> {
+	const result = selectedReceiptFields(receipt, RECEIPT_FIELDS);
+	result.briefing = receipt.briefing ?? null;
+	result.outcomeCode = receipt.outcomeCode ?? null;
+	result.steering = receipt.steering ?? null;
+	return result;
+}
+
+function ledgerDigestFields(envelope: RunEnvelope): Record<string, unknown> {
+	return {
+		id: envelope.id,
+		agentId: envelope.agentId,
+		executionRole: envelope.executionRole,
+		task: envelope.task,
+		targetId: envelope.targetId,
+		wireModelId: envelope.wireModelId,
+		runtimeId: envelope.runtimeId,
+		runtimeKind: envelope.runtimeKind,
+		startedAt: envelope.startedAt,
+		endedAt: envelope.endedAt,
+		status: envelope.status,
+		exitCode: envelope.exitCode,
+		sessionId: envelope.sessionId,
+		cwd: envelope.cwd,
+		tokenCount: envelope.tokenCount,
+		cacheReadTokenCount: envelope.cacheReadTokenCount,
+		cacheWriteTokenCount: envelope.cacheWriteTokenCount,
+		reasoningTokenCount: envelope.reasoningTokenCount,
+		staticShellHash: envelope.staticShellHash,
+		sessionShellHash: envelope.sessionShellHash,
+		dynamicHash: envelope.dynamicHash,
+		costUsd: envelope.costUsd,
+		agentAudience: envelope.agentAudience ?? null,
+		requestOrigin: envelope.requestOrigin ?? null,
+		outcome: envelope.outcome ?? null,
+		outcomeDetail: envelope.outcomeDetail ?? null,
+		lineage: envelope.lineage ?? null,
+		identity: envelope.identity ?? null,
+		node: envelope.node ?? null,
+		reroutes: envelope.reroutes ?? null,
+		pipeline: envelope.pipeline ?? null,
+		gate: envelope.gate ?? null,
+		plan: envelope.plan ?? null,
+		personaOverride: envelope.personaOverride ?? null,
+		inputTokenCount: envelope.inputTokenCount ?? 0,
+		outputTokenCount: envelope.outputTokenCount ?? 0,
+		promptSignature: envelope.promptSignature ?? null,
+		toolSignature: envelope.toolSignature ?? null,
+		briefing: envelope.briefing ?? null,
+		outcomeCode: envelope.outcomeCode ?? null,
+		steering: envelope.steering ?? null,
+	};
+}
+
+function integrityPayload(receipt: RunReceipt | RunReceiptDraft, envelope: RunEnvelope): Record<string, unknown> {
+	return {
+		contract: "clio.runReceipt.integrity",
+		version: RUN_RECEIPT_INTEGRITY_VERSION,
+		sources: ["receipt", "run-ledger"],
+		receipt: receiptDigestFields(receipt),
+		ledger: ledgerDigestFields(envelope),
+	};
+}
+
+export function computeReceiptIntegrity(
+	receipt: RunReceipt | RunReceiptDraft,
+	envelope: RunEnvelope,
+): RunReceiptIntegrity {
+	return {
+		version: RUN_RECEIPT_INTEGRITY_VERSION,
+		algorithm: RUN_RECEIPT_INTEGRITY_ALGORITHM,
+		digest: sha256(canonicalJson(integrityPayload(receipt, envelope))),
+	};
+}
+
+function isReceiptQuality(value: unknown): value is RunReceiptQuality {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const quality = value as Record<string, unknown>;
+	if (quality.version !== 1 || !Array.isArray(quality.typedValidations)) return false;
+	if (
+		!quality.typedValidations.every(
+			(fact) =>
+				fact !== null &&
+				typeof fact === "object" &&
+				typeof (fact as Record<string, unknown>).sourceId === "string" &&
+				typeof (fact as Record<string, unknown>).validatorDigest === "string" &&
+				/^[0-9a-f]{64}$/.test(String((fact as Record<string, unknown>).validatorDigest)) &&
+				typeof (fact as Record<string, unknown>).passed === "boolean",
+		)
+	)
+		return false;
+	const schema = quality.responseSchema;
+	if (!schema || typeof schema !== "object" || Array.isArray(schema)) return false;
+	const responseSchema = schema as Record<string, unknown>;
+	const resultContract = quality.resultContract;
+	const validResultContract =
+		resultContract === null ||
+		(resultContract !== undefined &&
+			typeof resultContract === "object" &&
+			!Array.isArray(resultContract) &&
+			typeof (resultContract as Record<string, unknown>).sourceId === "string" &&
+			typeof (resultContract as Record<string, unknown>).validatorDigest === "string" &&
+			/^[0-9a-f]{64}$/.test(String((resultContract as Record<string, unknown>).validatorDigest)) &&
+			((resultContract as Record<string, unknown>).conformance === "pass" ||
+				(resultContract as Record<string, unknown>).conformance === "fail" ||
+				(resultContract as Record<string, unknown>).conformance === "not-reached") &&
+			((resultContract as Record<string, unknown>).quality === "pass" ||
+				(resultContract as Record<string, unknown>).quality === "fail" ||
+				(resultContract as Record<string, unknown>).quality === "unmeasured"));
+	return (
+		(responseSchema.sourceId === null || typeof responseSchema.sourceId === "string") &&
+		(responseSchema.schemaDigest === null ||
+			(typeof responseSchema.schemaDigest === "string" && /^[0-9a-f]{64}$/.test(responseSchema.schemaDigest))) &&
+		typeof responseSchema.runtimeEnforceable === "boolean" &&
+		(responseSchema.enforcementPassed === null || typeof responseSchema.enforcementPassed === "boolean") &&
+		validResultContract
+	);
+}
+
+function isCurrentRouteDecision(value: unknown): boolean {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const decision = value as Record<string, unknown>;
+	return (
+		decision.policyVersion === ROUTE_POLICY_VERSION &&
+		(decision.mode === "fixed" || decision.mode === "shadow" || decision.mode === "active") &&
+		isRouteDecisionAgentSelection(decision.agentSelection) &&
+		typeof decision.decisionHash === "string" &&
+		/^[0-9a-f]{64}$/u.test(decision.decisionHash)
+	);
+}
+
+export function withReceiptIntegrity(receipt: RunReceiptDraft, envelope: RunEnvelope): RunReceipt {
+	if (!isReceiptQuality(receipt.quality)) throw new Error("receipt integrity: required quality block invalid");
+	if (!isExecutionRole(receipt.executionRole)) throw new Error("receipt integrity: required execution role invalid");
+	if (!isRoutingIntent(receipt.routingIntent)) {
+		throw new Error("receipt integrity: required routing intent invalid");
+	}
+	if (receipt.routeDecision !== undefined && !isCurrentRouteDecision(receipt.routeDecision)) {
+		throw new Error("receipt integrity: route decision is invalid or retired");
+	}
+	return {
+		...receipt,
+		routingIntent: receipt.routingIntent,
+		integrity: computeReceiptIntegrity(receipt, envelope),
+	};
+}
+
+export function isReceiptIntegrity(value: unknown): value is RunReceiptIntegrity {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const candidate = value as Record<string, unknown>;
+	return (
+		candidate.version === RUN_RECEIPT_INTEGRITY_VERSION &&
+		candidate.algorithm === RUN_RECEIPT_INTEGRITY_ALGORITHM &&
+		typeof candidate.digest === "string" &&
+		/^[0-9a-f]{64}$/.test(candidate.digest)
+	);
+}
+
+function firstLedgerMismatch(receipt: RunReceipt, envelope: RunEnvelope): string | null {
+	const sharedFields: Array<[string, unknown, unknown]> = [
+		["runId", receipt.runId, envelope.id],
+		["agentId", receipt.agentId, envelope.agentId],
+		["executionRole", receipt.executionRole, envelope.executionRole],
+		["agentAudience", receipt.agentAudience, envelope.agentAudience],
+		["requestOrigin", receipt.requestOrigin, envelope.requestOrigin],
+		["task", receipt.task, envelope.task],
+		["targetId", receipt.targetId, envelope.targetId],
+		["wireModelId", receipt.wireModelId, envelope.wireModelId],
+		["runtimeId", receipt.runtimeId, envelope.runtimeId],
+		["runtimeKind", receipt.runtimeKind, envelope.runtimeKind],
+		["startedAt", receipt.startedAt, envelope.startedAt],
+		["endedAt", receipt.endedAt, envelope.endedAt],
+		["exitCode", receipt.exitCode, envelope.exitCode],
+		["tokenCount", receipt.tokenCount, envelope.tokenCount],
+		["cacheReadTokenCount", receipt.cacheReadTokenCount ?? 0, envelope.cacheReadTokenCount ?? 0],
+		["cacheWriteTokenCount", receipt.cacheWriteTokenCount ?? 0, envelope.cacheWriteTokenCount ?? 0],
+		["reasoningTokenCount", receipt.reasoningTokenCount ?? 0, envelope.reasoningTokenCount ?? 0],
+		["staticShellHash", receipt.staticShellHash ?? null, envelope.staticShellHash ?? null],
+		["sessionShellHash", receipt.sessionShellHash ?? null, envelope.sessionShellHash ?? null],
+		["dynamicHash", receipt.dynamicHash ?? null, envelope.dynamicHash ?? null],
+		["costUsd", receipt.costUsd, envelope.costUsd],
+		["sessionId", receipt.sessionId, envelope.sessionId],
+		["outcome", receipt.outcome ?? null, envelope.outcome ?? null],
+		["outcomeDetail", receipt.outcomeDetail ?? null, envelope.outcomeDetail ?? null],
+		["nodeId", receipt.node?.id ?? null, envelope.node?.id ?? null],
+		["outcomeCode", receipt.outcomeCode ?? null, envelope.outcomeCode ?? null],
+	];
+	for (const [field, receiptValue, ledgerValue] of sharedFields) {
+		if (!Object.is(receiptValue, ledgerValue)) return field;
+	}
+	if (canonicalJson(receipt.briefing ?? null) !== canonicalJson(envelope.briefing ?? null)) return "briefing";
+	if (canonicalJson(receipt.steering ?? null) !== canonicalJson(envelope.steering ?? null)) return "steering";
+	return null;
+}
+
+export function verifyReceiptIntegrity(receipt: RunReceipt, envelope: RunEnvelope): ReceiptIntegrityResult {
+	if (!isReceiptQuality(receipt.quality) || !isReceiptIntegrity(receipt.integrity)) {
+		return { ok: false, reason: "integrity invalid" };
+	}
+	if (!isExecutionRole(receipt.executionRole)) return { ok: false, reason: "execution role invalid" };
+	if (!isRoutingIntent(receipt.routingIntent)) {
+		return { ok: false, reason: "routing intent invalid" };
+	}
+	if (receipt.routeDecision !== undefined && !isCurrentRouteDecision(receipt.routeDecision)) {
+		return { ok: false, reason: "route decision invalid" };
+	}
+	const mismatch = firstLedgerMismatch(receipt, envelope);
+	if (mismatch) {
+		return { ok: false, reason: `ledger mismatch: ${mismatch}` };
+	}
+	const expected = computeReceiptIntegrity(receipt, envelope);
+	if (expected.digest !== receipt.integrity.digest) {
+		return { ok: false, reason: "integrity mismatch" };
+	}
+	return { ok: true };
+}