immune-brain 3.6.9 → 4.0.0

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

@@ -3,7 +3,9 @@
 // for one confirmed canary task. Requires a valid EnrollmentCapability.
 // No CLI, runtime route, or production issuer exists in P2B0.
 
-import { canonicalIntentHash, readTaskIntent } from "./intent";
+import { readRunRowByTask, withKernelRead } from "./sqlite_store";
+import { readTaskIntent } from "./intent";
+import { inspectSpecBinding } from "./spec_binding";
 import {
 	type EnrollmentAuthorityRegistry,
 	type EnrollmentCapabilityBinding,
@@ -12,12 +14,16 @@ import type {
 	BatchAuthorityRegistry,
 	BatchAuthorizationBinding,
 } from "./batch_authority";
-import { readTaskTombstone, type BackendClaim } from "./backend_claim";
+import type { BackendClaim } from "./backend_claim";
 import { preparePiCanary, readGitHead } from "./pi_canary_prepare";
+import { writeEnrollmentBaseline } from "../workspace_scope";
+import { enrollmentRequestDigest } from "./run_identity";
 import {
 	commitEnrollmentLocked,
+	readCommittedEnrollmentResult,
 	readTaskRecordRaw,
 	readWorkspaceStateRaw,
+	reconcileKernelAuthority,
 	withKernelStoreLock,
 } from "./storage";
 import type { TaskRecord, TaskRecordV4, WorkspaceStateLike } from "./types";
@@ -113,10 +119,18 @@ function runEnrollmentPreconditionChecks<T>(
 			blockers.push(report);
 		};
 
-		const tombstone = readTaskTombstone(root, input.task_id);
-		if (tombstone) {
+		// Terminal protection is the *local* committed run, never the audit
+		// evidence: another worktree's run of the same logical task exports its
+		// own audit directory, and that evidence must not forbid a first
+		// enrollment here. Audit files remain readable as historical evidence for
+		// tasks this worktree has no run for (see reconcileKernelAuthority).
+		const localRun = reconcileKernelAuthority(root, input.task_id);
+		const localTerminal =
+			localRun.state === "terminal_owner" &&
+			withKernelRead(root, (db) => readRunRowByTask(db, input.task_id)) !== null;
+		if (localTerminal) {
 			fail(
-				"task tombstone exists; same-task re-enrollment is forbidden",
+				"local run is terminal; same-task re-enrollment is forbidden",
 				new Error(`task ${input.task_id} is terminal; same-task re-enrollment is forbidden`),
 			);
 		} else {
@@ -138,6 +152,12 @@ function runEnrollmentPreconditionChecks<T>(
 		} catch (error) {
 			fail(`intent: ${error instanceof Error ? error.message : String(error)}`, error);
 		}
+		// A simple Intent binds no Spec. A complex binding that names a Spec must
+		// be complete and unambiguous before any Executor turn.
+		if (intent) {
+			const binding = inspectSpecBinding(intent.intent);
+			if (!binding.ok) fail(binding.message, new Error(binding.message));
+		}
 		try {
 			gitBaseHead = readGitHead(root);
 		} catch (error) {
@@ -219,20 +239,65 @@ export function runEnrollmentRehearsal(
 	};
 }
 
+function enrollmentEventId(taskId: string, now: string): string {
+	return `enroll-${taskId}-${now}`;
+}
+
+function digestForEnrollment(input: EnrollCanaryInput): {
+	eventId: string;
+	digest: string;
+} {
+	const eventId = enrollmentEventId(input.task_id, input.now);
+	return {
+		eventId,
+		digest: enrollmentRequestDigest({
+			task_id: input.task_id,
+			intent_path: input.intent_path,
+			intent_revision: input.intent_revision,
+			intent_content_hash: input.capability_binding.intent_content_hash,
+			preparation_digest: input.preparation_digest,
+			enrollment_event_id: eventId,
+			actor_id: input.capability_binding.actor_id,
+			confirmation_ref: input.capability_binding.confirmation_ref,
+			nonce: input.capability_binding.nonce,
+		}),
+	};
+}
+
 /**
  * Atomic canary enrollment. Runs inside the same store lock as v1/v2
  * transactions; consumes the capability only after every precondition
- * passes, immediately before writing the enrollment marker.
+ * passes, immediately before writing the enrollment marker. A lost
+ * response of the exact same request returns the committed result
+ * without repeating those first-execution checks.
  */
 export function enrollCanaryTask(
 	root: string,
 	input: EnrollCanaryInput,
 	registry: EnrollmentAuthorityRegistry,
 ): EnrollCanaryResult {
+	const { eventId, digest } = digestForEnrollment(input);
+	// A committed enrollment answers the exact same request: the retry cannot
+	// pass the first-execution checks (the capability is consumed and the
+	// record now exists), so the durable operation is the only correct answer.
+	const replayed = readCommittedEnrollmentResult(root, input.task_id, eventId, digest);
+	if (replayed)
+		return {
+			record: replayed.record,
+			backend_claim: replayed.claim,
+			workspace: { revision: "", state: replayed.workspace },
+		};
+
 	let gitBaseHead: string | null = null;
-	return runEnrollmentPreconditionChecks(
-		root,
-		input,
+	// The batch child slot is consumed with the capability and handed back when
+	// the enrollment call fails. The commit happens at the outer store
+	// transaction, so any throw from this call means nothing was committed and
+	// the release has to wrap the whole call rather than only the record write.
+	let consumed = false;
+	try {
+		return runEnrollmentPreconditionChecks(
+			root,
+			input,
 		input.capability,
 		registry,
 		"fail_fast",
@@ -250,6 +315,12 @@ export function enrollCanaryTask(
 		(checks) => {
 			if (!checks.validated || !checks.intent || !checks.workspace || !checks.current)
 				throw new Error("enrollment precondition state incomplete");
+			// Recompute under the store lock: a confirmation bound to an older
+			// workspace revision must not commit after another enrollment and
+			// settlement raced between beforeLock and this callback.
+			const locked = preparePiCanary(root, { task_id: input.task_id, now: input.now });
+			if (locked.digest !== input.preparation_digest)
+				throw new Error("enrollment preparation digest mismatch");
 			if (checks.intent.intent.revision !== input.intent_revision)
 				throw new Error("intent revision mismatch");
 			if (checks.intent.content_hash !== checks.validated.intent_content_hash)
@@ -285,8 +356,9 @@ export function enrollCanaryTask(
 					);
 			}
 
-			// consume immediately before the marker write
+			// consume immediately before the store transaction
 			registry.consume(input.capability, input.capability_binding);
+			consumed = true;
 			if (input.batch)
 				input.batch.registry.consumeChild(
 					input.batch.capability,
@@ -310,37 +382,55 @@ export function enrollCanaryTask(
 				task_id: input.task_id,
 				intent_revision: input.intent_revision,
 				intent_content_hash: checks.intent.content_hash,
-				enrollment_event_id: `enroll-${input.task_id}-${input.now}`,
+				enrollment_event_id: eventId,
 				lifecycle_status: "active",
 				created_at: input.now,
 				updated_at: input.now,
 			};
-			let mutation: ReturnType<typeof commitEnrollmentLocked>;
-			try {
-				mutation = commitEnrollmentLocked(
-					root,
-					input.task_id,
-					{
-						contract: "assurance_kernel/workspace_transaction/v2",
-						task_id: input.task_id,
-						expected_record_hash: checks.current.revision,
-						next_record_content: `${JSON.stringify(record, null, 2)}\n`,
-						expected_workspace_hash: checks.workspace.revision,
-						next_workspace_content: `${JSON.stringify(nextWorkspace, null, 2)}\n`,
-					},
-					claim as unknown as Record<string, unknown>,
-				);
-			} catch (error) {
-				// No TaskRecord was written, so the child slot must not stay used.
-				if (input.batch)
-					input.batch.registry.releaseChild(input.batch.capability, input.task_id);
-				throw error;
-			}
+			const mutation = commitEnrollmentLocked(
+				root,
+				input.task_id,
+				{
+					contract: "assurance_kernel/workspace_transaction/v2",
+					task_id: input.task_id,
+					expected_record_hash: checks.current.revision,
+					next_record_content: `${JSON.stringify(record, null, 2)}\n`,
+					expected_workspace_hash: checks.workspace.revision,
+					next_workspace_content: `${JSON.stringify(nextWorkspace, null, 2)}\n`,
+				},
+				claim as unknown as Record<string, unknown>,
+				digest,
+			);
+			writeEnrollmentBaseline(root);
 			return {
 				record: mutation.record,
 				backend_claim: claim,
 				workspace: { revision: "", state: mutation.workspace },
 			};
-		},
-	);
+			},
+		);
+	} catch (error) {
+		// A child slot is released only when the enrollment provably did not
+		// commit. The envelope can also fail *after* the Kernel transaction
+		// committed — a follow-up transaction that cannot start, for example —
+		// and releasing then would leave the batch view ahead of an owner the
+		// Kernel already recorded. The committed run decides, not the throw.
+		const ownership = (() => {
+			try {
+				return {
+					known: true,
+					owned:
+						reconcileKernelAuthority(root, input.task_id).owner_task_id === input.task_id,
+				};
+			} catch {
+				return { known: false, owned: false };
+			}
+		})();
+		// Unknown is not "not committed". When the store cannot be read the slot
+		// stays consumed, so the batch view never runs ahead of a run that may
+		// exist, and the operator reconciles from the Kernel's own state.
+		if (consumed && input.batch && ownership.known && !ownership.owned)
+			input.batch.registry.releaseChild(input.batch.capability, input.task_id);
+		throw error;
+	}
 }

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

@@ -3,19 +3,27 @@
 // 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");
 
-export interface EnrollmentCapabilityBinding {
+/**
+ * The three fields every capability binding shares, whichever authority issues
+ * it. `nonce` is deliberately not part of this base: the enrollment and batch
+ * bindings carry it for their own replay digest, while `CapabilityBindingV2`
+ * uses `action_digest` instead and has no `nonce` field at all.
+ */
+export interface BaseCapabilityBinding {
+	actor_id: string;
+	confirmation_ref: string;
+	expires_at: string;
+}
+
+export interface EnrollmentCapabilityBinding extends BaseCapabilityBinding {
 	task_id: string;
 	intent_path: string;
 	intent_revision: number;
 	intent_content_hash: string;
 	preparation_digest: string;
-	actor_id: string;
-	confirmation_ref: string;
-	expires_at: string;
 	nonce: string;
 }
 

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

@@ -1,8 +1,8 @@
 export * from "./types";
 export * from "./intent";
 export * from "./validation";
+export * from "./legacy_task_record";
 export * from "./completion";
-export * from "./legacy";
 // v4 storage retirement: the v1 TaskRecord storage entry points are no
 // longer part of the production kernel surface. Only the v2 store read/commit
 // primitives (used by enrollment/rehearsal/audit) remain exported from
@@ -14,6 +14,8 @@ export {
 	readSecureProjectFile,
 	commitTaskRecordLocked,
 	withKernelStoreLock,
+	withKernelStoreLockForTask,
+	probeKernelStore,
 	serializeWorkspace,
 	revisionForContent,
 	appendJournalEntry,

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

@@ -118,7 +118,6 @@ function riskFloorForScope(scopeHint: string[]): TaskRisk | null {
 		: null;
 }
 
-const SHA256_HEX = /^sha256:[a-f0-9]{64}$/;
 const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const portablePathCollator = new Intl.Collator("und", {
 	usage: "search",
@@ -486,11 +485,9 @@ function resolveCanonicalRoot(root: string): string {
 
 // Resolve a path-less read to the sidecar that actually exists.
 //
-// The active path stays authoritative whenever it is present: that is the
-// pre-freeze layout every path-less caller assumes, and a leftover archived
-// sidecar from an earlier task reusing the same id must never shadow it. Only
-// when the active path is gone — the post-`freeze_artifacts` layout — does the
-// archive answer, which is exactly the case that used to fail with a raw ENOENT.
+// The active path stays authoritative whenever it is present. A leftover
+// archived sidecar from an earlier task reusing the same id must never shadow
+// it. Only when the active path is gone does the historical archive answer.
 function resolveSidecarPath(
 	canonicalRoot: string,
 	activePath: string,
@@ -554,11 +551,10 @@ function readTaskIntentSource(
 	const canonicalRoot = resolveCanonicalRoot(root);
 	const activePath = `${INTENT_SIDECAR_RELATIVE_PREFIX}${taskId}.intent.json`;
 	const archivedPath = `${INTENT_SIDECAR_RELATIVE_PREFIX}archive/${taskId}.intent.json`;
-	// `freeze_artifacts` relocates the sidecar from the active path to the archive
-	// path, so the caller's TaskRecord `intent_ref.path` is the authority. When no
-	// path is requested, resolve the single sidecar that exists rather than
-	// assuming the pre-freeze layout; a missing or ambiguous sidecar is a stable
-	// contract failure, not a raw `lstat` ENOENT.
+	// Freeze binds the sidecar in place. The caller's TaskRecord `intent_ref.path`
+	// is the authority. When no path is requested, resolve the sidecar that exists
+	// (active, else historical archive). A missing sidecar is a stable contract
+	// failure, not a raw `lstat` ENOENT.
 	const sidecarPath = requestedPath ?? resolveSidecarPath(canonicalRoot, activePath, archivedPath);
 	if (sidecarPath !== activePath && sidecarPath !== archivedPath)
 		throw new Error("intent sidecar path is not the active or archived task path");

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

@@ -7,13 +7,16 @@
  * observation, TaskRecord, or workspace state. It never imports, synthesizes,
  * or activates a Kernel TaskRecord from legacy data.
  *
+ * Removal milestone: read-only transitional code. It is deleted in the next
+ * major release, after the release that removes the retired file store.
+ *
  * Not exported from kernel/index.ts; reached only through the v4 CLI
  * `imm-kernel audit --legacy` surface.
  */
 import { createHash } from "node:crypto";
 import { lstatSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { LEGACY_V3_RELATIVE, legacyV3Path } from "./storage_paths";
+import { legacyV3Path } from "./storage_paths";
 
 const MAX_BYTES = 2 * 1024 * 1024;
 

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

@@ -0,0 +1,323 @@
+/**
+ * Frozen historical TaskRecord reader. TaskRecord v2 and v3 are no longer
+ * live contracts: nothing in the reducer/validation/coordinator dispatch
+ * accepts them. This module exists solely so `readAuditTaskPair` can keep
+ * reading `.imm/audit/` evidence written before the v3 drain window closed.
+ * Nothing here changes; it is relocated, not reimplemented.
+ */
+import {
+	TASK_PHASES,
+	TASK_RECORD_CONTRACT_V2,
+	type ApprovalAuthorityRole,
+	type ApprovalKind,
+	type AuthorityAuditDescriptor,
+	type EvidenceStatus,
+	type TaskFinding,
+	type TaskIntentRefV1,
+	type TaskIntentV1,
+	type TaskApprovalV2,
+	type TaskPhase,
+	type TaskRecordV3,
+} from "./types";
+import { canonicalIntentHash, parseTaskIntentV1 } from "./intent";
+import {
+	EVIDENCE_STATUSES,
+	KernelInvariantError,
+	KernelValidationError,
+	SHA256_HEX,
+	arrayAt,
+	enumAt,
+	objectAt,
+	parseApprovalV2,
+	parseFinding,
+	parseTaskRecordAtVersion,
+	positiveInteger,
+	rejectUnknown,
+	stringAt,
+	uniqueIds,
+} from "./validation";
+
+export interface TaskEvidenceV2 {
+	id: string;
+	acceptance_id: string;
+	task_revision: number;
+	intent_content_hash: string;
+	diff_hash: string;
+	status: EvidenceStatus;
+	actor_id: string;
+	summary: string;
+}
+
+export interface TaskHistoryEntryV2 {
+	id: string;
+	at: string;
+	type: string;
+	from_phase: TaskPhase;
+	to_phase: TaskPhase;
+	reason: string;
+	authority?: AuthorityAuditDescriptor;
+}
+
+export interface TaskRecordV2 {
+	contract: typeof TASK_RECORD_CONTRACT_V2;
+	task_id: string;
+	intent_revision: number;
+	intent_snapshot: TaskIntentV1;
+	intent_ref: TaskIntentRefV1;
+	artifact_ref?: { state: "active" | "frozen"; spec_path?: string };
+	phase: TaskPhase;
+	baseline: string;
+	evidence: TaskEvidenceV2[];
+	findings: TaskFinding[];
+	approvals: TaskApprovalV2[];
+	history: TaskHistoryEntryV2[];
+}
+
+function parseHistoryV2(
+	value: unknown,
+	index: number,
+	violations: string[],
+): TaskHistoryEntryV2 {
+	const item = objectAt(value, `record.history[${index}]`, violations);
+	rejectUnknown(
+		item,
+		["id", "at", "type", "from_phase", "to_phase", "reason", "authority"],
+		`record.history[${index}]`,
+		violations,
+	);
+	let authority: AuthorityAuditDescriptor | undefined;
+	if (item.authority !== undefined) {
+		const auth = objectAt(item.authority, `record.history[${index}].authority`, violations);
+		rejectUnknown(
+			auth,
+			["authority_kind", "actor_id", "confirmation_ref", "issued_at", "expires_at"],
+			`record.history[${index}].authority`,
+			violations,
+		);
+		const kind = enumAt(
+			auth.authority_kind,
+			["review", "qa", "user"],
+			`record.history[${index}].authority.authority_kind`,
+			violations,
+		);
+		authority = {
+			authority_kind: kind as AuthorityAuditDescriptor["authority_kind"],
+			actor_id: stringAt(auth.actor_id, `record.history[${index}].authority.actor_id`, violations),
+			confirmation_ref: stringAt(auth.confirmation_ref, `record.history[${index}].authority.confirmation_ref`, violations),
+			issued_at: stringAt(auth.issued_at, `record.history[${index}].authority.issued_at`, violations),
+			expires_at: stringAt(auth.expires_at, `record.history[${index}].authority.expires_at`, violations),
+		};
+	}
+	return {
+		id: stringAt(item.id, `record.history[${index}].id`, violations),
+		at: stringAt(item.at, `record.history[${index}].at`, violations),
+		type: stringAt(item.type, `record.history[${index}].type`, violations),
+		from_phase: enumAt(item.from_phase, TASK_PHASES, `record.history[${index}].from_phase`, violations),
+		to_phase: enumAt(item.to_phase, TASK_PHASES, `record.history[${index}].to_phase`, violations),
+		reason: stringAt(item.reason, `record.history[${index}].reason`, violations),
+		...(authority ? { authority } : {}),
+	};
+}
+
+function parseEvidenceV2(
+	value: unknown,
+	index: number,
+	acceptanceIds: Set<string> | null,
+	violations: string[],
+): TaskEvidenceV2 {
+	const item = objectAt(value, `record.evidence[${index}]`, violations);
+	rejectUnknown(
+		item,
+		["id", "acceptance_id", "task_revision", "intent_content_hash", "diff_hash", "status", "actor_id", "summary"],
+		`record.evidence[${index}]`,
+		violations,
+	);
+	const acceptanceId = stringAt(
+		item.acceptance_id,
+		`record.evidence[${index}].acceptance_id`,
+		violations,
+	);
+	if (acceptanceIds && !acceptanceIds.has(acceptanceId))
+		violations.push(
+			`evidence ${String(item.id)} references unknown acceptance ${acceptanceId}`,
+		);
+	const intentContentHash = stringAt(
+		item.intent_content_hash,
+		`record.evidence[${index}].intent_content_hash`,
+		violations,
+	);
+	if (!SHA256_HEX.test(intentContentHash))
+		violations.push(`record.evidence[${index}].intent_content_hash must be sha256:<64 hex>`);
+	const diffHash = stringAt(item.diff_hash, `record.evidence[${index}].diff_hash`, violations);
+	if (!SHA256_HEX.test(diffHash))
+		violations.push(`record.evidence[${index}].diff_hash must be sha256:<64 hex>`);
+	return {
+		id: stringAt(item.id, `record.evidence[${index}].id`, violations),
+		acceptance_id: acceptanceId,
+		task_revision: positiveInteger(
+			item.task_revision,
+			`record.evidence[${index}].task_revision`,
+			violations,
+		),
+		intent_content_hash: intentContentHash,
+		diff_hash: diffHash,
+		status: enumAt(item.status, EVIDENCE_STATUSES, `record.evidence[${index}].status`, violations),
+		actor_id: stringAt(item.actor_id, `record.evidence[${index}].actor_id`, violations),
+		summary: stringAt(item.summary, `record.evidence[${index}].summary`, violations),
+	};
+}
+
+export function parseTaskRecordV2(raw: unknown): TaskRecordV2 {
+	const violations: string[] = [];
+	const value = objectAt(raw, "record", violations);
+	rejectUnknown(
+		value,
+		["contract", "task_id", "intent_revision", "intent_snapshot", "intent_ref", "artifact_ref", "phase", "baseline", "evidence", "findings", "approvals", "history"],
+		"record",
+		violations,
+	);
+	if (value.contract !== TASK_RECORD_CONTRACT_V2)
+		violations.push(`contract must equal ${TASK_RECORD_CONTRACT_V2}`);
+
+	let snapshot: TaskIntentV1 | null = null;
+	try {
+		snapshot = parseTaskIntentV1(value.intent_snapshot);
+	} catch {
+		violations.push("record.intent_snapshot must be a valid TaskIntent v1");
+	}
+
+	const taskId = stringAt(value.task_id, "record.task_id", violations);
+	const intentRevision = positiveInteger(
+		value.intent_revision,
+		"record.intent_revision",
+		violations,
+	);
+
+	const refRaw = objectAt(value.intent_ref, "record.intent_ref", violations);
+	rejectUnknown(refRaw, ["path", "revision", "content_hash"], "record.intent_ref", violations);
+	const refPath = stringAt(refRaw.path, "record.intent_ref.path", violations);
+	const refRevision = positiveInteger(
+		refRaw.revision,
+		"record.intent_ref.revision",
+		violations,
+	);
+	const refContentHash = stringAt(
+		refRaw.content_hash,
+		"record.intent_ref.content_hash",
+		violations,
+	);
+	if (!SHA256_HEX.test(refContentHash))
+		violations.push("record.intent_ref.content_hash must be sha256:<64 hex>");
+
+	let artifactRef: TaskRecordV2["artifact_ref"];
+	if (value.artifact_ref !== undefined) {
+		const artifactRaw = objectAt(value.artifact_ref, "record.artifact_ref", violations);
+		rejectUnknown(artifactRaw, ["state", "spec_path"], "record.artifact_ref", violations);
+		const state = enumAt(artifactRaw.state, ["active", "frozen"], "record.artifact_ref.state", violations) as "active" | "frozen";
+		const specPath = artifactRaw.spec_path === undefined
+			? undefined
+			: stringAt(artifactRaw.spec_path, "record.artifact_ref.spec_path", violations);
+		if (specPath !== undefined && (!/^docs\/specs\/(?!archive\/)[A-Za-z0-9._/-]+\.spec\.md$/.test(specPath) || specPath.includes("..")))
+			violations.push("record.artifact_ref.spec_path must be one canonical active Spec path");
+		artifactRef = { state, ...(specPath === undefined ? {} : { spec_path: specPath }) };
+	}
+
+	const activeIntentPath = `docs/plans/${taskId}.intent.json`;
+	const frozenIntentPath = `docs/plans/archive/${taskId}.intent.json`;
+	if (
+		snapshot &&
+		(snapshot.task_id !== taskId ||
+			snapshot.revision !== intentRevision ||
+			snapshot.revision !== refRevision ||
+			(refPath !== activeIntentPath && refPath !== frozenIntentPath))
+	)
+		violations.push("intent_snapshot and intent_ref must match record identity");
+	if (artifactRef?.state === "active" && refPath !== activeIntentPath)
+		violations.push("active artifact_ref requires the active intent path");
+	if (artifactRef?.state === "frozen" && refPath !== activeIntentPath && refPath !== frozenIntentPath)
+		violations.push("frozen artifact_ref requires the active or archived intent path");
+	if (
+		snapshot &&
+		refContentHash !== "" &&
+		canonicalIntentHash(snapshot) !== refContentHash
+	)
+		violations.push("intent_ref.content_hash must equal the snapshot canonical hash");
+
+	const baseline = stringAt(value.baseline, "record.baseline", violations);
+	if (!SHA256_HEX.test(baseline))
+		violations.push("record.baseline must be sha256:<64 hex>");
+
+	const acceptanceIds = new Set(
+		snapshot ? snapshot.acceptance.map((item) => item.id) : [],
+	);
+	const evidence = arrayAt(value.evidence, "record.evidence", violations).map(
+		(item, index) => parseEvidenceV2(item, index, acceptanceIds, violations),
+	);
+	const findings = arrayAt(value.findings, "record.findings", violations).map(
+		(item, index) => parseFinding(item, index, violations),
+	);
+	const approvals = arrayAt(value.approvals, "record.approvals", violations).map(
+		(item, index) => parseApprovalV2(item, index, violations),
+	);
+	const history = arrayAt(value.history, "record.history", violations).map(
+		(item, index) => parseHistoryV2(item, index, violations),
+	);
+	uniqueIds(evidence, "record.evidence", violations);
+	uniqueIds(findings, "record.findings", violations);
+	uniqueIds(approvals, "record.approvals", violations);
+	uniqueIds(history, "record.history", violations);
+
+	const phase = enumAt(value.phase, TASK_PHASES, "phase", violations);
+
+	if (violations.length > 0) throw new KernelValidationError(violations);
+	return {
+		contract: TASK_RECORD_CONTRACT_V2,
+		task_id: taskId,
+		intent_revision: intentRevision,
+		intent_snapshot: snapshot as TaskIntentV1,
+		intent_ref: {
+			path: refPath,
+			revision: refRevision,
+			content_hash: refContentHash,
+		},
+		...(artifactRef ? { artifact_ref: artifactRef } : {}),
+		phase,
+		baseline,
+		evidence,
+		findings,
+		approvals,
+		history,
+	};
+}
+
+/** Strict v3 drain parser: unknown fields and revision identity stay illegal. */
+export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
+	return parseTaskRecordAtVersion(raw, 3) as TaskRecordV3;
+}
+
+export function assertKernelInvariantsV2(
+	intentRaw: TaskIntentV1,
+	recordRaw: TaskRecordV2,
+): void {
+	const intent = parseTaskIntentV1(intentRaw);
+	const record = parseTaskRecordV2(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_revision)
+		violations.push("intent revision and record intent_revision must match");
+	if (canonicalIntentHash(record.intent_snapshot) !== record.intent_ref.content_hash)
+		violations.push("record intent_ref.content_hash must match its snapshot");
+	const requiredRole: Record<ApprovalKind, ApprovalAuthorityRole> = {
+		review: "reviewer",
+		qa: "qa",
+		user: "user",
+	};
+	for (const approval of record.approvals) {
+		if (approval.authority_role !== requiredRole[approval.kind])
+			violations.push(
+				`approval ${approval.id} kind ${approval.kind} requires authority_role ${requiredRole[approval.kind]}`,
+			);
+	}
+	if (violations.length > 0) throw new KernelInvariantError(violations);
+}