immune-brain 2.8.2 → 3.0.1

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

@@ -1,10 +1,7 @@
 // P2B2 mutation authority consumption port. NOT exported from kernel/index.ts.
-// Registry/application pairing: each registry owns its capability state in a
-// closure-private WeakMap, and capabilities are only recognized by the
-// registry that issued them. No module-level singleton and no test issuer
-// exist here; the production registry/application pair is created inside the
-// Pi lifecycle extension activation closure, and tests issue capabilities
-// through tests/fixtures/mutation-authority-test-seam.ts.
+// Uses the shared capability registry factory; mutation-specific binding
+// validation, action digest, findings digest enforcement, and projection
+// remain here.
 
 import { createHash } from "node:crypto";
 
@@ -15,6 +12,7 @@ import {
 	type MutationAuthorityKind,
 	type TaskAction,
 } from "./types";
+import { createCapabilityRegistry } from "./capability_registry";
 
 export interface CapabilityBindingV2 {
 	authority_kind: MutationAuthorityKind;
@@ -31,11 +29,6 @@ export interface CapabilityBindingV2 {
 	findings_digest: string | null;
 }
 
-interface CapabilityState extends CapabilityBindingV2 {
-	issued_at: string;
-	consumed: boolean;
-}
-
 export interface ValidatedAuthorityV2 {
 	audit: AuthorityAuditDescriptor;
 	action_digest: string;
@@ -84,125 +77,95 @@ export function digestOfAction(action: TaskAction): string {
 }
 
 export function createMutationAuthorityRegistry(): MutationAuthorityRegistry {
-	const states = new WeakMap<object, CapabilityState>();
-	const brand = Symbol("assurance-kernel-mutation-authority-registry");
-
-	function isCapability(value: unknown): value is MutationAuthorityCapabilityV2 {
-		return (
-			!!value &&
-			typeof value === "object" &&
-			(value as Record<symbol, unknown>)[MUTATION_AUTHORITY_CAPABILITY_BRAND] === true &&
-			(value as Record<symbol, unknown>)[brand] === true
-		);
-	}
-
-	function stateOf(capability: MutationAuthorityCapabilityV2): CapabilityState {
-		const state = states.get(capability);
-		if (!state) throw new Error("authority capability is not recognized by this registry");
-		return state;
-	}
-
-	function validateBinding(binding: CapabilityBindingV2, issuedAt: string): void {
-		const missing: string[] = [];
-		for (const [key, value] of Object.entries(binding)) {
-			if (key === "findings_digest") continue;
-			if (value === undefined || value === null || value === "") missing.push(key);
-		}
-		if (missing.length > 0)
-			throw new Error(`authority capability binding is incomplete: ${missing.join(", ")}`);
-		if (binding.findings_digest !== null && !/^sha256:[a-f0-9]{64}$/.test(binding.findings_digest))
-			throw new Error("authority capability findings_digest must be a canonical sha256 hash");
-		if (Number.isNaN(Date.parse(binding.expires_at)) || Date.parse(binding.expires_at) <= Date.parse(issuedAt))
-			throw new Error("authority capability must have a future expiry");
-	}
-
-	return {
-		brand,
-		issue(binding: CapabilityBindingV2, issuedAt = new Date().toISOString()): MutationAuthorityCapabilityV2 {
-			validateBinding(binding, issuedAt);
-			const capability = Object.freeze(
-				Object.defineProperties(
-					{},
-					{
-						[MUTATION_AUTHORITY_CAPABILITY_BRAND]: {
-							value: true,
-							enumerable: false,
-							writable: false,
-							configurable: false,
-						},
-						[brand]: {
-							value: true,
-							enumerable: false,
-							writable: false,
-							configurable: false,
-						},
+	const inner = createCapabilityRegistry<CapabilityBindingV2, MutationAuthorityInspection, ValidatedAuthorityV2, MutationAuthorityCapabilityV2>(
+		MUTATION_AUTHORITY_CAPABILITY_BRAND,
+		{
+			validateBinding(binding, issuedAt) {
+				const missing: string[] = [];
+				for (const [key, value] of Object.entries(binding)) {
+					if (key === "findings_digest") continue;
+					if (value === undefined || value === null || value === "") missing.push(key);
+				}
+				if (missing.length > 0)
+					throw new Error(`authority capability binding is incomplete: ${missing.join(", ")}`);
+				if (binding.findings_digest !== null && !/^sha256:[a-f0-9]{64}$/.test(binding.findings_digest))
+					throw new Error("authority capability findings_digest must be a canonical sha256 hash");
+				if (Number.isNaN(Date.parse(binding.expires_at)) || Date.parse(binding.expires_at) <= Date.parse(issuedAt))
+					throw new Error("authority capability must have a future expiry");
+			},
+			validateAndProject(state, expected, now) {
+				if (Date.parse(state.expires_at) <= now)
+					throw new Error("authority capability has expired");
+				const actionDigest = digestOfAction(expected.action);
+				if (state.action_digest !== actionDigest)
+					throw new Error("authority capability action digest mismatch");
+				if (state.task_id !== expected.task_id)
+					throw new Error("authority capability task mismatch");
+				if (state.expected_record_hash !== expected.expected_record_hash)
+					throw new Error("authority capability record hash mismatch");
+				if (state.intent_revision !== expected.intent_revision)
+					throw new Error("authority capability intent revision mismatch");
+				if (state.intent_content_hash !== expected.intent_content_hash)
+					throw new Error("authority capability intent hash mismatch");
+				if (state.diff_hash !== expected.diff_hash)
+					throw new Error("authority capability diff hash mismatch");
+				if (expected.findings_digest !== undefined) {
+					if (state.findings_digest === null)
+						throw new Error("authority capability is not bound to findings");
+					if (state.findings_digest !== expected.findings_digest)
+						throw new Error("authority capability findings digest mismatch");
+				}
+				return {
+					audit: {
+						authority_kind: state.authority_kind,
+						actor_id: state.actor_id,
+						confirmation_ref: state.confirmation_ref,
+						issued_at: state.issued_at,
+						expires_at: state.expires_at,
 					},
-				),
-			) as MutationAuthorityCapabilityV2;
-			states.set(capability, {
-				...binding,
-				issued_at: issuedAt,
-				consumed: false,
-			});
-			return capability;
+					action_digest: actionDigest,
+					expected_record_hash: state.expected_record_hash,
+					intent_revision: state.intent_revision,
+					intent_content_hash: state.intent_content_hash,
+					diff_hash: state.diff_hash,
+					task_id: state.task_id,
+				};
+			},
 		},
+		"authority",
+	);
+
+	return {
+		brand: inner.brand,
+		issue: inner.issue.bind(inner),
 		inspect(
 			capability: MutationAuthorityCapabilityV2 | undefined,
 			expected: MutationAuthorityInspection,
 			now = Date.now(),
 		): ValidatedAuthorityV2 {
-			if (!capability || !isCapability(capability))
+			if (!capability)
 				throw new Error("privileged action requires an opaque authority capability");
-			const state = stateOf(capability);
-			if (state.consumed) throw new Error("authority capability is already consumed");
-			if (Date.parse(state.expires_at) <= now)
-				throw new Error("authority capability has expired");
-			const actionDigest = digestOfAction(expected.action);
-			if (state.action_digest !== actionDigest)
-				throw new Error("authority capability action digest mismatch");
-			if (state.task_id !== expected.task_id)
-				throw new Error("authority capability task mismatch");
-			if (state.expected_record_hash !== expected.expected_record_hash)
-				throw new Error("authority capability record hash mismatch");
-			if (state.intent_revision !== expected.intent_revision)
-				throw new Error("authority capability intent revision mismatch");
-			if (state.intent_content_hash !== expected.intent_content_hash)
-				throw new Error("authority capability intent hash mismatch");
-			if (state.diff_hash !== expected.diff_hash)
-				throw new Error("authority capability diff hash mismatch");
-			if (expected.findings_digest !== undefined) {
-				if (state.findings_digest === null)
-					throw new Error("authority capability is not bound to findings");
-				if (state.findings_digest !== expected.findings_digest)
-					throw new Error("authority capability findings digest mismatch");
+			try {
+				return inner.inspect(capability, expected, now);
+			} catch (err) {
+				if (err instanceof Error && err.message.includes("not recognized by this registry"))
+					throw new Error("privileged action requires an opaque authority capability");
+				throw err;
 			}
-			return {
-				audit: {
-					authority_kind: state.authority_kind,
-					actor_id: state.actor_id,
-					confirmation_ref: state.confirmation_ref,
-					issued_at: state.issued_at,
-					expires_at: state.expires_at,
-				},
-				action_digest: actionDigest,
-				expected_record_hash: state.expected_record_hash,
-				intent_revision: state.intent_revision,
-				intent_content_hash: state.intent_content_hash,
-				diff_hash: state.diff_hash,
-				task_id: state.task_id,
-			};
 		},
 		consume(
 			capability: MutationAuthorityCapabilityV2,
 			expected: MutationAuthorityInspection,
 			now = Date.now(),
 		): ValidatedAuthorityV2 {
-			const validated = this.inspect(capability, expected, now);
-			stateOf(capability).consumed = true;
-			return validated;
-		},
-		isConsumed(capability: MutationAuthorityCapabilityV2): boolean {
-			return stateOf(capability).consumed;
+			try {
+				return inner.consume(capability, expected, now);
+			} catch (err) {
+				if (err instanceof Error && err.message.includes("not recognized by this registry"))
+					throw new Error("privileged action requires an opaque authority capability");
+				throw err;
+			}
 		},
+		isConsumed: inner.isConsumed.bind(inner),
 	};
 }

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 ||