@gajae-code/coding-agent 0.11.1 → 0.11.3

package/src/extensibility/shared-events.ts

@@ -179,6 +179,8 @@ export interface AgentStartEvent {
 export interface AgentEndEvent {
 	type: "agent_end";
 	messages: AgentMessage[];
+	/** Indicates whether the loop ended normally, suspended, cancelled, or entered maintenance. */
+	stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
 }
 
 /** Fired at the start of each turn */

package/src/gjc-runtime/deep-interview-recorder.ts

@@ -8,13 +8,18 @@ import {
 } from "./deep-interview-ambiguity";
 import {
 	answerHash,
+	assertDeepInterviewIntentManifest,
+	createDeepInterviewIntentManifest,
 	type DeepInterviewEstablishedFact,
+	type DeepInterviewIntentItem,
+	type DeepInterviewIntentSubstitution,
 	type DeepInterviewRoundRecord,
 	type DeepInterviewStateEnvelope,
 	type DeepInterviewTriggerMetadata,
 	deriveRoundKey,
 	normalizeDeepInterviewEnvelope,
 	questionHash,
+	reviewDeepInterviewIntent,
 } from "./deep-interview-state";
 import { writeSessionActivityMarker } from "./session-resolution";
 import { readExistingStateForMutation, writeGuardedWorkflowEnvelopeAtomic } from "./state-writer";
@@ -48,6 +53,12 @@ export interface DeepInterviewAnswerInput {
 	ambiguity?: number;
 	selectedOptions?: string[];
 	customInput?: string;
+	intent_contract?: { items: DeepInterviewIntentItem[]; confirmation_options: string[] };
+	intent_review?: {
+		observed_items: DeepInterviewIntentItem[];
+		supporting_substitutions: DeepInterviewIntentSubstitution[];
+		approval_options: string[];
+	};
 }
 
 export interface DeepInterviewScoringInput {
@@ -417,15 +428,64 @@ export async function appendOrMergeDeepInterviewRound(
 ): Promise<{ action: AppendOrMergeAction; record: DeepInterviewRoundRecord; disputedFactIds?: string[] }> {
 	const envelope = await readEnvelope(statePath);
 	const interviewId = input.interviewId ?? interviewIdOf(envelope);
-	const shell = buildAnswerShell({ ...input, interviewId });
+	const shell = buildAnswerShell({
+		...input,
+		interviewId,
+		customInput: input.intent_contract || input.intent_review ? undefined : input.customInput,
+	});
 	const rounds = readRounds(envelope);
 	const priorRecord = rounds.find(r => r.round_key === shell.round_key);
 	const result = appendOrMergeRound(rounds, shell);
-	if (result.action === "noop") {
+	const inner = envelope.state as Record<string, unknown>;
+	let intentStateChanged = false;
+	if (input.intent_contract) {
+		if (input.round !== 0 || input.component !== "review-topology" || input.dimension !== "topology")
+			throw new Error("intent contract requires Round 0 topology metadata");
+		const confirmed =
+			input.selectedOptions?.length === 1 &&
+			input.intent_contract.confirmation_options.includes(input.selectedOptions[0]);
+		if (confirmed) {
+			const contract = createDeepInterviewIntentManifest(input.intent_contract.items, {
+				round: 0,
+				answer_hash: shell.answer_hash,
+			});
+			const existingContract = inner.intent_contract;
+			if (existingContract !== undefined) {
+				assertDeepInterviewIntentManifest(existingContract);
+				if (
+					existingContract.digest !== contract.digest ||
+					existingContract.confirmation_answer_hash !== contract.confirmation_answer_hash
+				)
+					throw new Error("locked intent contract cannot be replaced");
+			} else {
+				inner.intent_contract = contract;
+				intentStateChanged = true;
+			}
+		}
+	}
+	if (input.intent_review) {
+		if (input.round <= 0) throw new Error("intent review requires a post-Round-0 answer");
+		const locked = inner.intent_contract;
+		assertDeepInterviewIntentManifest(locked);
+		const approved =
+			input.selectedOptions?.length === 1 && input.intent_review.approval_options.includes(input.selectedOptions[0]);
+		inner.intent_review = reviewDeepInterviewIntent(locked, input.intent_review.observed_items, {
+			status: approved ? "approved" : "pending",
+			supporting_substitutions: input.intent_review.supporting_substitutions,
+			...(approved
+				? {
+						approval_round: input.round,
+						answer_hash: shell.answer_hash,
+						user_answer_evidence: `answer_hash:${shell.answer_hash}`,
+					}
+				: {}),
+		});
+		intentStateChanged = true;
+	}
+	if (result.action === "noop" && !intentStateChanged) {
 		await repairRecorderHudFromPersisted(cwd, statePath, options.sessionId);
 		return { action: result.action, record: result.record };
 	}
-	const inner = envelope.state as Record<string, unknown>;
 	inner.rounds = result.rounds;
 	let disputedFactIds: string[] | undefined;
 	if (result.action === "replaced" && priorRecord?.lifecycle === "scored") {

package/src/gjc-runtime/deep-interview-runtime.ts

@@ -6,12 +6,21 @@ import { YAML } from "bun";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { deriveDeepInterviewHud } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
-import { normalizeDeepInterviewEnvelope } from "./deep-interview-state";
+import {
+	assertDeepInterviewIntentReview,
+	type DeepInterviewIntentCategory,
+	type DeepInterviewIntentItem,
+	type DeepInterviewIntentManifest,
+	type DeepInterviewIntentReview,
+	normalizeDeepInterviewEnvelope,
+	reviewDeepInterviewIntent,
+} from "./deep-interview-state";
 import { runNativeRalplanCommand } from "./ralplan-runtime";
 import { modeStatePath, sessionSpecsDir } from "./session-layout";
 import { resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { runNativeStateCommand } from "./state-runtime";
 import { appendJsonl, readExistingStateForMutation, writeArtifact, writeWorkflowEnvelopeAtomic } from "./state-writer";
+import { assertSafePathComponent, CommandError, flagValue, hasFlag } from "./workflow-cli-common";
 
 export * from "./deep-interview-recorder";
 
@@ -31,8 +40,6 @@ export interface DeepInterviewCommandResult {
 	stderr?: string;
 }
 
-const PATH_COMPONENT_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
-
 const DEFAULT_AMBIGUITY_THRESHOLD = 0.05;
 
 const RESOLUTION_THRESHOLDS = {
@@ -105,12 +112,9 @@ interface DeepInterviewTraceSummary {
 
 type DeepInterviewResolution = keyof typeof RESOLUTION_THRESHOLDS;
 
-class DeepInterviewCommandError extends Error {
-	constructor(
-		public readonly exitStatus: number,
-		message: string,
-	) {
-		super(message);
+class DeepInterviewCommandError extends CommandError {
+	constructor(exitStatus: number, message: string) {
+		super(exitStatus, message);
 		this.name = "DeepInterviewCommandError";
 	}
 }
@@ -125,22 +129,6 @@ const VALUE_FLAGS = new Set([
 	"--handoff",
 ]);
 
-function flagValue(args: readonly string[], flag: string): string | undefined {
-	const index = args.indexOf(flag);
-	if (index < 0) return undefined;
-	return args[index + 1];
-}
-
-function hasFlag(args: readonly string[], flag: string): boolean {
-	return args.includes(flag);
-}
-
-function assertSafePathComponent(value: string, label: string): void {
-	if (!PATH_COMPONENT_RE.test(value) || value.includes("..")) {
-		throw new DeepInterviewCommandError(2, `invalid path component for --${label}: ${value}`);
-	}
-}
-
 function defaultSpecSlug(now: Date = new Date()): string {
 	const yyyy = now.getUTCFullYear().toString().padStart(4, "0");
 	const mm = (now.getUTCMonth() + 1).toString().padStart(2, "0");
@@ -585,6 +573,61 @@ async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): P
 	};
 }
 
+function intentIdsInSpec(content: string): string[] {
+	const ids = content.match(/(?:artifact|surface|integration|constraint):[a-z0-9][a-z0-9._/-]{0,127}/g) ?? [];
+	return [...new Set(ids)].sort();
+}
+
+function resolveLockedIntentReview(existing: unknown, content: string): DeepInterviewIntentReview | undefined {
+	const envelope = normalizeDeepInterviewEnvelope(existing);
+	const state = envelope.state;
+	if (!state) return undefined;
+	if (state.intent_contract === undefined) {
+		if (state.intent_contract_required === true)
+			throw new DeepInterviewCommandError(
+				2,
+				"deep-interview locked intent blocks spec persistence: missing Round 0 intent contract",
+			);
+		return undefined;
+	}
+	const locked = state.intent_contract as DeepInterviewIntentManifest;
+	const observedIds = intentIdsInSpec(content);
+	const rounds = Array.isArray(state.rounds)
+		? state.rounds
+				.filter(
+					(round): round is Record<string, unknown> =>
+						Boolean(round) && typeof round === "object" && !Array.isArray(round),
+				)
+				.map(round => ({ round: round.round, answer_hash: round.answer_hash }))
+		: [];
+	try {
+		if (state.intent_review === undefined) {
+			if (locked.items.some(item => !observedIds.includes(item.id))) throw new Error("missing intent review");
+			const lockedById = new Map(locked.items.map(item => [item.id, item]));
+			const observedItems: DeepInterviewIntentItem[] = observedIds.map(id => {
+				const existingItem = lockedById.get(id);
+				if (existingItem) return existingItem;
+				return {
+					id,
+					category: id.slice(0, id.indexOf(":")) as DeepInterviewIntentCategory,
+					statement: id,
+				};
+			});
+			return reviewDeepInterviewIntent(locked, observedItems, {
+				status: "not_required",
+				supporting_substitutions: [],
+			});
+		}
+		assertDeepInterviewIntentReview(state.intent_review, locked, observedIds, rounds);
+		return state.intent_review as DeepInterviewIntentReview;
+	} catch (error) {
+		throw new DeepInterviewCommandError(
+			2,
+			`deep-interview locked intent blocks spec persistence: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
 export async function persistDeepInterviewSpec(
 	cwd: string,
 	resolved: ResolvedDeepInterviewSpecWriteArgs,
@@ -599,8 +642,9 @@ export async function persistDeepInterviewSpec(
 	}
 	const existing = existingRead.kind === "valid" ? existingRead.value : {};
 
-	const specPath = path.join(sessionSpecsDir(cwd, resolved.sessionId), `deep-interview-${resolved.slug}.md`);
 	const content = resolved.spec.endsWith("\n") ? resolved.spec : `${resolved.spec}\n`;
+	const intentReview = resolveLockedIntentReview(existing, content);
+	const specPath = path.join(sessionSpecsDir(cwd, resolved.sessionId), `deep-interview-${resolved.slug}.md`);
 	await writeArtifact(specPath, content, {
 		cwd,
 		audit: {
@@ -642,6 +686,10 @@ export async function persistDeepInterviewSpec(
 		spec_persisted_at: createdAt,
 		updated_at: createdAt,
 	}) as Record<string, unknown>;
+	if (intentReview) {
+		const state = payload.state as Record<string, unknown>;
+		state.intent_review = intentReview;
+	}
 	if (resolved.sessionId) payload.session_id = resolved.sessionId;
 	await writeWorkflowEnvelopeAtomic(statePath, payload, {
 		cwd,
@@ -694,6 +742,7 @@ async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepIntervi
 		threshold_source: resolved.thresholdSource,
 		state: {
 			initial_idea: resolved.idea,
+			intent_contract_required: true,
 			rounds: [],
 			established_facts: [],
 			current_ambiguity: 1.0,
@@ -867,7 +916,7 @@ export async function runNativeDeepInterviewCommand(
 				].join("\n");
 		return { status: 0, stdout };
 	} catch (error) {
-		if (error instanceof DeepInterviewCommandError) return { status: error.exitStatus, stderr: `${error.message}\n` };
+		if (error instanceof CommandError) return { status: error.exitStatus, stderr: `${error.message}\n` };
 		return { status: 1, stderr: `${error instanceof Error ? error.message : String(error)}\n` };
 	}
 }

package/src/gjc-runtime/deep-interview-state.ts

@@ -102,7 +102,9 @@ export function questionHash(questionText: string): string {
 }
 
 export function answerHash(selectedOptions: string[] | undefined, customInput: string | undefined): string {
-	return hashContent(JSON.stringify({ selected: selectedOptions ?? [], custom: customInput ?? null }));
+	return createHash("sha256")
+		.update(JSON.stringify({ selected: selectedOptions ?? [], custom: customInput ?? null }))
+		.digest("hex");
 }
 
 /**
@@ -335,9 +337,30 @@ export function mergeDeepInterviewEnvelope(
 	const incomingHasEstablishedFacts =
 		Object.hasOwn(incomingNestedState, "established_facts") || Object.hasOwn(incomingEnvelope, "established_facts");
 	const normalizedIncoming = normalizeDeepInterviewEnvelope(incoming);
-	if (options.replace) return normalizedIncoming;
-
 	const normalizedExisting = normalizeDeepInterviewEnvelope(existing);
+	const existingState = isPlainObject(normalizedExisting.state) ? normalizedExisting.state : {};
+	const incomingState = isPlainObject(normalizedIncoming.state) ? { ...normalizedIncoming.state } : {};
+	if (existingState.intent_contract !== undefined) {
+		assertDeepInterviewIntentManifest(existingState.intent_contract);
+		if (Object.hasOwn(incomingState, "intent_contract")) {
+			if (incomingState.intent_contract === null) throw new Error("locked intent contract cannot be deleted");
+			assertDeepInterviewIntentManifest(incomingState.intent_contract);
+			if (
+				incomingState.intent_contract.digest !== existingState.intent_contract.digest ||
+				incomingState.intent_contract.confirmation_answer_hash !==
+					existingState.intent_contract.confirmation_answer_hash
+			)
+				throw new Error("locked intent contract cannot be replaced");
+		} else {
+			incomingState.intent_contract = existingState.intent_contract;
+		}
+	}
+	if (existingState.intent_contract_required === true) incomingState.intent_contract_required = true;
+	if (options.replace) {
+		normalizedIncoming.state = incomingState;
+		return normalizedIncoming;
+	}
+
 	const merged: Record<string, unknown> = {};
 	for (const [key, value] of Object.entries(normalizedExisting)) {
 		if (key !== "state") merged[key] = value;
@@ -348,8 +371,6 @@ export function mergeDeepInterviewEnvelope(
 		else merged[key] = value;
 	}
 
-	const existingState = isPlainObject(normalizedExisting.state) ? normalizedExisting.state : {};
-	const incomingState = isPlainObject(normalizedIncoming.state) ? normalizedIncoming.state : {};
 	const mergedState: Record<string, unknown> = { ...existingState };
 	for (const [key, value] of Object.entries(incomingState)) {
 		if (key === "rounds") continue;
@@ -364,3 +385,294 @@ export function mergeDeepInterviewEnvelope(
 	merged.state = mergedState;
 	return merged as DeepInterviewStateEnvelope;
 }
+
+export const DEEP_INTERVIEW_INTENT_CATEGORIES = ["artifact", "surface", "integration", "constraint"] as const;
+export type DeepInterviewIntentCategory = (typeof DEEP_INTERVIEW_INTENT_CATEGORIES)[number];
+
+const INTENT_ID_RE = /^(artifact|surface|integration|constraint):[a-z0-9][a-z0-9._/-]{0,127}$/;
+const ANSWER_HASH_RE = /^[a-f0-9]{64}$/;
+const INTENT_RATIONALE_REF_RE = /^sha256:[a-f0-9]{64}$/;
+const MAX_INTENT_ITEMS = 64;
+const MAX_INTENT_STATEMENT_LENGTH = 1_000;
+const MAX_INTENT_RATIONALE_LENGTH = 500;
+const MAX_INTENT_EVIDENCE_LENGTH = 80;
+
+export interface DeepInterviewIntentItem {
+	id: string;
+	category: DeepInterviewIntentCategory;
+	statement: string;
+}
+
+export interface DeepInterviewIntentManifest {
+	version: 1;
+	items: DeepInterviewIntentItem[];
+	digest: string;
+	confirmation_round: 0;
+	confirmation_answer_hash: string;
+	confirmation_evidence: string;
+}
+
+export interface DeepInterviewIntentSubstitution {
+	removed_id: string;
+	replacement_ids: string[];
+	rationale: string;
+}
+
+export interface DeepInterviewIntentReview {
+	version: 1;
+	status: "not_required" | "pending" | "approved";
+	locked_digest: string;
+	observed_digest: string;
+	removed_locked_ids: string[];
+	supporting_substitutions: DeepInterviewIntentSubstitution[];
+	approval_round?: number;
+	answer_hash?: string;
+	user_answer_evidence?: string;
+}
+
+export function isCanonicalDeepInterviewAnswerHash(value: unknown): value is string {
+	return typeof value === "string" && ANSWER_HASH_RE.test(value);
+}
+
+function isEvidenceReference(value: unknown, answerHashValue: string): value is string {
+	return (
+		typeof value === "string" &&
+		value.length <= MAX_INTENT_EVIDENCE_LENGTH &&
+		value === `answer_hash:${answerHashValue}`
+	);
+}
+
+function assertIntentItem(value: unknown): asserts value is DeepInterviewIntentItem {
+	if (!isPlainObject(value) || Object.keys(value).length !== 3) throw new Error("invalid intent item");
+	const { id, category, statement } = value;
+	if (typeof id !== "string" || !INTENT_ID_RE.test(id)) throw new Error("invalid intent id");
+	if (
+		!DEEP_INTERVIEW_INTENT_CATEGORIES.includes(category as DeepInterviewIntentCategory) ||
+		!id.startsWith(`${category}:`)
+	)
+		throw new Error("invalid intent category");
+	if (typeof statement !== "string" || !statement.trim() || statement.length > MAX_INTENT_STATEMENT_LENGTH)
+		throw new Error(`intent item ${id} requires a bounded statement`);
+}
+
+function canonicalIntentItems(items: readonly DeepInterviewIntentItem[]): DeepInterviewIntentItem[] {
+	return [...items]
+		.map(item => ({ id: item.id.trim(), category: item.category, statement: item.statement.trim() }))
+		.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function deepInterviewIntentManifestDigest(items: readonly DeepInterviewIntentItem[]): string {
+	return createHash("sha256")
+		.update(JSON.stringify(canonicalIntentItems(items)))
+		.digest("hex");
+}
+
+export function deepInterviewObservedIntentDigest(ids: readonly string[]): string {
+	return createHash("sha256")
+		.update(JSON.stringify([...new Set(ids)].sort()))
+		.digest("hex");
+}
+
+export function createDeepInterviewIntentManifest(
+	items: readonly DeepInterviewIntentItem[],
+	confirmation: { round: 0; answer_hash: string },
+): DeepInterviewIntentManifest {
+	if (!Array.isArray(items) || items.length === 0 || items.length > MAX_INTENT_ITEMS)
+		throw new Error("intent manifest requires bounded items");
+	if (confirmation.round !== 0 || !isCanonicalDeepInterviewAnswerHash(confirmation.answer_hash))
+		throw new Error("intent confirmation requires Round 0 canonical answer hash");
+	const canonical = canonicalIntentItems(items);
+	const ids = new Set<string>();
+	for (const item of canonical) {
+		assertIntentItem(item);
+		if (ids.has(item.id)) throw new Error(`duplicate intent id: ${item.id}`);
+		ids.add(item.id);
+	}
+	return {
+		version: 1,
+		items: canonical,
+		digest: deepInterviewIntentManifestDigest(canonical),
+		confirmation_round: 0,
+		confirmation_answer_hash: confirmation.answer_hash,
+		confirmation_evidence: `answer_hash:${confirmation.answer_hash}`,
+	};
+}
+
+export function assertDeepInterviewIntentManifest(value: unknown): asserts value is DeepInterviewIntentManifest {
+	if (!isPlainObject(value) || Object.keys(value).length !== 6 || value.version !== 1 || !Array.isArray(value.items))
+		throw new Error("invalid intent contract");
+	const manifest = createDeepInterviewIntentManifest(value.items as DeepInterviewIntentItem[], {
+		round: value.confirmation_round as 0,
+		answer_hash: value.confirmation_answer_hash as string,
+	});
+	if (
+		value.digest !== manifest.digest ||
+		value.confirmation_round !== 0 ||
+		!isEvidenceReference(value.confirmation_evidence, manifest.confirmation_answer_hash)
+	)
+		throw new Error("intent contract integrity mismatch");
+}
+
+export function reviewDeepInterviewIntent(
+	locked: DeepInterviewIntentManifest,
+	observedItems: readonly DeepInterviewIntentItem[],
+	input: Omit<DeepInterviewIntentReview, "version" | "locked_digest" | "observed_digest" | "removed_locked_ids">,
+): DeepInterviewIntentReview {
+	assertDeepInterviewIntentManifest(locked);
+	const observed = createDeepInterviewIntentManifest(observedItems, {
+		round: 0,
+		answer_hash: locked.confirmation_answer_hash,
+	});
+	const observedIds = new Set(observed.items.map(item => item.id));
+	const removed = locked.items
+		.map(item => item.id)
+		.filter(id => !observedIds.has(id))
+		.sort();
+	const substitutions = input.supporting_substitutions;
+	if (!Array.isArray(substitutions)) throw new Error("invalid intent substitutions");
+	const substitutionIds = new Set(substitutions.map(item => item.removed_id));
+	if (substitutionIds.size !== substitutions.length) throw new Error("duplicate intent substitution");
+	for (const substitution of substitutions) {
+		if (!isPlainObject(substitution) || !removed.includes(substitution.removed_id))
+			throw new Error("substitution does not bind removed intent");
+		if (
+			!Array.isArray(substitution.replacement_ids) ||
+			substitution.replacement_ids.length === 0 ||
+			substitution.replacement_ids.some(id => typeof id !== "string" || !observedIds.has(id)) ||
+			typeof substitution.rationale !== "string" ||
+			!substitution.rationale.trim() ||
+			substitution.rationale.length > MAX_INTENT_RATIONALE_LENGTH
+		)
+			throw new Error("invalid intent substitution");
+	}
+	const redactedSubstitutions = substitutions.map(substitution => ({
+		removed_id: substitution.removed_id,
+		replacement_ids: [...new Set(substitution.replacement_ids)].sort(),
+		rationale: `sha256:${createHash("sha256").update(substitution.rationale.trim()).digest("hex")}`,
+	}));
+	if (input.status !== "not_required" && input.status !== "pending" && input.status !== "approved")
+		throw new Error("invalid intent review status");
+	if (input.status === "not_required") {
+		if (
+			removed.length > 0 ||
+			substitutions.length > 0 ||
+			input.approval_round !== undefined ||
+			input.answer_hash !== undefined ||
+			input.user_answer_evidence !== undefined
+		)
+			throw new Error("not_required intent review cannot carry reduction evidence");
+	}
+	if (
+		input.status === "pending" &&
+		(input.approval_round !== undefined ||
+			input.answer_hash !== undefined ||
+			input.user_answer_evidence !== undefined)
+	)
+		throw new Error("pending intent review cannot carry approval evidence");
+	if (input.status === "approved") {
+		if (removed.some(id => !substitutionIds.has(id)))
+			throw new Error("approved intent reduction requires every substitution");
+		if (
+			typeof input.approval_round !== "number" ||
+			!Number.isFinite(input.approval_round) ||
+			!Number.isInteger(input.approval_round) ||
+			input.approval_round <= 0 ||
+			!isCanonicalDeepInterviewAnswerHash(input.answer_hash) ||
+			!isEvidenceReference(input.user_answer_evidence, input.answer_hash)
+		)
+			throw new Error("approved intent reduction requires durable redacted answer evidence");
+	}
+	return {
+		...input,
+		supporting_substitutions: redactedSubstitutions,
+		version: 1,
+		locked_digest: locked.digest,
+		observed_digest: deepInterviewObservedIntentDigest([...observedIds]),
+		removed_locked_ids: removed,
+	};
+}
+
+export function assertDeepInterviewIntentReview(
+	value: unknown,
+	locked: DeepInterviewIntentManifest,
+	observedIds: readonly string[],
+	recordedAnswers: readonly { round: unknown; answer_hash: unknown }[],
+): asserts value is DeepInterviewIntentReview {
+	assertDeepInterviewIntentManifest(locked);
+	if (!isPlainObject(value)) throw new Error("missing or invalid intent review");
+	const allowedKeys = new Set([
+		"version",
+		"status",
+		"locked_digest",
+		"observed_digest",
+		"removed_locked_ids",
+		"supporting_substitutions",
+		"approval_round",
+		"answer_hash",
+		"user_answer_evidence",
+	]);
+	if (Object.keys(value).some(key => !allowedKeys.has(key)) || value.version !== 1)
+		throw new Error("invalid intent review");
+	if (
+		value.locked_digest !== locked.digest ||
+		value.observed_digest !== deepInterviewObservedIntentDigest(observedIds)
+	)
+		throw new Error("stale intent review");
+	const observed = new Set(observedIds);
+	const removed = locked.items
+		.map(item => item.id)
+		.filter(id => !observed.has(id))
+		.sort();
+	if (
+		!Array.isArray(value.removed_locked_ids) ||
+		JSON.stringify([...value.removed_locked_ids].sort()) !== JSON.stringify(removed)
+	)
+		throw new Error("intent review removed IDs mismatch");
+	if (!Array.isArray(value.supporting_substitutions)) throw new Error("invalid intent substitutions");
+	const substitutions = value.supporting_substitutions;
+	const substitutionIds = new Set<string>();
+	for (const substitution of substitutions) {
+		if (!isPlainObject(substitution) || Object.keys(substitution).length !== 3)
+			throw new Error("invalid intent substitution");
+		const { removed_id, replacement_ids, rationale } = substitution;
+		if (
+			typeof removed_id !== "string" ||
+			!removed.includes(removed_id) ||
+			substitutionIds.has(removed_id) ||
+			!Array.isArray(replacement_ids) ||
+			replacement_ids.length === 0 ||
+			replacement_ids.some(id => typeof id !== "string" || !INTENT_ID_RE.test(id) || !observed.has(id)) ||
+			typeof rationale !== "string" ||
+			!INTENT_RATIONALE_REF_RE.test(rationale)
+		)
+			throw new Error("invalid intent substitution");
+		substitutionIds.add(removed_id);
+	}
+	if (value.status === "not_required") {
+		if (
+			removed.length > 0 ||
+			substitutions.length > 0 ||
+			value.approval_round !== undefined ||
+			value.answer_hash !== undefined ||
+			value.user_answer_evidence !== undefined
+		)
+			throw new Error("not_required intent review cannot carry reduction evidence");
+		return;
+	}
+	if (value.status !== "approved") {
+		if (value.status === "pending") throw new Error("intent reduction is pending or unapproved");
+		throw new Error("invalid intent review status");
+	}
+	if (removed.some(id => !substitutionIds.has(id)))
+		throw new Error("approved intent reduction requires every substitution");
+	if (
+		typeof value.approval_round !== "number" ||
+		!Number.isFinite(value.approval_round) ||
+		!Number.isInteger(value.approval_round) ||
+		value.approval_round <= 0 ||
+		!isCanonicalDeepInterviewAnswerHash(value.answer_hash) ||
+		!isEvidenceReference(value.user_answer_evidence, value.answer_hash) ||
+		!recordedAnswers.some(answer => answer.round === value.approval_round && answer.answer_hash === value.answer_hash)
+	)
+		throw new Error("intent review approval evidence is invalid");
+}