@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/dispatch/route-policy.ts

@@ -0,0 +1,327 @@
+/**
+ * Pure route-estimation and posture policy. Hard constraints are applied by the
+ * resolver before this module runs; none of the values below can trade a hard
+ * admission property for a better score.
+ */
+
+import type { AgentLatencyClass } from "../agents/spec.js";
+import type { RouteHistoryRecord } from "./route-history.js";
+import type { RouteQualityLabel } from "./route-quality.js";
+
+export const ROUTE_POLICY_VERSION = "route-policy/4";
+export const MINIMUM_QUALITY_LABELED_OUTCOMES = 6;
+
+export type RoutingPosture = "manual" | "quality" | "balanced" | "latency" | "economy";
+
+export const ROUTING_POSTURES: ReadonlyArray<RoutingPosture> = ["manual", "quality", "balanced", "latency", "economy"];
+
+export interface RouteEstimate {
+	/** Quality denominators contain pass/fail labels only; unmeasured work is excluded. */
+	qualityLabeledCount: number;
+	unmeasuredCount: number;
+	qualityCoverage: number;
+	qualityMean: number;
+	/** 95% Wilson lower bound, the only quality value used for posture floors. */
+	qualityLowerBound: number;
+	firstPassSuccessProbability: number;
+	expectedCostUsd: number;
+	costUpperBoundUsd: number;
+	expectedEndToEndMs: number;
+	p95EndToEndMs: number;
+	reliability: number;
+	cacheHitProbability: number;
+	queueWaitMs: number;
+	sampleCount: number;
+	confidence: number;
+}
+
+export interface RoutePosturePolicy {
+	floors: { qualityLowerBound: number; reliability: number };
+	weights: { quality: number; cost: number; latency: number };
+	deadlineFirst: boolean;
+}
+
+export const ROUTE_POSTURES: Readonly<Record<RoutingPosture, RoutePosturePolicy>> = {
+	manual: {
+		floors: { qualityLowerBound: 0, reliability: 0 },
+		weights: { quality: 1, cost: 0, latency: 0 },
+		deadlineFirst: false,
+	},
+	quality: {
+		floors: { qualityLowerBound: 0.8, reliability: 0.8 },
+		weights: { quality: 1, cost: 0.1, latency: 0.1 },
+		deadlineFirst: false,
+	},
+	balanced: {
+		floors: { qualityLowerBound: 0.6, reliability: 0.6 },
+		weights: { quality: 0.6, cost: 0.2, latency: 0.2 },
+		deadlineFirst: false,
+	},
+	latency: {
+		floors: { qualityLowerBound: 0.5, reliability: 0.6 },
+		weights: { quality: 0.3, cost: 0.1, latency: 0.6 },
+		deadlineFirst: true,
+	},
+	economy: {
+		floors: { qualityLowerBound: 0.6, reliability: 0.6 },
+		weights: { quality: 0.3, cost: 0.6, latency: 0.1 },
+		deadlineFirst: false,
+	},
+};
+
+export interface RoutePrior {
+	qualityMean: number;
+	firstPassSuccessProbability: number;
+	costUpperBoundUsd: number;
+	expectedEndToEndMs: number;
+	reliability: number;
+	queueWaitMs: number;
+}
+
+export const DEFAULT_ROUTE_PRIOR: RoutePrior = {
+	qualityMean: 0.5,
+	firstPassSuccessProbability: 0.5,
+	costUpperBoundUsd: 1,
+	expectedEndToEndMs: 120_000,
+	reliability: 0.5,
+	queueWaitMs: 0,
+};
+
+/** Cold-start latency only. Completed route timing supersedes these priors. */
+export const LATENCY_CLASS_ROUTE_PRIORS: Readonly<Record<AgentLatencyClass, RoutePrior>> = {
+	fast: { ...DEFAULT_ROUTE_PRIOR, expectedEndToEndMs: 30_000 },
+	balanced: { ...DEFAULT_ROUTE_PRIOR, expectedEndToEndMs: 120_000 },
+	deep: { ...DEFAULT_ROUTE_PRIOR, expectedEndToEndMs: 300_000 },
+};
+
+export function routePriorForLatencyClass(latencyClass: AgentLatencyClass): RoutePrior {
+	return { ...LATENCY_CLASS_ROUTE_PRIORS[latencyClass] };
+}
+
+/** The estimator projection of one durable route-history record. */
+export interface RouteObservation {
+	qualityLabel: RouteQualityLabel;
+	reliability: "success" | "failure" | "neutral";
+	firstPass: boolean;
+	completedCostUsd: number | null;
+	completedEndToEndMs: number | null;
+	cacheRead: boolean;
+	queueWaitMs: number | null;
+}
+
+export function routeObservationFromHistory(record: RouteHistoryRecord): RouteObservation {
+	return {
+		qualityLabel: record.qualityLabel,
+		reliability: record.reliability,
+		firstPass: record.firstPass,
+		completedCostUsd: record.completedCostUsd,
+		completedEndToEndMs: record.completedPhaseTiming?.totalEndToEndMs ?? null,
+		cacheRead: record.cacheRead,
+		queueWaitMs: record.completedPhaseTiming?.queueWaitMs ?? null,
+	};
+}
+
+export const ROUTE_ESTIMATE_SHRINKAGE = 5;
+
+function mean(values: ReadonlyArray<number>, fallback: number): number {
+	if (values.length === 0) return fallback;
+	return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function quantile(values: ReadonlyArray<number>, fraction: number, fallback: number): number {
+	if (values.length === 0) return fallback;
+	const sorted = [...values].sort((left, right) => left - right);
+	const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(fraction * sorted.length) - 1));
+	return sorted[index] ?? fallback;
+}
+
+function shrink(measured: number, prior: number, sampleCount: number): number {
+	const weight = sampleCount / (sampleCount + ROUTE_ESTIMATE_SHRINKAGE);
+	return measured * weight + prior * (1 - weight);
+}
+
+function rate(values: ReadonlyArray<boolean>, fallback = 0): number {
+	if (values.length === 0) return fallback;
+	return values.filter(Boolean).length / values.length;
+}
+
+/** Conservative 95% Wilson lower confidence bound for a Bernoulli success rate. */
+export function wilsonLowerBound(successes: number, observations: number, z = 1.96): number {
+	if (observations <= 0) return 0;
+	const proportion = successes / observations;
+	const z2 = z * z;
+	const center = proportion + z2 / (2 * observations);
+	const margin = z * Math.sqrt((proportion * (1 - proportion) + z2 / (4 * observations)) / observations);
+	return Math.max(0, Math.min(1, (center - margin) / (1 + z2 / observations)));
+}
+
+/**
+ * Quality uses only explicitly labeled pass/fail outcomes. Reliability excludes
+ * cancellation, policy denial, and permission denial through `neutral`.
+ * Completed cost/timing exclude all fast failed work.
+ */
+export function estimateRoute(
+	samples: ReadonlyArray<RouteObservation>,
+	prior: RoutePrior = DEFAULT_ROUTE_PRIOR,
+): RouteEstimate {
+	const labeled = samples.filter((sample) => sample.qualityLabel !== "unmeasured");
+	const qualityPasses = labeled.filter((sample) => sample.qualityLabel === "pass").length;
+	const attributable = samples.filter((sample) => sample.reliability !== "neutral");
+	const completed = samples.filter((sample) => sample.completedCostUsd !== null && sample.completedEndToEndMs !== null);
+	const costs = completed.flatMap((sample) => (sample.completedCostUsd === null ? [] : [sample.completedCostUsd]));
+	const latencies = completed.flatMap((sample) =>
+		sample.completedEndToEndMs === null ? [] : [sample.completedEndToEndMs],
+	);
+	const queueWaits = completed.flatMap((sample) => (sample.queueWaitMs === null ? [] : [sample.queueWaitMs]));
+	const completedCount = completed.length;
+	const reliabilityCount = attributable.length;
+	const qualityMean = labeled.length === 0 ? prior.qualityMean : qualityPasses / labeled.length;
+	const completedCosts = mean(costs, prior.costUpperBoundUsd);
+	const completedLatency = mean(latencies, prior.expectedEndToEndMs);
+	return {
+		qualityLabeledCount: labeled.length,
+		unmeasuredCount: samples.length - labeled.length,
+		qualityCoverage: samples.length === 0 ? 0 : labeled.length / samples.length,
+		qualityMean,
+		qualityLowerBound: wilsonLowerBound(qualityPasses, labeled.length),
+		firstPassSuccessProbability: shrink(
+			rate(
+				attributable.map((sample) => sample.firstPass),
+				prior.firstPassSuccessProbability,
+			),
+			prior.firstPassSuccessProbability,
+			reliabilityCount,
+		),
+		expectedCostUsd: shrink(completedCosts, prior.costUpperBoundUsd, completedCount),
+		costUpperBoundUsd: Math.max(prior.costUpperBoundUsd, quantile(costs, 0.95, prior.costUpperBoundUsd)),
+		expectedEndToEndMs: shrink(completedLatency, prior.expectedEndToEndMs, completedCount),
+		p95EndToEndMs: Math.max(completedLatency, quantile(latencies, 0.95, prior.expectedEndToEndMs)),
+		reliability: shrink(
+			rate(
+				attributable.map((sample) => sample.reliability === "success"),
+				prior.reliability,
+			),
+			prior.reliability,
+			reliabilityCount,
+		),
+		cacheHitProbability: completedCount === 0 ? 0 : rate(completed.map((sample) => sample.cacheRead)),
+		queueWaitMs: shrink(mean(queueWaits, prior.queueWaitMs), prior.queueWaitMs, completedCount),
+		sampleCount: samples.length,
+		confidence: labeled.length / (labeled.length + ROUTE_ESTIMATE_SHRINKAGE),
+	};
+}
+
+/** Active eligibility requires a lower bound and six exact-route quality labels. */
+export function clearsPostureFloors(estimate: RouteEstimate, posture: RoutingPosture): boolean {
+	if (posture === "manual") return true;
+	const policy = ROUTE_POSTURES[posture];
+	return (
+		estimate.qualityLabeledCount >= MINIMUM_QUALITY_LABELED_OUTCOMES &&
+		estimate.qualityLowerBound >= policy.floors.qualityLowerBound &&
+		estimate.reliability >= policy.floors.reliability
+	);
+}
+
+function normalize(value: number, min: number, max: number): number {
+	if (!(max > min)) return 0;
+	return (value - min) / (max - min);
+}
+
+export interface RouteScoreScale {
+	minCostUsd: number;
+	maxCostUsd: number;
+	minLatencyMs: number;
+	maxLatencyMs: number;
+	minQueueWaitMs: number;
+	maxQueueWaitMs: number;
+}
+
+export function routeScoreScale(estimates: ReadonlyArray<RouteEstimate>): RouteScoreScale {
+	const costs = estimates.map((estimate) => estimate.expectedCostUsd);
+	const latencies = estimates.map((estimate) => estimate.p95EndToEndMs);
+	const queueWaits = estimates.map((estimate) => estimate.queueWaitMs);
+	return {
+		minCostUsd: costs.length > 0 ? Math.min(...costs) : 0,
+		maxCostUsd: costs.length > 0 ? Math.max(...costs) : 0,
+		minLatencyMs: latencies.length > 0 ? Math.min(...latencies) : 0,
+		maxLatencyMs: latencies.length > 0 ? Math.max(...latencies) : 0,
+		minQueueWaitMs: queueWaits.length > 0 ? Math.min(...queueWaits) : 0,
+		maxQueueWaitMs: queueWaits.length > 0 ? Math.max(...queueWaits) : 0,
+	};
+}
+
+const SCORE_PRECISION = 1e-9;
+
+function round(value: number): number {
+	return Math.round(value / SCORE_PRECISION) * SCORE_PRECISION;
+}
+
+export function scoreRoute(estimate: RouteEstimate, posture: RoutingPosture, scale: RouteScoreScale): number {
+	const policy = ROUTE_POSTURES[posture];
+	const costPenalty = normalize(estimate.expectedCostUsd, scale.minCostUsd, scale.maxCostUsd);
+	const latencyPenalty = normalize(
+		policy.deadlineFirst ? estimate.p95EndToEndMs : estimate.expectedEndToEndMs,
+		scale.minLatencyMs,
+		scale.maxLatencyMs,
+	);
+	const queuePenalty = normalize(estimate.queueWaitMs, scale.minQueueWaitMs, scale.maxQueueWaitMs);
+	// A bounded task prior orders only wholly cold routes. The first labeled
+	// role-specific outcome replaces it; active floors always use the Wilson
+	// lower bound and minimum label count regardless.
+	const qualitySignal = estimate.qualityLabeledCount === 0 ? estimate.qualityMean : estimate.qualityLowerBound;
+	const health = qualitySignal * 0.7 + estimate.reliability * 0.3;
+	const affinityBonus = estimate.cacheHitProbability * 0.01;
+	return round(
+		policy.weights.quality * health -
+			policy.weights.cost * costPenalty -
+			policy.weights.latency * (latencyPenalty * 0.9 + queuePenalty * 0.1) +
+			affinityBonus,
+	);
+}
+
+export function dominatesRoute(left: RouteEstimate, right: RouteEstimate): boolean {
+	const noWorse =
+		left.qualityLowerBound >= right.qualityLowerBound &&
+		left.reliability >= right.reliability &&
+		left.expectedCostUsd <= right.expectedCostUsd &&
+		left.p95EndToEndMs <= right.p95EndToEndMs &&
+		left.queueWaitMs <= right.queueWaitMs &&
+		left.cacheHitProbability >= right.cacheHitProbability;
+	return (
+		noWorse &&
+		(left.qualityLowerBound > right.qualityLowerBound ||
+			left.reliability > right.reliability ||
+			left.expectedCostUsd < right.expectedCostUsd ||
+			left.p95EndToEndMs < right.p95EndToEndMs ||
+			left.queueWaitMs < right.queueWaitMs ||
+			left.cacheHitProbability > right.cacheHitProbability)
+	);
+}
+
+export interface RankedRoute {
+	key: string;
+	order: number;
+	estimate: RouteEstimate;
+	score: number;
+}
+
+export function compareRankedRoutes(left: RankedRoute, right: RankedRoute): number {
+	if (left.score !== right.score) return right.score - left.score;
+	if (left.estimate.expectedCostUsd !== right.estimate.expectedCostUsd) {
+		return left.estimate.expectedCostUsd - right.estimate.expectedCostUsd;
+	}
+	if (left.estimate.reliability !== right.estimate.reliability) {
+		return right.estimate.reliability - left.estimate.reliability;
+	}
+	if (left.estimate.p95EndToEndMs !== right.estimate.p95EndToEndMs) {
+		return left.estimate.p95EndToEndMs - right.estimate.p95EndToEndMs;
+	}
+	if (left.estimate.queueWaitMs !== right.estimate.queueWaitMs) {
+		return left.estimate.queueWaitMs - right.estimate.queueWaitMs;
+	}
+	if (left.estimate.cacheHitProbability !== right.estimate.cacheHitProbability) {
+		return right.estimate.cacheHitProbability - left.estimate.cacheHitProbability;
+	}
+	if (left.order !== right.order) return left.order - right.order;
+	return left.key < right.key ? -1 : left.key > right.key ? 1 : 0;
+}

