immune-brain 2.8.3 → 3.0.2

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

@@ -12,6 +12,7 @@ import {
 	type MutationAuthorityRegistry,
 } from "./authority_port";
 import { applyTaskAction } from "./application";
+import { asTaskDiffSnapshot } from "./completion";
 import { readTaskIntent } from "./intent";
 import {
 	inspectIntentTokenPair,
@@ -23,7 +24,7 @@ import {
 	type BackendClaim,
 } from "./backend_claim";
 import { canonicalIntentHash } from "./intent";
-import { parseTaskRecordV3 } from "./validation";
+import { parseTaskRecord } from "./validation";
 import type { TaskIntentIdentityToken } from "./intent_token_registry";
 import {
 	commitDrainLocked,
@@ -41,6 +42,7 @@ import type {
 	TaskApprovalV2,
 	TaskFinding,
 	TaskIntentV1,
+	TaskRecord,
 } from "./types";
 
 export type CanaryOperation =
@@ -62,7 +64,7 @@ export interface CanaryExecuteInput {
 	operation: CanaryOperation;
 	prior_intent_token: TaskIntentIdentityToken;
 	/** Trusted injected diff provider; the application derives the diff identity. */
-	diffProvider: (root: string, intent: TaskIntentV1) => string;
+	diffProvider: (root: string, record: TaskRecord) => string | { diff_hash: string; changed_paths?: readonly string[] };
 	now?: string;
 }
 
@@ -264,7 +266,7 @@ export function createCanaryApplication(
 			consumeIntentToken(input.prior_intent_token);
 			consumeIntentToken(fresh.token);
 			const at = input.now ?? new Date().toISOString();
-			const nextRecord = parseTaskRecordV3({
+			const nextRecord = parseTaskRecord({
 				...current.record,
 				intent_ref: { ...current.record.intent_ref, path: transition.next_intent_path },
 				artifact_state: transition.next_artifact_state,
@@ -318,7 +320,7 @@ export function createCanaryApplication(
 				record: current.record,
 			};
 		});
-		const diffHash = input.diffProvider(input.root, snapshot.intent_snapshot);
+		const diffHash = asTaskDiffSnapshot(input.diffProvider(input.root, snapshot.record)).diff_hash;
 		if (operation.op === "stop" && !("capability" in operation))
 			throw new KernelInvariantError(["stop requires user authority capability"]);
 		const hasBoundSpec = snapshot.intent_snapshot.scope_hint.some(

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

@@ -0,0 +1,89 @@
+// Shared opaque capability registry primitive. NOT exported from kernel/index.ts.
+// Each registry owns its WeakMap; capabilities are only recognized by the
+// registry that issued them. No module-level singleton.
+
+export interface CapabilityRegistryHooks<TBinding, TExpected, TValidated> {
+	/** Validate the binding at issue time. Throw on invalid input. */
+	validateBinding(binding: TBinding, issuedAt: string): void;
+	/** Validate stored state against expected input at inspect time. Return the domain-specific validated result. */
+	validateAndProject(
+		state: TBinding & { issued_at: string },
+		expected: TExpected,
+		now: number,
+	): TValidated;
+}
+
+export interface CapabilityRegistry<TBinding, TExpected, TValidated, TCapability> {
+	readonly brand: symbol;
+	issue(binding: TBinding, issuedAt?: string): TCapability;
+	inspect(capability: TCapability, expected: TExpected, now?: number): TValidated;
+	consume(capability: TCapability, expected: TExpected, now?: number): TValidated;
+	isConsumed(capability: TCapability): boolean;
+}
+
+interface StoredState<TBinding> {
+	binding: TBinding;
+	issued_at: string;
+	consumed: boolean;
+}
+
+export function createCapabilityRegistry<TBinding, TExpected, TValidated, TCapability = object>(
+	capabilityBrand: symbol,
+	hooks: CapabilityRegistryHooks<TBinding, TExpected, TValidated>,
+	domainLabel: string,
+): CapabilityRegistry<TBinding, TExpected, TValidated, TCapability> {
+	const states = new WeakMap<object, StoredState<TBinding>>();
+	const brand = Symbol(`${domainLabel}-registry`);
+
+	function isCapability(value: unknown): value is TCapability {
+		return (
+			!!value &&
+			typeof value === "object" &&
+			(value as Record<symbol, unknown>)[capabilityBrand] === true &&
+			(value as Record<symbol, unknown>)[brand] === true
+		);
+	}
+
+	function stateOf(capability: TCapability): StoredState<TBinding> {
+		const state = states.get(capability as object);
+		if (!state) throw new Error(`${domainLabel} capability is not recognized by this registry`);
+		return state;
+	}
+
+	return {
+		brand,
+		issue(binding: TBinding, issuedAt = new Date().toISOString()): TCapability {
+			hooks.validateBinding(binding, issuedAt);
+			const capability = Object.freeze(
+				Object.defineProperties(
+					{},
+					{
+						[capabilityBrand]: { value: true, enumerable: false, writable: false, configurable: false },
+						[brand]: { value: true, enumerable: false, writable: false, configurable: false },
+					},
+				),
+			) as TCapability;
+			states.set(capability as object, { binding: { ...binding }, issued_at: issuedAt, consumed: false });
+			return capability;
+		},
+		inspect(capability: TCapability, expected: TExpected, now = Date.now()): TValidated {
+			if (!isCapability(capability))
+				throw new Error(`${domainLabel} capability is not recognized by this registry`);
+			const state = stateOf(capability);
+			if (state.consumed) throw new Error(`${domainLabel} capability already consumed`);
+			return hooks.validateAndProject(
+				{ ...state.binding, issued_at: state.issued_at },
+				expected,
+				now,
+			);
+		},
+		consume(capability: TCapability, expected: TExpected, now = Date.now()): TValidated {
+			const validated = this.inspect(capability, expected, now);
+			stateOf(capability).consumed = true;
+			return validated;
+		},
+		isConsumed(capability: TCapability): boolean {
+			return stateOf(capability).consumed;
+		},
+	};
+}

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

@@ -1,12 +1,13 @@
+import { classifyTaskRisk } from "./intent";
 import type {
 	ApprovalKind,
 	CompletionDecision,
 	TaskAttestationV3,
 	TaskIntentV1,
 	TaskProjectionV3,
-	TaskRecordV3,
+	TaskRecord,
 } from "./types";
-import { assertKernelInvariantsV3 } from "./validation";
+import { assertKernelInvariantsV3, KernelInvariantError } from "./validation";
 
 const REQUIRED_ATTESTATIONS: Record<TaskIntentV1["risk"], ApprovalKind[]> = {
 	routine: ["qa"],
@@ -14,6 +15,55 @@ const REQUIRED_ATTESTATIONS: Record<TaskIntentV1["risk"], ApprovalKind[]> = {
 	critical: ["qa", "review", "user"],
 };
 
+function archiveActivePlanningPath(path: string): string | null {
+	const matched = path.match(/^docs\/(plans|specs)\/([^/]+)$/);
+	return matched ? `docs/${matched[1]}/archive/${matched[2]}` : null;
+}
+
+function ownSidecarPaths(intent: TaskIntentV1): Set<string> {
+	const activeIntent = `docs/plans/${intent.task_id}.intent.json`;
+	const archivedIntent = archiveActivePlanningPath(activeIntent);
+	const excluded = new Set<string>([activeIntent]);
+	if (archivedIntent) excluded.add(archivedIntent);
+	const specs = intent.scope_hint.filter((path) => {
+		const archived = archiveActivePlanningPath(path);
+		return archived !== null && /^docs\/specs\/[^/]+\.spec\.md$/.test(path) && intent.scope_hint.includes(archived);
+	});
+	if (specs.length > 1) {
+		throw new KernelInvariantError([
+			`artifact transition requires at most one scope-bound Spec; found ${specs.length}`,
+		]);
+	}
+	const spec = specs[0];
+	if (spec) {
+		excluded.add(spec);
+		const archived = archiveActivePlanningPath(spec);
+		if (archived) excluded.add(archived);
+	}
+	return excluded;
+}
+
+export type TaskDiffInput = string | { diff_hash: string; changed_paths?: readonly string[] };
+
+export function asTaskDiffSnapshot(value: TaskDiffInput): {
+	diff_hash: string;
+	changed_paths?: readonly string[];
+} {
+	if (typeof value === "string") return { diff_hash: value };
+	return { diff_hash: value.diff_hash, changed_paths: value.changed_paths };
+}
+
+export function resolveProjectedRisk(
+	intent: TaskIntentV1,
+	changedPaths: readonly string[] = [],
+): TaskIntentV1["risk"] {
+	const excluded = ownSidecarPaths(intent);
+	return classifyTaskRisk(
+		changedPaths.filter((path) => !excluded.has(path)),
+		intent.risk,
+	);
+}
+
 function hasDistinctAuthorityAssignment(
 	required: ApprovalKind[],
 	candidates: TaskAttestationV3[],
@@ -32,9 +82,10 @@ function hasDistinctAuthorityAssignment(
 
 export function completionDecision(
 	intent: TaskIntentV1,
-	record: TaskRecordV3,
+	record: TaskRecord,
 	currentDiffHash: string,
 	currentIntentContentHash: string,
+	changedPaths: readonly string[] = [],
 ): CompletionDecision {
 	assertKernelInvariantsV3(intent, record);
 	const freshAttestations = record.attestations.filter(
@@ -63,7 +114,7 @@ export function completionDecision(
 		)
 		.map((item) => item.id);
 
-	const requiredKinds = REQUIRED_ATTESTATIONS[intent.risk];
+	const requiredKinds = REQUIRED_ATTESTATIONS[resolveProjectedRisk(intent, changedPaths)];
 	const candidates = freshAttestations.filter((item) => requiredKinds.includes(item.kind));
 	const missingApprovalKinds = requiredKinds.filter(
 		(kind) => !candidates.some((attestation) => attestation.kind === kind),
@@ -117,11 +168,18 @@ export function completionDecision(
 
 export function projectTask(
 	intent: TaskIntentV1,
-	record: TaskRecordV3,
+	record: TaskRecord,
 	currentDiffHash: string,
 	currentIntentContentHash: string,
+	changedPaths: readonly string[] = [],
 ): TaskProjectionV3 {
-	const decision = completionDecision(intent, record, currentDiffHash, currentIntentContentHash);
+	const decision = completionDecision(
+		intent,
+		record,
+		currentDiffHash,
+		currentIntentContentHash,
+		changedPaths,
+	);
 	const blocked =
 		decision.blocking_finding_ids.length > 0 ||
 		decision.unresolved_user_decision_ids.length > 0 ||

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 },
+			};
+		},
+	);
 }