@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/domains/dispatch/reservation-store.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { withStateFileLockSync } from "../../core/state-file-lock.js";
+import { endpointLabel } from "../providers/endpoint-capacity.js";
 import {
 	acquireCapacityLease,
 	activeCapacityDrainUnsafe,
@@ -7,6 +8,7 @@ import {
 	type CapacityLimits,
 	type CapacityStateFile,
 	capacityStateLockPath,
+	describeEndpointCapacityHolders,
 	readCapacityStateUnsafe,
 	writeCapacityStateUnsafe,
 } from "./capacity-lease.js";
@@ -19,9 +21,10 @@ export type ReservationMemberStatus = "held" | "consumed" | "released";
 export type ReservationStatus = "active" | "released" | "rolled_back" | "expired";
 
 /**
- * A reservation holds three scarce things and nothing else: a global
- * concurrency slot, a per-node slot, and a budget upper bound. Node identity
- * matters only because slots are per-node. Agent, target, model, and runtime
+ * A reservation holds four scarce things and nothing else: a global
+ * concurrency slot, a per-node slot, an inference-endpoint slot, and a budget
+ * upper bound. Node and endpoint identity matter only because slots bind on
+ * those dimensions. Agent, target, model, and runtime
  * identity are route identity, which the failover envelope owns
  * (`assertRouteWithinApprovedEnvelope`); pinning them here made a
  * plan-approved dispatch unable to fail over at all.
@@ -30,6 +33,7 @@ export interface ReservationPlanTask {
 	memberId: string;
 	wave: number;
 	nodeId: string;
+	endpointKey?: string;
 	costUpperBoundUsd: number;
 }
 
@@ -54,17 +58,31 @@ export interface DispatchReservationRecord {
 export interface ReservationCapacitySnapshot {
 	global: { active: number; limit: number };
 	nodes: Readonly<Record<string, { active: number; limit: number }>>;
+	endpoints: Readonly<Record<string, { active: number; limit: number; leases?: number; foregroundStreams?: number }>>;
 	budget: { currentUsd: number; ceilingUsd: number };
 }
 
 export interface ReservationAllocation {
 	globalSlots: number;
 	nodeSlots: Readonly<Record<string, number>>;
+	endpointSlots: Readonly<Record<string, number>>;
 	budgetUsd: number;
 }
 
 export type ReservationPlanResult = { ok: true; allocation: ReservationAllocation } | { ok: false; reason: string };
 
+function endpointCapacityDenial(input: {
+	endpointKey: string;
+	limit: number;
+	used: number;
+	requested: number;
+	leases: number;
+	reservations: number;
+	foregroundStreams: number;
+}): string {
+	return `dispatch: admission denied: endpoint '${endpointLabel(input.endpointKey)}' capacity exceeded (${input.used + input.requested}/${input.limit} slots): ${describeEndpointCapacityHolders(input)}; reduce the same-wave worker count, collect in-flight runs, or point workers at a second server`;
+}
+
 function copyRecord(record: DispatchReservationRecord): DispatchReservationRecord {
 	return { ...record, members: record.members.map((member) => ({ ...member })) };
 }
@@ -96,6 +114,7 @@ function validRecord(value: unknown): value is DispatchReservationRecord {
 				typeof member.memberId === "string" &&
 				Number.isInteger(member.wave) &&
 				typeof member.nodeId === "string" &&
+				(member.endpointKey === undefined || typeof member.endpointKey === "string") &&
 				typeof member.costUpperBoundUsd === "number" &&
 				Number.isFinite(member.costUpperBoundUsd) &&
 				member.costUpperBoundUsd >= 0 &&
@@ -145,9 +164,13 @@ function reservationAllocation(tasks: ReadonlyArray<ReservationPlanTask>): Reser
 		),
 	);
 	const nodeSlots = peakBy(tasks.map((task) => ({ wave: task.wave, key: task.nodeId })));
+	const endpointSlots = peakBy(
+		tasks.flatMap((task) => (task.endpointKey === undefined ? [] : [{ wave: task.wave, key: task.endpointKey }])),
+	);
 	return {
 		globalSlots,
 		nodeSlots,
+		endpointSlots,
 		budgetUsd: tasks.reduce((sum, task) => sum + task.costUpperBoundUsd, 0),
 	};
 }
@@ -191,6 +214,26 @@ function allocateReservation(
 			return { ok: false, reason: `node '${nodeId}' capacity exceeded (${used + slots}/${node.limit})` };
 		}
 	}
+	for (const [endpointKey, slots] of Object.entries(requested.endpointSlots)) {
+		const endpoint = capacity.endpoints[endpointKey];
+		if (!endpoint || !Number.isFinite(endpoint.limit)) continue;
+		const heldSlots = held.reduce((sum, allocation) => sum + (allocation.endpointSlots[endpointKey] ?? 0), 0);
+		const used = endpoint.active + heldSlots;
+		if (used + slots > endpoint.limit) {
+			return {
+				ok: false,
+				reason: endpointCapacityDenial({
+					endpointKey,
+					limit: endpoint.limit,
+					used,
+					requested: slots,
+					leases: endpoint.leases ?? endpoint.active - (endpoint.foregroundStreams ?? 0),
+					reservations: heldSlots,
+					foregroundStreams: endpoint.foregroundStreams ?? 0,
+				}),
+			};
+		}
+	}
 	const existingBudget = activeRecords.reduce((sum, record) => sum + outstandingBudget(record), 0);
 	const projected = capacity.budget.currentUsd + existingBudget + requested.budgetUsd;
 	if (projected >= capacity.budget.ceilingUsd) {
@@ -225,7 +268,9 @@ export function createDispatchReservation(input: {
 		if (!planned.ok) {
 			replaceReservations(state, records);
 			writeCapacityStateUnsafe(state);
-			throw new Error(`dispatch: reservation denied: ${planned.reason}`);
+			throw new Error(
+				planned.reason.startsWith("dispatch:") ? planned.reason : `dispatch: reservation denied: ${planned.reason}`,
+			);
 		}
 		const createdAt = new Date(nowMs).toISOString();
 		const record: DispatchReservationRecord = {
@@ -250,6 +295,7 @@ export function transferDispatchReservationToLease(input: {
 	memberId: string;
 	assignmentId: string;
 	nodeId: string;
+	endpointKey?: string;
 	limits: CapacityLimits;
 	nowMs?: number;
 	ttlMs?: number;
@@ -258,6 +304,7 @@ export function transferDispatchReservationToLease(input: {
 	return acquireCapacityLease({
 		assignmentId: input.assignmentId,
 		nodeId: input.nodeId,
+		...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 		limits: input.limits,
 		nowMs,
 		...(input.ttlMs !== undefined ? { ttlMs: input.ttlMs } : {}),
@@ -290,6 +337,7 @@ export function rebindDispatchReservationMember(input: {
 	ownerId: string;
 	memberId: string;
 	nodeId: string;
+	endpointKey?: string;
 	costUpperBoundUsd: number;
 	capacity: ReservationCapacitySnapshot;
 	nowMs?: number;
@@ -304,11 +352,42 @@ export function rebindDispatchReservationMember(input: {
 		if (member.status === "released") {
 			throw new Error(`dispatch: reservation member '${input.memberId}' was already released`);
 		}
-		if (member.nodeId === input.nodeId && member.costUpperBoundUsd === input.costUpperBoundUsd) {
+		if (
+			member.nodeId === input.nodeId &&
+			member.endpointKey === input.endpointKey &&
+			member.costUpperBoundUsd === input.costUpperBoundUsd
+		) {
 			return copyRecord(record);
 		}
-
 		const others = records.filter((entry) => entry.status === "active" && entry.ownerId !== input.ownerId);
+		if (member.endpointKey !== input.endpointKey && input.endpointKey !== undefined) {
+			const endpointKey = input.endpointKey;
+			const endpoint = input.capacity.endpoints[endpointKey];
+			if (endpoint !== undefined && Number.isFinite(endpoint.limit)) {
+				const siblingSlots = record.members.filter(
+					(entry) => entry !== member && entry.status !== "released" && entry.endpointKey === endpointKey,
+				).length;
+				const otherHeld = others.reduce(
+					(sum, entry) => sum + (reservationAllocation(outstandingTasks(entry)).endpointSlots[endpointKey] ?? 0),
+					0,
+				);
+				const used = endpoint.active + otherHeld + siblingSlots;
+				if (used + 1 > endpoint.limit) {
+					throw new Error(
+						endpointCapacityDenial({
+							endpointKey,
+							limit: endpoint.limit,
+							used,
+							requested: 1,
+							leases: endpoint.leases ?? endpoint.active - (endpoint.foregroundStreams ?? 0),
+							reservations: otherHeld + siblingSlots,
+							foregroundStreams: endpoint.foregroundStreams ?? 0,
+						}),
+					);
+				}
+			}
+		}
+
 		if (member.nodeId !== input.nodeId) {
 			const node = input.capacity.nodes[input.nodeId];
 			if (node !== undefined && Number.isFinite(node.limit)) {
@@ -342,6 +421,8 @@ export function rebindDispatchReservationMember(input: {
 		}
 
 		member.nodeId = input.nodeId;
+		if (input.endpointKey === undefined) delete member.endpointKey;
+		else member.endpointKey = input.endpointKey;
 		member.costUpperBoundUsd = Math.max(0, input.costUpperBoundUsd);
 		writeStore(records);
 		return copyRecord(record);
@@ -370,6 +451,26 @@ export function releaseDispatchReservationMember(
 	});
 }
 
+/** Settle every member after the scheduler has finished the reserved plan. */
+export function releaseDispatchReservation(ownerId: string, nowMs = Date.now()): DispatchReservationRecord | null {
+	return withStateFileLockSync(capacityStateLockPath(), () => {
+		const records = readStore();
+		const record = records.find((entry) => entry.ownerId === ownerId);
+		if (!record) return null;
+		if (record.status !== "active") return copyRecord(record);
+		const settledAt = new Date(nowMs).toISOString();
+		for (const member of record.members) {
+			if (member.status === "released") continue;
+			member.status = "released";
+			member.releasedAt = settledAt;
+		}
+		record.status = "released";
+		record.settledAt = settledAt;
+		writeStore(records);
+		return copyRecord(record);
+	});
+}
+
 export function rollbackDispatchReservation(ownerId: string, nowMs = Date.now()): DispatchReservationRecord | null {
 	return withStateFileLockSync(capacityStateLockPath(), () => {
 		const records = readStore();
@@ -488,14 +589,21 @@ export function reservedBudgetUsd(): number {
 		.reduce((sum, record) => sum + outstandingBudget(record), 0);
 }
 
-export function reservedCapacity(): { globalSlots: number; nodeSlots: Readonly<Record<string, number>> } {
+export function reservedCapacity(): {
+	globalSlots: number;
+	nodeSlots: Readonly<Record<string, number>>;
+	endpointSlots: Readonly<Record<string, number>>;
+} {
 	let globalSlots = 0;
 	const nodeSlots: Record<string, number> = {};
+	const endpointSlots: Record<string, number> = {};
 	for (const record of readStore().filter((entry) => entry.status === "active")) {
 		const allocation = reservationAllocation(outstandingTasks(record));
 		globalSlots += allocation.globalSlots;
 		for (const [nodeId, count] of Object.entries(allocation.nodeSlots))
 			nodeSlots[nodeId] = (nodeSlots[nodeId] ?? 0) + count;
+		for (const [endpointKey, count] of Object.entries(allocation.endpointSlots))
+			endpointSlots[endpointKey] = (endpointSlots[endpointKey] ?? 0) + count;
 	}
-	return { globalSlots, nodeSlots };
+	return { globalSlots, nodeSlots, endpointSlots };
 }

package/src/domains/dispatch/state.ts

@@ -107,6 +107,10 @@ export async function writeFleetRun(record: FleetRunRecord): Promise<void> {
 	await atomicWrite(fleetRunPath(record.id), `${JSON.stringify(record, null, 2)}\n`);
 }
 
+// `RunEnvelope.heartbeatAt` deliberately persists only the absolute wall-clock
+// anchor used for operator display and crash recovery. The monotonic heartbeat
+// stamp belongs to the live transport in this process; serializing it would
+// give a restarted process a number from an origin it cannot share.
 function readRuns(): RunEnvelope[] {
 	const path = runsPath();
 	if (!existsSync(path)) return [];

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 }),
 	};
 }