gentle-pi 2.1.2 → 2.3.0

package/lib/review-compact.ts

@@ -1,947 +0,0 @@
-import { createHash } from "node:crypto";
-import { canonicalJsonV1, domainHashV1 } from "./review-canonical.ts";
-import {
-	REVIEW_RISK_TIER,
-	correctionBudget,
-	type ReviewRiskTier,
-} from "./review-risk.ts";
-import {
-	REVIEW_MODE,
-	type CorrectionSnapshotV1,
-	type SnapshotV1,
-} from "./review-snapshot.ts";
-import {
-	FULL_4R_LENSES,
-	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",
-	CORRECTION_REQUIRED: "correction_required",
-	VALIDATING: "validating",
-	APPROVED: "approved",
-	ESCALATED: "escalated",
-} as const;
-
-export type CompactReviewStateName =
-	(typeof COMPACT_REVIEW_STATE)[keyof typeof COMPACT_REVIEW_STATE];
-
-export const CAUSAL_DISPOSITION = {
-	INTRODUCED: "introduced",
-	BEHAVIOR_ACTIVATED: "behavior-activated",
-	WORSENED: "worsened",
-	PRE_EXISTING: "pre-existing",
-	BASE_ONLY: "base-only",
-	UNKNOWN: "unknown",
-} as const;
-
-export type CausalDisposition =
-	(typeof CAUSAL_DISPOSITION)[keyof typeof CAUSAL_DISPOSITION];
-
-export const COMPACT_EVIDENCE_CLASS = {
-	DETERMINISTIC: "deterministic",
-	INFERENTIAL: "inferential",
-	INSUFFICIENT: "insufficient",
-	INFO: "info",
-} as const;
-
-export type CompactEvidenceClass =
-	(typeof COMPACT_EVIDENCE_CLASS)[keyof typeof COMPACT_EVIDENCE_CLASS];
-
-export const COMPACT_FINDING_OUTCOME = {
-	CORROBORATED: "corroborated",
-	REFUTED: "refuted",
-	INCONCLUSIVE: "inconclusive",
-	INFO: "info",
-} as const;
-
-export type CompactFindingOutcome =
-	(typeof COMPACT_FINDING_OUTCOME)[keyof typeof COMPACT_FINDING_OUTCOME];
-
-export const COMPACT_SEVERITY = {
-	BLOCKER: "BLOCKER",
-	CRITICAL: "CRITICAL",
-	WARNING: "WARNING",
-	SUGGESTION: "SUGGESTION",
-} as const;
-
-export type CompactSeverity =
-	(typeof COMPACT_SEVERITY)[keyof typeof COMPACT_SEVERITY];
-
-export const CAUSAL_PROOF_KIND = {
-	CHANGED_HUNK: "changed-hunk",
-	CANDIDATE_CREATED_PATH: "candidate-created-path",
-	DIFFERENTIAL_TEST: "differential-test",
-	BEFORE_AFTER: "before-after",
-} as const;
-
-export type CausalProofKind =
-	(typeof CAUSAL_PROOF_KIND)[keyof typeof CAUSAL_PROOF_KIND];
-
-export interface CompactFindingInput {
-	id?: string;
-	lens?: string;
-	location?: string;
-	severity?: string;
-	claim?: string;
-	evidence_class?: string;
-	causal_disposition?: string;
-	proof_refs?: string[];
-}
-
-export interface CompactFinding {
-	id: string;
-	lens: ReviewLens;
-	location: string;
-	severity: CompactSeverity;
-	claim: string;
-	evidence_class: CompactEvidenceClass;
-	causal_disposition: CausalDisposition;
-	proof_refs: string[];
-}
-
-export interface CompactLensResultInput {
-	lens?: string;
-	findings: CompactFindingInput[];
-	evidence: string[];
-}
-
-export interface CompactLensResult {
-	lens: ReviewLens;
-	findings: CompactFinding[];
-	evidence: string[];
-}
-
-export interface CompactRefuterResultInput {
-	finding_id: string;
-	outcome: string;
-	proof_refs: string[];
-}
-
-export interface CompactRefuterResult {
-	finding_id: string;
-	outcome: Exclude<CompactFindingOutcome, "info">;
-	proof_refs: string[];
-}
-
-export interface CompactFollowUp {
-	finding_id: string;
-	location: string;
-	summary: string;
-	proof_refs: string[];
-}
-
-export interface CompactReviewResultInput {
-	lens_results: CompactLensResultInput[];
-	refuter_request_hash?: string;
-	refuter_results?: CompactRefuterResultInput[];
-}
-
-export interface CompactRefuterRequest {
-	request_hash: string;
-	findings: CompactFinding[];
-}
-
-export interface CompactValidationCheckInput {
-	passed: boolean;
-	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;
-	fix_caused_findings?: CompactFindingInput[];
-	follow_ups: CompactFollowUp[];
-}
-
-export interface CompactTargetedValidation {
-	correction_ids: string[];
-	original_criteria: CompactValidationCheckInput;
-	correction_regression: CompactValidationCheckInput;
-	follow_ups: CompactFollowUp[];
-}
-
-export interface CompactCorrectionRecord {
-	candidate_tree: string;
-	changed_paths: string[];
-	changed_lines: number;
-	fix_diff_hash: string;
-	correction_ids: string[];
-	intended_untracked: string[];
-}
-
-export interface CompactReviewStateV2 {
-	schema: "gentle-ai.review-state/v2";
-	lineage_id: string;
-	generation: 1;
-	mode: typeof REVIEW_MODE.ORDINARY;
-	state: CompactReviewStateName;
-	initial_snapshot: SnapshotV1;
-	current_candidate_tree: string;
-	genesis_paths: string[];
-	intended_untracked: string[];
-	policy_hash: string;
-	risk_tier: ReviewRiskTier;
-	selected_lenses: readonly ReviewLens[];
-	original_changed_lines: number;
-	correction_budget: number;
-	lens_results: CompactLensResult[];
-	findings: CompactFinding[];
-	outcomes: Record<string, CompactFindingOutcome>;
-	correction_ids: string[];
-	follow_ups: CompactFollowUp[];
-	correction_line_forecast?: number;
-	validator_request?: CompactValidatorRequest;
-	runtime_identity: LoadedReviewRuntimeIdentityV1;
-	correction?: CompactCorrectionRecord;
-	validation?: CompactTargetedValidation;
-	final_evidence_hash?: string;
-	escalation_reasons: string[];
-}
-
-export interface CompactReceiptBodyV2 {
-	schema: "gentle-ai.review-receipt-body/v2";
-	lineage_id: string;
-	generation: 1;
-	authority_revision: string;
-	base_tree: string;
-	initial_review_tree: string;
-	final_candidate_tree: string;
-	genesis_paths_hash: string;
-	intended_untracked_hash: string;
-	policy_hash: string;
-	risk_tier: ReviewRiskTier;
-	selected_lenses: readonly ReviewLens[];
-	original_changed_lines: number;
-	correction_budget: number;
-	correction_ids: string[];
-	fix_diff_hash: string;
-	evidence_hash: string;
-	terminal_state: "approved" | "escalated";
-}
-
-export interface CompactReceiptEnvelopeV2 {
-	body: CompactReceiptBodyV2;
-	receipt_hash: string;
-}
-
-const DIGEST = /^[0-9a-f]{64}$/;
-const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
-const LINEAGE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const FINDING_ID = /^[A-Z][A-Z0-9-]*-[0-9]{3,}$/;
-const PROOF_PREFIX = new RegExp(`^(?:${Object.values(CAUSAL_PROOF_KIND).join("|")}):\\S`);
-const CANDIDATE_CAUSED = new Set<CausalDisposition>([
-	CAUSAL_DISPOSITION.INTRODUCED,
-	CAUSAL_DISPOSITION.BEHAVIOR_ACTIVATED,
-	CAUSAL_DISPOSITION.WORSENED,
-]);
-const SEVERE = new Set<CompactSeverity>([
-	COMPACT_SEVERITY.BLOCKER,
-	COMPACT_SEVERITY.CRITICAL,
-]);
-const LENS_PREFIX: Record<ReviewLens, string> = {
-	[REVIEW_LENS.RISK]: "RISK",
-	[REVIEW_LENS.RESILIENCE]: "RESILIENCE",
-	[REVIEW_LENS.READABILITY]: "READABILITY",
-	[REVIEW_LENS.RELIABILITY]: "RELIABILITY",
-};
-
-function clone<T>(value: T): T {
-	return JSON.parse(canonicalJsonV1(value)) as T;
-}
-
-function canonicalStrings(values: readonly string[], label: string): string[] {
-	if (values.some((value) => typeof value !== "string" || value.trim() !== value || value.length === 0)) {
-		throw new Error(`${label} must contain non-empty canonical strings`);
-	}
-	return [...new Set(values)].toSorted();
-}
-
-function equal(left: unknown, right: unknown): boolean {
-	return canonicalJsonV1(left) === canonicalJsonV1(right);
-}
-
-function expectedLenses(tier: ReviewRiskTier): readonly ReviewLens[] {
-	if (tier === REVIEW_RISK_TIER.LOW) return [];
-	if (tier === REVIEW_RISK_TIER.HIGH) return FULL_4R_LENSES;
-	return [];
-}
-
-function assertSelectedLenses(
-	tier: ReviewRiskTier,
-	lenses: readonly ReviewLens[],
-): void {
-	if (tier === REVIEW_RISK_TIER.MEDIUM) {
-		if (lenses.length !== 1 || !Object.values(REVIEW_LENS).includes(lenses[0]!)) {
-			throw new Error("Medium compact review requires exactly one selected lens");
-		}
-		return;
-	}
-	if (!equal(lenses, expectedLenses(tier))) {
-		throw new Error("Compact selected lenses do not match the frozen risk tier");
-	}
-}
-
-function isConcreteProof(proofRefs: readonly string[]): boolean {
-	return proofRefs.length > 0 && proofRefs.every((proof) => PROOF_PREFIX.test(proof));
-}
-
-function normalizeSeverity(value: string | undefined): CompactSeverity | undefined {
-	const normalized = value?.trim().toUpperCase();
-	return Object.values(COMPACT_SEVERITY).find((severity) => severity === normalized);
-}
-
-function normalizeEvidenceClass(value: string | undefined): CompactEvidenceClass | undefined {
-	const normalized = value?.trim().toLowerCase();
-	if (normalized === "inferential-severe") return COMPACT_EVIDENCE_CLASS.INFERENTIAL;
-	return Object.values(COMPACT_EVIDENCE_CLASS).find((item) => item === normalized);
-}
-
-function normalizeDisposition(value: string | undefined): CausalDisposition | undefined {
-	const normalized = value?.trim().toLowerCase();
-	return Object.values(CAUSAL_DISPOSITION).find((item) => item === normalized);
-}
-
-function canonicalizeLensResults(
-	selectedLenses: readonly ReviewLens[],
-	inputs: readonly CompactLensResultInput[],
-): { results: CompactLensResult[]; findings: CompactFinding[]; reasons: string[] } {
-	if (inputs.length !== selectedLenses.length) {
-		throw new Error(`Compact review requires all ${selectedLenses.length} selected lens results`);
-	}
-	const reasons: string[] = [];
-	const usedIds = new Set<string>();
-	const results = inputs.map((input, lensIndex): CompactLensResult => {
-		const lens = selectedLenses[lensIndex]!;
-		if (!Array.isArray(input.findings) || !Array.isArray(input.evidence)) {
-			throw new Error(`Compact lens result ${lensIndex + 1} requires explicit findings and evidence arrays`);
-		}
-		if (input.lens !== undefined && input.lens !== lens) {
-			reasons.push(`Lens result ${lensIndex + 1} claimed ${input.lens} instead of selected lens ${lens}.`);
-		}
-		const sorted = input.findings.map((finding, index) => ({ finding, index })).toSorted((left, right) => {
-			const leftKey = [left.finding.location ?? "", left.finding.claim ?? "", left.finding.severity ?? "", left.index];
-			const rightKey = [right.finding.location ?? "", right.finding.claim ?? "", right.finding.severity ?? "", right.index];
-			return canonicalJsonV1(leftKey).localeCompare(canonicalJsonV1(rightKey));
-		});
-		let nextId = 1;
-		const findings = sorted.map(({ finding }): CompactFinding => {
-			const severity = normalizeSeverity(finding.severity) ?? COMPACT_SEVERITY.CRITICAL;
-			const severe = SEVERE.has(severity);
-			const evidenceClass = severe
-				? normalizeEvidenceClass(finding.evidence_class) ?? COMPACT_EVIDENCE_CLASS.INSUFFICIENT
-				: COMPACT_EVIDENCE_CLASS.INFO;
-			const disposition = severe
-				? normalizeDisposition(finding.causal_disposition) ?? CAUSAL_DISPOSITION.UNKNOWN
-				: normalizeDisposition(finding.causal_disposition) ?? CAUSAL_DISPOSITION.UNKNOWN;
-			const proofRefs = Array.isArray(finding.proof_refs)
-				? finding.proof_refs.filter((proof): proof is string => typeof proof === "string").toSorted()
-				: [];
-			let id = finding.id?.trim().toUpperCase() ?? "";
-			while (!id || !FINDING_ID.test(id) || usedIds.has(id)) {
-				if (id && severe) reasons.push(`Finding ID ${id} was malformed or duplicated and was replaced natively.`);
-				id = `${LENS_PREFIX[lens]}-${String(nextId).padStart(3, "0")}`;
-				nextId += 1;
-				if (!usedIds.has(id)) break;
-			}
-			usedIds.add(id);
-			const location = finding.location?.trim() || "unknown:0";
-			const claim = finding.claim?.trim() || "Malformed severe finding without a concrete claim.";
-			if (severe && (
-				!normalizeSeverity(finding.severity) ||
-				!finding.location?.trim() ||
-				!finding.claim?.trim() ||
-				!normalizeEvidenceClass(finding.evidence_class) ||
-				!normalizeDisposition(finding.causal_disposition) ||
-				!isConcreteProof(proofRefs)
-			)) {
-				reasons.push(`${id} is a malformed or insufficient severe claim.`);
-			}
-			return {
-				id,
-				lens,
-				location,
-				severity,
-				claim,
-				evidence_class: evidenceClass,
-				causal_disposition: disposition,
-				proof_refs: proofRefs,
-			};
-		});
-		return {
-			lens,
-			findings: findings.toSorted((left, right) => left.id.localeCompare(right.id)),
-			evidence: input.evidence.filter((item): item is string => typeof item === "string").toSorted(),
-		};
-	});
-	return { results, findings: results.flatMap(({ findings }) => findings), reasons };
-}
-
-function refuterRequest(
-	current: CompactReviewStateV2,
-	canonical: ReturnType<typeof canonicalizeLensResults>,
-): CompactRefuterRequest | undefined {
-	const findings = canonical.findings.filter((finding) =>
-		SEVERE.has(finding.severity) &&
-		finding.evidence_class === COMPACT_EVIDENCE_CLASS.INFERENTIAL &&
-		CANDIDATE_CAUSED.has(finding.causal_disposition) &&
-		isConcreteProof(finding.proof_refs)
-	);
-	if (findings.length === 0) return undefined;
-	return {
-		request_hash: domainHashV1("compact-refuter-request", {
-			lineage_id: current.lineage_id,
-			candidate_tree: current.current_candidate_tree,
-			lens_results: canonical.results,
-			finding_ids: findings.map(({ id }) => id),
-		}),
-		findings: clone(findings),
-	};
-}
-
-export function createCompactRefuterRequest(
-	current: CompactReviewStateV2,
-	lensResults: readonly CompactLensResultInput[],
-): CompactRefuterRequest | undefined {
-	assertCompactReviewState(current);
-	if (current.state !== COMPACT_REVIEW_STATE.REVIEWING) throw new Error(`Cannot request compact refutation from ${current.state}`);
-	return refuterRequest(current, canonicalizeLensResults(current.selected_lenses, lensResults));
-}
-
-function causalFollowUp(finding: CompactFinding): CompactFollowUp {
-	return {
-		finding_id: finding.id,
-		location: finding.location,
-		summary: finding.claim,
-		proof_refs: [...finding.proof_refs],
-	};
-}
-
-function validateRefuterBatch(
-	inferentialIds: readonly string[],
-	input: readonly CompactRefuterResultInput[] | undefined,
-): { results: CompactRefuterResult[]; reasons: string[] } {
-	if (inferentialIds.length === 0) {
-		return {
-			results: [],
-			reasons: input && input.length > 0
-				? ["A refuter batch was supplied without inferential candidate-caused severe findings."]
-				: [],
-		};
-	}
-	if (!input) {
-		return { results: [], reasons: ["Inferential severe findings require exactly one complete refuter batch."] };
-	}
-	const expected = new Set(inferentialIds);
-	const seen = new Set<string>();
-	const reasons: string[] = [];
-	const results: CompactRefuterResult[] = [];
-	for (const item of input as readonly unknown[]) {
-		if (typeof item !== "object" || item === null || Array.isArray(item)) {
-			reasons.push("Refuter result <malformed> is malformed, duplicated, or outside the complete batch.");
-			continue;
-		}
-		const row = item as Partial<CompactRefuterResultInput>;
-		const id = typeof row.finding_id === "string" ? row.finding_id.trim().toUpperCase() : "";
-		const outcome = typeof row.outcome === "string" ? Object.values(COMPACT_FINDING_OUTCOME).find((value) => value === row.outcome) as CompactFindingOutcome | undefined : undefined;
-		const proofRefs = Array.isArray(row.proof_refs) && row.proof_refs.every((proof) => typeof proof === "string") ? row.proof_refs : undefined;
-		if (!expected.has(id) || seen.has(id) || outcome === undefined || outcome === COMPACT_FINDING_OUTCOME.INFO || !proofRefs || !isConcreteProof(proofRefs)) {
-			reasons.push(`Refuter result ${id || "<missing>"} is malformed, duplicated, or outside the complete batch.`);
-			continue;
-		}
-		seen.add(id);
-		results.push({
-			finding_id: id,
-			outcome,
-			proof_refs: [...proofRefs].toSorted(),
-		});
-	}
-	for (const id of inferentialIds) {
-		if (!seen.has(id)) reasons.push(`Refuter batch omitted inferential finding ${id}.`);
-	}
-	return { results: results.toSorted((left, right) => left.finding_id.localeCompare(right.finding_id)), reasons };
-}
-
-export function createCompactReviewState(input: {
-	lineageId: string;
-	snapshot: SnapshotV1;
-	policyHash: string;
-}): CompactReviewStateV2 {
-	if (!LINEAGE_ID.test(input.lineageId)) throw new Error("Compact review lineage ID is invalid");
-	if (input.snapshot.mode !== REVIEW_MODE.ORDINARY) throw new Error("Compact reviews require ordinary mode");
-	if (!DIGEST.test(input.policyHash)) throw new Error("Compact review policy hash is invalid");
-	const state: CompactReviewStateV2 = {
-		schema: "gentle-ai.review-state/v2",
-		lineage_id: input.lineageId,
-		generation: 1,
-		mode: REVIEW_MODE.ORDINARY,
-		state: COMPACT_REVIEW_STATE.REVIEWING,
-		initial_snapshot: clone(input.snapshot),
-		current_candidate_tree: input.snapshot.initial_review_tree,
-		genesis_paths: [...(input.snapshot.genesis_paths ?? [])],
-		intended_untracked: [...input.snapshot.intended_untracked],
-		policy_hash: input.policyHash,
-		risk_tier: input.snapshot.risk_tier,
-		selected_lenses: Object.freeze([...input.snapshot.lenses]),
-		original_changed_lines: input.snapshot.original_changed_lines,
-		correction_budget: input.snapshot.correction_budget,
-		lens_results: [],
-		findings: [],
-		outcomes: {},
-		correction_ids: [],
-		follow_ups: [],
-		runtime_identity: loadedReviewRuntimeIdentity(),
-		escalation_reasons: [],
-	};
-	assertCompactReviewState(state);
-	return state;
-}
-
-export function completeCompactReview(
-	current: CompactReviewStateV2,
-	input: CompactReviewResultInput,
-): CompactReviewStateV2 {
-	assertCompactReviewState(current);
-	if (current.state !== COMPACT_REVIEW_STATE.REVIEWING) {
-		throw new Error(`Cannot complete compact review from ${current.state}`);
-	}
-	const next = clone(current);
-	const canonical = canonicalizeLensResults(current.selected_lenses, input.lens_results);
-	const request = refuterRequest(current, canonical);
-	if (request?.request_hash !== input.refuter_request_hash) {
-		throw new Error("Compact refuter request hash is missing or does not match the identical canonical lens input");
-	}
-	next.lens_results = canonical.results;
-	next.findings = canonical.findings;
-	next.escalation_reasons.push(...canonical.reasons);
-	const inferential: string[] = [];
-	for (const finding of next.findings) {
-		if (!SEVERE.has(finding.severity)) {
-			next.outcomes[finding.id] = COMPACT_FINDING_OUTCOME.INFO;
-			continue;
-		}
-		if (finding.evidence_class === COMPACT_EVIDENCE_CLASS.INSUFFICIENT || !isConcreteProof(finding.proof_refs)) {
-			next.outcomes[finding.id] = COMPACT_FINDING_OUTCOME.INCONCLUSIVE;
-			next.escalation_reasons.push(`${finding.id} has insufficient or malformed severe evidence.`);
-			continue;
-		}
-		if (
-			finding.causal_disposition === CAUSAL_DISPOSITION.PRE_EXISTING ||
-			finding.causal_disposition === CAUSAL_DISPOSITION.BASE_ONLY
-		) {
-			next.outcomes[finding.id] = COMPACT_FINDING_OUTCOME.INFO;
-			next.follow_ups.push(causalFollowUp(finding));
-			continue;
-		}
-		if (finding.causal_disposition === CAUSAL_DISPOSITION.UNKNOWN) {
-			next.outcomes[finding.id] = COMPACT_FINDING_OUTCOME.INCONCLUSIVE;
-			next.escalation_reasons.push(`${finding.id} has unknown causal disposition.`);
-			continue;
-		}
-		if (!CANDIDATE_CAUSED.has(finding.causal_disposition)) {
-			next.outcomes[finding.id] = COMPACT_FINDING_OUTCOME.INCONCLUSIVE;
-			next.escalation_reasons.push(`${finding.id} has unsupported causal disposition.`);
-			continue;
-		}
-		if (finding.evidence_class === COMPACT_EVIDENCE_CLASS.DETERMINISTIC) {
-			next.outcomes[finding.id] = COMPACT_FINDING_OUTCOME.CORROBORATED;
-			next.correction_ids.push(finding.id);
-		} else if (finding.evidence_class === COMPACT_EVIDENCE_CLASS.INFERENTIAL) {
-			inferential.push(finding.id);
-		} else {
-			next.outcomes[finding.id] = COMPACT_FINDING_OUTCOME.INCONCLUSIVE;
-			next.escalation_reasons.push(`${finding.id} has insufficient severe evidence.`);
-		}
-	}
-	const refuter = validateRefuterBatch(inferential, input.refuter_results);
-	next.escalation_reasons.push(...refuter.reasons);
-	for (const result of refuter.results) {
-		next.outcomes[result.finding_id] = result.outcome;
-		if (result.outcome === COMPACT_FINDING_OUTCOME.CORROBORATED) {
-			next.correction_ids.push(result.finding_id);
-		} else if (result.outcome === COMPACT_FINDING_OUTCOME.INCONCLUSIVE) {
-			next.escalation_reasons.push(`${result.finding_id} remained inconclusive after the only refuter batch.`);
-		}
-	}
-	for (const id of inferential) {
-		if (next.outcomes[id] === undefined) next.outcomes[id] = COMPACT_FINDING_OUTCOME.INCONCLUSIVE;
-	}
-	next.correction_ids = canonicalStrings(next.correction_ids, "Compact correction IDs");
-	next.follow_ups = next.follow_ups.toSorted((left, right) => left.finding_id.localeCompare(right.finding_id));
-	next.state = next.escalation_reasons.length > 0
-		? COMPACT_REVIEW_STATE.ESCALATED
-		: next.correction_ids.length > 0
-			? COMPACT_REVIEW_STATE.CORRECTION_REQUIRED
-			: COMPACT_REVIEW_STATE.VALIDATING;
-	assertCompactReviewState(next);
-	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,
-): CompactReviewStateV2 {
-	assertCompactReviewState(current);
-	if (
-		current.state !== COMPACT_REVIEW_STATE.CORRECTION_REQUIRED ||
-		current.correction_line_forecast !== undefined
-	) {
-		throw new Error(`Cannot begin compact correction from ${current.state}`);
-	}
-	if (!Number.isSafeInteger(forecast) || forecast <= 0) {
-		throw new Error("Compact correction requires a positive changed-line forecast before editing");
-	}
-	const next = clone(current);
-	next.correction_line_forecast = forecast;
-	if (forecast > next.correction_budget) {
-		next.state = COMPACT_REVIEW_STATE.ESCALATED;
-		next.escalation_reasons.push(`Correction forecast ${forecast} exceeds frozen budget ${next.correction_budget}.`);
-	}
-	assertCompactReviewState(next);
-	return next;
-}
-
-export function completeCompactCorrection(
-	current: CompactReviewStateV2,
-	snapshot: CorrectionSnapshotV1,
-	intendedUntracked: readonly string[],
-	input: CompactTargetedValidationInput,
-): CompactReviewStateV2 {
-	assertCompactReviewState(current);
-	if (
-		current.state !== COMPACT_REVIEW_STATE.CORRECTION_REQUIRED ||
-		current.correction_line_forecast === undefined
-	) {
-		throw new Error(`Cannot complete compact correction from ${current.state}`);
-	}
-	if (current.correction_line_forecast > current.correction_budget) {
-		throw new Error("Compact correction forecast exceeds the frozen budget");
-	}
-	if (snapshot.changed_lines > current.correction_budget) {
-		throw new Error(`Actual correction is ${snapshot.changed_lines} changed lines, exceeding frozen budget ${current.correction_budget}`);
-	}
-	if (!equal(canonicalStrings(snapshot.changed_paths, "Correction paths"), snapshot.changed_paths)) {
-		throw new Error("Correction paths are not canonical");
-	}
-	if (snapshot.changed_paths.some((path) => !current.genesis_paths.includes(path))) {
-		throw new Error("Compact correction touches a path outside the frozen original scope");
-	}
-	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");
-	}
-	if (
-		!Array.isArray(input.original_criteria?.evidence) ||
-		input.original_criteria.evidence.length === 0 ||
-		!Array.isArray(input.correction_regression?.evidence) ||
-		input.correction_regression.evidence.length === 0
-	) {
-		throw new Error("Targeted validation requires original criteria and correction regression evidence");
-	}
-	const next = clone(current);
-	next.current_candidate_tree = snapshot.candidate_tree;
-	next.correction = {
-		candidate_tree: snapshot.candidate_tree,
-		changed_paths: [...snapshot.changed_paths],
-		changed_lines: snapshot.changed_lines,
-		fix_diff_hash: snapshot.fix_diff_hash,
-		correction_ids: [...current.correction_ids],
-		intended_untracked: [...intendedUntracked],
-	};
-	next.validation = {
-		correction_ids: correctionIds,
-		original_criteria: clone(input.original_criteria),
-		correction_regression: clone(input.correction_regression),
-		follow_ups: clone(input.follow_ups ?? []).toSorted((left, right) => left.finding_id.localeCompare(right.finding_id)),
-	};
-	next.follow_ups.push(...next.validation.follow_ups);
-	if ((input.fix_caused_findings?.length ?? 0) > 0) {
-		next.escalation_reasons.push("Targeted validation attempted to add correction-caused findings or scope.");
-	}
-	if (!input.original_criteria.passed) next.escalation_reasons.push("Original criteria failed during targeted validation.");
-	if (!input.correction_regression.passed) next.escalation_reasons.push("Correction regression check failed.");
-	next.state = next.escalation_reasons.length > 0
-		? COMPACT_REVIEW_STATE.ESCALATED
-		: COMPACT_REVIEW_STATE.VALIDATING;
-	assertCompactReviewState(next);
-	return next;
-}
-
-export function completeCompactVerification(
-	current: CompactReviewStateV2,
-	evidence: string | Uint8Array,
-	approved: boolean,
-): CompactReviewStateV2 {
-	assertCompactReviewState(current);
-	if (current.state !== COMPACT_REVIEW_STATE.VALIDATING) {
-		throw new Error(`Cannot complete compact verification from ${current.state}`);
-	}
-	const bytes = typeof evidence === "string" ? new TextEncoder().encode(evidence) : evidence;
-	if (bytes.byteLength === 0) throw new Error("Compact final verification evidence is required");
-	const next = clone(current);
-	next.final_evidence_hash = createHash("sha256").update(bytes).digest("hex");
-	next.state = approved ? COMPACT_REVIEW_STATE.APPROVED : COMPACT_REVIEW_STATE.ESCALATED;
-	if (!approved) next.escalation_reasons.push("Final verification failed.");
-	assertCompactReviewState(next);
-	return next;
-}
-
-export function assertCompactReviewState(state: CompactReviewStateV2): void {
-	if (state.schema !== "gentle-ai.review-state/v2" || state.mode !== REVIEW_MODE.ORDINARY) {
-		throw new Error("Unsupported compact review state schema or mode");
-	}
-	if (!LINEAGE_ID.test(state.lineage_id) || state.generation !== 1) throw new Error("Compact review identity is invalid");
-	if (!OBJECT_ID.test(state.initial_snapshot.base_tree) || !OBJECT_ID.test(state.initial_snapshot.initial_review_tree) || !OBJECT_ID.test(state.current_candidate_tree)) {
-		throw new Error("Compact review tree identity is invalid");
-	}
-	if (!DIGEST.test(state.policy_hash)) throw new Error("Compact policy hash is invalid");
-	if (state.initial_snapshot.mode !== REVIEW_MODE.ORDINARY) throw new Error("Compact initial snapshot mode is invalid");
-	const genesis = canonicalStrings(state.genesis_paths, "Compact genesis paths");
-	if (!equal(genesis, state.genesis_paths) || !equal(genesis, state.initial_snapshot.genesis_paths ?? [])) {
-		throw new Error("Compact genesis paths do not match the frozen snapshot scope");
-	}
-	const untracked = canonicalStrings(state.intended_untracked, "Compact intended-untracked paths");
-	if (!equal(untracked, state.intended_untracked) || !equal(untracked, state.initial_snapshot.intended_untracked)) {
-		throw new Error("Compact intended-untracked paths do not match the frozen snapshot");
-	}
-	if (state.risk_tier !== state.initial_snapshot.risk_tier || state.original_changed_lines !== state.initial_snapshot.original_changed_lines || state.correction_budget !== state.initial_snapshot.correction_budget) {
-		throw new Error("Compact authored-risk baseline changed");
-	}
-	if (state.correction_budget !== correctionBudget(state.original_changed_lines)) {
-		throw new Error("Compact correction budget does not match original changed lines");
-	}
-	assertSelectedLenses(state.risk_tier, state.selected_lenses);
-	if (!equal(state.selected_lenses, state.initial_snapshot.lenses)) {
-		throw new Error("Compact selected lenses changed from the frozen snapshot");
-	}
-	if (!Array.isArray(state.lens_results) || !Array.isArray(state.findings) || !Array.isArray(state.correction_ids) || !Array.isArray(state.follow_ups) || !Array.isArray(state.escalation_reasons)) {
-		throw new Error("Compact review collections must be explicit");
-	}
-	if (state.lens_results.length > state.selected_lenses.length) throw new Error("Compact review has extra lens results");
-	for (const [index, result] of state.lens_results.entries()) {
-		if (result.lens !== state.selected_lenses[index]) throw new Error("Compact lens results are not in selected-lens order");
-		if (!equal(result.evidence, [...result.evidence].toSorted())) throw new Error("Compact lens evidence is not canonical");
-		if (!equal(result.findings, [...result.findings].toSorted((left, right) => left.id.localeCompare(right.id)))) throw new Error("Compact lens findings are not canonical");
-		if (result.findings.some((finding) => finding.lens !== result.lens)) throw new Error("Compact finding lens does not match its selected result");
-	}
-	if (!equal(state.findings, state.lens_results.flatMap(({ findings }) => findings))) {
-		throw new Error("Compact findings do not match canonical lens result concatenation");
-	}
-	if (new Set(state.findings.map(({ id }) => id)).size !== state.findings.length) throw new Error("Compact finding IDs are duplicated");
-	if (!equal(canonicalStrings(state.correction_ids, "Compact correction IDs"), state.correction_ids)) {
-		throw new Error("Compact correction IDs are not canonical");
-	}
-	if (state.state !== COMPACT_REVIEW_STATE.REVIEWING) {
-		const findingIds = state.findings.map(({ id }) => id).toSorted();
-		if (!equal(Object.keys(state.outcomes).toSorted(), findingIds)) throw new Error("Compact finding outcomes are missing or contain unknown IDs");
-		const expectedCorrectionIds: string[] = [];
-		let unresolved = false;
-		for (const finding of state.findings) {
-			const outcome = state.outcomes[finding.id];
-			if (!SEVERE.has(finding.severity)) {
-				if (outcome !== COMPACT_FINDING_OUTCOME.INFO) throw new Error("Non-severe compact findings must remain informational");
-				continue;
-			}
-			if (finding.causal_disposition === CAUSAL_DISPOSITION.PRE_EXISTING || finding.causal_disposition === CAUSAL_DISPOSITION.BASE_ONLY) {
-				if (outcome !== COMPACT_FINDING_OUTCOME.INFO || !state.follow_ups.some(({ finding_id }) => finding_id === finding.id)) throw new Error("Non-candidate severe finding is not an inert follow-up");
-				continue;
-			}
-			if (finding.causal_disposition === CAUSAL_DISPOSITION.UNKNOWN || finding.evidence_class === COMPACT_EVIDENCE_CLASS.INSUFFICIENT || outcome === COMPACT_FINDING_OUTCOME.INCONCLUSIVE) {
-				if (outcome !== COMPACT_FINDING_OUTCOME.INCONCLUSIVE) throw new Error("Unresolved compact severe finding must be inconclusive");
-				unresolved = true;
-				continue;
-			}
-			if (CANDIDATE_CAUSED.has(finding.causal_disposition) && outcome === COMPACT_FINDING_OUTCOME.CORROBORATED) expectedCorrectionIds.push(finding.id);
-			else if (outcome !== COMPACT_FINDING_OUTCOME.REFUTED) throw new Error("Candidate-caused severe finding has an invalid outcome");
-		}
-		if (!equal(expectedCorrectionIds.toSorted(), state.correction_ids)) throw new Error("Compact correction IDs do not match causal corroborated findings");
-		if (unresolved && state.state !== COMPACT_REVIEW_STATE.ESCALATED) throw new Error("Unresolved severe findings must escalate");
-	} else if (Object.keys(state.outcomes).length > 0) {
-		throw new Error("Reviewing compact state contains finding outcomes");
-	}
-	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");
-		}
-	}
-	if (state.validation && (!state.correction || !equal(state.validation.correction_ids, state.correction_ids) || state.validation.original_criteria.evidence.length === 0 || state.validation.correction_regression.evidence.length === 0)) {
-		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.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) {
-		throw new Error("Post-review compact state requires every selected lens result");
-	}
-	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 || !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 ?? "")) {
-		throw new Error("Approved compact state requires final verification evidence");
-	}
-	if (!Object.values(COMPACT_REVIEW_STATE).includes(state.state)) throw new Error("Compact review state is invalid");
-}
-
-export function createCompactReceipt(
-	state: CompactReviewStateV2,
-	authorityRevision: string,
-): CompactReceiptEnvelopeV2 {
-	assertCompactReviewState(state);
-	if (state.state !== COMPACT_REVIEW_STATE.APPROVED && state.state !== COMPACT_REVIEW_STATE.ESCALATED) {
-		throw new Error("Compact receipt requires terminal authority");
-	}
-	if (!DIGEST.test(authorityRevision)) throw new Error("Compact receipt authority revision is invalid");
-	const body: CompactReceiptBodyV2 = {
-		schema: "gentle-ai.review-receipt-body/v2",
-		lineage_id: state.lineage_id,
-		generation: state.generation,
-		authority_revision: authorityRevision,
-		base_tree: state.initial_snapshot.base_tree,
-		initial_review_tree: state.initial_snapshot.initial_review_tree,
-		final_candidate_tree: state.current_candidate_tree,
-		genesis_paths_hash: domainHashV1("compact-paths", state.genesis_paths),
-		intended_untracked_hash: domainHashV1("compact-untracked", state.intended_untracked),
-		policy_hash: state.policy_hash,
-		risk_tier: state.risk_tier,
-		selected_lenses: [...state.selected_lenses],
-		original_changed_lines: state.original_changed_lines,
-		correction_budget: state.correction_budget,
-		correction_ids: [...state.correction_ids],
-		fix_diff_hash: state.correction?.fix_diff_hash ?? domainHashV1("compact-empty-fix", null),
-		evidence_hash: state.final_evidence_hash ?? domainHashV1("compact-empty-evidence", null),
-		terminal_state: state.state,
-	};
-	return { body, receipt_hash: domainHashV1("compact-receipt", body) };
-}
-
-export function assertCompactReceipt(
-	receipt: CompactReceiptEnvelopeV2,
-): void {
-	const { body } = receipt;
-	if (body.schema !== "gentle-ai.review-receipt-body/v2" || body.generation !== 1 || !LINEAGE_ID.test(body.lineage_id)) throw new Error("Compact receipt identity is invalid");
-	for (const digest of [body.authority_revision, body.genesis_paths_hash, body.intended_untracked_hash, body.policy_hash, body.fix_diff_hash, body.evidence_hash, receipt.receipt_hash]) {
-		if (!DIGEST.test(digest)) throw new Error("Compact receipt contains an invalid digest");
-	}
-	for (const tree of [body.base_tree, body.initial_review_tree, body.final_candidate_tree]) {
-		if (!OBJECT_ID.test(tree)) throw new Error("Compact receipt contains an invalid tree");
-	}
-	assertSelectedLenses(body.risk_tier, body.selected_lenses);
-	if (!equal(canonicalStrings(body.correction_ids, "Compact receipt correction IDs"), body.correction_ids)) throw new Error("Compact receipt correction IDs are not canonical");
-	if (body.correction_budget !== correctionBudget(body.original_changed_lines)) throw new Error("Compact receipt budget is invalid");
-	if (receipt.receipt_hash !== domainHashV1("compact-receipt", body)) throw new Error("Compact receipt hash mismatch");
-}