immune-brain 2.8.3 → 3.0.2

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

@@ -1,9 +1,8 @@
 // P2B1 enrollment authority. NOT exported from kernel/index.ts.
-// Explicit registry factory: each registry owns its WeakMap; capabilities are
-// only recognized by the registry that issued them. No module-level singleton.
-// The production registry is created only inside the Pi extension activation
-// closure; tests create isolated registries via the fixture seam.
+// Uses the shared capability registry factory; enrollment-specific binding
+// validation and projection remain here.
 
+import { createCapabilityRegistry } from "./capability_registry";
 import { MUTATION_AUTHORITY_CAPABILITY_BRAND } from "./types";
 
 export const ENROLLMENT_CAPABILITY_BRAND = Symbol.for("assurance-kernel.enrollment-capability-brand");
@@ -20,11 +19,6 @@ export interface EnrollmentCapabilityBinding {
 	nonce: string;
 }
 
-interface EnrollmentCapabilityState extends EnrollmentCapabilityBinding {
-	issued_at: string;
-	consumed: boolean;
-}
-
 export interface ValidatedEnrollment {
 	task_id: string;
 	intent_path: string;
@@ -48,76 +42,39 @@ export interface EnrollmentAuthorityRegistry {
 }
 
 export function createEnrollmentAuthorityRegistry(): EnrollmentAuthorityRegistry {
-	const states = new WeakMap<object, EnrollmentCapabilityState>();
-	const brand = Symbol.for("assurance-kernel.enrollment-capability-registry");
-
-	function isEnrollmentCapability(value: unknown): value is object {
-		return (
-			!!value &&
-			typeof value === "object" &&
-			(value as Record<symbol, unknown>)[ENROLLMENT_CAPABILITY_BRAND] === true &&
-			(value as Record<symbol, unknown>)[brand] === true
-		);
-	}
-
-	function stateOf(capability: object): EnrollmentCapabilityState {
-		const state = states.get(capability);
-		if (!state) throw new Error("enrollment capability is not recognized by this registry");
-		return state;
-	}
-
-	return {
-		brand,
-		issue(binding: EnrollmentCapabilityBinding, issuedAt = new Date().toISOString()): object {
-			const missing: string[] = [];
-			for (const [key, value] of Object.entries(binding)) {
-				if (value === undefined || value === null || value === "") missing.push(key);
-			}
-			if (missing.length > 0)
-				throw new Error(`enrollment capability binding is incomplete: ${missing.join(", ")}`);
-			if (Number.isNaN(Date.parse(binding.expires_at)) || Date.parse(binding.expires_at) <= Date.parse(issuedAt))
-				throw new Error("enrollment capability must have a future expiry");
-			const capability = Object.freeze(
-				Object.defineProperties(
-					{},
-					{
-						[ENROLLMENT_CAPABILITY_BRAND]: { value: true, enumerable: false, writable: false, configurable: false },
-						[brand]: { value: true, enumerable: false, writable: false, configurable: false },
-					},
-				),
-			);
-			states.set(capability, { ...binding, issued_at: issuedAt, consumed: false });
-			return capability;
-		},
-		inspect(capability: object, expected: EnrollmentCapabilityBinding, now = Date.now()): ValidatedEnrollment {
-			if (!isEnrollmentCapability(capability)) throw new Error("enrollment capability required");
-			const state = stateOf(capability);
-			if (state.consumed) throw new Error("enrollment capability already consumed");
-			if (Date.parse(state.expires_at) <= now) throw new Error("enrollment capability has expired");
-			for (const key of Object.keys(expected) as Array<keyof EnrollmentCapabilityBinding>) {
-				if (state[key] !== expected[key])
-					throw new Error(`enrollment capability ${key} mismatch`);
-			}
-			return {
-				task_id: state.task_id,
-				intent_path: state.intent_path,
-				intent_revision: state.intent_revision,
-				intent_content_hash: state.intent_content_hash,
-				preparation_digest: state.preparation_digest,
-				actor_id: state.actor_id,
-				confirmation_ref: state.confirmation_ref,
-				issued_at: state.issued_at,
-				expires_at: state.expires_at,
-				nonce: state.nonce,
-			};
-		},
-		consume(capability: object, expected: EnrollmentCapabilityBinding, now = Date.now()): ValidatedEnrollment {
-			const validated = this.inspect(capability, expected, now);
-			stateOf(capability).consumed = true;
-			return validated;
-		},
-		isConsumed(capability: object): boolean {
-			return stateOf(capability).consumed;
+	return createCapabilityRegistry<EnrollmentCapabilityBinding, EnrollmentCapabilityBinding, ValidatedEnrollment>(
+		ENROLLMENT_CAPABILITY_BRAND,
+		{
+			validateBinding(binding, issuedAt) {
+				const missing: string[] = [];
+				for (const [key, value] of Object.entries(binding)) {
+					if (value === undefined || value === null || value === "") missing.push(key);
+				}
+				if (missing.length > 0)
+					throw new Error(`enrollment capability binding is incomplete: ${missing.join(", ")}`);
+				if (Number.isNaN(Date.parse(binding.expires_at)) || Date.parse(binding.expires_at) <= Date.parse(issuedAt))
+					throw new Error("enrollment capability must have a future expiry");
+			},
+			validateAndProject(state, expected, now) {
+				if (Date.parse(state.expires_at) <= now) throw new Error("enrollment capability has expired");
+				for (const key of Object.keys(expected) as Array<keyof EnrollmentCapabilityBinding>) {
+					if (state[key] !== expected[key])
+						throw new Error(`enrollment capability ${key} mismatch`);
+				}
+				return {
+					task_id: state.task_id,
+					intent_path: state.intent_path,
+					intent_revision: state.intent_revision,
+					intent_content_hash: state.intent_content_hash,
+					preparation_digest: state.preparation_digest,
+					actor_id: state.actor_id,
+					confirmation_ref: state.confirmation_ref,
+					issued_at: state.issued_at,
+					expires_at: state.expires_at,
+					nonce: state.nonce,
+				};
+			},
 		},
-	};
+		"enrollment",
+	);
 }

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

@@ -46,6 +46,16 @@ export const RISK_FLOOR_SCOPE_PREFIXES = [
 	"plugins/immune-brain/.pi-extension",
 ] as const;
 
+// Concrete changed paths use a narrower, segment-safe prefix policy. Keep this
+// separate from the glob-aware scope_hint policy above: the two inputs have
+// different contracts and docs-only scope remains routine today.
+export const CHANGED_PATH_RISK_FLOOR_PREFIXES = [
+	"plugins/immune-brain/runtime/kernel",
+	"plugins/immune-brain/.pi-extension",
+	"docs/specs",
+	"docs/plans",
+] as const;
+
 function segmentMatches(e: string, s: string): boolean {
 	if (e === "*") return true;
 	if (!e.includes("*") && !e.includes("?")) return e === s;
@@ -330,6 +340,20 @@ export function canonicalIntentHash(intent: unknown): string {
 
 const RISK_RANK: Record<TaskRisk, number> = { routine: 0, material: 1, critical: 2 };
 
+export function classifyTaskRisk(
+	changedPaths: readonly string[],
+	declaredRisk: TaskRisk,
+): TaskRisk {
+	const pathFloor = changedPaths.some((path) =>
+		CHANGED_PATH_RISK_FLOOR_PREFIXES.some(
+			(prefix) => path === prefix || path.startsWith(`${prefix}/`),
+		),
+	)
+		? "material"
+		: "routine";
+	return RISK_RANK[declaredRisk] >= RISK_RANK[pathFloor] ? declaredRisk : pathFloor;
+}
+
 function contentHashWithoutRevision(intent: TaskIntentV1): string {
 	const { revision: _revision, ...rest } = intent;
 	return canonicalIntentHash(rest);

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

@@ -4,6 +4,7 @@
 // enrollment call, or writer. Direct import cannot authorize or mutate.
 
 import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import { readBackendClaim, readTaskTombstone } from "./backend_claim";
 import { readTaskIntent } from "./intent";
@@ -13,6 +14,21 @@ import {
 } from "./storage";
 
 const SOURCE_PATH = ".imm/state/workspace.json";
+const GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
+/**
+ * The Enrollment base commit. v4 TaskRecords bind this exact commit so QA,
+ * Review, authorization, and completion can all derive one scoped revision.
+ */
+export function readGitHead(root: string): string {
+	const result = spawnSync("git", ["-C", root, "rev-parse", "--verify", "HEAD^{commit}"], {
+		encoding: "utf8",
+	});
+	const head = typeof result.stdout === "string" ? result.stdout.trim() : "";
+	if (result.status !== 0 || !GIT_OBJECT_ID.test(head))
+		throw new Error("enrollment requires a committed Git HEAD in the project root");
+	return head.toLowerCase();
+}
 
 export interface PiCanaryPrepareInput {
 	task_id: string;
@@ -43,6 +59,9 @@ export interface PiCanaryPreparation {
 		lifecycle: string | null;
 		artifact_state: string | null;
 	} | null;
+	/** Commit the confirmation is bound to; becomes TaskRecord v4 `git_base_head`. */
+	git_base_head: string | null;
+	git_error: string | null;
 	workspace: {
 		current_working: string | null;
 	};
@@ -139,6 +158,16 @@ export function preparePiCanary(root: string, input: PiCanaryPrepareInput): PiCa
 			`workspace owner ${state.state.current_working} contradicts backend claim task ${claim.task_id}`,
 		);
 
+	// A missing HEAD is a readiness blocker, not a crash: the rehearsal and the
+	// native gate must be able to report it while still binding the digest.
+	let gitBaseHead: string | null = null;
+	let gitError: string | null = null;
+	try {
+		gitBaseHead = readGitHead(canonicalRoot);
+	} catch (error) {
+		gitError = error instanceof Error ? error.message : String(error);
+	}
+
 	const preparation: PiCanaryPreparation = {
 		contract: "assurance_kernel/pi_canary_preparation/v1",
 		task_id: input.task_id,
@@ -148,6 +177,8 @@ export function preparePiCanary(root: string, input: PiCanaryPrepareInput): PiCa
 		backend_claim: backend,
 		task_tombstone: taskTombstone,
 		task_record_v3: record,
+		git_base_head: gitBaseHead,
+		git_error: gitError,
 		workspace,
 		digest: "",
 	};

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;