immune-brain 2.8.2 → 3.0.1

package/plugins/immune-brain/runtime/kernel/reducer.ts

@@ -6,20 +6,21 @@ import { createHash } from "node:crypto";
 import { completionDecision } from "./completion";
 import {
 	REDUCED_MUTATION_BRAND,
+	TASK_RECORD_CONTRACT_V4,
 	type AuthorityAuditDescriptor,
 	type ReducedTaskMutation,
 	type TaskAction,
 	type TaskFinding,
 	type TaskIntentRefV3,
 	type TaskIntentV1,
-	type TaskRecordV3,
+	type TaskRecord,
 } from "./types";
 import {
 	KernelInvariantError,
 	assertKernelInvariantsV3,
 	assertTaskRecordUpdateV3,
 	parseTaskAction,
-	parseTaskRecordV3,
+	parseTaskRecord,
 } from "./validation";
 import { classifyIntentRevision, canonicalIntentHash } from "./intent";
 
@@ -29,7 +30,7 @@ const RISK_RANK: Record<TaskIntentV1["risk"], number> = {
 	critical: 2,
 };
 
-function transitionLifecycle(record: TaskRecordV3, to: "done" | "stopped"): void {
+function transitionLifecycle(record: TaskRecord, to: "done" | "stopped"): void {
 	if (record.lifecycle !== "active")
 		throw new KernelInvariantError([
 			`illegal lifecycle transition: ${record.lifecycle} -> ${to}`,
@@ -37,7 +38,7 @@ function transitionLifecycle(record: TaskRecordV3, to: "done" | "stopped"): void
 	record.lifecycle = to;
 }
 
-function stateOf(record: TaskRecordV3): string {
+function stateOf(record: TaskRecord): string {
 	return `${record.lifecycle}:${record.artifact_state}`;
 }
 
@@ -54,7 +55,7 @@ function stableJson(value: unknown): string {
 	return primitive === undefined ? "null" : primitive;
 }
 
-export function canonicalRecordHash(record: TaskRecordV3): string {
+export function canonicalRecordHash(record: TaskRecord): string {
 	// Must equal the storage CAS revision: the exact serialized file bytes.
 	return `sha256:${createHash("sha256")
 		.update(`${JSON.stringify(record, null, 2)}\n`)
@@ -99,7 +100,7 @@ export function recordedActionFingerprint(reason: string | null): string | null
 	return matched?.[1] ?? null;
 }
 
-function copyRecord(record: TaskRecordV3): TaskRecordV3 {
+function copyRecord(record: TaskRecord): TaskRecord {
 	return {
 		...record,
 		intent_snapshot: { ...record.intent_snapshot },
@@ -113,7 +114,7 @@ function copyRecord(record: TaskRecordV3): TaskRecordV3 {
 	};
 }
 
-function reviewRound(record: TaskRecordV3): number {
+function reviewRound(record: TaskRecord): number {
 	return (
 		Math.max(
 			0,
@@ -125,7 +126,7 @@ function reviewRound(record: TaskRecordV3): number {
 }
 
 function appendHistory(
-	record: TaskRecordV3,
+	record: TaskRecord,
 	action: TaskAction,
 	from: string,
 	detail: string | null,
@@ -200,11 +201,12 @@ export function findingsDigestV2(findings: TaskFinding[]): string {
 }
 
 export function reduceTask(
-	recordRaw: TaskRecordV3,
+	recordRaw: TaskRecord,
 	actionRaw: TaskAction,
 	authorityAudit: AuthorityAuditDescriptor | null = null,
+	changedPaths?: readonly string[],
 ): ReducedTaskMutation {
-	const previous = parseTaskRecordV3(recordRaw);
+	const previous = parseTaskRecord(recordRaw);
 	assertKernelInvariantsV3(previous.intent_snapshot, previous);
 	const action = parseTaskAction(actionRaw);
 	const record = copyRecord(previous);
@@ -343,8 +345,23 @@ export function reduceTask(
 				throw new KernelInvariantError([
 					`attestations contains duplicate id ${approval.id}`,
 				]);
+			// A v4 review attestation must pin the exact immutable revision the
+			// reviewer analyzed; nothing else may carry that identity.
+			const reviewRevision = approval.review_revision;
+			if (reviewRevision && approval.kind !== "review")
+				throw new KernelInvariantError(["review_revision is only valid on review approvals"]);
+			if (record.contract !== TASK_RECORD_CONTRACT_V4) {
+				if (reviewRevision)
+					throw new KernelInvariantError(["review_revision requires a TaskRecord v4"]);
+			} else if (approval.kind === "review") {
+				if (!reviewRevision)
+					throw new KernelInvariantError(["v4 review approval requires review_revision"]);
+				if (reviewRevision.base_head !== record.git_base_head)
+					throw new KernelInvariantError(["review_revision.base_head must equal the Enrollment git_base_head"]);
+			}
+			const { review_revision: storedReviewRevision, ...approvalWithoutRevision } = approval;
 			record.attestations.push({
-				...approval,
+				...approvalWithoutRevision,
 				acceptance_results: approval.kind === "qa"
 					? record.intent_snapshot.acceptance.map((item) => ({
 						acceptance_id: item.id,
@@ -352,6 +369,7 @@ export function reduceTask(
 						summary: `host-attested QA: ${approval.summary}`,
 					}))
 					: [],
+				...(storedReviewRevision ? { review_revision: storedReviewRevision } : {}),
 			});
 			appendHistory(record, action, from, approval.id, authorityAudit);
 			break;
@@ -380,6 +398,8 @@ export function reduceTask(
 				throw new KernelInvariantError([
 					`attestations contains duplicate id ${approval.id}`,
 				]);
+			if (approval.review_revision)
+				throw new KernelInvariantError(["review_revision is only valid on review approvals"]);
 			record.attestations.push({ ...approval, acceptance_results: [] });
 			appendHistory(record, action, from, approval.id, authorityAudit);
 			break;
@@ -518,11 +538,14 @@ export function reduceTask(
 				throw new KernelInvariantError([
 					`cannot complete while state is ${stateOf(record)}`,
 				]);
+			if (!Array.isArray(changedPaths))
+				throw new KernelInvariantError(["complete requires trusted changed paths"]);
 			const decision = completionDecision(
 				record.intent_snapshot,
 				record,
 				diffHash,
 				record.intent_ref.content_hash,
+				changedPaths,
 			);
 			if (!decision.complete)
 				throw new KernelInvariantError([
@@ -587,12 +610,12 @@ export function reduceTask(
 	return brandResult(record, nextWorkingFor(record));
 }
 
-function nextWorkingFor(record: TaskRecordV3): string | null {
+function nextWorkingFor(record: TaskRecord): string | null {
 	return record.lifecycle === "active" ? record.task_id : null;
 }
 
 function brandResult(
-	record: TaskRecordV3,
+	record: TaskRecord,
 	nextWorking: string | null,
 ): ReducedTaskMutation {
 	const target = {} as ReducedTaskMutation;

package/plugins/immune-brain/runtime/kernel/storage.ts

@@ -33,12 +33,12 @@ import {
 	stateTransactionPath,
 	stateWorkspacePath,
 } from "./storage_paths";
-import { parseTaskRecordV2, parseTaskRecordV3 } from "./validation";
+import { parseTaskRecord, parseTaskRecordV2 } from "./validation";
 import type {
 	TaskLifecycle,
 	TaskPhase,
 	TaskRecordV2,
-	TaskRecordV3,
+	TaskRecord,
 	StoredTaskMutationV3,
 	V3AuthorityObservation,
 } from "./types";
@@ -649,7 +649,7 @@ function parseWorkspaceTransactionV2(raw: Record<string, unknown>): WorkspaceTra
 		...(artifactRelocations.length > 0 ? { artifact_relocations: artifactRelocations } : {}),
 	};
 	validateTaskId(transaction.task_id);
-	const record = parseTaskRecordV3(
+	const record = parseTaskRecord(
 		JSON.parse(transaction.next_record_content),
 	);
 	if (record.task_id !== transaction.task_id)
@@ -736,7 +736,7 @@ function completeTransactionV2Locked(
 		transaction.expected_workspace_hash,
 		transaction.next_workspace_content,
 	);
-	const record = parseTaskRecordV3(
+	const record = parseTaskRecord(
 		JSON.parse(transaction.next_record_content),
 	);
 	const workspace = parseWorkspaceContent(transaction.next_workspace_content);
@@ -791,7 +791,7 @@ function recoverAnyPendingTransactionLocked(root: string): void {
 export function readTaskRecordRaw(
 	root: string,
 	taskId: string,
-): { revision: string; record: TaskRecordV3 | null } {
+): { revision: string; record: TaskRecord | null } {
 	validateTaskId(taskId);
 	const relativePath = stateTaskRecordPath(taskId);
 	if (currentRevision(root, relativePath) === MISSING_REVISION)
@@ -802,7 +802,7 @@ export function readTaskRecordRaw(
 		throw new KernelStoreSecurityError(
 			"TaskRecord v2 is not supported in the state layout; v2 records belong to the historical audit layout",
 		);
-	const record = parseTaskRecordV3(raw);
+	const record = parseTaskRecord(raw);
 	if (record.task_id !== taskId)
 		throw new KernelStoreSecurityError("task record v3 identity is inconsistent");
 	return { revision: revisionFor(content), record };
@@ -821,7 +821,7 @@ export function readAuditTaskPair(
 	taskId: string,
 ): {
 	recordRevision: string;
-	record: TaskRecordV3 | TaskRecordV2;
+	record: TaskRecord | TaskRecordV2;
 	proof: TaskTombstone;
 } | null {
 	validateTaskId(taskId);
@@ -846,7 +846,7 @@ export function readAuditTaskPair(
 			"terminal audit proof does not match its task record",
 		);
 	const raw = JSON.parse(recordContent) as { contract?: unknown };
-	let record: TaskRecordV3 | TaskRecordV2;
+	let record: TaskRecord | TaskRecordV2;
 	if (raw.contract === "assurance_kernel/task_record/v2") {
 		const legacy = parseTaskRecordV2(raw);
 		if (
@@ -858,7 +858,7 @@ export function readAuditTaskPair(
 			);
 		record = legacy;
 	} else {
-		const current = parseTaskRecordV3(raw);
+		const current = parseTaskRecord(raw);
 		if (
 			current.task_id !== taskId ||
 			(current.lifecycle !== "done" && current.lifecycle !== "stopped")
@@ -874,7 +874,7 @@ export function readAuditTaskPair(
 export function readTaskRecord(
 	root: string,
 	taskId: string,
-): { revision: string; record: TaskRecordV3 | null } {
+): { revision: string; record: TaskRecord | null } {
 	return withKernelStoreLock(root, () => readTaskRecordRaw(root, taskId));
 }
 
@@ -883,7 +883,7 @@ export function commitTaskRecordLocked(
 	root: string,
 	taskId: string,
 	expectedRecordHash: string,
-	nextRecord: TaskRecordV3,
+	nextRecord: TaskRecord,
 	expectedWorkspaceHash: string,
 	nextWorkspace: WorkspaceState,
 	artifactRelocations: ArtifactRelocationV1[] = [],
@@ -1358,7 +1358,7 @@ export function commitEnrollmentLocked(
 		);
 	}
 	return {
-		record: parseTaskRecordV3(JSON.parse(transaction.next_record_content)),
+		record: parseTaskRecord(JSON.parse(transaction.next_record_content)),
 		workspace: parseWorkspaceContent(transaction.next_workspace_content),
 	};
 }
@@ -1572,7 +1572,7 @@ function parseTerminalMarker(raw: Record<string, unknown>): TerminalMarker {
 		expected_claim_sha256: expectedClaim,
 		at: raw.at as string,
 	};
-	const record = parseTaskRecordV3(JSON.parse(marker.audit_record_content));
+	const record = parseTaskRecord(JSON.parse(marker.audit_record_content));
 	if (record.task_id !== marker.task_id)
 		throw new KernelStoreSecurityError("terminal marker task identity is inconsistent");
 	if (record.lifecycle !== "done" && record.lifecycle !== "stopped")
@@ -1709,7 +1709,7 @@ export function commitTerminalLocked(
 	taskId: string,
 	transaction: WorkspaceTransactionV2,
 	tombstone: TaskTombstone,
-): { record: TaskRecordV3; workspace: WorkspaceState } {
+): { record: TaskRecord; workspace: WorkspaceState } {
 	validateTaskId(taskId);
 	if (transaction.task_id !== taskId)
 		throw new KernelStoreSecurityError(
@@ -1728,7 +1728,7 @@ export function commitTerminalLocked(
 		throw new KernelStoreSecurityError(
 			"terminal proof must match the terminal record bytes",
 		);
-	const terminalRecord = parseTaskRecordV3(
+	const terminalRecord = parseTaskRecord(
 		JSON.parse(transaction.next_record_content) as Record<string, unknown>,
 	);
 	if (tombstone.terminal_lifecycle !== terminalRecord.lifecycle)
@@ -1774,7 +1774,7 @@ export function commitTerminalLocked(
 		);
 	}
 	return {
-		record: parseTaskRecordV3(JSON.parse(transaction.next_record_content)),
+		record: parseTaskRecord(JSON.parse(transaction.next_record_content)),
 		workspace: parseWorkspaceContent(transaction.next_workspace_content),
 	};
 }

package/plugins/immune-brain/runtime/kernel/types.ts

@@ -99,6 +99,9 @@ export interface V3AuthorityObservation {
 export const TASK_INTENT_CONTRACT_V1 = "assurance_kernel/task_intent/v1" as const;
 export const TASK_RECORD_CONTRACT_V2 = "assurance_kernel/task_record/v2" as const;
 export const TASK_RECORD_CONTRACT_V3 = "assurance_kernel/task_record/v3" as const;
+export const TASK_RECORD_CONTRACT_V4 = "assurance_kernel/task_record/v4" as const;
+export const REVIEW_REVISION_IDENTITY_CONTRACT =
+	"assurance_kernel/review_revision_identity/v1" as const;
 
 export interface TaskIntentAcceptanceItemV1 {
 	id: string;
@@ -148,6 +151,20 @@ export interface TaskApprovalV2 {
 	diff_hash: string;
 	actor_id: string;
 	summary: string;
+	/**
+	 * Immutable Git revision identity the reviewer actually analyzed. Legal only
+	 * on a review attestation of a TaskRecord v4; the strict parser rejects it
+	 * anywhere else, so QA and user attestations never carry revision bytes.
+	 */
+	review_revision?: ReviewRevisionIdentityV1;
+}
+
+export interface ReviewRevisionIdentityV1 {
+	contract: typeof REVIEW_REVISION_IDENTITY_CONTRACT;
+	base_head: string;
+	review_commit: string;
+	review_tree: string;
+	manifest_digest: string;
 }
 
 export interface TaskHistoryEntryV2 {
@@ -206,6 +223,19 @@ export interface TaskRecordV3 {
 	history: TaskHistoryEntryV3[];
 }
 
+/**
+ * TaskRecord v4 binds the Enrollment commit so Review, QA, authorization, and
+ * completion can all derive one scoped revision from base to final index tree.
+ * `git_base_head` is immutable from Enrollment through terminal settlement.
+ */
+export interface TaskRecordV4 extends Omit<TaskRecordV3, "contract"> {
+	contract: typeof TASK_RECORD_CONTRACT_V4;
+	git_base_head: string;
+}
+
+/** The record shape every Kernel owner passes around during the v3 drain window. */
+export type TaskRecord = TaskRecordV3 | TaskRecordV4;
+
 export interface TaskProjectionV3 extends CompletionDecision {
 	contract: "assurance_kernel/projection/v3";
 	task_id: string;
@@ -268,13 +298,13 @@ export const REDUCED_MUTATION_BRAND = Symbol("assurance-kernel-reduced-mutation-
 
 export interface ReducedTaskMutation {
 	readonly [REDUCED_MUTATION_BRAND]: true;
-	readonly record: TaskRecordV3;
+	readonly record: TaskRecord;
 	readonly next_workspace_working: string | null;
 }
 
 export interface StoredTaskMutationV3 {
 	revision: string;
-	record: TaskRecordV3;
+	record: TaskRecord;
 	workspace: {
 		revision: string;
 		state: WorkspaceStateLike;

package/plugins/immune-brain/runtime/kernel/validation.ts

@@ -4,6 +4,8 @@ import {
 	TASK_PHASES,
 	TASK_RECORD_CONTRACT_V2,
 	TASK_RECORD_CONTRACT_V3,
+	TASK_RECORD_CONTRACT_V4,
+	REVIEW_REVISION_IDENTITY_CONTRACT,
 	type ApprovalAuthorityRole,
 	type ApprovalKind,
 	type EvidenceStatus,
@@ -19,11 +21,16 @@ import {
 	type TaskHistoryEntryV2,
 	type TaskHistoryEntryV3,
 	type TaskIntentV1,
+	type ReviewRevisionIdentityV1,
+	type TaskRecord,
 	type TaskRecordV2,
 	type TaskRecordV3,
+	type TaskRecordV4,
 } from "./types";
 import { canonicalIntentHash, parseTaskIntentV1 } from "./intent";
 
+const GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
 export class KernelValidationError extends Error {
 	readonly code = "kernel_schema_invalid";
 
@@ -320,11 +327,13 @@ function parseApprovalV2(
 	value: unknown,
 	index: number,
 	violations: string[],
+	allowReviewRevision = false,
 ): TaskApprovalV2 {
 	const item = objectAt(value, `record.approvals[${index}]`, violations);
 	rejectUnknown(
 		item,
-		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary"],
+		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary",
+			...(allowReviewRevision ? ["review_revision"] : [])],
 		`record.approvals[${index}]`,
 		violations,
 	);
@@ -356,18 +365,52 @@ function parseApprovalV2(
 		diff_hash: diffHash,
 		actor_id: stringAt(item.actor_id, `record.approvals[${index}].actor_id`, violations),
 		summary: stringAt(item.summary, `record.approvals[${index}].summary`, violations),
+		...(allowReviewRevision && item.review_revision !== undefined
+			? { review_revision: parseReviewRevisionIdentity(item.review_revision, `record.approvals[${index}].review_revision`, violations) }
+			: {}),
 	};
 }
 
+function parseReviewRevisionIdentity(
+	value: unknown,
+	path: string,
+	violations: string[],
+): ReviewRevisionIdentityV1 {
+	const item = objectAt(value, path, violations);
+	rejectUnknown(item, ["contract", "base_head", "review_commit", "review_tree", "manifest_digest"], path, violations);
+	if (item.contract !== REVIEW_REVISION_IDENTITY_CONTRACT)
+		violations.push(`${path}.contract must equal ${REVIEW_REVISION_IDENTITY_CONTRACT}`);
+	const identity = {
+		contract: REVIEW_REVISION_IDENTITY_CONTRACT,
+		base_head: stringAt(item.base_head, `${path}.base_head`, violations),
+		review_commit: stringAt(item.review_commit, `${path}.review_commit`, violations),
+		review_tree: stringAt(item.review_tree, `${path}.review_tree`, violations),
+		manifest_digest: stringAt(item.manifest_digest, `${path}.manifest_digest`, violations),
+	};
+	for (const field of ["base_head", "review_commit", "review_tree"] as const)
+		if (!GIT_OBJECT_ID.test(identity[field]))
+			violations.push(`${path}.${field} must be a lowercase Git object id`);
+	if (!SHA256_HEX.test(identity.manifest_digest))
+		violations.push(`${path}.manifest_digest must be sha256:<64 hex>`);
+	return identity;
+}
+
 function parseAttestationV3(
 	value: unknown,
 	index: number,
 	acceptanceIds: Set<string>,
 	violations: string[],
+	allowReviewRevision = false,
 ): TaskAttestationV3 {
 	const path = `record.attestations[${index}]`;
 	const item = objectAt(value, path, violations);
-	rejectUnknown(item, ["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "acceptance_results"], path, violations);
+	rejectUnknown(
+		item,
+		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "acceptance_results",
+			...(allowReviewRevision ? ["review_revision"] : [])],
+		path,
+		violations,
+	);
 	const kind = enumAt(item.kind, APPROVAL_KINDS, `${path}.kind`, violations);
 	const intentContentHash = stringAt(item.intent_content_hash, `${path}.intent_content_hash`, violations);
 	const diffHash = stringAt(item.diff_hash, `${path}.diff_hash`, violations);
@@ -392,6 +435,13 @@ function parseAttestationV3(
 		if (resultIds.length !== acceptanceIds.size || new Set(resultIds).size !== acceptanceIds.size)
 			violations.push(`${path}.acceptance_results must cover every acceptance exactly once`);
 	}
+	const reviewRevision = item.review_revision === undefined
+		? undefined
+		: parseReviewRevisionIdentity(item.review_revision, `${path}.review_revision`, violations);
+	if (reviewRevision && kind !== "review")
+		violations.push(`${path}.review_revision is only valid on review attestations`);
+	if (allowReviewRevision && kind === "review" && !reviewRevision)
+		violations.push(`${path}.review_revision is required for v4 review attestations`);
 	return {
 		id: stringAt(item.id, `${path}.id`, violations),
 		kind,
@@ -402,6 +452,7 @@ function parseAttestationV3(
 		actor_id: stringAt(item.actor_id, `${path}.actor_id`, violations),
 		summary: stringAt(item.summary, `${path}.summary`, violations),
 		acceptance_results: acceptanceResults,
+		...(reviewRevision ? { review_revision: reviewRevision } : {}),
 	};
 }
 
@@ -528,17 +579,19 @@ export function parseTaskRecordV2(raw: unknown): TaskRecordV2 {
 	};
 }
 
-export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
+function parseTaskRecordAtVersion(raw: unknown, version: 3 | 4): TaskRecordV3 | TaskRecordV4 {
 	const violations: string[] = [];
 	const value = objectAt(raw, "record", violations);
 	rejectUnknown(
 		value,
-		["contract", "task_id", "intent_snapshot", "intent_ref", "lifecycle", "artifact_state", "baseline", "attestations", "findings", "history"],
+		["contract", "task_id", "intent_snapshot", "intent_ref", "lifecycle", "artifact_state", "baseline", "attestations", "findings", "history",
+			...(version === 4 ? ["git_base_head"] : [])],
 		"record",
 		violations,
 	);
-	if (value.contract !== TASK_RECORD_CONTRACT_V3)
-		violations.push(`contract must equal ${TASK_RECORD_CONTRACT_V3}`);
+	const expectedContract = version === 4 ? TASK_RECORD_CONTRACT_V4 : TASK_RECORD_CONTRACT_V3;
+	if (value.contract !== expectedContract)
+		violations.push(`contract must equal ${expectedContract}`);
 
 	let snapshot: TaskIntentV1 | null = null;
 	try {
@@ -570,31 +623,65 @@ export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
 
 	const baseline = stringAt(value.baseline, "record.baseline", violations);
 	if (!SHA256_HEX.test(baseline)) violations.push("record.baseline must be sha256:<64 hex>");
+	let gitBaseHead = "";
+	if (version === 4) {
+		const rawGitBaseHead = stringAt(value.git_base_head, "record.git_base_head", violations);
+		if (rawGitBaseHead !== rawGitBaseHead.toLowerCase())
+			violations.push("record.git_base_head must be lowercase");
+		gitBaseHead = rawGitBaseHead;
+		if (!GIT_OBJECT_ID.test(gitBaseHead))
+			violations.push("record.git_base_head must be a lowercase Git commit id");
+	}
 	const acceptanceIds = new Set(snapshot ? snapshot.acceptance.map((item) => item.id) : []);
-	const attestations = arrayAt(value.attestations, "record.attestations", violations).map((item, index) => parseAttestationV3(item, index, acceptanceIds, violations));
+	const attestations = arrayAt(value.attestations, "record.attestations", violations).map((item, index) => parseAttestationV3(item, index, acceptanceIds, violations, version === 4));
+	if (version === 4) {
+		for (const [index, attestation] of attestations.entries()) {
+			if (attestation.kind === "review" && attestation.review_revision && attestation.review_revision.base_head !== gitBaseHead)
+				violations.push(`record.attestations[${index}].review_revision.base_head must equal record.git_base_head`);
+		}
+	}
 	const findings = arrayAt(value.findings, "record.findings", violations).map((item, index) => parseFinding(item, index, violations));
 	const history = arrayAt(value.history, "record.history", violations).map((item, index) => parseHistoryV3(item, index, violations));
 	uniqueIds(attestations, "record.attestations", violations);
 	uniqueIds(findings, "record.findings", violations);
 	uniqueIds(history, "record.history", violations);
 	if (violations.length > 0) throw new KernelValidationError(violations);
-	return {
-		contract: TASK_RECORD_CONTRACT_V3,
+	const record = {
+		contract: expectedContract,
 		task_id: taskId,
 		intent_snapshot: snapshot as TaskIntentV1,
 		intent_ref: { path: refPath, content_hash: refContentHash },
 		lifecycle: lifecycle as TaskRecordV3["lifecycle"],
 		artifact_state: artifactState as TaskRecordV3["artifact_state"],
 		baseline,
+		...(version === 4 ? { git_base_head: gitBaseHead } : {}),
 		attestations,
 		findings,
 		history,
 	};
+	return record as TaskRecordV3 | TaskRecordV4;
+}
+
+/** Strict v3 drain parser: unknown fields and revision identity stay illegal. */
+export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
+	return parseTaskRecordAtVersion(raw, 3) as TaskRecordV3;
+}
+
+/** Strict v4 parser: the Enrollment base commit is mandatory. */
+export function parseTaskRecordV4(raw: unknown): TaskRecordV4 {
+	return parseTaskRecordAtVersion(raw, 4) as TaskRecordV4;
+}
+
+/** Version-dispatched parser used by every durable Kernel owner. */
+export function parseTaskRecord(raw: unknown): TaskRecord {
+	const contract = (raw as { contract?: unknown } | null)?.contract;
+	if (contract === TASK_RECORD_CONTRACT_V4) return parseTaskRecordV4(raw);
+	return parseTaskRecordV3(raw);
 }
 
-export function assertKernelInvariantsV3(intentRaw: TaskIntentV1, recordRaw: TaskRecordV3): void {
+export function assertKernelInvariantsV3(intentRaw: TaskIntentV1, recordRaw: TaskRecord): void {
 	const intent = parseTaskIntentV1(intentRaw);
-	const record = parseTaskRecordV3(recordRaw);
+	const record = parseTaskRecord(recordRaw);
 	const violations: string[] = [];
 	if (intent.task_id !== record.task_id) violations.push("intent and record task_id must match");
 	if (intent.revision !== record.intent_snapshot.revision) violations.push("intent revision must match record snapshot");
@@ -752,7 +839,9 @@ export function parseTaskAction(raw: unknown): TaskAction {
 				"action",
 				violations,
 			);
-			const approval = parseApprovalV2(value.approval, 0, violations);
+			const approval = parseApprovalV2(value.approval, 0, violations, true);
+			if (approval.review_revision && approval.kind !== "review")
+				violations.push("action.approval.review_revision is only valid on review approvals");
 			action = {
 				...base,
 				type: base.type,
@@ -871,12 +960,12 @@ export function parseTaskAction(raw: unknown): TaskAction {
 }
 
 export function assertTaskRecordUpdateV3(
-	previousRaw: TaskRecordV3,
-	nextRaw: TaskRecordV3,
+	previousRaw: TaskRecord,
+	nextRaw: TaskRecord,
 	action: TaskAction,
 ): void {
-	const previous = parseTaskRecordV3(previousRaw);
-	const next = parseTaskRecordV3(nextRaw);
+	const previous = parseTaskRecord(previousRaw);
+	const next = parseTaskRecord(nextRaw);
 	const violations: string[] = [];
 
 	if (next.contract !== previous.contract)
@@ -885,6 +974,8 @@ export function assertTaskRecordUpdateV3(
 		violations.push("record task_id must remain immutable");
 	if (next.baseline !== previous.baseline)
 		violations.push("record baseline must remain immutable");
+	if (previous.contract === TASK_RECORD_CONTRACT_V4 && next.contract === TASK_RECORD_CONTRACT_V4 && next.git_base_head !== previous.git_base_head)
+		violations.push("record git_base_head must remain immutable");
 
 	const isIntentAction =
 		action.type === "revise_intent" ||

package/plugins/immune-brain/runtime/loop_contract.ts

@@ -217,7 +217,7 @@ export function buildLoopAction(input: {
 export interface LoopRoleDispatch {
 	packet: RoleDelegationPacket;
 	call: {
-		subagent_type: "general-purpose";
+		subagent_type: LoopRoleSubagent;
 		description: string;
 		prompt: string;
 		inherit_context: false;
@@ -226,6 +226,21 @@ export interface LoopRoleDispatch {
 	};
 }
 
+/**
+ * Authoritative code review runs on the host's configured `Review` agent so the
+ * user's own model/provider selection applies. Architecture exploration uses
+ * the host `Explore` agent. Every other internal role, and especially the
+ * tool-less planning `advisory-reviewer`, stays on the generic agent and never
+ * inherits review authority.
+ */
+export type LoopRoleSubagent = "Review" | "Explore" | "general-purpose";
+
+export function loopRoleSubagentFor(role: LoopRole): LoopRoleSubagent {
+	if (role === "code-review") return "Review";
+	if (role === "arch-explorer") return "Explore";
+	return "general-purpose";
+}
+
 export function buildLoopRoleDispatch(input: {
 	role: LoopRole;
 	context: RoleDelegationContext;
@@ -235,7 +250,7 @@ export function buildLoopRoleDispatch(input: {
 	return {
 		packet,
 		call: {
-			subagent_type: "general-purpose",
+			subagent_type: loopRoleSubagentFor(input.role),
 			description: input.description ?? `${input.role} internal role`,
 			prompt: packet.prompt,
 			inherit_context: false,