@iowarp/clio-coder 0.4.3 → 0.4.4

package/src/tools/verify/authoring.ts

@@ -15,15 +15,20 @@ import { resolveSafeCwd, SAFE_EXEC_DEFAULT_TIMEOUT_MS } from "../../core/safe-ex
 import { parseTomlDocument, tomlTableAt } from "../../core/toml.js";
 import { isVerificationScriptName } from "../../core/verification-scripts.js";
 import { compareCodepoints } from "../../domains/evidence/ordering.js";
+import { loadValidationContract, VALIDATION_CONTRACT_MARKDOWN_PATH } from "../../domains/safety/validation-contract.js";
 import type { ToolResult } from "../registry.js";
 import {
 	type DeclaredCheck,
+	type DeclaredCheckKind,
+	type DeclaredNumericCompare,
+	type DeclaredPerfBudget,
 	PROJECT_VERIFIER_CATALOG_CAPS,
 	PROJECT_VERIFIER_CATALOG_RELATIVE_PATH,
 	PROJECT_VERIFIER_CATALOG_VERSION,
 	parseProjectVerifierCatalogText,
 } from "./catalog.js";
 import { verifyTool } from "./index.js";
+import { type NumericTolerance, normalizeNumericTolerance } from "./numeric.js";
 import { discoverDeclaredChecksAtRoot, discoverDeclaredProjectEntriesAtRoot } from "./scripts.js";
 
 export type VerifierProposalAuthority = "project-declared" | "toolchain-defined";
@@ -54,12 +59,31 @@ export interface AuthoringCheck {
 	cwd: string;
 	timeoutMs: number;
 	tags: string[];
+	/** Absent means `command`. Written to the catalog only when it is not the default. */
+	kind?: DeclaredCheckKind;
+	numeric?: DeclaredNumericCompare;
+	perf?: DeclaredPerfBudget;
 	provenance: VerifierProvenance;
 	state: "active" | "existing" | "proposed" | "manual";
 	/** The id this check has in the on-disk catalog, so a rename still edits its node in place. */
 	catalogId?: string;
 }
 
