@iowarp/clio-coder 0.4.8 → 0.4.9

package/src/tools/verify/perf.ts

@@ -2,20 +2,73 @@
  * Pure budget math for `kind: perf-budget` verifier checks. The harness
  * measures the command's wall time; this module decides pass or fail against
  * a declared budget or a recorded baseline and writes the structured report.
- * It reads no file and runs nothing.
+ * It reads no file and runs nothing; the one impure function here,
+ * {@link capturePerfEnvironment}, reads the host description so a baseline
+ * can say where it was measured.
+ *
+ * A wall-time verdict is a statement about this machine at this moment. The
+ * report carries the baseline's recorded environment beside the current one
+ * and names every field that differs, because a baseline recorded on a
+ * different CPU says little about a regression here. The comparison is
+ * informational: it never changes pass or fail.
  */
 
+import { arch, cpus, hostname, platform, totalmem } from "node:os";
+
 export interface PerfBudgetSpec {
 	wallTimeMs: number;
 	tolerance?: { relative?: number };
 }
 
+/** The host a baseline was recorded on, as far as Node can describe it. */
+export interface PerfEnvironment {
+	hostname: string;
+	platform: string;
+	arch: string;
+	cpuModel: string;
+	cpuCount: number;
+	totalMemoryBytes: number;
+	nodeVersion: string;
+}
+
+export type PerfEnvironmentField = keyof PerfEnvironment;
+
+const PERF_ENVIRONMENT_FIELDS: ReadonlyArray<PerfEnvironmentField> = [
+	"hostname",
+	"platform",
+	"arch",
+	"cpuModel",
+	"cpuCount",
+	"totalMemoryBytes",
+	"nodeVersion",
+];
+
 export interface PerfBaseline {
 	wallTimeMs: number;
 	/** ISO time the baseline was recorded; informational. */
 	recordedAt?: string;
 	/** Check id the baseline was recorded for; informational. */
 	check?: string;
+	/** Host the baseline was recorded on; absent on version 1 files. */
+	environment?: PerfEnvironment;
+}
+
+/** Identity of the baseline file a judgement read. */
+export interface PerfBaselineProvenance {
+	path: string;
+	/** SHA-256 of the exact baseline text. */
+	sha256: string;
+	bytes: number;
+	recordedAt?: string;
+	check?: string;
+}
+
+/** Baseline host beside the judging host, with the fields that differ named. */
+export interface PerfEnvironmentComparison {
+	/** Null when the baseline file recorded no environment (a version 1 file). */
+	baseline: PerfEnvironment | null;
+	current: PerfEnvironment;
+	differing: PerfEnvironmentField[];
 }
 
 export interface PerfBudgetReport {
@@ -31,9 +84,15 @@ export interface PerfBudgetReport {
 	referenceMs: number;
 	relative: number;
 	summary: string;
+	/** Present for a baseline judgement when the judging host was captured. Informational only. */
+	environment?: PerfEnvironmentComparison;
+	/** Present when the judgement read a baseline file. */
+	baseline?: PerfBaselineProvenance;
 }
 
-export const PERF_BASELINE_VERSION = 1;
+/** The version this build writes. Version 1 files, which record no environment, still load. */
+export const PERF_BASELINE_VERSION = 2;
+const SUPPORTED_BASELINE_VERSIONS: ReadonlyArray<number> = [1, PERF_BASELINE_VERSION];
 
 export function normalizePerfBudget(value: unknown): PerfBudgetSpec | Error {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) {
@@ -68,7 +127,56 @@ export function normalizePerfTolerance(value: unknown, location: string): { rela
 	return { relative: record.relative };
 }
 
-/** Parse a baseline file written by `clio-coder verifiers baseline <id>`. */
+/** Describe the host this process runs on. */
+export function capturePerfEnvironment(): PerfEnvironment {
+	const processors = cpus();
+	return {
+		hostname: hostname(),
+		platform: platform(),
+		arch: arch(),
+		cpuModel: processors[0]?.model.trim() ?? "unknown",
+		cpuCount: processors.length,
+		totalMemoryBytes: totalmem(),
+		nodeVersion: process.version,
+	};
+}
+
+function parsePerfEnvironment(value: unknown, label: string): PerfEnvironment | Error {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		return new Error(`${label} must be an object describing the recording host`);
+	}
+	const record = value as Record<string, unknown>;
+	const unknown = Object.keys(record).filter((key) => !(PERF_ENVIRONMENT_FIELDS as ReadonlyArray<string>).includes(key));
+	if (unknown.length > 0) return new Error(`${label} has unknown field(s): ${unknown.sort().join(", ")}`);
+	for (const field of ["hostname", "platform", "arch", "cpuModel", "nodeVersion"] as const) {
+		if (typeof record[field] !== "string") return new Error(`${label}.${field} must be a string`);
+	}
+	if (typeof record.cpuCount !== "number" || !Number.isInteger(record.cpuCount) || record.cpuCount < 0) {
+		return new Error(`${label}.cpuCount must be a non-negative integer`);
+	}
+	if (
+		typeof record.totalMemoryBytes !== "number" ||
+		!Number.isFinite(record.totalMemoryBytes) ||
+		record.totalMemoryBytes < 0
+	) {
+		return new Error(`${label}.totalMemoryBytes must be a non-negative number`);
+	}
+	return {
+		hostname: record.hostname as string,
+		platform: record.platform as string,
+		arch: record.arch as string,
+		cpuModel: record.cpuModel as string,
+		cpuCount: record.cpuCount,
+		totalMemoryBytes: record.totalMemoryBytes,
+		nodeVersion: record.nodeVersion as string,
+	};
+}
+
+/**
+ * Parse a baseline file written by `clio-coder verifiers baseline <id>`. A
+ * version 1 file (or one without a version) carries no environment; a version
+ * 2 file carries the recording host.
+ */
 export function parsePerfBaseline(text: string, label: string): PerfBaseline | Error {
 	let parsed: unknown;
 	try {
@@ -80,38 +188,81 @@ export function parsePerfBaseline(text: string, label: string): PerfBaseline | E
 		return new Error(`${label} must be a JSON object with wallTimeMs`);
 	}
 	const record = parsed as Record<string, unknown>;
+	if (Object.hasOwn(record, "version")) {
+		if (typeof record.version !== "number" || !SUPPORTED_BASELINE_VERSIONS.includes(record.version)) {
+			return new Error(`${label}.version must be one of ${SUPPORTED_BASELINE_VERSIONS.join(", ")}`);
+		}
+	}
 	if (typeof record.wallTimeMs !== "number" || !Number.isFinite(record.wallTimeMs) || record.wallTimeMs <= 0) {
 		return new Error(`${label}.wallTimeMs must be a positive number of milliseconds`);
 	}
 	const baseline: PerfBaseline = { wallTimeMs: record.wallTimeMs };
 	if (typeof record.recordedAt === "string") baseline.recordedAt = record.recordedAt;
 	if (typeof record.check === "string") baseline.check = record.check;
+	if (Object.hasOwn(record, "environment") && record.environment !== undefined) {
+		const environment = parsePerfEnvironment(record.environment, `${label}.environment`);
+		if (environment instanceof Error) return environment;
+		baseline.environment = environment;
+	}
 	return baseline;
 }
 
 /** The JSON text a baseline file holds; stable key order so a re-record is a clean diff. */
-export function renderPerfBaseline(input: { wallTimeMs: number; check: string; recordedAt: string }): string {
+export function renderPerfBaseline(input: {
+	wallTimeMs: number;
+	check: string;
+	recordedAt: string;
+	environment: PerfEnvironment;
+}): string {
 	return `${JSON.stringify(
-		{ version: PERF_BASELINE_VERSION, check: input.check, wallTimeMs: input.wallTimeMs, recordedAt: input.recordedAt },
+		{
+			version: PERF_BASELINE_VERSION,
+			check: input.check,
+			wallTimeMs: input.wallTimeMs,
+			recordedAt: input.recordedAt,
+			environment: {
+				hostname: input.environment.hostname,
+				platform: input.environment.platform,
+				arch: input.environment.arch,
+				cpuModel: input.environment.cpuModel,
+				cpuCount: input.environment.cpuCount,
+				totalMemoryBytes: input.environment.totalMemoryBytes,
+				nodeVersion: input.environment.nodeVersion,
+			},
+		},
 		null,
 		2,
 	)}\n`;
 }
 
+/** Name every field on which the judging host differs from the recording host. */
+export function comparePerfEnvironments(
+	baseline: PerfEnvironment | undefined,
+	current: PerfEnvironment,
+): PerfEnvironmentComparison {
+	if (baseline === undefined) return { baseline: null, current, differing: [] };
+	const differing = PERF_ENVIRONMENT_FIELDS.filter((field) => baseline[field] !== current[field]);
+	return { baseline, current, differing };
+}
+
 /**
  * Judge a measurement. A declared budget bounds the time at
  * `wallTimeMs * (1 + tolerance.relative)`; a baseline bounds it at
  * `baseline.wallTimeMs * (1 + relative)`. Measured time above the bound fails.
+ * When `environment` names the judging host and the judgement uses a
+ * baseline, the report compares the two hosts; a difference is reported and
+ * never changes the verdict.
  */
 export function evaluatePerfBudget(
 	measuredMs: number,
-	spec: { budget?: PerfBudgetSpec; baseline?: PerfBaseline; relative?: number },
+	spec: { budget?: PerfBudgetSpec; baseline?: PerfBaseline; relative?: number; environment?: PerfEnvironment },
 ): PerfBudgetReport | Error {
 	if (!Number.isFinite(measuredMs) || measuredMs < 0)
 		return new Error("measured wall time must be a non-negative number");
 	let source: PerfBudgetReport["source"];
 	let referenceMs: number;
 	let relative: number;
+	let comparison: PerfEnvironmentComparison | undefined;
 	if (spec.budget !== undefined) {
 		source = "budget";
 		referenceMs = spec.budget.wallTimeMs;
@@ -120,6 +271,7 @@ export function evaluatePerfBudget(
 		source = "baseline";
 		referenceMs = spec.baseline.wallTimeMs;
 		relative = spec.relative ?? 0;
+		if (spec.environment !== undefined) comparison = comparePerfEnvironments(spec.baseline.environment, spec.environment);
 	} else {
 		return new Error("perf-budget needs a budget or a recorded baseline");
 	}
@@ -127,6 +279,17 @@ export function evaluatePerfBudget(
 	const ratio = Math.round((measuredMs / budgetMs) * 1000) / 1000;
 	const passed = measuredMs <= budgetMs;
 	const bound = `${Math.round(budgetMs)}ms (${source} ${Math.round(referenceMs)}ms${relative > 0 ? ` +${Math.round(relative * 100)}%` : ""})`;
+	const verdict = passed
+		? `perf-budget passed: measured ${Math.round(measuredMs)}ms within ${bound}, ratio ${ratio}`
+		: `perf-budget failed: measured ${Math.round(measuredMs)}ms exceeds ${bound}, ratio ${ratio}`;
+	const environmentNote =
+		comparison === undefined
+			? ""
+			: comparison.baseline === null
+				? "; baseline records no environment"
+				: comparison.differing.length > 0
+					? `; environment differs: ${comparison.differing.join(", ")}`
+					: "";
 	return {
 		kind: "perf-budget",
 		passed,
@@ -136,8 +299,7 @@ export function evaluatePerfBudget(
 		source,
 		referenceMs,
 		relative,
-		summary: passed
-			? `perf-budget passed: measured ${Math.round(measuredMs)}ms within ${bound}, ratio ${ratio}`
-			: `perf-budget failed: measured ${Math.round(measuredMs)}ms exceeds ${bound}, ratio ${ratio}`,
+		summary: `${verdict}${environmentNote}`,
+		...(comparison !== undefined ? { environment: comparison } : {}),
 	};
 }

package/src/tools/verify/scripts.ts

@@ -1,4 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { resolveSafeCwd, runCommandVector, type SafeCommandResult } from "../../core/safe-exec.js";
 import { declaredVerificationScripts, VERIFICATION_SCRIPT_FAMILY_HINT } from "../../core/verification-scripts.js";
@@ -16,9 +17,11 @@ import {
 } from "./catalog.js";
 import { compareNumeric, type NumericCompareReport, parseNumericPayload, renderNumericReport } from "./numeric.js";
 import {
+	capturePerfEnvironment,
 	evaluatePerfBudget,
 	type PerfBaseline,
 	type PerfBudgetReport,
+	type PerfEnvironment,
 	parsePerfBaseline,
 	renderPerfBaseline,
 } from "./perf.js";
@@ -26,6 +29,52 @@ import {
 /** The structured verdict a numeric-compare or perf-budget check records beside the command facts. */
 export type DeclaredCheckReport = NumericCompareReport | PerfBudgetReport;
 
+/**
+ * Output ceiling for a judged check's command. A numeric payload may carry up
+ * to NUMERIC_PAYLOAD_CAPS.elements numbers, which as printed JSON can exceed
+ * the safe-exec default of 600 KB by a wide margin, so the judged path has its
+ * own bound. The runner retains the whole capture in memory as a string until
+ * judgement, so this constant is also the memory bound one judged check may
+ * hold; output past it ends the command before judgement. Baseline recording
+ * runs the same command under the same ceiling, and a reference or baseline
+ * file is refused past it before being read, so no judged input exceeds it.
+ */
+export const JUDGED_CHECK_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+
+export type CheckExecutionOutcome = "succeeded" | "failed" | "timed-out" | "aborted" | "output-capped";
+
+/**
+ * A verifier result answers three separate questions, and a reader must not
+ * fold them into one. Execution says whether the command ran to completion.
+ * Validation says what the declared judgement concluded: a tolerance or budget
+ * verdict for a judged check, the exit code itself for a command check, or
+ * `not-run` when execution ended before any judgement. Scientific validity is
+ * never established by a check: a payload within tolerance of its reference
+ * says nothing about whether the reference is right.
+ */
+export interface CheckJudgement {
+	execution: CheckExecutionOutcome;
+	validation: "passed" | "failed" | "exit-code" | "not-run";
+	scientificValidity: typeof SCIENTIFIC_VALIDITY_NOT_ESTABLISHED;
+}
+
+export const SCIENTIFIC_VALIDITY_NOT_ESTABLISHED = "not established by this check";
+
+function sha256(text: string): string {
+	return createHash("sha256").update(text).digest("hex");
+}
+
+function executionOutcome(result: Pick<SafeCommandResult, "aborted" | "timedOut" | "outputCapped" | "exitCode">) {
+	if (result.aborted) return "aborted" as const;
+	if (result.timedOut) return "timed-out" as const;
+	if (result.outputCapped) return "output-capped" as const;
+	return result.exitCode === 0 ? ("succeeded" as const) : ("failed" as const);
+}
+
+function judgement(execution: CheckExecutionOutcome, validation: CheckJudgement["validation"]): CheckJudgement {
+	return { execution, validation, scientificValidity: SCIENTIFIC_VALIDITY_NOT_ESTABLISHED };
+}
+
 /**
  * Package scripts and the project catalog meet here as one canonical check
  * projection. Project checks retain their admitted argv/cwd/timeout exactly;
@@ -203,11 +252,34 @@ export function listChecks(cwdArg: string | undefined): ToolResult {
 	};
 }
 
+/**
+ * Attach the judgement facts to a `command` check's result, whose whole
+ * verdict is its exit code: a package script or a catalog `command` check.
+ * Judged checks attach their own facts before reaching here and keep them; a
+ * result without exec facts (a refusal before anything ran) gets none.
+ */
+function withCommandJudgement(result: ToolResult): ToolResult {
+	const details = result.details ?? {};
+	if (details.judgement !== undefined) return result;
+	// The exec record always names exitCode (a number, or null for a signal
+	// death) once the command ran; a refusal before spawning carries none.
+	if (!Object.hasOwn(details, "exitCode")) return result;
+	const execution = executionOutcome({
+		aborted: details.aborted === true,
+		timedOut: details.timedOut === true,
+		outputCapped: details.outputCapped === true,
+		exitCode: typeof details.exitCode === "number" ? details.exitCode : null,
+	});
+	const validation = execution === "succeeded" || execution === "failed" ? "exit-code" : "not-run";
+	return { ...result, details: { ...details, judgement: judgement(execution, validation) } };
+}
+
 function withDeclaredEvidence(result: ToolResult, check: DeclaredCheck): ToolResult {
+	const judged = check.kind === "command" ? withCommandJudgement(result) : result;
 	return {
-		...result,
+		...judged,
 		details: {
-			...result.details,
+			...judged.details,
 			action: "verify",
 			check: check.id,
 			kind: check.kind,
@@ -239,7 +311,12 @@ export function extractNumericPayloadText(output: string): string {
 	}
 }
 
-/** Read a repository-relative check file inside the workspace root, as text. */
+/**
+ * Read a repository-relative check file inside the workspace root, as text.
+ * The file is bounded by JUDGED_CHECK_MAX_OUTPUT_BYTES, the same ceiling as
+ * the command output it is judged beside, and the size is checked before any
+ * byte is read so an oversized file costs nothing but a stat.
+ */
 function readCheckFile(workspaceRoot: string, relative: string, label: string): string | Error {
 	let resolved: string;
 	try {
@@ -249,24 +326,45 @@ function readCheckFile(workspaceRoot: string, relative: string, label: string):
 	}
 	if (!existsSync(resolved)) return new Error(`${label} '${relative}' does not exist`);
 	try {
+		const { size } = statSync(resolved);
+		if (size > JUDGED_CHECK_MAX_OUTPUT_BYTES) {
+			return new Error(`${label} '${relative}' exceeds the ${JUDGED_CHECK_MAX_OUTPUT_BYTES}-byte cap (${size} bytes)`);
+		}
 		return readFileSync(resolved, "utf8");
 	} catch (error) {
 		return new Error(`${label} '${relative}' cannot be read (${error instanceof Error ? error.message : String(error)})`);
 	}
 }
 
-/** Judge a numeric-compare command's stdout against reference text already read from disk. Pure. */
+/**
+ * Judge a numeric-compare command's stdout against reference text already
+ * read from disk. Pure. The report records the identity of both texts it
+ * judged: the reference's digest and size beside the caller's label (and its
+ * path when the caller names one), and the digest and size of the payload
+ * text extracted from stdout.
+ */
 export function judgeNumericTexts(
 	stdout: string,
 	referenceText: string,
 	tolerance: DeclaredNumericCompare["tolerance"],
 	referenceLabel: string,
+	referencePath?: string,
 ): NumericCompareReport | Error {
 	const reference = parseNumericPayload(referenceText, referenceLabel);
 	if (reference instanceof Error) return reference;
-	const actual = parseNumericPayload(extractNumericPayloadText(stdout), "command output");
+	const payloadText = extractNumericPayloadText(stdout);
+	const actual = parseNumericPayload(payloadText, "command output");
 	if (actual instanceof Error) return actual;
-	return compareNumeric(actual, reference, tolerance);
+	return {
+		...compareNumeric(actual, reference, tolerance),
+		reference: {
+			source: referenceLabel,
+			...(referencePath !== undefined ? { path: referencePath } : {}),
+			sha256: sha256(referenceText),
+			bytes: Buffer.byteLength(referenceText, "utf8"),
+		},
+		actual: { sha256: sha256(payloadText), bytes: Buffer.byteLength(payloadText, "utf8") },
+	};
 }
 
 /** Judge a numeric-compare command's stdout against the declared reference under the workspace root. */
@@ -277,17 +375,35 @@ function judgeNumericCompare(
 ): NumericCompareReport | Error {
 	const referenceText = readCheckFile(workspaceRoot, numeric.reference, "reference");
 	if (referenceText instanceof Error) return referenceText;
-	return judgeNumericTexts(stdout, referenceText, numeric.tolerance, `reference '${numeric.reference}'`);
+	return judgeNumericTexts(
+		stdout,
+		referenceText,
+		numeric.tolerance,
+		`reference '${numeric.reference}'`,
+		numeric.reference,
+	);
+}
+
+export interface JudgePerfOptions {
+	/** The judging host; captured from this process when omitted. Tests inject one for determinism. */
+	environment?: PerfEnvironment;
 }
 
-/** Judge a measured wall time against a budget, or against baseline text already read from disk. Pure. */
+/**
+ * Judge a measured wall time against a budget, or against baseline text
+ * already read from disk. Pure given `options.environment`. A baseline
+ * judgement records the baseline file's identity and compares its recorded
+ * host against the judging host; that comparison is reported, never enforced.
+ */
 export function judgePerfTexts(
 	measuredMs: number,
 	perf: DeclaredPerfBudget,
 	baselineText: string | undefined,
 	baselineLabel: string,
+	options: JudgePerfOptions = {},
 ): PerfBudgetReport | Error {
 	let baseline: PerfBaseline | undefined;
+	let provenance: PerfBudgetReport["baseline"];
 	if (perf.baseline !== undefined) {
 		if (baselineText === undefined) {
 			return new Error(`${baselineLabel} is missing; record it with \`clio-coder verifiers baseline <id>\``);
@@ -295,12 +411,21 @@ export function judgePerfTexts(
 		const parsed = parsePerfBaseline(baselineText, baselineLabel);
 		if (parsed instanceof Error) return parsed;
 		baseline = parsed;
+		provenance = {
+			path: perf.baseline,
+			sha256: sha256(baselineText),
+			bytes: Buffer.byteLength(baselineText, "utf8"),
+			...(parsed.recordedAt !== undefined ? { recordedAt: parsed.recordedAt } : {}),
+			...(parsed.check !== undefined ? { check: parsed.check } : {}),
+		};
 	}
-	return evaluatePerfBudget(measuredMs, {
+	const report = evaluatePerfBudget(measuredMs, {
 		...(perf.budget !== undefined ? { budget: perf.budget } : {}),
-		...(baseline !== undefined ? { baseline } : {}),
+		...(baseline !== undefined ? { baseline, environment: options.environment ?? capturePerfEnvironment() } : {}),
 		...(perf.tolerance?.relative !== undefined ? { relative: perf.tolerance.relative } : {}),
 	});
+	if (report instanceof Error || provenance === undefined) return report;
+	return { ...report, baseline: provenance };
 }
 
 /** Judge a measured wall time against the declared budget or the recorded baseline under the workspace root. */
@@ -336,8 +461,11 @@ function commandFacts(result: SafeCommandResult): Record<string, unknown> {
 /**
  * Run a numeric-compare or perf-budget check: the command through the same
  * safe-exec spine as a command check, then the pure judgement. A command that
- * exits non-zero, times out, or is aborted fails before any comparison, so a
- * crashed validator never reads as a tolerance verdict.
+ * exits non-zero, times out, is aborted, or overruns the output ceiling fails
+ * before any comparison, so a crashed or truncated validator never reads as a
+ * tolerance verdict. Every result carries the three-part judgement so a
+ * reader can tell execution failure, validation failure, and the unanswered
+ * question of scientific validity apart.
  */
 async function runJudgedCheck(
 	check: DeclaredCheck,
@@ -351,16 +479,25 @@ async function runJudgedCheck(
 		result = await runCommandVector(file, vector, {
 			cwd,
 			timeoutMs: check.timeoutMs,
+			maxOutputBytes: JUDGED_CHECK_MAX_OUTPUT_BYTES,
 			...(options?.signal !== undefined ? { signal: options.signal } : {}),
 		});
 	} catch (error) {
 		return { kind: "error", message: `verify: ${error instanceof Error ? error.message : String(error)}` };
 	}
-	const facts = commandFacts(result);
-	const tail = `${result.stdout}${result.stderr}`.trim().slice(-2_000);
+	const execution = executionOutcome(result);
+	const facts = { ...commandFacts(result), judgement: judgement(execution, "not-run") };
 	if (result.aborted) return { kind: "error", message: "verify: aborted", details: facts };
 	if (result.timedOut) return { kind: "error", message: `verify: timed out after ${check.timeoutMs}ms`, details: facts };
+	if (result.outputCapped) {
+		return {
+			kind: "error",
+			message: `verify: ${check.kind} command output exceeded ${JUDGED_CHECK_MAX_OUTPUT_BYTES} bytes before judgement`,
+			details: facts,
+		};
+	}
 	if (result.exitCode !== 0) {
+		const tail = `${result.stdout}${result.stderr}`.trim().slice(-2_000);
 		return {
 			kind: "error",
 			message: `verify: ${check.kind} command exited with code ${result.exitCode ?? "?"} before judgement: ${tail}`,
@@ -375,7 +512,7 @@ async function runJudgedCheck(
 				: new Error(`declared check '${check.id}' has kind ${check.kind} without its parameters`);
 	if (report instanceof Error) return { kind: "error", message: `verify: ${report.message}`, details: facts };
 	const rendered = report.kind === "numeric-compare" ? renderNumericReport(report) : report.summary;
-	const details = { ...facts, report };
+	const details = { ...facts, report, judgement: judgement(execution, report.passed ? "passed" : "failed") };
 	if (!report.passed) return { kind: "error", message: `verify: ${rendered}`, details };
 	return { kind: "ok", output: `${rendered}\n`, details };
 }
@@ -394,12 +531,15 @@ export async function runProjectCheck(check: DeclaredCheck, options?: { signal?:
 
 /**
  * Run a perf-budget check once and write its wall time as the baseline the
- * check's `baseline` path names. The command must exit cleanly; a failed run
- * records nothing, so a baseline never encodes a broken command's timing.
+ * check's `baseline` path names. The command runs under the judged check's
+ * output ceiling, so the recording run and the judged run are the same run.
+ * The command must exit cleanly; a failed, timed-out, aborted, or
+ * output-capped run records nothing, so a baseline never encodes a broken
+ * command's timing.
  */
 export async function recordPerfBaseline(
 	check: DeclaredCheck,
-	options?: { signal?: AbortSignal; now?: () => Date },
+	options?: { signal?: AbortSignal; now?: () => Date; environment?: PerfEnvironment },
 ): Promise<{ ok: true; path: string; wallTimeMs: number } | { ok: false; message: string }> {
 	if (check.kind !== "perf-budget" || check.perf?.baseline === undefined) {
 		return { ok: false, message: `check '${check.id}' is not a perf-budget check with a baseline path` };
@@ -413,16 +553,23 @@ export async function recordPerfBaseline(
 		result = await runCommandVector(file, vector, {
 			cwd,
 			timeoutMs: check.timeoutMs,
+			maxOutputBytes: JUDGED_CHECK_MAX_OUTPUT_BYTES,
 			...(options?.signal !== undefined ? { signal: options.signal } : {}),
 		});
 	} catch (error) {
 		return { ok: false, message: error instanceof Error ? error.message : String(error) };
 	}
-	if (result.aborted || result.timedOut || result.exitCode !== 0) {
-		return {
-			ok: false,
-			message: `command ${result.timedOut ? "timed out" : result.aborted ? "was aborted" : `exited with code ${result.exitCode ?? "?"}`}; no baseline recorded`,
-		};
+	const execution = executionOutcome(result);
+	if (execution !== "succeeded") {
+		const ended =
+			execution === "aborted"
+				? "was aborted"
+				: execution === "timed-out"
+					? "timed out"
+					: execution === "output-capped"
+						? `output exceeded ${JUDGED_CHECK_MAX_OUTPUT_BYTES} bytes`
+						: `exited with code ${result.exitCode ?? "?"}`;
+		return { ok: false, message: `command ${ended}; no baseline recorded` };
 	}
 	let target: string;
 	try {
@@ -431,9 +578,14 @@ export async function recordPerfBaseline(
 		return { ok: false, message: `baseline ${error instanceof Error ? error.message : String(error)}` };
 	}
 	const recordedAt = (options?.now?.() ?? new Date()).toISOString();
+	const environment = options?.environment ?? capturePerfEnvironment();
 	try {
 		mkdirSync(path.dirname(target), { recursive: true });
-		writeFileSync(target, renderPerfBaseline({ wallTimeMs: result.durationMs, check: check.id, recordedAt }), "utf8");
+		writeFileSync(
+			target,
+			renderPerfBaseline({ wallTimeMs: result.durationMs, check: check.id, recordedAt, environment }),
+			"utf8",
+		);
 	} catch (error) {
 		return {
 			ok: false,
@@ -471,7 +623,7 @@ export async function runScriptCheck(
 		: [];
 	const vector = ["run", check];
 	if (extraArgs.length > 0) vector.push("--", ...extraArgs);
-	return runVectorTool("verify", "npm", vector, { ...args, cwd }, options);
+	return withCommandJudgement(await runVectorTool("verify", "npm", vector, { ...args, cwd }, options));
 }
 
 export { VERIFICATION_SCRIPT_FAMILY_HINT };

package/src/tools/web-fetch-surface.ts

@@ -20,3 +20,25 @@ export const webFetchToolSurface = {
 	baseActionClass: "read",
 	executionMode: "parallel",
 } satisfies ToolSurface;
+
+/**
+ * The read half of the web split. It shares web_fetch's implementation and
+ * accepts no method, headers, or body, so no argument can turn it into an
+ * outward action: it is read class unconditionally and never asks for an
+ * outward approval.
+ */
+export const webReadToolSurface = {
+	name: ToolNames.WebRead,
+	description:
+		"Read an http(s) URL with a GET request; HTML is cleaned and converted to Markdown, arXiv and repository-tree URLs are summarized. Sends nothing outward: no method, headers, or body. Non-2xx responses are errors; private networks require operator opt-in.",
+	parameters: Type.Object({
+		url: Type.String({ description: "Fully-qualified http(s) URL." }),
+		timeout_ms: Type.Optional(Type.Number({ description: "Timeout ms (default 30000)." })),
+		max_bytes: Type.Optional(Type.Number({ description: "Max bytes returned (default 600000)." })),
+		format: Type.Optional(
+			Type.String({ description: "auto (default) converts HTML to Markdown; raw returns the body unconverted." }),
+		),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+} satisfies ToolSurface;