gentle-pi 1.0.0 → 1.0.2

package/lib/review-compact-contract.ts

@@ -0,0 +1,183 @@
+import {
+	CAUSAL_DISPOSITION,
+	COMPACT_EVIDENCE_CLASS,
+	COMPACT_FINDING_OUTCOME,
+	COMPACT_SEVERITY,
+	type CompactRefuterResultInput,
+	type CompactValidationProofInput,
+	type CompactReviewResultInput,
+	type CompactTargetedValidationInput,
+} from "./review-compact.ts";
+import { REVIEW_LENS } from "./review-triggers.ts";
+
+const DIGEST = /^[0-9a-f]{64}$/;
+const LINEAGE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export class CompactReviewContractError extends Error {
+	readonly area: string;
+	readonly code: string;
+
+	constructor(area: string, code: string, message: string) {
+		super(`${area}: ${message}`);
+		this.name = "CompactReviewContractError";
+		this.area = area;
+		this.code = code;
+	}
+}
+
+export interface CompactStartContractInput {
+	cwd: string;
+	lineageId?: string;
+	policyHash: string;
+	projection?: { kind: "complete" };
+}
+
+export interface CompactFinalizeContractInput {
+	cwd: string;
+	lineageId?: string;
+	review_result?: CompactReviewResultInput;
+	correction_line_forecast?: number;
+	validation_proof?: CompactValidationProofInput;
+	validation?: CompactTargetedValidationInput;
+	final_evidence?: string;
+	final_verification_passed?: boolean;
+}
+
+function fail(area: string, code: string, message: string): never {
+	throw new CompactReviewContractError(area, code, message);
+}
+
+function record(value: unknown, area: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+		return fail(area, "type", "must be a plain object");
+	}
+	return value as Record<string, unknown>;
+}
+
+function exact(value: unknown, area: string, required: readonly string[], optional: readonly string[] = []): Record<string, unknown> {
+	const object = record(value, area);
+	for (const key of Object.keys(object)) if (!required.includes(key) && !optional.includes(key)) fail(area, "unknown-key", `contains unknown field ${key}`);
+	for (const key of required) if (!(key in object)) fail(area, "required", `requires ${key}`);
+	return object;
+}
+
+function string(value: unknown, area: string): string {
+	if (typeof value !== "string") return fail(area, "type", "must be a string");
+	if (value.length === 0 || value.trim() !== value) return fail(area, "canonical-string", "must be non-empty and trimmed");
+	return value;
+}
+
+function optionalString(value: unknown, area: string): string | undefined {
+	return value === undefined ? undefined : string(value, area);
+}
+
+function strings(value: unknown, area: string): string[] {
+	if (!Array.isArray(value)) return fail(area, "type", "must be an array");
+	const parsed = value.map((item, index) => string(item, `${area}[${index}]`));
+	if (new Set(parsed).size !== parsed.length) fail(area, "duplicate", "must not contain duplicates");
+	return parsed;
+}
+
+function enumValue<T extends Record<string, string>>(value: unknown, values: T, area: string): T[keyof T] {
+	const parsed = string(value, area);
+	if (!Object.values(values).includes(parsed)) return fail(area, "enum", "contains an unsupported value");
+	return parsed as T[keyof T];
+}
+
+function optionalLineage(value: unknown, area: string): string | undefined {
+	const parsed = optionalString(value, area);
+	if (parsed !== undefined && !LINEAGE_ID.test(parsed)) fail(area, "lineage", "is malformed");
+	return parsed;
+}
+
+function parseFinding(value: unknown, area: string) {
+	const row = exact(value, area, ["location", "severity", "claim", "evidence_class", "causal_disposition", "proof_refs"], ["id", "lens"]);
+	return {
+		...(row.id === undefined ? {} : { id: string(row.id, `${area}.id`) }),
+		...(row.lens === undefined ? {} : { lens: enumValue(row.lens, REVIEW_LENS, `${area}.lens`) }),
+		location: string(row.location, `${area}.location`),
+		severity: enumValue(row.severity, COMPACT_SEVERITY, `${area}.severity`),
+		claim: string(row.claim, `${area}.claim`),
+		evidence_class: enumValue(row.evidence_class, COMPACT_EVIDENCE_CLASS, `${area}.evidence_class`),
+		causal_disposition: enumValue(row.causal_disposition, CAUSAL_DISPOSITION, `${area}.causal_disposition`),
+		proof_refs: strings(row.proof_refs, `${area}.proof_refs`),
+	};
+}
+
+function parseReviewResult(value: unknown, area: string): CompactReviewResultInput {
+	const input = exact(value, area, ["lens_results"], ["refuter_request_hash", "refuter_results"]);
+	if (!Array.isArray(input.lens_results)) fail(`${area}.lens_results`, "type", "must be an array");
+	const lens_results = input.lens_results.map((item, index) => {
+		const row = exact(item, `${area}.lens_results[${index}]`, ["findings", "evidence"], ["lens"]);
+		if (!Array.isArray(row.findings)) fail(`${area}.lens_results[${index}].findings`, "type", "must be an array");
+		return {
+			...(row.lens === undefined ? {} : { lens: enumValue(row.lens, REVIEW_LENS, `${area}.lens_results[${index}].lens`) }),
+			findings: row.findings.map((finding, findingIndex) => parseFinding(finding, `${area}.lens_results[${index}].findings[${findingIndex}]`)),
+			evidence: strings(row.evidence, `${area}.lens_results[${index}].evidence`),
+		};
+	});
+	const refuter_request_hash = optionalString(input.refuter_request_hash, `${area}.refuter_request_hash`);
+	if (refuter_request_hash !== undefined && !DIGEST.test(refuter_request_hash)) fail(`${area}.refuter_request_hash`, "digest", "is malformed");
+	let refuter_results: CompactRefuterResultInput[] | undefined;
+	if (input.refuter_results !== undefined) {
+		if (!Array.isArray(input.refuter_results)) fail(`${area}.refuter_results`, "type", "must be an array");
+		refuter_results = input.refuter_results.map((item, index) => {
+			const row = exact(item, `${area}.refuter_results[${index}]`, ["finding_id", "outcome", "proof_refs"]);
+			return { finding_id: string(row.finding_id, `${area}.refuter_results[${index}].finding_id`), outcome: enumValue(row.outcome, COMPACT_FINDING_OUTCOME, `${area}.refuter_results[${index}].outcome`), proof_refs: strings(row.proof_refs, `${area}.refuter_results[${index}].proof_refs`) };
+		});
+	}
+	return { lens_results, ...(refuter_request_hash === undefined ? {} : { refuter_request_hash }), ...(refuter_results === undefined ? {} : { refuter_results }) };
+}
+
+function parseValidationProof(value: unknown, area: string): CompactValidationProofInput {
+	const input = exact(value, area, ["original_criteria", "correction_regression"]);
+	const check = (item: unknown, label: string) => {
+		const row = exact(item, label, ["passed", "evidence"]);
+		if (typeof row.passed !== "boolean") fail(`${label}.passed`, "type", "must be boolean");
+		return { passed: row.passed, evidence: strings(row.evidence, `${label}.evidence`) };
+	};
+	return { original_criteria: check(input.original_criteria, `${area}.original_criteria`), correction_regression: check(input.correction_regression, `${area}.correction_regression`) };
+}
+
+function parseValidation(value: unknown, area: string): CompactTargetedValidationInput {
+	const input = exact(value, area, ["request_hash", "correction_ids", "original_criteria", "correction_regression", "fix_caused_findings", "follow_ups"]);
+	const check = (item: unknown, label: string) => {
+		const row = exact(item, label, ["passed", "evidence"]);
+		if (typeof row.passed !== "boolean") fail(`${label}.passed`, "type", "must be boolean");
+		return { passed: row.passed, evidence: strings(row.evidence, `${label}.evidence`) };
+	};
+	if (!Array.isArray(input.fix_caused_findings) || input.fix_caused_findings.length !== 0) fail(`${area}.fix_caused_findings`, "scope", "must be an explicitly empty array");
+	if (!Array.isArray(input.follow_ups)) fail(`${area}.follow_ups`, "type", "must be an array");
+	const follow_ups = input.follow_ups.map((item, index) => {
+		const row = exact(item, `${area}.follow_ups[${index}]`, ["finding_id", "location", "summary", "proof_refs"]);
+		return { finding_id: string(row.finding_id, `${area}.follow_ups[${index}].finding_id`), location: string(row.location, `${area}.follow_ups[${index}].location`), summary: string(row.summary, `${area}.follow_ups[${index}].summary`), proof_refs: strings(row.proof_refs, `${area}.follow_ups[${index}].proof_refs`) };
+	});
+	const request_hash = string(input.request_hash, `${area}.request_hash`);
+	if (!DIGEST.test(request_hash)) fail(`${area}.request_hash`, "digest", "is malformed");
+	return { request_hash, correction_ids: strings(input.correction_ids, `${area}.correction_ids`), original_criteria: check(input.original_criteria, `${area}.original_criteria`), correction_regression: check(input.correction_regression, `${area}.correction_regression`), fix_caused_findings: [], follow_ups };
+}
+
+export function parseCompactStartInput(value: unknown): CompactStartContractInput {
+	const input = exact(value, "review/start", ["cwd", "policyHash"], ["lineageId", "projection"]);
+	const policyHash = string(input.policyHash, "review/start.policyHash");
+	if (!DIGEST.test(policyHash)) fail("review/start.policyHash", "digest", "is malformed");
+	let projection: { kind: "complete" } | undefined;
+	if (input.projection !== undefined) {
+		const raw = exact(input.projection, "review/start.projection", ["kind"]);
+		if (raw.kind !== "complete") fail("review/start.projection.kind", "enum", "must be complete");
+		projection = { kind: "complete" };
+	}
+	return { cwd: string(input.cwd, "review/start.cwd"), ...(optionalLineage(input.lineageId, "review/start.lineageId") === undefined ? {} : { lineageId: optionalLineage(input.lineageId, "review/start.lineageId")! }), policyHash, ...(projection === undefined ? {} : { projection }) };
+}
+
+export function parseCompactFinalizeInput(value: unknown): CompactFinalizeContractInput {
+	const input = exact(value, "review/finalize", ["cwd"], ["lineageId", "review_result", "correction_line_forecast", "validation_proof", "validation", "final_evidence", "final_verification_passed"]);
+	if ((input.final_evidence === undefined) !== (input.final_verification_passed === undefined)) fail("review/finalize", "field-pair", "final evidence and result must appear together");
+	let correction_line_forecast: number | undefined;
+	if (input.correction_line_forecast !== undefined) {
+		if (!Number.isSafeInteger(input.correction_line_forecast) || input.correction_line_forecast <= 0) fail("review/finalize.correction_line_forecast", "range", "must be a positive safe integer");
+		correction_line_forecast = input.correction_line_forecast;
+	}
+	if (input.final_verification_passed !== undefined && typeof input.final_verification_passed !== "boolean") fail("review/finalize.final_verification_passed", "type", "must be boolean");
+	return { cwd: string(input.cwd, "review/finalize.cwd"), ...(optionalLineage(input.lineageId, "review/finalize.lineageId") === undefined ? {} : { lineageId: optionalLineage(input.lineageId, "review/finalize.lineageId")! }), ...(input.review_result === undefined ? {} : { review_result: parseReviewResult(input.review_result, "review/finalize.review_result") }), ...(correction_line_forecast === undefined ? {} : { correction_line_forecast }), ...(input.validation_proof === undefined ? {} : { validation_proof: parseValidationProof(input.validation_proof, "review/finalize.validation_proof") }), ...(input.validation === undefined ? {} : { validation: parseValidation(input.validation, "review/finalize.validation") }), ...(input.final_evidence === undefined ? {} : { final_evidence: string(input.final_evidence, "review/finalize.final_evidence") }), ...(input.final_verification_passed === undefined ? {} : { final_verification_passed: input.final_verification_passed }) };
+}

