immune-brain 2.8.2 → 3.0.1

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

@@ -9,14 +9,14 @@ import {
 	type EnrollmentCapabilityBinding,
 } from "./enrollment_authority";
 import { readTaskTombstone, type BackendClaim } from "./backend_claim";
-import { preparePiCanary } from "./pi_canary_prepare";
+import { preparePiCanary, readGitHead } from "./pi_canary_prepare";
 import {
 	commitEnrollmentLocked,
 	readTaskRecordRaw,
 	readWorkspaceStateRaw,
 	withKernelStoreLock,
 } from "./storage";
-import type { TaskRecordV3, WorkspaceStateLike } from "./types";
+import type { TaskRecord, TaskRecordV4, WorkspaceStateLike } from "./types";
 
 export interface EnrollCanaryInput {
 	task_id: string;
@@ -29,17 +29,121 @@ export interface EnrollCanaryInput {
 }
 
 export interface EnrollCanaryResult {
-	record: TaskRecordV3;
+	record: TaskRecord;
 	backend_claim: BackendClaim;
 	workspace: { revision: string; state: WorkspaceStateLike };
 }
 
-function buildTaskRecordV3(
+type EnrollmentPreconditionState = {
+	validated: ReturnType<EnrollmentAuthorityRegistry["inspect"]> | null;
+	current: ReturnType<typeof readTaskRecordRaw> | null;
+	workspace: ReturnType<typeof readWorkspaceStateRaw> | null;
+	intent: Awaited<ReturnType<typeof readTaskIntent>> | null;
+	gitBaseHead: string | null;
+};
+
+type EnrollmentPreconditionResult = EnrollmentPreconditionState & {
+	blockers: string[];
+};
+
+function runEnrollmentPreconditionChecks<T>(
+	root: string,
+	input: EnrollCanaryInput,
+	capability: object,
+	registry: EnrollmentAuthorityRegistry,
+	mode: "report" | "fail_fast",
+	beforeLock: (validated: EnrollmentPreconditionState["validated"]) => void,
+	onReady: (state: EnrollmentPreconditionState) => T,
+): T;
+function runEnrollmentPreconditionChecks(
+	root: string,
+	input: EnrollCanaryInput,
+	capability: object,
+	registry: EnrollmentAuthorityRegistry,
+	mode: "report" | "fail_fast",
+	beforeLock: (validated: EnrollmentPreconditionState["validated"]) => void,
+): EnrollmentPreconditionResult;
+function runEnrollmentPreconditionChecks<T>(
+	root: string,
+	input: EnrollCanaryInput,
+	capability: object,
+	registry: EnrollmentAuthorityRegistry,
+	mode: "report" | "fail_fast",
+	beforeLock: (validated: EnrollmentPreconditionState["validated"]) => void,
+	onReady?: (state: EnrollmentPreconditionState) => T,
+): T | EnrollmentPreconditionResult {
+	const blockers: string[] = [];
+	let validated: EnrollmentPreconditionState["validated"] = null;
+	try {
+		validated = registry.inspect(capability, input.capability_binding);
+		if (mode === "fail_fast" && validated.task_id !== input.task_id)
+			throw new Error("enrollment capability task mismatch");
+	} catch (error) {
+		if (mode === "fail_fast") throw error;
+		blockers.push(`capability: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	beforeLock(validated);
+
+	return withKernelStoreLock(root, () => {
+		let current: EnrollmentPreconditionState["current"] = null;
+		let workspace: EnrollmentPreconditionState["workspace"] = null;
+		let intent: EnrollmentPreconditionState["intent"] = null;
+		let gitBaseHead: string | null = null;
+		const fail = (report: string, error: unknown) => {
+			if (mode === "fail_fast")
+				throw error instanceof Error ? error : new Error(String(error));
+			blockers.push(report);
+		};
+
+		const tombstone = readTaskTombstone(root, input.task_id);
+		if (tombstone) {
+			fail(
+				"task tombstone exists; same-task re-enrollment is forbidden",
+				new Error(`task ${input.task_id} is terminal; same-task re-enrollment is forbidden`),
+			);
+		} else {
+			current = readTaskRecordRaw(root, input.task_id);
+			if (current.record)
+				fail(
+					"task record already exists",
+					new Error(`task ${input.task_id} already has a TaskRecord`),
+				);
+		}
+		workspace = readWorkspaceStateRaw(root);
+		if (workspace.state.current_working !== null)
+			fail(
+				`workspace already owned by ${workspace.state.current_working}`,
+				new Error(`workspace is already owned by ${workspace.state.current_working}`),
+			);
+		try {
+			intent = readTaskIntent(root, input.task_id);
+		} catch (error) {
+			fail(`intent: ${error instanceof Error ? error.message : String(error)}`, error);
+		}
+		try {
+			gitBaseHead = readGitHead(root);
+		} catch (error) {
+			fail(`git base: ${error instanceof Error ? error.message : String(error)}`, error);
+		}
+
+		const state: EnrollmentPreconditionState = {
+			validated,
+			current,
+			workspace,
+			intent,
+			gitBaseHead,
+		};
+		return onReady ? onReady(state) : { ...state, blockers };
+	});
+}
+
+function buildTaskRecordV4(
 	input: EnrollCanaryInput,
 	intent: Awaited<ReturnType<typeof readTaskIntent>>,
-): TaskRecordV3 {
+	gitBaseHead: string,
+): TaskRecordV4 {
 	return {
-		contract: "assurance_kernel/task_record/v3",
+		contract: "assurance_kernel/task_record/v4",
 		task_id: input.task_id,
 		intent_snapshot: intent.intent,
 		intent_ref: {
@@ -49,6 +153,7 @@ function buildTaskRecordV3(
 		lifecycle: "active",
 		artifact_state: "active",
 		baseline: intent.content_hash,
+		git_base_head: gitBaseHead,
 		attestations: [],
 		findings: [],
 		history: [],
@@ -75,43 +180,25 @@ export function runEnrollmentRehearsal(
 		generated_at: string;
 	};
 } {
-	const blockers: string[] = [];
-	const result = {
+	const preconditions = runEnrollmentPreconditionChecks(
+		root,
+		input,
+		capability,
+		registry,
+		"report",
+		() => undefined,
+	);
+	return {
 		rehearsed: true,
 		writes_performed: false,
 		evidence: {
-			contract: "assurance_kernel/enrollment_rehearsal/v1" as const,
+			contract: "assurance_kernel/enrollment_rehearsal/v1",
 			task_id: input.task_id,
-			outcome: "ready" as "ready" | "not_ready",
-			blockers,
+			outcome: preconditions.blockers.length === 0 ? "ready" : "not_ready",
+			blockers: preconditions.blockers,
 			generated_at: input.now,
 		},
 	};
-	try {
-		// capability inspect (does not consume)
-		registry.inspect(capability, input.capability_binding);
-	} catch (error) {
-		blockers.push(`capability: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	withKernelStoreLock(root, () => {
-		const tombstone = readTaskTombstone(root, input.task_id);
-		if (tombstone) {
-			blockers.push("task tombstone exists; same-task re-enrollment is forbidden");
-		} else {
-			const current = readTaskRecordRaw(root, input.task_id);
-			if (current.record) blockers.push("task record already exists");
-		}
-		const workspace = readWorkspaceStateRaw(root);
-		if (workspace.state.current_working !== null)
-			blockers.push(`workspace already owned by ${workspace.state.current_working}`);
-	});
-	try {
-		readTaskIntent(root, input.task_id);
-	} catch (error) {
-		blockers.push(`intent: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	result.evidence.outcome = blockers.length === 0 ? "ready" : "not_ready";
-	return result;
 }
 
 /**
@@ -124,71 +211,73 @@ export function enrollCanaryTask(
 	input: EnrollCanaryInput,
 	registry: EnrollmentAuthorityRegistry,
 ): EnrollCanaryResult {
-	const validated = registry.inspect(input.capability, input.capability_binding);
-	if (validated.task_id !== input.task_id)
-		throw new Error("enrollment capability task mismatch");
-
-	// v4 storage retirement: the capability is bound to the preparation
-	// digest computed from Kernel owners only. Recompute it inside the store
-	// lock and reject if the owner set changed since the confirmation.
-	const recomputed = preparePiCanary(root, { task_id: input.task_id, now: input.now });
-	if (recomputed.digest !== input.preparation_digest)
-		throw new Error("enrollment preparation digest mismatch");
-
-	return withKernelStoreLock(root, () => {
-		const tombstone = readTaskTombstone(root, input.task_id);
-		if (tombstone)
-			throw new Error(
-				`task ${input.task_id} is terminal; same-task re-enrollment is forbidden`,
-			);
-		const current = readTaskRecordRaw(root, input.task_id);
-		if (current.record)
-			throw new Error(`task ${input.task_id} already has a TaskRecord`);
-		const workspace = readWorkspaceStateRaw(root);
-		if (workspace.state.current_working !== null)
-			throw new Error(`workspace is already owned by ${workspace.state.current_working}`);
-
-		// fresh secure intent reread inside the lock
-		const intent = readTaskIntent(root, input.task_id);
-		if (intent.intent.revision !== input.intent_revision)
-			throw new Error("intent revision mismatch");
+	let gitBaseHead: string | null = null;
+	return runEnrollmentPreconditionChecks(
+		root,
+		input,
+		input.capability,
+		registry,
+		"fail_fast",
+		() => {
+			// v4 storage retirement: the capability is bound to the preparation
+			// digest computed from Kernel owners only. Recompute it before the
+			// locked owner reads and reject if the owner set changed.
+			const recomputed = preparePiCanary(root, { task_id: input.task_id, now: input.now });
+			if (recomputed.digest !== input.preparation_digest)
+				throw new Error("enrollment preparation digest mismatch");
+			gitBaseHead = recomputed.git_base_head;
+			if (!gitBaseHead)
+				throw new Error(recomputed.git_error ?? "enrollment requires a committed Git HEAD");
+		},
+		(checks) => {
+			if (!checks.validated || !checks.intent || !checks.workspace || !checks.current)
+				throw new Error("enrollment precondition state incomplete");
+			if (checks.intent.intent.revision !== input.intent_revision)
+				throw new Error("intent revision mismatch");
+			if (checks.intent.content_hash !== checks.validated.intent_content_hash)
+				throw new Error("intent content hash mismatch");
+			// The confirmation is bound to this exact commit; a moved HEAD means the
+			// operator approved a different base than the one being recorded.
+			if (checks.gitBaseHead !== gitBaseHead)
+				throw new Error("Git HEAD moved after the enrollment confirmation");
 
-		// consume immediately before the marker write
-		registry.consume(input.capability, input.capability_binding);
+			// consume immediately before the marker write
+			registry.consume(input.capability, input.capability_binding);
 
-		const record = buildTaskRecordV3(input, intent);
-		const nextWorkspace: WorkspaceStateLike = {
-			...workspace.state,
-			current_working: input.task_id,
-		};
-		const claim: BackendClaim = {
-			contract: "assurance_kernel/backend_claim/v2",
-			backend: "kernel",
-			task_id: input.task_id,
-			intent_revision: input.intent_revision,
-			intent_content_hash: intent.content_hash,
-			enrollment_event_id: `enroll-${input.task_id}-${input.now}`,
-			lifecycle_status: "active",
-			created_at: input.now,
-			updated_at: input.now,
-		};
-		const mutation = commitEnrollmentLocked(
-			root,
-			input.task_id,
-			{
-				contract: "assurance_kernel/workspace_transaction/v2",
+			const record = buildTaskRecordV4(input, checks.intent, gitBaseHead);
+			const nextWorkspace: WorkspaceStateLike = {
+				...checks.workspace.state,
+				current_working: input.task_id,
+			};
+			const claim: BackendClaim = {
+				contract: "assurance_kernel/backend_claim/v2",
+				backend: "kernel",
 				task_id: input.task_id,
-				expected_record_hash: current.revision,
-				next_record_content: `${JSON.stringify(record, null, 2)}\n`,
-				expected_workspace_hash: workspace.revision,
-				next_workspace_content: `${JSON.stringify(nextWorkspace, null, 2)}\n`,
-			},
-			claim as unknown as Record<string, unknown>,
-		);
-		return {
-			record: mutation.record,
-			backend_claim: claim,
-			workspace: { revision: "", state: mutation.workspace },
-		};
-	});
+				intent_revision: input.intent_revision,
+				intent_content_hash: checks.intent.content_hash,
+				enrollment_event_id: `enroll-${input.task_id}-${input.now}`,
+				lifecycle_status: "active",
+				created_at: input.now,
+				updated_at: input.now,
+			};
+			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>,
+			);
+			return {
+				record: mutation.record,
+				backend_claim: claim,
+				workspace: { revision: "", state: mutation.workspace },
+			};
+		},
+	);
 }

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: "",
 	};