+/**
+ * A numeric-compare check the validation contract implies but cannot make
+ * executable: the artifact declared tolerances, so the reference and the
+ * tolerance are known, and the command is the operator's to supply. It never
+ * enters the draft, so nothing about it runs until an explicit `add`.
+ */
+export interface NumericProposal {
+	id: string;
+	artifactPath: string;
+	reference: string;
+	tolerance: NumericTolerance;
+	/** The exact `clio-coder verifiers add` invocation with `--command` left to fill. */
+	addCommand: string;
+}
+
 export interface VerifierAuthoringDiscovery {
 	ok: true;
 	workspaceRoot: string;
@@ -67,6 +91,8 @@ export interface VerifierAuthoringDiscovery {
 	activeChecks: AuthoringCheck[];
 	existingChecks: AuthoringCheck[];
 	proposals: AuthoringCheck[];
+	/** Tolerance-bearing contract artifacts, each rendered as an incomplete numeric-compare check. */
+	numericProposals: NumericProposal[];
 	diagnostics: string[];
 	manualEntry: string;
 	/** The catalog file as found, when one exists; revisions are written into it in place. */
@@ -86,6 +112,8 @@ export interface VerifierDraft {
 	catalogPath: string;
 	activeChecks: AuthoringCheck[];
 	checks: AuthoringCheck[];
+	/** Rendered in the preview beneath the executable checks; never serialized. */
+	numericProposals: NumericProposal[];
 	diagnostics: string[];
 	manualEntry: string;
 	catalogText?: string;
@@ -96,7 +124,9 @@ export type VerifierRevision =
 	| {
 			kind: "edit";
 			id: string;
-			changes: Partial<Pick<AuthoringCheck, "description" | "command" | "cwd" | "timeoutMs" | "tags">>;
+			changes: Partial<
+				Pick<AuthoringCheck, "description" | "command" | "cwd" | "timeoutMs" | "tags" | "kind" | "numeric" | "perf">
+			>;
 	  }
 	| { kind: "rename"; id: string; newId: string }
 	| { kind: "remove"; id: string };
@@ -168,12 +198,6 @@ interface RawProposal {
 }
 
 const DECLARED_FILE_CAP_BYTES = 1024 * 1024;
-const VALIDATION_CONTRACT_PATHS = [
-	".clio-coder/validation.yaml",
-	".clio-coder/validation.yml",
-	"validation.yaml",
-	"validation.yml",
-] as const;
 
 function manualEntryInstruction(): string {
 	return (
@@ -187,10 +211,25 @@ function cloneCheck(check: AuthoringCheck): AuthoringCheck {
 		...check,
 		command: [...check.command],
 		tags: [...check.tags],
+		...(check.numeric !== undefined ? { numeric: structuredClone(check.numeric) } : {}),
+		...(check.perf !== undefined ? { perf: structuredClone(check.perf) } : {}),
 		provenance: { ...check.provenance },
 	};
 }
 
+/** The kind fields of a declared or authored check, absent for a plain command check. */
+function kindFields(
+	check: Pick<DeclaredCheck, "kind" | "numeric" | "perf"> | Pick<AuthoringCheck, "kind" | "numeric" | "perf">,
+): Pick<AuthoringCheck, "kind" | "numeric" | "perf"> {
+	const kind = check.kind ?? "command";
+	if (kind === "command") return {};
+	return {
+		kind,
+		...(check.numeric !== undefined ? { numeric: structuredClone(check.numeric) } : {}),
+		...(check.perf !== undefined ? { perf: structuredClone(check.perf) } : {}),
+	};
+}
+
 function relativePath(workspaceRoot: string, filePath: string): string {
 	const relative = path.relative(workspaceRoot, filePath);
 	return relative.length === 0 ? "." : relative.split(path.sep).join("/");
@@ -283,6 +322,7 @@ function projectedCheck(workspaceRoot: string, check: DeclaredCheck): AuthoringC
 		cwd: check.cwd,
 		timeoutMs: check.timeoutMs,
 		tags: [...check.tags],
+		...kindFields(check),
 		provenance: sourceProvenance(workspaceRoot, check),
 		state: check.source.kind === "package.json" ? "active" : "existing",
 		...(check.source.kind === "package.json" ? {} : { catalogId: check.id }),
@@ -626,18 +666,6 @@ function shellLikeArgv(command: string): string[] | Error {
 	return argv;
 }
 
-function validatorArgv(value: unknown): string[] | Error {
-	if (typeof value === "string") return shellLikeArgv(value);
-	if (
-		!Array.isArray(value) ||
-		value.length === 0 ||
-		value.some((entry) => typeof entry !== "string" || entry.length === 0)
-	) {
-		return new Error("validator must be a command string or a non-empty argv string array");
-	}
-	return [...(value as string[])];
-}
-
 function validationPreferredId(argv: ReadonlyArray<string>): string {
 	const executable = path.basename(argv[0] ?? "check").replace(/\.[^.]+$/u, "");
 	const script = argv.find((entry, index) => index > 0 && /\.(?:py|js|mjs|sh)$/u.test(entry));
@@ -647,87 +675,76 @@ function validationPreferredId(argv: ReadonlyArray<string>): string {
 
 function validationContractProposals(workspaceRoot: string, diagnostics: string[]): RawProposal[] {
 	const proposals: RawProposal[] = [];
-	for (const relative of VALIDATION_CONTRACT_PATHS) {
-		const text = regularFileText(path.join(workspaceRoot, relative), workspaceRoot);
-		if (text === null) continue;
-		if (text instanceof Error) {
-			diagnostics.push(`${relative}: ${text.message}; validation command discovery skipped.`);
-			continue;
-		}
-		const document = parseDocument(text, { prettyErrors: false, strict: true, uniqueKeys: true });
-		if (document.errors.length > 0) {
-			diagnostics.push(`${relative}: invalid YAML; validation command discovery skipped.`);
-			continue;
-		}
-		let parsed: unknown;
-		try {
-			parsed = document.toJS({ maxAliasCount: 0 }) as unknown;
-		} catch (error) {
-			diagnostics.push(`${relative}: invalid YAML (${error instanceof Error ? error.message : String(error)}).`);
-			continue;
-		}
-		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) continue;
-		const validators = (parsed as Record<string, unknown>).validators;
-		if (!Array.isArray(validators)) continue;
-		for (const [index, validator] of validators.entries()) {
-			const record =
-				validator !== null && typeof validator === "object" && !Array.isArray(validator)
-					? (validator as Record<string, unknown>)
-					: null;
-			if (record !== null) {
-				const typedFields: ReadonlyArray<readonly [string, (value: unknown) => boolean]> = [
-					["id", (value: unknown) => typeof value === "string"],
-					["description", (value: unknown) => typeof value === "string"],
-					["cwd", (value: unknown) => typeof value === "string"],
-					["timeoutMs", (value: unknown) => typeof value === "number"],
-					["tags", (value: unknown) => Array.isArray(value) && value.every((tag) => typeof tag === "string")],
-				];
-				const invalidField = typedFields.find(([field, valid]) => Object.hasOwn(record, field) && !valid(record[field]));
-				if (invalidField !== undefined) {
-					diagnostics.push(
-						`${relative}: validators[${index}].${String(invalidField[0])} has an ambiguous type; use manual argv entry.`,
-					);
-					continue;
-				}
-			}
-			const commandValue = record === null ? validator : record.command;
-			const argv = validatorArgv(commandValue);
+	const loaded = loadValidationContract(workspaceRoot);
+	if (!loaded.ok) {
+		diagnostics.push(`${loaded.path}: ${loaded.reason}; validation command discovery skipped.`);
+	} else if (loaded.contract !== null) {
+		for (const [index, validator] of (loaded.contract.validators ?? []).entries()) {
+			const argv = shellLikeArgv(validator);
 			if (argv instanceof Error) {
-				diagnostics.push(`${relative}: validators[${index}] is ambiguous (${argv.message}); use manual argv entry.`);
+				diagnostics.push(`${loaded.path}: validators[${index}] is ambiguous (${argv.message}); use manual argv entry.`);
 				continue;
 			}
-			const declaredId = typeof record?.id === "string" ? record.id : validationPreferredId(argv);
-			const description =
-				typeof record?.description === "string"
-					? record.description
-					: `Run validation contract command ${JSON.stringify(argv)}`;
-			const cwd = typeof record?.cwd === "string" ? record.cwd : ".";
-			const timeoutMs = typeof record?.timeoutMs === "number" ? record.timeoutMs : SAFE_EXEC_DEFAULT_TIMEOUT_MS;
-			const tags = Array.isArray(record?.tags) ? record.tags.filter((tag): tag is string => typeof tag === "string") : [];
 			proposals.push({
-				preferredId: declaredId,
-				description,
+				preferredId: validationPreferredId(argv),
+				description: `Run validation contract command ${JSON.stringify(argv)}`,
 				command: argv,
-				cwd,
-				timeoutMs,
-				tags: tags.length > 0 ? tags : ["scientific", "validation"],
+				cwd: ".",
+				timeoutMs: SAFE_EXEC_DEFAULT_TIMEOUT_MS,
+				tags: ["scientific", "validation"],
 				provenance: {
 					kind: "validation-contract",
-					path: relative,
+					path: loaded.path,
 					detail: `validators[${index}]`,
 					authority: "project-declared",
 				},
 			});
 		}
 	}
-	if (existsSync(path.join(workspaceRoot, "VALIDATION.md"))) {
+	if (existsSync(path.join(workspaceRoot, VALIDATION_CONTRACT_MARKDOWN_PATH))) {
 		diagnostics.push(
-			"VALIDATION.md is advisory prose; enter an exact argv vector manually instead of inferring a command.",
+			`${VALIDATION_CONTRACT_MARKDOWN_PATH} is advisory prose; enter an exact argv vector manually instead of inferring a command.`,
 		);
 	}
 	return proposals;
 }
 
+/**
+ * One incomplete numeric-compare check per contract artifact that declares
+ * `numerical_tolerances`. The reference path is the artifact's path with a
+ * `.reference.json` suffix, a suggestion the operator may change; the
+ * command is deliberately absent, so the proposal cannot become executable
+ * until the operator confirms an exact argv through `verifiers add`.
+ */
+function numericContractProposals(workspaceRoot: string): NumericProposal[] {
+	const loaded = loadValidationContract(workspaceRoot);
+	if (!loaded.ok || loaded.contract === null) return [];
+	const proposals: NumericProposal[] = [];
+	const seen = new Set<string>();
+	for (const artifact of loaded.contract.artifacts ?? []) {
+		if (artifact.numerical_tolerances === undefined) continue;
+		const tolerance = normalizeNumericTolerance(artifact.numerical_tolerances);
+		if (tolerance instanceof Error) continue;
+		const base = slug(path.basename(artifact.path).replace(/\.[^.]+$/u, ""), "artifact");
+		const preferred = boundedId(`numeric-${base}`);
+		let id = preferred;
+		for (let suffix = 2; seen.has(id); suffix += 1) id = `${boundedId(preferred, `-${suffix}`)}-${suffix}`;
+		seen.add(id);
+		const reference = `${artifact.path}.reference.json`;
+		proposals.push({
+			id,
+			artifactPath: artifact.path,
+			reference,
+			tolerance,
+			addCommand:
+				`clio-coder verifiers add --id ${id} --kind numeric-compare --reference ${JSON.stringify(reference)} ` +
+				`--tolerance '${JSON.stringify(tolerance)}' --description ${JSON.stringify(`Compare ${artifact.path} against its reference within tolerance`)} ` +
+				`--command '["<executable>","<arg>"]'`,
+		});
+	}
+	return proposals;
+}
+
 function deduplicatedRawProposals(proposals: RawProposal[], diagnostics: string[]): RawProposal[] {
 	const seen = new Map<string, RawProposal>();
 	for (const proposal of proposals.sort(rawProposalSort)) {
@@ -825,6 +842,7 @@ export function discoverVerifierAuthoring(workspaceRoot = process.cwd()): Verifi
 		activeChecks,
 		existingChecks,
 		proposals,
+		numericProposals: numericContractProposals(workspaceRoot),
 		diagnostics,
 		manualEntry,
 		...(typeof catalogText === "string" ? { catalogText } : {}),
@@ -842,14 +860,30 @@ export function createVerifierDraft(
 		checks: [...discovery.existingChecks, ...(options.includeProposals === false ? [] : discovery.proposals)]
 			.map(cloneCheck)
 			.sort((left, right) => compareCodepoints(left.id, right.id)),
+		numericProposals:
+			options.includeProposals === false ? [] : discovery.numericProposals.map((proposal) => ({ ...proposal })),
 		diagnostics: [...discovery.diagnostics],
 		manualEntry: discovery.manualEntry,
 		...(discovery.catalogText === undefined ? {} : { catalogText: discovery.catalogText }),
 	};
 }
 
-function catalogEntry({ id, description, command, cwd, timeoutMs, tags }: AuthoringCheck): Record<string, unknown> {
-	return { id, description, command: [...command], cwd, timeoutMs, tags: [...tags] };
+function catalogEntry(check: AuthoringCheck): Record<string, unknown> {
+	const { id, description, command, cwd, timeoutMs, tags } = check;
+	const entry: Record<string, unknown> = { id, description, command: [...command], cwd, timeoutMs, tags: [...tags] };
+	const kind = check.kind ?? "command";
+	if (kind === "command") return entry;
+	entry.kind = kind;
+	if (check.numeric !== undefined) {
+		entry.reference = check.numeric.reference;
+		entry.tolerance = { ...check.numeric.tolerance };
+	}
+	if (check.perf !== undefined) {
+		if (check.perf.budget !== undefined) entry.budget = structuredClone(check.perf.budget);
+		if (check.perf.baseline !== undefined) entry.baseline = check.perf.baseline;
+		if (check.perf.tolerance !== undefined) entry.tolerance = { ...check.perf.tolerance };
+	}
+	return entry;
 }
 
 /**
@@ -885,8 +919,20 @@ function serializeVerifierDraft(draft: VerifierDraft): string {
 			node.set(field, value);
 			changed = true;
 		}
+		// A check that returned to a plain command drops the kind fields it no longer carries.
+		for (const field of ["kind", "reference", "tolerance", "budget", "baseline"]) {
+			if (Object.hasOwn(current, field) && !Object.hasOwn(entry, field)) {
+				node.delete(field);
+				changed = true;
+			}
+		}
 	}
 	if (!changed && appended.length === 0 && kept.size === sequence.items.length) return draft.catalogText as string;
+	// The edited file speaks this build's schema version: a version-1 file that
+	// gains a judged check would otherwise be rejected by its own version line.
+	if (document.get("version") !== PROJECT_VERIFIER_CATALOG_VERSION) {
+		document.set("version", PROJECT_VERIFIER_CATALOG_VERSION);
+	}
 	sequence.items = [...sequence.items.filter((node) => isMap(node) && kept.has(node)), ...appended];
 	return document.toString({ lineWidth: 0 });
 }
@@ -919,6 +965,7 @@ function validateVerifierDraft(draft: VerifierDraft): VerifierDraftValidation {
 			cwd: check.cwd,
 			timeoutMs: check.timeoutMs,
 			tags: [...check.tags],
+			...kindFields(check),
 			provenance:
 				original?.provenance ??
 				({
@@ -939,6 +986,7 @@ function cloneDraft(draft: VerifierDraft): VerifierDraft {
 		...draft,
 		activeChecks: draft.activeChecks.map(cloneCheck),
 		checks: draft.checks.map(cloneCheck),
+		numericProposals: draft.numericProposals.map((proposal) => ({ ...proposal })),
 		diagnostics: [...draft.diagnostics],
 	};
 }
@@ -1005,6 +1053,17 @@ function reviseVerifierDraft(draft: VerifierDraft, revisions: ReadonlyArray<Veri
 		if (revision.changes.cwd !== undefined) check.cwd = revision.changes.cwd;
 		if (revision.changes.timeoutMs !== undefined) check.timeoutMs = revision.changes.timeoutMs;
 		if (revision.changes.tags !== undefined) check.tags = [...revision.changes.tags];
+		if (revision.changes.kind !== undefined) {
+			const next = kindFields({
+				kind: revision.changes.kind,
+				...(revision.changes.numeric !== undefined ? { numeric: revision.changes.numeric } : {}),
+				...(revision.changes.perf !== undefined ? { perf: revision.changes.perf } : {}),
+			});
+			delete check.kind;
+			delete check.numeric;
+			delete check.perf;
+			Object.assign(check, next);
+		}
 		diagnostics.push(`Edited check '${revision.id}' without changing its deterministic ID.`);
 	}
 	next.checks.sort((left, right) => compareCodepoints(left.id, right.id));
@@ -1034,10 +1093,26 @@ function renderCheck(check: AuthoringCheck, destinationPath: string): string[] {
 		`  cwd: ${check.cwd}`,
 		`  timeoutMs: ${check.timeoutMs}`,
 		`  tags: ${JSON.stringify(check.tags)}`,
+		...renderKind(check),
 		`  effective execution authority: ${authorityDescription(check)}`,
 	];
 }
 
+function renderKind(check: AuthoringCheck): string[] {
+	const kind = check.kind ?? "command";
+	if (kind === "command") return [];
+	const lines = [`  kind: ${kind}`];
+	if (check.numeric !== undefined) {
+		lines.push(`  reference: ${check.numeric.reference}`, `  tolerance: ${JSON.stringify(check.numeric.tolerance)}`);
+	}
+	if (check.perf !== undefined) {
+		if (check.perf.budget !== undefined) lines.push(`  budget: ${JSON.stringify(check.perf.budget)}`);
+		if (check.perf.baseline !== undefined) lines.push(`  baseline: ${check.perf.baseline}`);
+		if (check.perf.tolerance !== undefined) lines.push(`  tolerance: ${JSON.stringify(check.perf.tolerance)}`);
+	}
+	return lines;
+}
+
 export interface VerifierPreviewOptions {
 	/** Suppress the unconfirmed-preview footer once the write is authorized. */
 	confirmed?: boolean;
@@ -1058,6 +1133,18 @@ export function previewVerifierDraft(draft: VerifierDraft, options: VerifierPrev
 	lines.push("", "Catalog checks after confirmation:");
 	if (draft.checks.length === 0) lines.push("(none)");
 	else for (const check of draft.checks) lines.push(...renderCheck(check, draft.catalogPath));
+	if (draft.numericProposals.length > 0) {
+		lines.push("", "Numeric-compare checks the validation contract implies (command required before they can be added):");
+		for (const proposal of draft.numericProposals) {
+			lines.push(
+				`- ${proposal.id}`,
+				`  artifact: ${proposal.artifactPath}`,
+				`  reference: ${proposal.reference}`,
+				`  tolerance: ${JSON.stringify(proposal.tolerance)}`,
+				`  add with: ${proposal.addCommand}`,
+			);
+		}
+	}
 	if (draft.diagnostics.length > 0) {
 		lines.push("", "Diagnostics:");
 		for (const diagnostic of draft.diagnostics) lines.push(`- ${diagnostic}`);

package/src/tools/verify/catalog.ts

@@ -4,9 +4,13 @@ import { parseDocument } from "yaml";
 import { resolveSafeCwd, SAFE_EXEC_DEFAULT_TIMEOUT_MS } from "../../core/safe-exec.js";
 import { isProjectVerifierCheckId } from "../../core/verification-scripts.js";
 import { compareCodepoints } from "../../domains/evidence/ordering.js";
+import { type NumericTolerance, normalizeNumericTolerance } from "./numeric.js";
+import { normalizePerfBudget, normalizePerfTolerance, type PerfBudgetSpec } from "./perf.js";
 
 export const PROJECT_VERIFIER_CATALOG_RELATIVE_PATH = ".clio-coder/verifiers.yaml";
-export const PROJECT_VERIFIER_CATALOG_VERSION = 1;
+/** The version this build writes. Version 1 files still load; every check there is `kind: command`. */
+export const PROJECT_VERIFIER_CATALOG_VERSION = 2;
+const SUPPORTED_CATALOG_VERSIONS: ReadonlyArray<number> = [1, PROJECT_VERIFIER_CATALOG_VERSION];
 
 /** Public schema limits. Diagnostics cite these values instead of hiding policy. */
 export const PROJECT_VERIFIER_CATALOG_CAPS = Object.freeze({
@@ -22,6 +26,31 @@ export const PROJECT_VERIFIER_CATALOG_CAPS = Object.freeze({
 	tagBytes: 32,
 });
 
+/**
+ * What a check proves. `command` reads the exit code. `numeric-compare` runs
+ * the command, parses its stdout as `string -> number | number[]`, and judges
+ * it against a reference file under a tolerance. `perf-budget` runs the
+ * command and judges its wall time against a budget or a recorded baseline.
+ */
+export type DeclaredCheckKind = "command" | "numeric-compare" | "perf-budget";
+
+export const DECLARED_CHECK_KINDS: ReadonlyArray<DeclaredCheckKind> = ["command", "numeric-compare", "perf-budget"];
+
+export interface DeclaredNumericCompare {
+	/** Repository-relative JSON file of the same shape as the command's stdout. */
+	reference: string;
+	tolerance: NumericTolerance;
+}
+
+export interface DeclaredPerfBudget {
+	/** Declared bound; exactly one of `budget` and `baseline` is present. */
+	budget?: PerfBudgetSpec;
+	/** Repository-relative JSON file written by `clio-coder verifiers baseline <id>`. */
+	baseline?: string;
+	/** Headroom over a recorded baseline; only with `baseline`. */
+	tolerance?: { relative?: number };
+}
+
 export type DeclaredCheckSourceKind = "package.json" | "project-catalog";
 
 export interface DeclaredCheckSourceRef {
@@ -38,6 +67,9 @@ export interface DeclaredCheck {
 	timeoutMs: number;
 	tags: string[];
 	source: DeclaredCheckSourceRef;
+	kind: DeclaredCheckKind;
+	numeric?: DeclaredNumericCompare;
+	perf?: DeclaredPerfBudget;
 }
 
 export interface DeclaredCheckSource extends DeclaredCheckSourceRef {
@@ -48,6 +80,8 @@ export type ProjectCatalogLoadResult = { ok: true; source: DeclaredCheckSource |
 
 const ROOT_FIELDS = new Set(["version", "checks"]);
 const CHECK_FIELDS = new Set(["id", "description", "command", "cwd", "timeoutMs", "tags"]);
+/** Version 2 adds the kind and its parameters; every one is optional and kind-gated. */
+const CHECK_FIELDS_V2 = new Set([...CHECK_FIELDS, "kind", "reference", "tolerance", "budget", "baseline"]);
 const TAG_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 const SHELL_EXECUTABLES = new Set([
 	"bash",
@@ -130,6 +164,85 @@ function safelyResolveCatalogCwd(
 	return { declared: relativeCwd(workspaceRoot, resolved), execution: realCwd };
 }
 
+/**
+ * A repository-relative file the check reads or writes at run time. It need
+ * not exist when the catalog loads (a baseline is written later), so only the
+ * shape is checked: relative, NUL-free, bounded, and unable to escape the root.
+ */
+function validateRepositoryFile(value: unknown, location: string): string | Error {
+	if (typeof value !== "string" || value.length === 0) {
+		return new Error(`${location} must be a non-empty repository-relative path`);
+	}
+	if (value.includes("\0")) return new Error(`${location} must not contain a NUL byte`);
+	if (utf8Bytes(value) > PROJECT_VERIFIER_CATALOG_CAPS.cwdBytes) {
+		return new Error(`${location} exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.cwdBytes}-byte cap`);
+	}
+	if (path.isAbsolute(value) || path.win32.isAbsolute(value)) {
+		return new Error(`${location} must be repository-relative; absolute path '${value}' is not allowed`);
+	}
+	const normalized = path.posix.normalize(value.split(path.sep).join("/"));
+	if (normalized === ".." || normalized.startsWith("../")) {
+		return new Error(`${location} escapes the workspace root: '${value}'`);
+	}
+	return normalized;
+}
+
+/**
+ * The kind-specific fields of one check. Version 1 admits no such field, so a
+ * version-1 check is always `command`. Under version 2 the kind gates which
+ * parameters may appear, and each kind requires its own.
+ */
+function validateCheckKind(
+	value: Record<string, unknown>,
+	location: string,
+	version: number,
+): Pick<DeclaredCheck, "kind" | "numeric" | "perf"> | Error {
+	const kindValue = Object.hasOwn(value, "kind") ? value.kind : "command";
+	if (typeof kindValue !== "string" || !(DECLARED_CHECK_KINDS as ReadonlyArray<string>).includes(kindValue)) {
+		return new Error(`${location}.kind must be one of ${DECLARED_CHECK_KINDS.join(", ")}`);
+	}
+	const kind = kindValue as DeclaredCheckKind;
+	const present = (field: string): boolean => Object.hasOwn(value, field);
+	const accepted: Record<DeclaredCheckKind, ReadonlyArray<string>> = {
+		command: [],
+		"numeric-compare": ["reference", "tolerance"],
+		"perf-budget": ["budget", "baseline", "tolerance"],
+	};
+	const stray = ["reference", "tolerance", "budget", "baseline"].filter(
+		(field) => present(field) && !accepted[kind].includes(field),
+	);
+	if (stray.length > 0) return new Error(`${location} kind '${kind}' does not accept ${stray.join(", ")}`);
+	if (version === 1 && kind !== "command") return new Error(`${location}.kind requires catalog version 2`);
+	if (kind === "command") return { kind };
+	if (kind === "numeric-compare") {
+		if (!present("reference")) return new Error(`${location}.reference is required for kind numeric-compare`);
+		if (!present("tolerance")) return new Error(`${location}.tolerance is required for kind numeric-compare`);
+		const reference = validateRepositoryFile(value.reference, `${location}.reference`);
+		if (reference instanceof Error) return reference;
+		const tolerance = normalizeNumericTolerance(value.tolerance);
+		if (tolerance instanceof Error) return new Error(`${location}.${tolerance.message}`);
+		return { kind, numeric: { reference, tolerance } };
+	}
+	if (present("budget") === present("baseline")) {
+		return new Error(`${location} kind 'perf-budget' requires exactly one of budget or baseline`);
+	}
+	if (present("budget")) {
+		if (present("tolerance")) return new Error(`${location}.tolerance belongs inside budget when budget is given`);
+		const budget = normalizePerfBudget(value.budget);
+		if (budget instanceof Error) return new Error(`${location}.${budget.message}`);
+		return { kind, perf: { budget } };
+	}
+	const baseline = validateRepositoryFile(value.baseline, `${location}.baseline`);
+	if (baseline instanceof Error) return baseline;
+	const perf: DeclaredPerfBudget = { baseline };
+	if (present("tolerance")) {
+		const tolerance = normalizePerfTolerance(value.tolerance, `${location}.tolerance`);
+		if (tolerance instanceof Error) return tolerance;
+		perf.tolerance = tolerance;
+	}
+	return { kind, perf };
+}
+
 /** Revalidate a stored catalog cwd and return its canonical in-workspace execution path. */
 export function resolveProjectVerifierExecutionCwd(rawCwd: string, workspaceRoot: string): string | Error {
 	const resolution = safelyResolveCatalogCwd(rawCwd, workspaceRoot, "project check cwd");
@@ -276,11 +389,12 @@ export function parseProjectVerifierCatalogText(
 	const rootUnknown = unknownFields(parsed, ROOT_FIELDS);
 	if (rootUnknown.length > 0) return catalogDiagnostic(`root has unknown field(s): ${rootUnknown.join(", ")}`);
 	if (!Object.hasOwn(parsed, "version")) return catalogDiagnostic("root.version is required");
-	if (parsed.version !== PROJECT_VERIFIER_CATALOG_VERSION) {
+	if (typeof parsed.version !== "number" || !SUPPORTED_CATALOG_VERSIONS.includes(parsed.version)) {
 		return catalogDiagnostic(
-			`unsupported version ${JSON.stringify(parsed.version)}; supported version is ${PROJECT_VERIFIER_CATALOG_VERSION}`,
+			`unsupported version ${JSON.stringify(parsed.version)}; supported versions are ${SUPPORTED_CATALOG_VERSIONS.join(" and ")}`,
 		);
 	}
+	const version = parsed.version;
 	if (!Object.hasOwn(parsed, "checks")) return catalogDiagnostic("root.checks is required");
 	if (!Array.isArray(parsed.checks)) return catalogDiagnostic("root.checks must be an array");
 	if (parsed.checks.length > PROJECT_VERIFIER_CATALOG_CAPS.checks) {
@@ -293,7 +407,7 @@ export function parseProjectVerifierCatalogText(
 	for (const [index, value] of parsed.checks.entries()) {
 		const location = `checks[${index}]`;
 		if (!isRecord(value)) return catalogDiagnostic(`${location} must be an object`);
-		const checkUnknown = unknownFields(value, CHECK_FIELDS);
+		const checkUnknown = unknownFields(value, version === 1 ? CHECK_FIELDS : CHECK_FIELDS_V2);
 		if (checkUnknown.length > 0) {
 			return catalogDiagnostic(`${location} has unknown field(s): ${checkUnknown.join(", ")}`);
 		}
@@ -325,9 +439,11 @@ export function parseProjectVerifierCatalogText(
 		if (timeoutMs instanceof Error) return catalogDiagnostic(timeoutMs.message);
 		const tags = validateTags(value.tags, `${location}.tags`);
 		if (tags instanceof Error) return catalogDiagnostic(tags.message);
+		const kindFields = validateCheckKind(value, location, version);
+		if (kindFields instanceof Error) return catalogDiagnostic(kindFields.message);
 
 		ids.set(id, index);
-		checks.push({ id, description, command, cwd, timeoutMs, tags, source: { ...sourceRef } });
+		checks.push({ id, description, command, cwd, timeoutMs, tags, source: { ...sourceRef }, ...kindFields });
 	}
 	checks.sort((left, right) => compareCodepoints(left.id, right.id));
 	return { ok: true, source: { ...sourceRef, checks } };
@@ -342,5 +458,6 @@ export function packageDeclaredCheck(id: string, packagePath: string, cwd: strin
 		timeoutMs: SAFE_EXEC_DEFAULT_TIMEOUT_MS,
 		tags,
 		source: { kind: "package.json", path: packagePath },
+		kind: "command",
 	};
 }

package/src/tools/verify/index.ts

@@ -36,6 +36,7 @@ export const verifyTool: ToolSpec = {
 				message: `verify: '${check}' is not a verification check (${VERIFICATION_SCRIPT_FAMILY_HINT} or "frontend"); run it through bash.`,
 			};
 		}
-		return runScriptCheck(check, args, options);
+		const result = await runScriptCheck(check, args, options);
+		return declared ? { ...result, details: { ...result.details, check, source: { ...declared.source } } } : result;
 	},
 };