package/lib/review-compact-store.ts

@@ -3,6 +3,7 @@ import {
 	closeSync,
 	existsSync,
 	fsyncSync,
+	lstatSync,
 	mkdirSync,
 	openSync,
 	readdirSync,
@@ -32,6 +33,7 @@ import {
 	type RepositoryAuthorityV1,
 } from "./review-repository.ts";
 import { ReviewTransactionStore } from "./review-transaction.ts";
+import { assertLoadedReviewRuntimeIdentity } from "./review-runtime-contract.ts";
 import {
 	captureCurrentReviewCandidateTree,
 	captureOrdinaryCorrectionSnapshot,
@@ -43,6 +45,7 @@ export const COMPACT_STORE_OPERATION = {
 	START: "review/start",
 	COMPLETE_REVIEW: "review/complete-review",
 	BEGIN_CORRECTION: "review/begin-correction",
+	FREEZE_VALIDATOR_REQUEST: "review/freeze-validator-request",
 	COMPLETE_CORRECTION: "review/complete-correction",
 	COMPLETE_VERIFICATION: "review/complete-verification",
 } as const;
@@ -61,6 +64,28 @@ export interface CompactReviewStoreOptions {
 	faultInjector?: (point: "before-state-rename" | "before-receipt-rename") => void;
 }
 
+export const COMPACT_AUTHORITY_OUTCOME = {
+	NONE: "none",
+	ACTIVE: "active",
+	APPROVED: "approved",
+	ESCALATED: "escalated",
+	INVALID: "invalid",
+} as const;
+
+export type CompactAuthorityOutcomeV2 =
+	(typeof COMPACT_AUTHORITY_OUTCOME)[keyof typeof COMPACT_AUTHORITY_OUTCOME];
+
+export interface CompactAuthorityLineageV2 {
+	lineage_id: string;
+	state: CompactReviewStateV2["state"];
+	revision: string;
+}
+
+export interface CompactAuthorityInspectionV2 {
+	outcome: CompactAuthorityOutcomeV2;
+	lineages: readonly CompactAuthorityLineageV2[];
+}
+
 export class CompactReviewStoreError extends Error {
 	constructor(message: string) {
 		super(message);
@@ -75,7 +100,7 @@ const STATE_KEYS = new Set([
 	"current_candidate_tree", "genesis_paths", "intended_untracked", "policy_hash",
 	"risk_tier", "selected_lenses", "original_changed_lines", "correction_budget",
 	"lens_results", "findings", "outcomes", "correction_ids", "follow_ups",
-	"correction_line_forecast", "correction", "validation", "final_evidence_hash",
+	"correction_line_forecast", "validator_request", "runtime_identity", "correction", "validation", "final_evidence_hash",
 	"escalation_reasons",
 ]);
 const SNAPSHOT_KEYS = new Set([
@@ -108,6 +133,15 @@ const VALIDATION_KEYS = new Set([
 	"correction_ids", "original_criteria", "correction_regression", "follow_ups",
 ]);
 const VALIDATION_CHECK_KEYS = new Set(["passed", "evidence"]);
+const VALIDATOR_REQUEST_KEYS = new Set(["body", "request_hash"]);
+const VALIDATOR_REQUEST_BODY_KEYS = new Set([
+	"schema", "purpose", "scope", "lineage_id", "candidate_tree", "fix_diff_hash", "correction_ids", "correction_paths",
+	"frozen_rows", "frozen_ledger_hash",
+]);
+const RUNTIME_IDENTITY_KEYS = new Set([
+	"schema", "compact_contract", "operation_contract", "state_schema", "record_schema", "receipt_schema",
+	"canonicalization", "identity_hash",
+]);
 const RECEIPT_BODY_KEYS = new Set([
 	"schema", "lineage_id", "generation", "authority_revision", "base_tree",
 	"initial_review_tree", "final_candidate_tree", "genesis_paths_hash",
@@ -168,6 +202,20 @@ function assertExactStateShape(state: CompactReviewStateV2): void {
 		assertObject(state.correction, "Compact correction");
 		assertExactKeys(state.correction, CORRECTION_KEYS, "Compact correction");
 	}
+	assertObject(state.runtime_identity, "Compact runtime identity");
+	assertExactKeys(state.runtime_identity, RUNTIME_IDENTITY_KEYS, "Compact runtime identity");
+	if (state.validator_request !== undefined) {
+		assertObject(state.validator_request, "Compact validator request");
+		assertExactKeys(state.validator_request, VALIDATOR_REQUEST_KEYS, "Compact validator request");
+		assertObject(state.validator_request.body, "Compact validator request body");
+		assertExactKeys(state.validator_request.body, VALIDATOR_REQUEST_BODY_KEYS, "Compact validator request body");
+		for (const finding of assertObjectArray(state.validator_request.body.frozen_rows, "Compact validator frozen rows")) {
+			assertExactKeys(finding, FINDING_KEYS, "Compact validator frozen row");
+		}
+		if (!Array.isArray(state.validator_request.body.scope) || state.validator_request.body.scope.some((scope) => typeof scope !== "string")) {
+			throw new CompactReviewStoreError("Compact validator request scope is malformed");
+		}
+	}
 	if (state.validation !== undefined) {
 		assertObject(state.validation, "Compact validation");
 		assertExactKeys(state.validation, VALIDATION_KEYS, "Compact validation");
@@ -184,6 +232,7 @@ function assertExactStateShape(state: CompactReviewStateV2): void {
 
 function operationMatchesState(operation: CompactStoreOperation, state: CompactReviewStateV2): boolean {
 	if (operation === COMPACT_STORE_OPERATION.START) return state.state === COMPACT_REVIEW_STATE.REVIEWING;
+	if (operation === COMPACT_STORE_OPERATION.FREEZE_VALIDATOR_REQUEST) return state.validator_request !== undefined;
 	if (operation === COMPACT_STORE_OPERATION.COMPLETE_VERIFICATION) return state.final_evidence_hash !== undefined;
 	if (operation === COMPACT_STORE_OPERATION.COMPLETE_CORRECTION) return state.correction !== undefined;
 	if (operation === COMPACT_STORE_OPERATION.BEGIN_CORRECTION) {
@@ -260,6 +309,7 @@ function immutableBinding(state: CompactReviewStateV2): unknown {
 		selected_lenses: state.selected_lenses,
 		original_changed_lines: state.original_changed_lines,
 		correction_budget: state.correction_budget,
+		runtime_identity: state.runtime_identity,
 	};
 }
 
@@ -306,6 +356,20 @@ function assertSuccessor(
 		if (!equal(expected, next)) throw new CompactReviewStoreError("Compact correction forecast changed unrelated state");
 		return;
 	}
+	if (operation === COMPACT_STORE_OPERATION.FREEZE_VALIDATOR_REQUEST) {
+		if (
+			previous.state !== COMPACT_REVIEW_STATE.CORRECTION_REQUIRED ||
+			previous.correction_line_forecast === undefined ||
+			previous.validator_request !== undefined ||
+			next.validator_request === undefined
+		) {
+			throw new CompactReviewStoreError("Invalid compact validator request successor");
+		}
+		const expected = clone(previous);
+		expected.validator_request = next.validator_request;
+		if (!equal(expected, next)) throw new CompactReviewStoreError("Compact validator request changed unrelated state");
+		return;
+	}
 	if (operation === COMPACT_STORE_OPERATION.COMPLETE_CORRECTION) {
 		if (
 			previous.state !== COMPACT_REVIEW_STATE.CORRECTION_REQUIRED ||
@@ -313,6 +377,8 @@ function assertSuccessor(
 			!stateIsOneOf(next.state, [COMPACT_REVIEW_STATE.VALIDATING, COMPACT_REVIEW_STATE.ESCALATED]) ||
 			!next.correction ||
 			!next.validation ||
+			!previous.validator_request ||
+			!equal(previous.validator_request, next.validator_request) ||
 			next.final_evidence_hash !== undefined ||
 			!equal(previous.lens_results, next.lens_results) ||
 			!equal(previous.findings, next.findings) ||
@@ -346,6 +412,10 @@ function graphCurrentExists(authority: RepositoryAuthorityV1): boolean {
 	return [0, 1, 2].some((slot) => existsSync(join(graphRoot, `CURRENT.${slot}`)));
 }
 
+export function hasGraphV1Authority(cwd: string): boolean {
+	return graphCurrentExists(resolveRepositoryAuthorityV1(cwd));
+}
+
 export function graphV1LineageExists(cwd: string, lineageId: string): boolean {
 	const authority = resolveRepositoryAuthorityV1(cwd);
 	if (!graphCurrentExists(authority)) return false;
@@ -403,7 +473,9 @@ export class CompactReviewStoreV2 {
 
 	load(): CompactStateRecordV2 {
 		try {
-			return parseRecord(readFileSync(this.statePath, "utf8"), this.#lineageId);
+			const record = parseRecord(readFileSync(this.statePath, "utf8"), this.#lineageId);
+			this.assertRuntimeIdentity(record.state);
+			return record;
 		} catch (error) {
 			if (error instanceof CompactReviewStoreError) throw error;
 			throw new CompactReviewStoreError(`Compact review state is unavailable: ${error instanceof Error ? error.message : String(error)}`);
@@ -416,6 +488,7 @@ export class CompactReviewStoreV2 {
 		nextState: CompactReviewStateV2,
 	): string {
 		assertCompactReviewState(nextState);
+		this.assertRuntimeIdentity(nextState);
 		if (nextState.lineage_id !== this.#lineageId) throw new CompactReviewStoreError("Compact state lineage does not match the store");
 		const owner = this.#lock.acquire();
 		try {
@@ -531,6 +604,14 @@ export class CompactReviewStoreV2 {
 		return clone(receipt);
 	}
 
+	private assertRuntimeIdentity(state: CompactReviewStateV2): void {
+		try {
+			assertLoadedReviewRuntimeIdentity(state.runtime_identity);
+		} catch {
+			throw new CompactReviewStoreError("Persisted compact runtime identity is incompatible: REVIEW_RUNTIME_INCOMPATIBLE");
+		}
+	}
+
 	private assertCurrentAuthority(): void {
 		const current = resolveRepositoryAuthorityV1(this.#cwd);
 		if (
@@ -569,8 +650,17 @@ export function discoverCompactReviewStores(cwd: string): CompactReviewStoreV2[]
 	const authority = resolveRepositoryAuthorityV1(cwd);
 	const root = assertManagedStorePathV1(authority.common_directory, join(authority.store_root, "compact-v2"));
 	if (!existsSync(root)) return [];
-	return readdirSync(root, { withFileTypes: true })
-		.filter((entry) => entry.isDirectory() && LINEAGE_ID.test(entry.name))
+	const rootStat = lstatSync(root);
+	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+		throw new CompactReviewStoreError("Invalid compact authority entry: compact-v2 root is not a real directory");
+	}
+	const entries = readdirSync(root, { withFileTypes: true });
+	for (const entry of entries) {
+		if (!entry.isDirectory() || entry.isSymbolicLink() || !LINEAGE_ID.test(entry.name)) {
+			throw new CompactReviewStoreError(`Invalid compact authority entry: ${entry.name}`);
+		}
+	}
+	return entries
 		.map((entry) => CompactReviewStoreV2.forRepository(cwd, entry.name))
 		.toSorted((left, right) => left.lineageDirectory.localeCompare(right.lineageDirectory));
 }
@@ -579,3 +669,33 @@ export function compactV2LineageExists(cwd: string, lineageId: string): boolean
 	const store = CompactReviewStoreV2.forRepository(cwd, lineageId);
 	return existsSync(store.statePath) && statSync(store.statePath).isFile();
 }
+
+export function inspectCompactReviewAuthorityV2(cwd: string): CompactAuthorityInspectionV2 {
+	const lineages: CompactAuthorityLineageV2[] = [];
+	try {
+		for (const store of discoverCompactReviewStores(cwd)) {
+			const record = store.load();
+			lineages.push({
+				lineage_id: record.state.lineage_id,
+				state: record.state.state,
+				revision: record.revision,
+			});
+		}
+	} catch {
+		return { outcome: COMPACT_AUTHORITY_OUTCOME.INVALID, lineages };
+	}
+	if (lineages.length === 0) return { outcome: COMPACT_AUTHORITY_OUTCOME.NONE, lineages };
+	if (lineages.some((lineage) =>
+		lineage.state !== COMPACT_REVIEW_STATE.APPROVED &&
+		lineage.state !== COMPACT_REVIEW_STATE.ESCALATED
+	)) {
+		return { outcome: COMPACT_AUTHORITY_OUTCOME.ACTIVE, lineages };
+	}
+	if (lineages.some((lineage) => lineage.state === COMPACT_REVIEW_STATE.ESCALATED)) {
+		return { outcome: COMPACT_AUTHORITY_OUTCOME.ESCALATED, lineages };
+	}
+	if (lineages.some((lineage) => lineage.state === COMPACT_REVIEW_STATE.APPROVED)) {
+		return { outcome: COMPACT_AUTHORITY_OUTCOME.APPROVED, lineages };
+	}
+	throw new CompactReviewStoreError("Compact authority inspection found no terminal or active lineage");
+}

package/lib/review-compact.ts

@@ -15,6 +15,11 @@ import {
 	REVIEW_LENS,
 	type ReviewLens,
 } from "./review-triggers.ts";
+import {
+	assertReviewRuntimeIdentity,
+	loadedReviewRuntimeIdentity,
+	type LoadedReviewRuntimeIdentityV1,
+} from "./review-runtime-contract.ts";
 
 export const COMPACT_REVIEW_STATE = {
 	REVIEWING: "reviewing",
@@ -148,7 +153,35 @@ export interface CompactValidationCheckInput {
 	evidence: string[];
 }
 
+export interface CompactValidationProofInput {
+	original_criteria: CompactValidationCheckInput;
+	correction_regression: CompactValidationCheckInput;
+}
+
+export const COMPACT_VALIDATOR_PURPOSE = { TARGETED_CORRECTION: "targeted-correction-validation" } as const;
+
+export const COMPACT_VALIDATOR_SCOPE = { ORIGINAL_CRITERIA: "original-criteria", CORRECTION_REGRESSION: "correction-regression" } as const;
+
+export interface CompactValidatorRequestBody {
+	schema: "gentle-ai.compact-validator-request/v1";
+	purpose: (typeof COMPACT_VALIDATOR_PURPOSE)[keyof typeof COMPACT_VALIDATOR_PURPOSE];
+	scope: Array<(typeof COMPACT_VALIDATOR_SCOPE)[keyof typeof COMPACT_VALIDATOR_SCOPE]>;
+	lineage_id: string;
+	candidate_tree: string;
+	fix_diff_hash: string;
+	correction_ids: string[];
+	correction_paths: string[];
+	frozen_rows: CompactFinding[];
+	frozen_ledger_hash: string;
+}
+
+export interface CompactValidatorRequest {
+	body: CompactValidatorRequestBody;
+	request_hash: string;
+}
+
 export interface CompactTargetedValidationInput {
+	request_hash: string;
 	correction_ids: string[];
 	original_criteria: CompactValidationCheckInput;
 	correction_regression: CompactValidationCheckInput;
@@ -193,6 +226,8 @@ export interface CompactReviewStateV2 {
 	correction_ids: string[];
 	follow_ups: CompactFollowUp[];
 	correction_line_forecast?: number;
+	validator_request?: CompactValidatorRequest;
+	runtime_identity: LoadedReviewRuntimeIdentityV1;
 	correction?: CompactCorrectionRecord;
 	validation?: CompactTargetedValidation;
 	final_evidence_hash?: string;
@@ -490,6 +525,7 @@ export function createCompactReviewState(input: {
 		outcomes: {},
 		correction_ids: [],
 		follow_ups: [],
+		runtime_identity: loadedReviewRuntimeIdentity(),
 		escalation_reasons: [],
 	};
 	assertCompactReviewState(state);
@@ -576,6 +612,48 @@ export function completeCompactReview(
 	return next;
 }
 
+export function createCompactValidatorRequest(
+	current: CompactReviewStateV2,
+	snapshot: CorrectionSnapshotV1,
+): CompactValidatorRequest {
+	assertCompactReviewState(current);
+	if (current.state !== COMPACT_REVIEW_STATE.CORRECTION_REQUIRED || current.correction_line_forecast === undefined) {
+		throw new Error(`Cannot create compact validator request from ${current.state}`);
+	}
+	const frozenRows = current.findings.filter((finding) => current.correction_ids.includes(finding.id));
+	const body: CompactValidatorRequestBody = {
+		schema: "gentle-ai.compact-validator-request/v1",
+		purpose: COMPACT_VALIDATOR_PURPOSE.TARGETED_CORRECTION,
+		scope: Object.values(COMPACT_VALIDATOR_SCOPE),
+		lineage_id: current.lineage_id,
+		candidate_tree: snapshot.candidate_tree,
+		fix_diff_hash: snapshot.fix_diff_hash,
+		correction_ids: [...current.correction_ids],
+		correction_paths: [...snapshot.changed_paths],
+		frozen_rows: clone(frozenRows),
+		frozen_ledger_hash: domainHashV1("compact-findings", current.findings),
+	};
+	return { body, request_hash: domainHashV1("compact-validator-request", body) };
+}
+
+export function freezeCompactValidatorRequest(
+	current: CompactReviewStateV2,
+	request: CompactValidatorRequest,
+): CompactReviewStateV2 {
+	assertCompactReviewState(current);
+	if (current.state !== COMPACT_REVIEW_STATE.CORRECTION_REQUIRED || current.correction_line_forecast === undefined) {
+		throw new Error(`Cannot freeze compact validator request from ${current.state}`);
+	}
+	if (current.validator_request !== undefined) {
+		if (!equal(current.validator_request, request)) throw new Error("Targeted validation does not match the frozen native validator request");
+		return clone(current);
+	}
+	const next = clone(current);
+	next.validator_request = clone(request);
+	assertCompactReviewState(next);
+	return next;
+}
+
 export function beginCompactCorrection(
 	current: CompactReviewStateV2,
 	forecast: number,
@@ -628,6 +706,17 @@ export function completeCompactCorrection(
 	if (!equal(canonicalStrings(intendedUntracked, "Correction untracked paths"), current.intended_untracked)) {
 		throw new Error("Compact correction changed the frozen untracked path set");
 	}
+	if (!DIGEST.test(input.request_hash)) throw new Error("Targeted validation request hash is invalid");
+	if (current.validator_request === undefined || input.request_hash !== current.validator_request.request_hash) {
+		throw new Error("Targeted validation does not match the frozen native validator request");
+	}
+	if (
+		snapshot.candidate_tree !== current.validator_request.body.candidate_tree ||
+		snapshot.fix_diff_hash !== current.validator_request.body.fix_diff_hash ||
+		!equal(snapshot.changed_paths, current.validator_request.body.correction_paths)
+	) {
+		throw new Error("Recaptured correction does not match the frozen validator request");
+	}
 	const correctionIds = canonicalStrings(input.correction_ids, "Targeted validation correction IDs");
 	if (!equal(correctionIds, current.correction_ids)) {
 		throw new Error("Targeted validation must cover exactly the frozen correction IDs");
@@ -764,6 +853,23 @@ export function assertCompactReviewState(state: CompactReviewStateV2): void {
 	if (state.correction_line_forecast !== undefined && (!Number.isSafeInteger(state.correction_line_forecast) || state.correction_line_forecast <= 0)) {
 		throw new Error("Compact correction forecast must be positive");
 	}
+	assertReviewRuntimeIdentity(state.runtime_identity);
+	if (state.validator_request !== undefined) {
+		const request = state.validator_request;
+		if (
+			state.correction_line_forecast === undefined ||
+			request.request_hash !== domainHashV1("compact-validator-request", request.body) ||
+			request.body.purpose !== COMPACT_VALIDATOR_PURPOSE.TARGETED_CORRECTION ||
+			!equal(request.body.scope, Object.values(COMPACT_VALIDATOR_SCOPE)) ||
+			request.body.lineage_id !== state.lineage_id ||
+			!equal(request.body.correction_ids, state.correction_ids) ||
+			!equal(request.body.frozen_rows, state.findings.filter((finding) => state.correction_ids.includes(finding.id))) ||
+			request.body.frozen_ledger_hash !== domainHashV1("compact-findings", state.findings) ||
+			request.body.correction_paths.some((path) => !state.genesis_paths.includes(path))
+		) {
+			throw new Error("Compact validator request is not bound to frozen review evidence");
+		}
+	}
 	if (state.correction) {
 		if (!DIGEST.test(state.correction.fix_diff_hash) || state.correction.changed_lines > state.correction_budget || state.correction.candidate_tree !== state.current_candidate_tree || !equal(state.correction.correction_ids, state.correction_ids) || !equal(state.correction.intended_untracked, state.intended_untracked)) {
 			throw new Error("Compact correction record is not bound to frozen authority");
@@ -773,7 +879,7 @@ export function assertCompactReviewState(state: CompactReviewStateV2): void {
 		throw new Error("Compact targeted validation is incomplete or unbound");
 	}
 	if (state.state === COMPACT_REVIEW_STATE.REVIEWING) {
-		if (state.findings.length > 0 || state.lens_results.length > 0 || state.correction_ids.length > 0 || state.final_evidence_hash !== undefined) {
+		if (state.findings.length > 0 || state.lens_results.length > 0 || state.correction_ids.length > 0 || state.validator_request !== undefined || state.final_evidence_hash !== undefined) {
 			throw new Error("Reviewing compact state contains post-review data");
 		}
 	} else if (state.lens_results.length !== state.selected_lenses.length) {
@@ -782,7 +888,7 @@ export function assertCompactReviewState(state: CompactReviewStateV2): void {
 	if (state.state === COMPACT_REVIEW_STATE.CORRECTION_REQUIRED && state.correction_ids.length === 0) {
 		throw new Error("Correction-required compact state has no correction IDs");
 	}
-	if (state.state === COMPACT_REVIEW_STATE.VALIDATING && state.correction_ids.length > 0 && (!state.correction || !state.validation)) {
+	if (state.state === COMPACT_REVIEW_STATE.VALIDATING && state.correction_ids.length > 0 && (!state.correction || !state.validation || !state.validator_request)) {
 		throw new Error("Corrected compact state requires one targeted validation");
 	}
 	if (state.state === COMPACT_REVIEW_STATE.APPROVED && !DIGEST.test(state.final_evidence_hash ?? "")) {