gentle-pi 1.0.1 → 1.0.2

package/assets/agents/gentle-ai-explore.md

@@ -5,13 +5,17 @@ tools:
   - read
   - grep
   - find
+  - codegraph
 ---
 
 You are the read-only explorer for generic non-SDD work.
 
 Map relevant files, symbols, relationships, and uncertainty within the parent-provided scope.
 
-- Read and search only. Do not edit, write, run commands, or mutate state.
+- For structural questions, use the cwd-scoped `codegraph` tool before broad filesystem searches. Initialize the workspace index with `operation: "init"` when it is absent, then use `query` or `explore`; never ask it to target another path.
+- `codegraph` may create or update only the current workspace `.codegraph/` index. This is the sole permitted mutation; all tracked files, source files, and other project content remain read-only.
+- If CodeGraph reports that it is unavailable or fails, then use `read`, `grep`, and `find` as the fallback. Do not use that fallback before CodeGraph is unavailable or fails.
+- Other than the explicit `.codegraph/` index exception, read and search only. Do not edit, write, run commands, or mutate state.
 - Do not fix findings, delegate to child agents, commit, or push.
 - Do not use SDD phase protocols or review lenses.
 

package/assets/agents/review-readability.md

@@ -44,11 +44,11 @@ Return only this compact-v2 native JSON envelope, with one lens result for this
   "review_result": {
     "lens_results": [
       {
-        "lens": "readability",
+        "lens": "review-readability",
         "findings": [
           {
             "id": "READABILITY-001",
-            "lens": "readability",
+            "lens": "review-readability",
             "location": "path/to/file.ts:1",
             "severity": "CRITICAL",
             "claim": "Concrete user-impact claim.",

package/assets/agents/review-reliability.md

@@ -45,11 +45,11 @@ Return only this compact-v2 native JSON envelope, with one lens result for this
   "review_result": {
     "lens_results": [
       {
-        "lens": "reliability",
+        "lens": "review-reliability",
         "findings": [
           {
             "id": "RELIABILITY-001",
-            "lens": "reliability",
+            "lens": "review-reliability",
             "location": "path/to/file.ts:1",
             "severity": "CRITICAL",
             "claim": "Concrete user-impact claim.",

package/assets/agents/review-resilience.md

@@ -44,11 +44,11 @@ Return only this compact-v2 native JSON envelope, with one lens result for this
   "review_result": {
     "lens_results": [
       {
-        "lens": "resilience",
+        "lens": "review-resilience",
         "findings": [
           {
             "id": "RESILIENCE-001",
-            "lens": "resilience",
+            "lens": "review-resilience",
             "location": "path/to/file.ts:1",
             "severity": "CRITICAL",
             "claim": "Concrete user-impact claim.",

package/assets/agents/review-risk.md

@@ -46,11 +46,11 @@ Return only this compact-v2 native JSON envelope, with one lens result for this
   "review_result": {
     "lens_results": [
       {
-        "lens": "risk",
+        "lens": "review-risk",
         "findings": [
           {
             "id": "RISK-001",
-            "lens": "risk",
+            "lens": "review-risk",
             "location": "path/to/file.ts:1",
             "severity": "CRITICAL",
             "claim": "Concrete user-impact claim.",

package/extensions/codegraph-tools.ts

@@ -0,0 +1,236 @@
+import { execFile, execFileSync } from "node:child_process";
+import { lstatSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const CODEGRAPH_OPERATION = {
+	INIT: "init",
+	QUERY: "query",
+	EXPLORE: "explore",
+} as const;
+
+const CODEGRAPH_STATUS = {
+	UNAVAILABLE: "unavailable",
+	FAILED: "failed",
+} as const;
+
+type CodeGraphOperation =
+	(typeof CODEGRAPH_OPERATION)[keyof typeof CODEGRAPH_OPERATION];
+type CodeGraphStatus =
+	(typeof CODEGRAPH_STATUS)[keyof typeof CODEGRAPH_STATUS];
+
+export interface CodeGraphToolParameters {
+	operation: CodeGraphOperation;
+	query?: string;
+	limit?: number;
+}
+
+export interface CodeGraphCommandResult {
+	stdout: string;
+	stderr: string;
+}
+
+export interface CodeGraphRunOptions {
+	cwd: string;
+	signal?: AbortSignal;
+	maxBuffer: number;
+}
+
+interface CodeGraphFallbackDetails {
+	status: CodeGraphStatus;
+	operation: CodeGraphOperation;
+	cwd: string;
+	fallback: string;
+}
+
+export type CodeGraphRunner = (
+	args: readonly string[],
+	options: CodeGraphRunOptions,
+) => Promise<CodeGraphCommandResult>;
+
+const CODEGRAPH_TOOL_PARAMETERS = {
+	type: "object",
+	additionalProperties: false,
+	required: ["operation"],
+	properties: {
+		operation: { type: "string", enum: Object.values(CODEGRAPH_OPERATION) },
+		query: { type: "string", minLength: 1, maxLength: 2_000 },
+		limit: { type: "integer", minimum: 1, maximum: 20 },
+	},
+} as const;
+
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 20;
+const MAX_OUTPUT_CHARS = 100_000;
+const PROCESS_MAX_BUFFER = MAX_OUTPUT_CHARS * 2;
+const FALLBACK_INSTRUCTIONS = "Use read, grep, and find for this exploration.";
+const execFileAsync = promisify(execFile);
+
+function resolveWorkspaceCwd(cwd: string): string {
+	const resolved = realpathSync(cwd);
+	if (!lstatSync(resolved).isDirectory()) {
+		throw new Error("CodeGraph can run only in the current workspace directory.");
+	}
+	if (resolved === realpathSync(homedir()) || resolved === realpathSync(tmpdir())) {
+		throw new Error("CodeGraph requires a real Git project root equal to the current workspace, not HOME or a temporary directory.");
+	}
+	try {
+		const root = realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			cwd: resolved,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim());
+		if (root !== resolved) {
+			throw new Error("CodeGraph requires a real Git project root equal to the current workspace.");
+		}
+		return resolved;
+	} catch (error) {
+		if (error instanceof Error && /real Git project root/.test(error.message)) throw error;
+		throw new Error("CodeGraph requires a real Git project root equal to the current workspace.");
+	}
+}
+
+function assertSafeIndexDirectory(cwd: string): void {
+	try {
+		const index = lstatSync(join(cwd, ".codegraph"));
+		if (index.isSymbolicLink() || !index.isDirectory()) {
+			throw new Error("CodeGraph .codegraph must be a real directory when it already exists.");
+		}
+	} catch (error: unknown) {
+		if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return;
+		throw error;
+	}
+}
+
+function resolveLimit(limit: number | undefined): number {
+	if (limit === undefined) return DEFAULT_LIMIT;
+	if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+		throw new Error(`CodeGraph limit must be an integer between 1 and ${MAX_LIMIT}.`);
+	}
+	return limit;
+}
+
+function requireQuery(query: string | undefined): string {
+	if (typeof query !== "string" || query.trim().length === 0) {
+		throw new Error("CodeGraph query is required for query and explore operations.");
+	}
+	if (query.length > 2_000) {
+		throw new Error("CodeGraph query must not exceed 2000 characters.");
+	}
+	return query;
+}
+
+function commandArguments(parameters: CodeGraphToolParameters, cwd: string): string[] {
+	switch (parameters.operation) {
+		case CODEGRAPH_OPERATION.INIT:
+			return [CODEGRAPH_OPERATION.INIT, cwd];
+		case CODEGRAPH_OPERATION.QUERY: {
+			const query = requireQuery(parameters.query);
+			return [
+				CODEGRAPH_OPERATION.QUERY,
+				"--path",
+				cwd,
+				"--limit",
+				String(resolveLimit(parameters.limit)),
+				"--",
+				query,
+			];
+		}
+		case CODEGRAPH_OPERATION.EXPLORE: {
+			const query = requireQuery(parameters.query);
+			return [
+				CODEGRAPH_OPERATION.EXPLORE,
+				"--path",
+				cwd,
+				"--max-files",
+				String(resolveLimit(parameters.limit)),
+				"--",
+				query,
+			];
+		}
+	}
+}
+
+function truncateOutput(output: string): string {
+	return output.length <= MAX_OUTPUT_CHARS
+		? output
+		: `${output.slice(0, MAX_OUTPUT_CHARS)}\n\n[CodeGraph output truncated]`;
+}
+
+function codeGraphFailureDetails(
+	error: unknown,
+	operation: CodeGraphOperation,
+	cwd: string,
+): CodeGraphFallbackDetails {
+	const status =
+		typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT"
+			? CODEGRAPH_STATUS.UNAVAILABLE
+			: CODEGRAPH_STATUS.FAILED;
+	return { status, operation, cwd, fallback: FALLBACK_INSTRUCTIONS };
+}
+
+function codeGraphFailureMessage(status: CodeGraphStatus): string {
+	return status === CODEGRAPH_STATUS.UNAVAILABLE
+		? `CodeGraph is unavailable because the codegraph binary was not found. ${FALLBACK_INSTRUCTIONS}`
+		: `CodeGraph failed to run. ${FALLBACK_INSTRUCTIONS}`;
+}
+
+const runCodeGraphCommand: CodeGraphRunner = async (args, options) => {
+	const result = await execFileAsync("codegraph", [...args], {
+		cwd: options.cwd,
+		signal: options.signal,
+		maxBuffer: options.maxBuffer,
+	});
+	return { stdout: result.stdout, stderr: result.stderr };
+};
+
+export function createCodeGraphTool(runner: CodeGraphRunner = runCodeGraphCommand) {
+	return {
+		name: "codegraph",
+		label: "CodeGraph",
+		description:
+			"Initialize, search, or explore the CodeGraph index for the current Pi workspace only. This tool never accepts a project path or shell command.",
+		promptSnippet: "Initialize and query CodeGraph for the current workspace without shell access",
+		promptGuidelines: [
+			"Use operation init before querying when the current workspace has no .codegraph index.",
+			"Use query for symbol search and explore for source plus call paths. Do not use this tool to run arbitrary commands or target another directory.",
+		],
+		parameters: CODEGRAPH_TOOL_PARAMETERS,
+		executionMode: "sequential" as const,
+		async execute(
+			_toolCallId: string,
+			parameters: CodeGraphToolParameters,
+			signal: AbortSignal | undefined,
+			_onUpdate: undefined,
+			ctx: ExtensionContext,
+		) {
+			const cwd = resolveWorkspaceCwd(ctx.cwd);
+			assertSafeIndexDirectory(cwd);
+			const args = commandArguments(parameters, cwd);
+			try {
+				const result = await runner(args, { cwd, signal, maxBuffer: PROCESS_MAX_BUFFER });
+				const output = truncateOutput([result.stdout, result.stderr].filter(Boolean).join("\n"));
+				return {
+					content: [{ type: "text" as const, text: output || "CodeGraph completed without output." }],
+					details: { operation: parameters.operation, cwd, args },
+				};
+			} catch (error: unknown) {
+				const details = codeGraphFailureDetails(error, parameters.operation, cwd);
+				return {
+					content: [{ type: "text" as const, text: codeGraphFailureMessage(details.status) }],
+					details,
+				};
+			}
+		},
+	};
+}
+
+export function registerCodeGraphTool(pi: ExtensionAPI): void {
+	pi.registerTool(createCodeGraphTool());
+}
+
+export default function codeGraphTools(pi: ExtensionAPI): void {
+	registerCodeGraphTool(pi);
+}

package/extensions/gentle-ai.ts

@@ -51,16 +51,25 @@ import type { TriggerEvent } from "../lib/review-triggers.ts";
 import { ReviewBundleExporter, ReviewBundleImporter } from "../lib/review-bundle.ts";
 import { domainHashV1 } from "../lib/review-canonical.ts";
 import { inspectLegacyReviewAuthorityV1, type LegacyInspectionV1 } from "../lib/review-legacy-detector.ts";
-import { destructiveResetReviewAuthorityV1 } from "../lib/review-reset.ts";
+import { compactResetRequestV1, destructiveResetReviewAuthorityV1 } from "../lib/review-reset.ts";
 import { ReviewMutationLockV1 } from "../lib/review-lock.ts";
 import {
+	COMPACT_START_BLOCK_ACTION,
 	GRAPH_V1_ORDINARY_READ_ONLY,
+	CompactReviewStartBlockedError,
 	discoverCompactReview,
 	finalizeCompactReview,
 	startCompactReview,
 } from "../lib/review-facade.ts";
 import { validateCompactReviewGate } from "../lib/review-compact-gate.ts";
-import { compactV2LineageExists, graphV1LineageExists } from "../lib/review-compact-store.ts";
+import {
+	COMPACT_AUTHORITY_OUTCOME,
+	compactV2LineageExists,
+	graphV1LineageExists,
+	hasGraphV1Authority,
+	inspectCompactReviewAuthorityV2,
+	type CompactAuthorityInspectionV2,
+} from "../lib/review-compact-store.ts";
 import {
 	inheritedUnsafeGitEnvironmentKeys,
 	resolveRepositoryAuthorityV1,
@@ -2327,11 +2336,38 @@ function durableResetRecoveryRequest(cwd: string): LegacyInspectionV1["reset_req
 	};
 }
 
-function inspectReviewAuthorityForController(cwd: string): LegacyInspectionV1 {
-	const inspection = inspectLegacyReviewAuthorityV1(cwd);
-	return inspection.outcome === "reset-in-progress"
-		? { ...inspection, reset_request: durableResetRecoveryRequest(cwd) }
-		: inspection;
+interface ControllerReviewAuthorityInspection extends LegacyInspectionV1 {
+	compact_authority?: CompactAuthorityInspectionV2;
+}
+
+function inspectReviewAuthorityForController(cwd: string): ControllerReviewAuthorityInspection {
+	const legacy = inspectLegacyReviewAuthorityV1(cwd);
+	const compact = inspectCompactReviewAuthorityV2(cwd);
+	const inspection = legacy.outcome === "reset-in-progress"
+		? { ...legacy, reset_request: durableResetRecoveryRequest(cwd) }
+		: compact.outcome === COMPACT_AUTHORITY_OUTCOME.INVALID
+			? { ...legacy, reset_request: compactResetRequestV1(cwd, legacy) }
+			: legacy;
+	return compact.outcome === COMPACT_AUTHORITY_OUTCOME.NONE
+		? inspection
+		: { ...inspection, compact_authority: compact };
+}
+
+function compactAuthorityAction(inspection: ControllerReviewAuthorityInspection): string | undefined {
+	switch (inspection.compact_authority?.outcome) {
+		case COMPACT_AUTHORITY_OUTCOME.APPROVED:
+			return COMPACT_START_BLOCK_ACTION.APPROVED;
+		case COMPACT_AUTHORITY_OUTCOME.ESCALATED:
+			return COMPACT_START_BLOCK_ACTION.ESCALATED;
+		case COMPACT_AUTHORITY_OUTCOME.ACTIVE:
+			return "finalize-existing-ordinary-review";
+		case COMPACT_AUTHORITY_OUTCOME.INVALID:
+			return inspection.outcome === "clean"
+				? "request-explicit-reset-authorization"
+				: "stop-and-report-ambiguous-authority";
+		default:
+			return undefined;
+	}
 }
 
 async function authorizeDestructiveReviewOperation(
@@ -3085,9 +3121,20 @@ function executeReviewControllerOperation(
 			operation: parameters.operation,
 			inspection,
 			lock: lock.inspect(),
-			...(inspection.outcome === "clean"
-				? { status: "ready", next_action: "start-ordinary-review" }
-				: inspection.outcome === "blocked-ambiguous"
+			...(inspection.outcome === "clean" && inspection.compact_authority !== undefined
+				? {
+					status: inspection.compact_authority.outcome === COMPACT_AUTHORITY_OUTCOME.ESCALATED
+						? "escalated"
+						: inspection.compact_authority.outcome === COMPACT_AUTHORITY_OUTCOME.APPROVED
+							? "terminal"
+							: inspection.compact_authority.outcome === COMPACT_AUTHORITY_OUTCOME.ACTIVE
+								? "in-progress"
+								: "blocked",
+					next_action: compactAuthorityAction(inspection),
+				}
+				: inspection.outcome === "clean"
+					? { status: "ready", next_action: "start-ordinary-review" }
+					: inspection.outcome === "blocked-ambiguous"
 					? { status: "blocked", next_action: "stop-and-report-ambiguous-authority" }
 					: {
 						status: "blocked",
@@ -3121,6 +3168,20 @@ function executeReviewControllerOperation(
 		return { operation: parameters.operation, result, inspection, next_action: inspection.outcome === "clean" ? "start-fresh-ordinary-review-after-verified-clean" : "inspect-reset-recovery" };
 	}
 	if (parameters.operation === REVIEW_CONTROLLER_OPERATION.REPAIR) {
+		const inspection = inspectReviewAuthorityForController(defaultCwd);
+		if (
+			inspection.outcome === "clean" &&
+			inspection.compact_authority !== undefined &&
+			!hasGraphV1Authority(defaultCwd)
+		) {
+			return {
+				operation: parameters.operation,
+				repaired: false,
+				compact_authority: "immutable-untouched",
+				inspection,
+				next_action: compactAuthorityAction(inspection),
+			};
+		}
 		const store = ReviewTransactionStore.forRepository(defaultCwd);
 		store.repairCurrentAuthority();
 		return { operation: parameters.operation, repaired: true };
@@ -3154,14 +3215,29 @@ function executeReviewControllerOperation(
 					? { kind: REVIEW_PROJECTION.COMPLETE } as const
 					: undefined;
 			if (!projection) throw new Error("New compact ordinary START requires the complete projection");
-			const result = startCompactReview({
-				cwd: defaultCwd,
-				...(parameters.lineageId === undefined ? {} : { lineageId: parameters.lineageId }),
-				policyHash: rawStart.policyHash,
-				projection,
-			});
-			const state = discoverCompactReview(defaultCwd, result.lineage_id).record.state;
-			return { operation: parameters.operation, result, state };
+			try {
+				const result = startCompactReview({
+					cwd: defaultCwd,
+					...(parameters.lineageId === undefined ? {} : { lineageId: parameters.lineageId }),
+					policyHash: rawStart.policyHash,
+					projection,
+				});
+				const state = discoverCompactReview(defaultCwd, result.lineage_id).record.state;
+				return { operation: parameters.operation, result, state };
+			} catch (error) {
+				if (error instanceof CompactReviewStartBlockedError) {
+					return {
+						operation: parameters.operation,
+						status: "blocked",
+						lineage_created: false,
+						lifecycle: `compact-${error.state}`,
+						lineage_id: error.lineageId,
+						next_action: error.action,
+						inspection: inspectReviewAuthorityForController(defaultCwd),
+					};
+				}
+				throw error;
+			}
 		}
 		const idempotencyKey = requiredControllerString(parameters, "idempotencyKey");
 		if (typeof parameters.lineageId !== "string" || parameters.lineageId.trim().length === 0) {
@@ -3228,6 +3304,7 @@ function executeReviewControllerOperation(
 				...(parameters.lineageId === undefined ? {} : { lineageId: parameters.lineageId }),
 				...(raw.review_result === undefined ? {} : { review_result: raw.review_result as never }),
 				...(raw.correction_line_forecast === undefined ? {} : { correction_line_forecast: Number(raw.correction_line_forecast) }),
+				...(raw.validation_proof === undefined ? {} : { validation_proof: raw.validation_proof as never }),
 				...(raw.validation === undefined ? {} : { validation: raw.validation as never }),
 				...(raw.final_evidence === undefined ? {} : { final_evidence: raw.final_evidence }),
 				...(raw.final_verification_passed === undefined ? {} : { final_verification_passed: raw.final_verification_passed }),

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