@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/dispatch/validation.ts

@@ -21,6 +21,7 @@ import {
 import { isExecutionRole } from "./execution-role.js";
 import { COMPETE_STANCES, type CompeteStance } from "./gate-role-prompts.js";
 import { type DispatchIntent, isDispatchIntent } from "./intent.js";
+import { classifyDispatchIntentCompatibility, dispatchIntentRefusals } from "./intent-compatibility.js";
 import { isRoutingIntent, type RoutingIntent } from "./routing-intent.js";
 import type {
 	DispatchRequestOrigin,
@@ -478,14 +479,21 @@ export function validateJobSpec(spec: unknown): Validated {
 			errors.push("writeRoots must be a non-empty array of non-empty strings");
 		}
 	}
-	if ("intent" in spec && spec.intent !== undefined && !isDispatchIntent(spec.intent)) {
-		errors.push("intent must be a normalized dispatch intent");
-	}
-	if (isDispatchIntent(spec.intent) && spec.intent.writeRoots.length > 0 && Array.isArray(spec.writeRoots)) {
-		const jobCwd = typeof spec.cwd === "string" && spec.cwd.length > 0 ? spec.cwd : process.cwd();
-		const legacy = [...new Set(spec.writeRoots.map((root) => resolvePathBoundary(jobCwd, String(root))))].sort();
-		const declared = [...new Set(spec.intent.writeRoots.map((root) => resolvePathBoundary(jobCwd, root)))].sort();
-		if (JSON.stringify(legacy) !== JSON.stringify(declared)) errors.push("intent_write_roots_contradiction");
+	// One owner for the typed-intent migration rules (#163). Every dispatch
+	// producer reaches a worker through this validator, so classifying here is
+	// what makes the compatibility table true of the fleet, CLI, ACP, and
+	// extension paths rather than only of the model-facing tool.
+	if ("intent" in spec) {
+		for (const refusal of dispatchIntentRefusals(
+			classifyDispatchIntentCompatibility({
+				intent: spec.intent,
+				...(spec.writeRoots !== undefined ? { writeRoots: spec.writeRoots } : {}),
+				...(spec.autonomy !== undefined ? { autonomy: spec.autonomy } : {}),
+				...(typeof spec.cwd === "string" && spec.cwd.length > 0 ? { cwd: spec.cwd } : {}),
+			}),
+		)) {
+			errors.push(refusal.message);
+		}
 	}
 
 	if ("requestOrigin" in spec && spec.requestOrigin !== undefined) {
@@ -696,6 +704,8 @@ function isValidProtectedArtifactRemap(value: unknown): value is ProtectedArtifa
 
 const VALID_GATE_ROLES = new Set(["builder", "reviewer", "candidate", "judge", "member", "synthesis"]);
 const VALID_GATE_VERDICTS = new Set(["pass", "fail", "revise"]);
+const VALID_WORKTREE_BACKENDS = new Set(["herdr", "native"]);
+const VALID_WORKTREE_FALLBACKS = new Set(["mux-unavailable", "mux-operation-failed"]);
 const VALID_PLAN_TOPOLOGIES = new Set([
 	"parallel",
 	"sequential",
@@ -724,6 +734,20 @@ function isValidGate(value: unknown): value is RunGateProvenance {
 	if (value.verdict !== undefined && (typeof value.verdict !== "string" || !VALID_GATE_VERDICTS.has(value.verdict))) {
 		return false;
 	}
+	if (value.worktree !== undefined) {
+		if (!isPlainObject(value.worktree)) return false;
+		if (typeof value.worktree.backend !== "string" || !VALID_WORKTREE_BACKENDS.has(value.worktree.backend)) return false;
+		if (typeof value.worktree.path !== "string" || !path.isAbsolute(value.worktree.path)) return false;
+		if (typeof value.worktree.branch !== "string" || value.worktree.branch.length === 0) return false;
+		if (value.worktree.workspaceId !== undefined && typeof value.worktree.workspaceId !== "string") return false;
+		if (
+			value.worktree.fallback !== undefined &&
+			(typeof value.worktree.fallback !== "string" || !VALID_WORKTREE_FALLBACKS.has(value.worktree.fallback))
+		) {
+			return false;
+		}
+		if (value.worktree.backend === "herdr" && typeof value.worktree.workspaceId !== "string") return false;
+	}
 	return true;
 }
 
@@ -734,6 +758,7 @@ function cloneGate(gate: RunGateProvenance): RunGateProvenance {
 		cycle: gate.cycle,
 		...(gate.subjects !== undefined ? { subjects: gate.subjects.map((subject) => ({ ...subject })) } : {}),
 		...(gate.verdict !== undefined ? { verdict: gate.verdict } : {}),
+		...(gate.worktree !== undefined ? { worktree: { ...gate.worktree } } : {}),
 	};
 }
 

package/src/domains/dispatch/worker-spawn.ts

@@ -26,10 +26,12 @@
 
 import { type ChildProcess, spawn } from "node:child_process";
 import { join } from "node:path";
+import { performance } from "node:perf_hooks";
 import { withClioAgentEnvironment } from "../../core/agent-environment.js";
 import { enableClioCompileCache, workerCompileCacheEnvironment } from "../../core/compile-cache.js";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import type { WorkerSpec } from "../../worker/spec-contract.js";
+import type { HeartbeatStamp } from "./heartbeat.js";
 import {
 	type AgentLedgerBody,
 	type ApprovedWorkerIdentity,
@@ -71,7 +73,7 @@ export interface SpawnedWorker {
 	promise: Promise<SpawnedWorkerResult>;
 	events: AsyncIterableIterator<unknown>;
 	abort(): void;
-	heartbeatAt: { current: number };
+	heartbeatAt: HeartbeatStamp;
 	/**
 	 * Write one JSON line to the worker's open stdin (the same line protocol
 	 * that carried the spec). Returns false when the worker has exited, its
@@ -134,15 +136,14 @@ export interface WorkerProcessOptions {
 	/** How long bulk output may precede the announce before the peer is refused. */
 	attestationGraceMs?: number;
 	/**
-	 * Clock behind the heartbeat stamp, defaulting to `Date.now`. The stamp stays
-	 * a wall-clock instant in production because the ledger, the receipt, and the
-	 * evidence record all serialize it as ISO-8601 for an operator to read. That
-	 * leaves a test with no honest way to assert the stamp advanced: comparing
-	 * two wall-clock reads taken either side of an interval orders them backward
-	 * on any host that resyncs its clock in between. A test injects the steppable
-	 * clock from tests/harness/clock.ts here and asserts on that instead.
+	 * Wall clock behind the heartbeat anchor, defaulting to `Date.now`. The
+	 * anchor stays a wall-clock instant because the ledger and evidence record
+	 * serialize the derived heartbeat as ISO-8601 for an operator to read. This
+	 * clock is read once; later heartbeat instants add a monotonic span to it.
 	 */
 	now?: () => number;
+	/** Monotonic clock used for heartbeat spans, defaulting to `performance.now`. */
+	monotonicNow?: () => number;
 }
 
 /**
@@ -192,6 +193,7 @@ export function spawnWorkerProcess(
 	const shutdownGraceMs = opts?.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS;
 	const attestationGraceMs = opts?.attestationGraceMs ?? DEFAULT_ATTESTATION_GRACE_MS;
 	const now = opts?.now ?? Date.now;
+	const monotonicNow = opts?.monotonicNow ?? (() => performance.now());
 	const approved = opts?.approvedIdentity ?? approvedIdentityForSpec(spec);
 
 	const child: ChildProcess = spawn(command, [...args], {
@@ -204,7 +206,19 @@ export function spawnWorkerProcess(
 	});
 	const pid = child.pid ?? null;
 
-	const heartbeatAt = { current: now() };
+	// One wall anchor plus a monotonic span keeps the persisted/display instant
+	// readable without ever asking a later wall-clock read how much time passed.
+	const heartbeatWallAnchor = now();
+	const heartbeatMonotonicAnchor = monotonicNow();
+	const heartbeatAt: HeartbeatStamp = {
+		current: heartbeatWallAnchor,
+		monotonic: heartbeatMonotonicAnchor,
+	};
+	const stampHeartbeat = (): void => {
+		const stamp = monotonicNow();
+		heartbeatAt.monotonic = stamp;
+		heartbeatAt.current = heartbeatWallAnchor + (stamp - heartbeatMonotonicAnchor);
+	};
 
 	const queue = createBoundedEventQueue();
 	const waiters: Array<(r: IteratorResult<unknown>) => void> = [];
@@ -233,7 +247,7 @@ export function spawnWorkerProcess(
 	}
 
 	function push(value: unknown): void {
-		heartbeatAt.current = now();
+		stampHeartbeat();
 		const w = waiters.shift();
 		if (w) {
 			w({ value, done: false });
@@ -378,7 +392,7 @@ export function spawnWorkerProcess(
 			if (!announceAccepted) failAttestation(`Invalid worker attestation: ${frame.reason}`);
 			return;
 		}
-		heartbeatAt.current = now();
+		stampHeartbeat();
 		if (frame.value.kind === "announce") {
 			if (announceAccepted || announceFailed) return;
 			const verdict = verifyWorkerAttestation(frame.value.attestation, approved);

package/src/domains/dispatch/write-boundary-enforcer.ts

@@ -26,6 +26,7 @@ import {
 	enforceWriteBoundary,
 	type WorkspaceSnapshot,
 	type WriteBoundaryAttribution,
+	type WriteBoundaryAttributionDowngrade,
 	type WriteBoundaryVerdict,
 	writeWriteBoundaryVerdict,
 } from "./write-boundary.js";
@@ -45,7 +46,7 @@ export interface WriteBoundaryEnforcerInput {
 	 * argument names. Absent entirely means the caller offers no record at all,
 	 * and every change outside the declaration is blamed on the window.
 	 */
-	recordedWritesFor?(stepId: string): ReadonlyArray<string> | null;
+	recordedWritesFor?(stepId: string): ReadonlyArray<string> | WriteBoundaryAttribution | null;
 	/** Called once per closed window with the sealed verdict and where it landed. */
 	onVerdict?(verdict: WriteBoundaryVerdict, path: string): void;
 }
@@ -91,16 +92,32 @@ export function createWriteBoundaryEnforcer(input: WriteBoundaryEnforcerInput):
 		const recordedWritesFor = input.recordedWritesFor;
 		if (recordedWritesFor === undefined) return undefined;
 		const recorded = new Set<string>();
+		const downgrades: WriteBoundaryAttributionDowngrade[] = [];
 		let complete = true;
 		for (const stepId of stepIds) {
 			const observed = recordedWritesFor(stepId);
 			if (observed === null) {
 				complete = false;
+				downgrades.push({
+					reason: "write_record_unavailable",
+					tool: null,
+					toolCallId: null,
+					runId: null,
+					stepId,
+				});
 				continue;
 			}
-			for (const target of observed) recorded.add(target);
+			if (!("recorded" in observed)) {
+				for (const target of observed) recorded.add(target);
+				continue;
+			}
+			for (const target of observed.recorded) recorded.add(target);
+			if (!observed.complete) complete = false;
+			for (const downgrade of observed.downgrades ?? []) {
+				downgrades.push({ ...downgrade, stepId: downgrade.stepId ?? stepId });
+			}
 		}
-		return { recorded: [...recorded].sort(), complete };
+		return { recorded: [...recorded].sort(), complete, downgrades };
 	};
 	return {
 		begin(window, stepIds) {

package/src/domains/dispatch/write-boundary.ts

@@ -283,6 +283,49 @@ export interface WriteBoundaryAttribution {
 	 * change outside the allowlist, and the verdict says it did.
 	 */
 	complete: boolean;
+	/** Durable causes for an incomplete record. Empty only when complete is true. */
+	downgrades?: ReadonlyArray<WriteBoundaryAttributionDowngrade>;
+}
+
+export type WriteBoundaryAttributionDowngradeReason =
+	| "opaque_tool_succeeded"
+	| "incomplete_tool_telemetry"
+	| "code_step_untracked"
+	| "write_record_unavailable";
+
+/** Why one step could not offer a closed write record. */
+export interface WriteBoundaryAttributionDowngrade {
+	reason: WriteBoundaryAttributionDowngradeReason;
+	/** Tool whose successful call opened the record, or null for a non-tool cause. */
+	tool: string | null;
+	/** Exact worker call when telemetry supplied one, or null for a non-tool cause. */
+	toolCallId: string | null;
+	/** Run that observed the cause, when one reached dispatch. */
+	runId: string | null;
+	/** Fleet step whose record was downgraded. */
+	stepId: string | null;
+}
+
+/** One operator-facing explanation shared by live and durable surfaces. */
+export function describeWriteBoundaryAttributionDowngrade(downgrade: WriteBoundaryAttributionDowngrade): string {
+	if (downgrade.reason === "opaque_tool_succeeded") {
+		const tool = downgrade.tool ?? "unknown";
+		const call = downgrade.toolCallId === null ? "" : ` (call ${downgrade.toolCallId})`;
+		return `a successful '${tool}' call${call} can write paths its arguments do not name`;
+	}
+	if (downgrade.reason === "incomplete_tool_telemetry") {
+		return downgrade.runId === null
+			? "tool telemetry was incomplete"
+			: `run '${downgrade.runId}' reported incomplete tool telemetry`;
+	}
+	if (downgrade.reason === "code_step_untracked") {
+		return downgrade.stepId === null
+			? "a code step ran through the untracked command runner"
+			: `code step '${downgrade.stepId}' ran through the untracked command runner`;
+	}
+	return downgrade.stepId === null
+		? "no usable write record was available"
+		: `step '${downgrade.stepId}' supplied no usable write record`;
 }
 
 export interface WriteBoundaryVerdict {
@@ -307,6 +350,8 @@ export interface WriteBoundaryVerdict {
 	unattributed: ReadonlyArray<string>;
 	/** Whether every step in the window offered an enumerable write record. */
 	attributionComplete: boolean;
+	/** Why attribution was incomplete, including the causal tool call when known. */
+	attributionDowngrades: ReadonlyArray<WriteBoundaryAttributionDowngrade>;
 	rolledBack: ReadonlyArray<WriteBoundaryRollback>;
 	unrecoverable: ReadonlyArray<WriteBoundaryUnrecoverable>;
 	status: WriteBoundaryStatus;
@@ -417,6 +462,19 @@ export function enforceWriteBoundary(input: EnforceWriteBoundaryInput): WriteBou
 	const changes = diffWorkspace(input.snapshot);
 	const outside = changes.filter((change) => !writeBoundaryCovers(allow, change.path));
 	const attributionComplete = input.attribution?.complete === true;
+	const attributionDowngrades: ReadonlyArray<WriteBoundaryAttributionDowngrade> = attributionComplete
+		? []
+		: input.attribution?.downgrades !== undefined && input.attribution.downgrades.length > 0
+			? input.attribution.downgrades.map((entry) => ({ ...entry }))
+			: [
+					{
+						reason: "write_record_unavailable",
+						tool: null,
+						toolCallId: null,
+						runId: null,
+						stepId: input.stepIds.length === 1 ? (input.stepIds[0] ?? null) : null,
+					},
+				];
 	const recorded = new Set<string>();
 	for (const target of input.attribution?.recorded ?? []) {
 		const relativeTarget = repoRelative(input.snapshot.root, target);
@@ -457,7 +515,9 @@ export function enforceWriteBoundary(input: EnforceWriteBoundaryInput): WriteBou
 								.join("; ")}.`,
 					attributionComplete
 						? "Each was blamed on this window because a run in it recorded writing that path."
-						: "This window had no complete write record, so every change outside the declaration was blamed on it.",
+						: `Attribution was incomplete because ${attributionDowngrades
+								.map(describeWriteBoundaryAttributionDowngrade)
+								.join("; ")}, so every change outside the declaration was blamed on this window.`,
 					"If the change was legitimate, widen the step's `writes:` declaration to cover it.",
 				];
 	const concurrentDetail =
@@ -482,6 +542,7 @@ export function enforceWriteBoundary(input: EnforceWriteBoundaryInput): WriteBou
 		violations: violations.map((change) => change.path),
 		unattributed: unattributed.map((change) => change.path),
 		attributionComplete,
+		attributionDowngrades,
 		rolledBack,
 		unrecoverable,
 		status,

package/src/domains/eval/artifacts/store.ts

@@ -3,6 +3,11 @@ import { join } from "node:path";
 import { assertSafeId } from "../../../core/safe-id.js";
 import { safeResourceWrite } from "../../../core/safe-resource-write.js";
 import type { EvalArtifactV4, EvalTokenAccountingV4 } from "../schema/artifact.js";
+import { assertEvalBehaviorReferencesVerdictV1, parseEvalBehaviorVerdictV1 } from "../schema/behavioral.js";
+import { parseEvalBehaviorMetricsV1 } from "../schema/behavioral-metrics.js";
+import { parseEvalExecutionEnvelopeV1, parseEvalExecutionMatrixDimensionsV1 } from "../schema/execution-envelope.js";
+import { parseEvalServingConfigurationV1 } from "../schema/serving.js";
+import { parseEvalVerdictEnvelopeV1 } from "../schema/verdict.js";
 import { evalRoot } from "../store.js";
 import { redactArtifactForStorage } from "./redact.js";
 
@@ -45,6 +50,14 @@ export function parseEvalArtifactV4(value: unknown, source: string): EvalArtifac
 	const summary = asRecord(value.summary, `${source}.summary`);
 	const matrix = asRecord(value.matrix, `${source}.matrix`);
 	const suite = asRecord(value.suite, `${source}.suite`);
+	const servingConfiguration =
+		value.servingConfiguration === undefined
+			? undefined
+			: parseEvalServingConfigurationV1(value.servingConfiguration, `${source}.servingConfiguration`);
+	const aggregates =
+		value.aggregates === undefined
+			? undefined
+			: (readArray(value, source, "aggregates") as NonNullable<EvalArtifactV4["aggregates"]>);
 	return {
 		version: 4,
 		evalId: readString(value, source, "evalId"),
@@ -62,7 +75,11 @@ export function parseEvalArtifactV4(value: unknown, source: string): EvalArtifac
 			target: readString(matrix, `${source}.matrix`, "target"),
 			model: readNullableString(matrix, `${source}.matrix`, "model"),
 			thinking: readNullableString(matrix, `${source}.matrix`, "thinking"),
+			...(matrix.dimensions === undefined
+				? {}
+				: { dimensions: parseEvalExecutionMatrixDimensionsV1(matrix.dimensions, `${source}.matrix.dimensions`) }),
 		},
+		...(servingConfiguration === undefined ? {} : { servingConfiguration }),
 		summary: {
 			runs: readNumber(summary, `${source}.summary`, "runs"),
 			passed: readNumber(summary, `${source}.summary`, "passed"),
@@ -71,6 +88,7 @@ export function parseEvalArtifactV4(value: unknown, source: string): EvalArtifac
 			tokens: parseTokenAccounting(summary.tokens, `${source}.summary.tokens`),
 			wallTimeMs: readNumber(summary, `${source}.summary`, "wallTimeMs"),
 		},
+		...(aggregates === undefined ? {} : { aggregates }),
 		results: readArray(value, source, "results").map((entry, index) => parseResult(entry, `${source}.results[${index}]`)),
 	};
 }
@@ -108,6 +126,46 @@ function parseTokenAccounting(value: unknown, source: string): EvalTokenAccounti
 function parseResult(value: unknown, source: string): EvalArtifactV4["results"][number] {
 	const record = asRecord(value, source);
 	const target = asRecord(record.target, `${source}.target`);
+	const verdict =
+		record.verdict === undefined ? undefined : parseEvalVerdictEnvelopeV1(record.verdict, `${source}.verdict`);
+	const behavioral =
+		record.behavioral === undefined ? undefined : parseEvalBehaviorVerdictV1(record.behavioral, `${source}.behavioral`);
+	const behavioralMetrics =
+		record.behavioralMetrics === undefined
+			? undefined
+			: parseEvalBehaviorMetricsV1(record.behavioralMetrics, `${source}.behavioralMetrics`);
+	const executionEnvelope =
+		record.executionEnvelope === undefined
+			? undefined
+			: parseEvalExecutionEnvelopeV1(record.executionEnvelope, `${source}.executionEnvelope`);
+	if (behavioral !== undefined && verdict === undefined) {
+		throw new Error(`${source}.behavioral: sibling document requires a verdict`);
+	}
+	if (behavioral !== undefined && verdict !== undefined) {
+		assertEvalBehaviorReferencesVerdictV1(behavioral, verdict, `${source}.behavioral`);
+	}
+	if (behavioralMetrics !== undefined) {
+		if (behavioral === undefined) throw new Error(`${source}.behavioralMetrics: requires a behavioral verdict`);
+		if (behavioralMetrics.scenarioId !== readString(record, source, "taskId")) {
+			throw new Error(`${source}.behavioralMetrics.scenarioId: conflicts with result taskId`);
+		}
+		if (
+			behavioralMetrics.target.id !== readString(target, `${source}.target`, "id") ||
+			behavioralMetrics.target.model !== readNullableString(target, `${source}.target`, "model")
+		) {
+			throw new Error(`${source}.behavioralMetrics.target: conflicts with result target`);
+		}
+	}
+	if (executionEnvelope !== undefined) {
+		if (behavioral === undefined) throw new Error(`${source}.executionEnvelope: requires a behavioral verdict`);
+		if (
+			executionEnvelope.target !== readString(target, `${source}.target`, "id") ||
+			executionEnvelope.corpus.id !== behavioral.corpus.id ||
+			executionEnvelope.corpus.version !== behavioral.corpus.version
+		) {
+			throw new Error(`${source}.executionEnvelope: conflicts with result target or behavioral corpus`);
+		}
+	}
 	return {
 		assignmentId: readNullableString(record, source, "assignmentId"),
 		terminalReceiptDigest: readNullableDigest(record, source, "terminalReceiptDigest"),
@@ -122,6 +180,10 @@ function parseResult(value: unknown, source: string): EvalArtifactV4["results"][
 		failureClass: readNullableString(record, source, "failureClass"),
 		metrics: asRecord(record.metrics, `${source}.metrics`) as Record<string, number | string | boolean | null>,
 		artifacts: asRecord(record.artifacts, `${source}.artifacts`) as Record<string, string | string[] | null>,
+		...(verdict === undefined ? {} : { verdict }),
+		...(behavioral === undefined ? {} : { behavioral }),
+		...(behavioralMetrics === undefined ? {} : { behavioralMetrics }),
+		...(executionEnvelope === undefined ? {} : { executionEnvelope }),
 	};
 }
 

package/src/domains/eval/compare/behavioral.ts

@@ -0,0 +1,224 @@
+import type { EvalArtifactResultV4, EvalArtifactV4 } from "../schema/artifact.js";
+import {
+	EVAL_BEHAVIOR_METRIC_DEFINITIONS_V1,
+	type EvalBehaviorMetricDefinitionV1,
+	type EvalBehaviorMetricFamilyV1,
+	type EvalBehaviorMetricNameV1,
+	type EvalBehaviorMetricSourceV1,
+} from "../schema/behavioral-metrics.js";
+import type { EvalExecutionMatrixDimensionV1 } from "../schema/execution-envelope.js";
+import {
+	compareEvalExecutionEnvelopesV1,
+	type EvalEnvelopeComparabilityV1,
+	type EvalEnvelopeMismatchV1,
+} from "./envelope.js";
+
+export type EvalMetricChangeV1 = "improved" | "regressed" | "unchanged" | "incomparable";
+
+export interface EvalBehaviorMetricDistributionV1 {
+	observations: number;
+	measured: number;
+	unmeasured: number;
+	mean: number | null;
+	min: number | null;
+	max: number | null;
+	p90: number | null;
+	variance: number | null;
+	standardDeviation: number | null;
+	source: EvalBehaviorMetricSourceV1;
+}
+
+export interface EvalBehaviorMetricComparisonV1 {
+	scenarioId: string;
+	role: string;
+	target: { id: string; model: string | null };
+	metric: EvalBehaviorMetricNameV1;
+	family: EvalBehaviorMetricFamilyV1;
+	direction: "higher" | "lower";
+	hardGate: boolean;
+	baseline: EvalBehaviorMetricDistributionV1;
+	candidate: EvalBehaviorMetricDistributionV1;
+	change: EvalMetricChangeV1;
+	meanDelta: number | null;
+	varianceChange: EvalMetricChangeV1;
+	varianceDelta: number | null;
+	comparability: EvalEnvelopeComparabilityV1;
+}
+
+export interface EvalBehaviorHardGateV1 {
+	pass: boolean;
+	envelopeFailures: EvalEnvelopeMismatchV1[];
+	failures: Array<{
+		scenarioId: string;
+		role: string;
+		target: { id: string; model: string | null };
+		metric: EvalBehaviorMetricNameV1;
+		change: "regressed" | "incomparable";
+	}>;
+}
+
+interface BehaviorGroup {
+	scenarioId: string;
+	role: string;
+	target: { id: string; model: string | null };
+	results: EvalArtifactResultV4[];
+}
+
+export function compareEvalBehaviorMetricsV1(
+	baseline: EvalArtifactV4,
+	candidate: EvalArtifactV4,
+): {
+	comparisons: EvalBehaviorMetricComparisonV1[];
+	hardGate: EvalBehaviorHardGateV1;
+	envelopeMismatches: EvalEnvelopeMismatchV1[];
+} {
+	const baselineGroups = behaviorGroups(baseline);
+	const candidateGroups = behaviorGroups(candidate);
+	const keys = new Set([...baselineGroups.keys(), ...candidateGroups.keys()]);
+	const comparisons: EvalBehaviorMetricComparisonV1[] = [];
+	const envelopeMismatches: EvalEnvelopeMismatchV1[] = [];
+	const baselineDimensions = baseline.matrix.dimensions ?? ([] as EvalExecutionMatrixDimensionV1[]);
+	const candidateDimensions = candidate.matrix.dimensions ?? ([] as EvalExecutionMatrixDimensionV1[]);
+	for (const key of [...keys].sort((left, right) => left.localeCompare(right))) {
+		const baselineGroup = baselineGroups.get(key);
+		const candidateGroup = candidateGroups.get(key);
+		const identity = baselineGroup ?? candidateGroup;
+		if (identity === undefined) continue;
+		const envelopeMismatch = compareEvalExecutionEnvelopesV1(
+			identity,
+			baselineGroup?.results ?? [],
+			candidateGroup?.results ?? [],
+			baselineDimensions,
+			candidateDimensions,
+		);
+		if (envelopeMismatch !== null) envelopeMismatches.push(envelopeMismatch);
+		const comparability: EvalEnvelopeComparabilityV1 = {
+			comparable: envelopeMismatch === null,
+			mismatchedFields: envelopeMismatch?.fields ?? [],
+		};
+		for (const definition of EVAL_BEHAVIOR_METRIC_DEFINITIONS_V1) {
+			const baselineDistribution = behaviorDistribution(baselineGroup?.results ?? [], definition);
+			const candidateDistribution = behaviorDistribution(candidateGroup?.results ?? [], definition);
+			comparisons.push({
+				scenarioId: identity.scenarioId,
+				role: identity.role,
+				target: identity.target,
+				metric: definition.name,
+				family: definition.family,
+				direction: definition.direction,
+				hardGate: definition.hardGate,
+				baseline: baselineDistribution,
+				candidate: candidateDistribution,
+				change:
+					envelopeMismatch === null
+						? classifyChange(baselineDistribution.mean, candidateDistribution.mean, definition.direction)
+						: "incomparable",
+				meanDelta: subtractNullable(candidateDistribution.mean, baselineDistribution.mean),
+				varianceChange:
+					envelopeMismatch === null
+						? classifyChange(baselineDistribution.variance, candidateDistribution.variance, "lower")
+						: "incomparable",
+				varianceDelta: subtractNullable(candidateDistribution.variance, baselineDistribution.variance),
+				comparability,
+			});
+		}
+	}
+	const failures = comparisons.flatMap((comparison) =>
+		comparison.hardGate &&
+		(comparison.change === "regressed" ||
+			(comparison.change === "incomparable" && comparison.baseline.mean !== null && comparison.candidate.mean === null))
+			? [
+					{
+						scenarioId: comparison.scenarioId,
+						role: comparison.role,
+						target: comparison.target,
+						metric: comparison.metric,
+						change: comparison.change,
+					},
+				]
+			: [],
+	);
+	return {
+		comparisons,
+		hardGate: {
+			pass: failures.length === 0 && envelopeMismatches.length === 0,
+			failures,
+			envelopeFailures: envelopeMismatches,
+		},
+		envelopeMismatches,
+	};
+}
+
+export function classifyChange(
+	baseline: number | null,
+	candidate: number | null,
+	direction: "higher" | "lower",
+): EvalMetricChangeV1 {
+	if (baseline === null || candidate === null) return "incomparable";
+	if (baseline === candidate) return "unchanged";
+	if (direction === "higher") return candidate > baseline ? "improved" : "regressed";
+	return candidate < baseline ? "improved" : "regressed";
+}
+
+function behaviorGroups(artifact: EvalArtifactV4): Map<string, BehaviorGroup> {
+	const groups = new Map<string, BehaviorGroup>();
+	for (const result of artifact.results) {
+		const behavioral = result.behavioralMetrics;
+		if (behavioral === undefined) continue;
+		const key = groupKey(behavioral.scenarioId, behavioral.role, behavioral.target);
+		const group = groups.get(key) ?? {
+			scenarioId: behavioral.scenarioId,
+			role: behavioral.role,
+			target: behavioral.target,
+			results: [],
+		};
+		group.results.push(result);
+		groups.set(key, group);
+	}
+	return groups;
+}
+
+function behaviorDistribution(
+	results: ReadonlyArray<EvalArtifactResultV4>,
+	definition: EvalBehaviorMetricDefinitionV1,
+): EvalBehaviorMetricDistributionV1 {
+	const observations = results.map((result) => result.behavioralMetrics?.metrics[definition.name].value ?? null);
+	const values = observations.flatMap((value) => (value === null ? [] : [value]));
+	if (values.length === 0) {
+		return {
+			observations: observations.length,
+			measured: 0,
+			unmeasured: observations.length,
+			mean: null,
+			min: null,
+			max: null,
+			p90: null,
+			variance: null,
+			standardDeviation: null,
+			source: definition.source,
+		};
+	}
+	const ordered = [...values].sort((left, right) => left - right);
+	const mean = ordered.reduce((sum, value) => sum + value, 0) / ordered.length;
+	const variance = ordered.reduce((sum, value) => sum + (value - mean) ** 2, 0) / ordered.length;
+	return {
+		observations: observations.length,
+		measured: values.length,
+		unmeasured: observations.length - values.length,
+		mean,
+		min: ordered[0] ?? null,
+		max: ordered.at(-1) ?? null,
+		p90: ordered[Math.max(0, Math.ceil(ordered.length * 0.9) - 1)] ?? null,
+		variance,
+		standardDeviation: Math.sqrt(variance),
+		source: definition.source,
+	};
+}
+
+function groupKey(scenarioId: string, role: string, target: { id: string; model: string | null }): string {
+	return JSON.stringify([scenarioId, role, target.id, target.model]);
+}
+
+function subtractNullable(left: number | null, right: number | null): number | null {
+	return left === null || right === null ? null : left - right;
+}