package/src/domains/dispatch/route-quality.ts

@@ -0,0 +1,256 @@
+import { createHash } from "node:crypto";
+import { gateRouteCorrelation } from "./execution-role.js";
+import { type GateDecisionArtifact, verifyGateDecisionArtifact } from "./gate-decisions.js";
+import { verifyReceiptIntegrity } from "./receipt-integrity.js";
+import type { RunEnvelope, RunReceipt } from "./types.js";
+
+/** A routing label is deliberately separate from the descriptive receipt verification state. */
+export type RouteQualityLabel = "pass" | "fail" | "unmeasured";
+
+export interface RouteQualityCheck {
+	kind: "typed-validation" | "result-contract" | "independent-gate" | "evaluation";
+	sourceDigest: string;
+	passed: boolean;
+}
+
+export interface CorrelatedGateEvidence {
+	sourceDigest: string;
+	outcome: "pass" | "fail";
+	reason: "same-agent" | "same-model-family";
+	/** Every correlated route dimension, so a small fleet reports rather than hides it. */
+	dimensions: string[];
+}
+
+export interface RouteQualityReduction {
+	label: RouteQualityLabel;
+	/** Trusted correctness-bearing checks, sorted for deterministic replay. */
+	checks: RouteQualityCheck[];
+	/** Valid gate verdicts that are intentionally not used as labels. */
+	correlatedGates: CorrelatedGateEvidence[];
+	/** Every authenticated source digest that contributed to this reduction. */
+	sourceDigests: string[];
+}
+
+export interface RouteQualityReceiptSource {
+	receipt: RunReceipt;
+	envelope: RunEnvelope;
+}
+
+/** The current eval artifact projection consumed by routing. Older formats are not evidence. */
+export interface RouteQualityEvalArtifact {
+	version: 4;
+	evalId: string;
+	results: ReadonlyArray<{
+		assignmentId: string | null;
+		terminalReceiptDigest: string | null;
+		pass: boolean;
+	}>;
+}
+
+export interface RouteQualityEvalSource {
+	artifact: RouteQualityEvalArtifact;
+	/** Canonical digest of the durable current-version artifact. */
+	digest: string;
+}
+
+export interface ReduceRouteQualityInput {
+	subject: RouteQualityReceiptSource;
+	/** Receipts referenced by later evidence, including the subject. */
+	receipts: ReadonlyArray<RouteQualityReceiptSource>;
+	gateArtifacts?: ReadonlyArray<GateDecisionArtifact>;
+	evalArtifacts?: ReadonlyArray<RouteQualityEvalSource>;
+}
+
+function compareStrings(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/**
+ * Integrity verdicts held against the receipt object that produced them.
+ *
+ * Verification canonically serializes and hashes a receipt and its envelope,
+ * and `reduceRouteQuality` verifies the whole receipt set on every call. That
+ * is fine for one subject and quadratic for a batch. Reconciling route history
+ * is a batch: 359 records against a 1247-receipt ledger is 447,673
+ * verifications of files averaging 23KB, which measured 70 seconds of CPU on
+ * the dispatch decision path and pushed every dispatch on this machine past
+ * its 60-second admission deadline. Dispatch had stopped working, and the
+ * error it reported was that no worker slots were free while zero were in use.
+ *
+ * The key is the receipt object, not its digest. A digest key would let a
+ * forged receipt claiming a known-good digest inherit that receipt's verdict,
+ * which is the thing verification exists to catch. Object identity can only be
+ * shared by a receipt that was already verified in this process, and a durable
+ * re-read produces fresh objects, so a ledger that changed on disk is verified
+ * again.
+ */
+const integrityVerdicts = new WeakMap<object, boolean>();
+
+function authenticated(source: RouteQualityReceiptSource): boolean {
+	const cached = integrityVerdicts.get(source.receipt);
+	if (cached !== undefined) return cached;
+	const verdict = verifyReceiptIntegrity(source.receipt, source.envelope).ok;
+	integrityVerdicts.set(source.receipt, verdict);
+	return verdict;
+}
+
+function receiptSourcesByRunId(
+	sources: ReadonlyArray<RouteQualityReceiptSource>,
+): Map<string, RouteQualityReceiptSource> {
+	const result = new Map<string, RouteQualityReceiptSource>();
+	for (const source of sources) {
+		if (!authenticated(source)) continue;
+		result.set(source.receipt.runId, source);
+	}
+	return result;
+}
+
+function gateReferencesMatch(
+	artifact: GateDecisionArtifact,
+	receipts: ReadonlyMap<string, RouteQualityReceiptSource>,
+): boolean {
+	const references = [...artifact.subjects, ...(artifact.decider === undefined ? [] : [artifact.decider])];
+	return references.every((reference) => receipts.get(reference.runId)?.receipt.integrity.digest === reference.digest);
+}
+
+function gateOutcome(artifact: GateDecisionArtifact): "pass" | "fail" | null {
+	if (artifact.outcome === "pass") return "pass";
+	if (artifact.outcome === "fail") return "fail";
+	// An integrity-valid operator-confirmed compete decision proves only the
+	// applied winner's positive verdict; losing candidates stay unmeasured.
+	if (artifact.outcome === "operator-confirmed" && artifact.confirmation !== undefined) return "pass";
+	return null;
+}
+
+function correlationFacts(receipt: RunReceipt): Parameters<typeof gateRouteCorrelation>[0] {
+	return {
+		agentId: receipt.agentId,
+		targetId: receipt.targetId,
+		wireModelId: receipt.wireModelId,
+		runtimeId: receipt.runtimeId,
+		nodeId: receipt.node?.id ?? "local",
+	};
+}
+
+function gateCorrelation(
+	subject: RunReceipt,
+	decider: RunReceipt,
+): Pick<CorrelatedGateEvidence, "reason" | "dimensions"> | null {
+	const correlation = gateRouteCorrelation(correlationFacts(subject), correlationFacts(decider));
+	if (correlation.independent) return null;
+	return {
+		reason: correlation.agent ? "same-agent" : "same-model-family",
+		dimensions: correlation.dimensions,
+	};
+}
+
+function evalAssignmentId(receipt: RunReceipt): string {
+	return receipt.lineage?.rootRunId ?? receipt.runId;
+}
+
+/**
+ * Reduce integrity-valid receipt, gate, and eval artifacts into one routing
+ * quality label. It is intentionally pure: callers own durable reads and
+ * persistence, so replaying the same authenticated inputs is byte-identical.
+ */
+export function reduceRouteQuality(input: ReduceRouteQualityInput): RouteQualityReduction {
+	if (!authenticated(input.subject)) {
+		return { label: "unmeasured", checks: [], correlatedGates: [], sourceDigests: [] };
+	}
+
+	const subject = input.subject.receipt;
+	const receipts = receiptSourcesByRunId([input.subject, ...input.receipts]);
+	const checks: RouteQualityCheck[] = [];
+	const correlatedGates: CorrelatedGateEvidence[] = [];
+	const sourceDigests = new Set<string>([subject.integrity.digest]);
+
+	for (const fact of subject.quality.typedValidations) {
+		checks.push({
+			kind: "typed-validation",
+			sourceDigest: subject.integrity.digest,
+			passed: fact.passed,
+		});
+	}
+	const resultContract = subject.quality.resultContract;
+	if (resultContract !== null && resultContract.quality !== "unmeasured") {
+		checks.push({
+			kind: "result-contract",
+			sourceDigest: subject.integrity.digest,
+			passed: resultContract.quality === "pass",
+		});
+	}
+
+	for (const artifact of input.gateArtifacts ?? []) {
+		if (!verifyGateDecisionArtifact(artifact).ok || !gateReferencesMatch(artifact, receipts)) continue;
+		const verdict = gateOutcome(artifact);
+		if (verdict === null || artifact.decider === undefined) continue;
+		const subjectReference = artifact.subjects.find(
+			(reference) => reference.runId === subject.runId && reference.digest === subject.integrity.digest,
+		);
+		if (subjectReference === undefined) continue;
+		const operatorConfirmed = artifact.outcome === "operator-confirmed" && artifact.confirmation !== undefined;
+		if (
+			operatorConfirmed &&
+			(artifact.winner === undefined ||
+				artifact.winner.subject.runId !== subject.runId ||
+				artifact.winner.subject.digest !== subject.integrity.digest)
+		)
+			continue;
+		const decider = receipts.get(artifact.decider.runId)?.receipt;
+		if (decider === undefined) continue;
+		const correlation = gateCorrelation(subject, decider);
+		sourceDigests.add(artifact.integrity.digest);
+		if (correlation !== null && !operatorConfirmed) {
+			correlatedGates.push({ sourceDigest: artifact.integrity.digest, outcome: verdict, ...correlation });
+			continue;
+		}
+		checks.push({ kind: "independent-gate", sourceDigest: artifact.integrity.digest, passed: verdict === "pass" });
+	}
+
+	for (const source of input.evalArtifacts ?? []) {
+		if (source.artifact.version !== 4 || !/^[0-9a-f]{64}$/u.test(source.digest)) continue;
+		for (const result of source.artifact.results) {
+			if (result.assignmentId !== evalAssignmentId(subject) || result.terminalReceiptDigest !== subject.integrity.digest)
+				continue;
+			sourceDigests.add(source.digest);
+			checks.push({ kind: "evaluation", sourceDigest: source.digest, passed: result.pass });
+		}
+	}
+
+	checks.sort((left, right) => {
+		const byKind = compareStrings(left.kind, right.kind);
+		if (byKind !== 0) return byKind;
+		if (left.sourceDigest !== right.sourceDigest) return compareStrings(left.sourceDigest, right.sourceDigest);
+		return Number(left.passed) - Number(right.passed);
+	});
+	correlatedGates.sort((left, right) => compareStrings(left.sourceDigest, right.sourceDigest));
+	const label: RouteQualityLabel = checks.some((check) => !check.passed)
+		? "fail"
+		: checks.some((check) => check.passed)
+			? "pass"
+			: "unmeasured";
+	return { label, checks, correlatedGates, sourceDigests: [...sourceDigests].sort(compareStrings) };
+}
+
+/** Stable digest for a current eval artifact when it enters route history. */
+export function routeQualityEvalDigest(artifact: RouteQualityEvalArtifact): string {
+	return createHash("sha256").update(canonicalJson(artifact), "utf8").digest("hex");
+}
+
+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("route quality eval 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(compareStrings)
+			.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+			.join(",")}}`;
+	}
+	throw new Error(`route quality eval digest cannot represent ${typeof value}`);
+}