immune-brain 5.3.0 → 5.5.1

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

@@ -41,6 +41,7 @@ import {
 } from "./storage";
 import { KernelInvariantError } from "./validation";
 import type {
+	ReviewRevisionIdentityV1,
 	StoredTaskMutationV3,
 	TaskAction,
 	TaskApprovalV2,
@@ -54,13 +55,21 @@ export type CanaryOperation =
 	| { op: "record_finding"; finding: Omit<TaskFinding, "status" | "source" | "review_round">; actor_id: string }
 	| { op: "resolve_finding"; finding_id: string; actor_id: string }
 	| { op: "refute_finding"; finding_id: string; attestation_id: string; actor_id: string }
-	| { op: "request_rework"; capability: object; findings: TaskFinding[]; actor_id: string }
+	| {
+			op: "request_rework";
+			capability: object;
+			findings: TaskFinding[];
+			actor_id: string;
+			/** Review-authored rework: the immutable revision Review analyzed. */
+			review_revision?: ReviewRevisionIdentityV1;
+	  }
 	| { op: "record_approval"; capability: object; approval: TaskApprovalV2; actor_id: string }
 	| { op: "revise_intent"; next_intent: TaskIntentV1; actor_id: string }
 	| { op: "approve_breaking_intent_revision"; capability: object; next_intent: TaskIntentV1; actor_id: string }
 	| { op: "complete"; actor_id: string }
 	| { op: "stop"; capability: object; reason: string; actor_id: string }
-	| { op: "authorize_rework"; capability: object; actor_id: string }
+	| { op: "authorize_rework"; capability: object; actor_id: string; rounds?: number }
+	| { op: "accept_residual_risk"; capability: object; reason: string; actor_id: string }
 	| { op: "resolve_user_decision"; capability: object; finding_id: string; resolution: string; actor_id: string };
 
 export interface CanaryExecuteInput {
@@ -116,6 +125,17 @@ export function beginDrainCapabilityAction(taskId: string, at: string): TaskActi
  * capability minted against this action's digest always validates.
  * "begin-drain" delegates to the canonical begin_drain action.
  */
+/** Fixed key order so the minted digest equals the parsed action's digest. */
+function canonicalReviewRevision(revision: ReviewRevisionIdentityV1): ReviewRevisionIdentityV1 {
+	return {
+		contract: revision.contract,
+		base_head: revision.base_head,
+		review_commit: revision.review_commit,
+		review_tree: revision.review_tree,
+		manifest_digest: revision.manifest_digest,
+	};
+}
+
 export function capabilityActionFor(input: {
 	op: string;
 	task_id: string;
@@ -128,6 +148,9 @@ export function capabilityActionFor(input: {
 	next_intent_ref?: unknown;
 	finding_id?: string;
 	resolution?: unknown;
+	review_revision?: ReviewRevisionIdentityV1;
+	/** authorize_rework only: further Review rounds granted, 1-5. */
+	rounds?: number;
 }): TaskAction {
 	if (input.op === "begin-drain") {
 		return beginDrainCapabilityAction(input.task_id, input.at);
@@ -148,9 +171,21 @@ export function capabilityActionFor(input: {
 		case "record_approval":
 			return { ...base, approval: input.approval } as TaskAction;
 		case "request_rework":
-			return { ...base, findings: input.findings } as TaskAction;
+			return {
+				...base,
+				findings: input.findings,
+				...(input.review_revision ? { review_revision: canonicalReviewRevision(input.review_revision) } : {}),
+			} as TaskAction;
 		case "authorize_rework":
-			return { ...base, type: "authorize_rework" } as TaskAction;
+			// `rounds` joins the digest only when present, so a legacy caller
+			// keeps the exact digest it always minted.
+			return {
+				...base,
+				type: "authorize_rework",
+				...(input.rounds !== undefined ? { rounds: input.rounds } : {}),
+			} as TaskAction;
+		case "accept_residual_risk":
+			return { ...base, type: "accept_residual_risk", reason: input.reason } as TaskAction;
 		case "stop":
 			return { ...base, reason: input.reason } as TaskAction;
 		case "approve_breaking_intent_revision":
@@ -216,7 +251,7 @@ export function createCanaryApplication(
 				throw new KernelInvariantError([`artifact freeze requires active lifecycle, got ${current.record.lifecycle}`]);
 			if (workspace.state.current_working !== input.task_id)
 				throw new KernelInvariantError([`workspace is not owned by task ${input.task_id}`]);
-			const fresh = readTaskIntent(input.root, input.task_id, current.record.intent_ref.path);
+			const fresh = readTaskIntent(input.root, input.task_id, current.record.intent_ref.path, current.record.intent_snapshot);
 			const pair = inspectIntentTokenPair(input.prior_intent_token, fresh.token);
 			if (
 				pair.prior.intent_content_hash !== current.record.intent_ref.content_hash
@@ -376,7 +411,14 @@ export function createCanaryApplication(
 				break;
 			case "request_rework":
 				capability = operation.capability;
-				action = { ...base, type: "request_rework", findings: operation.findings };
+				action = {
+					...base,
+					type: "request_rework",
+					findings: operation.findings,
+					...(operation.review_revision
+						? { review_revision: canonicalReviewRevision(operation.review_revision) }
+						: {}),
+				};
 				break;
 			case "record_approval":
 				capability = operation.capability;
@@ -414,7 +456,15 @@ export function createCanaryApplication(
 				break;
 			case "authorize_rework":
 				capability = operation.capability;
-				action = { ...base, type: "authorize_rework" };
+				action = {
+					...base,
+					type: "authorize_rework",
+					...(operation.rounds !== undefined ? { rounds: operation.rounds } : {}),
+				};
+				break;
+			case "accept_residual_risk":
+				capability = operation.capability;
+				action = { ...base, type: "accept_residual_risk", reason: operation.reason };
 				break;
 			case "resolve_user_decision":
 				capability = operation.capability;

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

@@ -1,4 +1,5 @@
 import { classifyTaskRisk } from "./intent";
+import { NO_RISK_FLOOR, raiseRisk, scopeRiskFloor, type RiskFloor } from "./risk_floor";
 import { archivePath, boundSpecPath, inspectSpecBinding } from "./spec_binding";
 import type {
 	ApprovalKind,
@@ -48,13 +49,16 @@ export function asTaskDiffSnapshot(value: TaskDiffInput): {
 export function resolveProjectedRisk(
 	intent: TaskIntentV1,
 	changedPaths: readonly string[] = [],
+	floor: RiskFloor = NO_RISK_FLOOR,
 ): TaskIntentV1["risk"] {
+	const risk = raiseRisk(intent.risk, scopeRiskFloor(intent.scope_hint, floor));
 	// Invalid bindings have no trusted planning-path exclusions.
-	if (!inspectSpecBinding(intent).ok) return classifyTaskRisk(changedPaths, intent.risk);
+	if (!inspectSpecBinding(intent).ok) return classifyTaskRisk(changedPaths, risk, floor);
 	const excluded = ownSidecarPaths(intent);
 	return classifyTaskRisk(
 		changedPaths.filter((path) => !excluded.has(path)),
-		intent.risk,
+		risk,
+		floor,
 	);
 }
 
@@ -80,6 +84,7 @@ export function completionDecision(
 	currentDiffHash: string,
 	currentIntentContentHash: string,
 	changedPaths: readonly string[] = [],
+	floor: RiskFloor = NO_RISK_FLOOR,
 ): CompletionDecision {
 	assertKernelInvariantsV3(intent, record);
 	const freshAttestations = record.attestations.filter(
@@ -108,7 +113,22 @@ export function completionDecision(
 		)
 		.map((item) => item.id);
 
-	const requiredKinds = REQUIRED_ATTESTATIONS[resolveProjectedRisk(intent, changedPaths)];
+	// A literal-user residual-risk acceptance stands in for the Review
+	// approval only while it names this exact intent revision, intent hash and
+	// diff, and every finding it accepted is still accepted. QA, acceptance and
+	// every other obligation are unaffected, and any later change makes it stale.
+	const acceptance = record.residual_risk_acceptance;
+	const residualRiskAccepted =
+		acceptance !== undefined &&
+		acceptance.intent_revision === intent.revision &&
+		acceptance.intent_content_hash === currentIntentContentHash &&
+		acceptance.diff_hash === currentDiffHash &&
+		acceptance.finding_ids.every((id) =>
+			record.findings.some((item) => item.id === id && item.status === "accepted_risk"),
+		);
+	const requiredKinds = REQUIRED_ATTESTATIONS[
+		resolveProjectedRisk(intent, changedPaths, floor)
+	].filter((kind) => !(residualRiskAccepted && kind === "review"));
 	const candidates = freshAttestations.filter((item) => requiredKinds.includes(item.kind));
 	const missingApprovalKinds = requiredKinds.filter(
 		(kind) => !candidates.some((attestation) => attestation.kind === kind),
@@ -160,6 +180,8 @@ export function completionDecision(
 
 	return {
 		complete:
+			// An invalid Spec binding is never complete, whatever the project's floor says.
+			inspectSpecBinding(intent).ok &&
 			missingAcceptanceIds.length === 0 &&
 			missingApprovalKinds.length === 0 &&
 			blockingFindingIds.length === 0 &&
@@ -183,6 +205,7 @@ export function projectTask(
 	currentDiffHash: string,
 	currentIntentContentHash: string,
 	changedPaths: readonly string[] = [],
+	floor: RiskFloor = NO_RISK_FLOOR,
 ): TaskProjectionV3 {
 	if (record.lifecycle === "active" && !inspectSpecBinding(intent).ok) {
 		assertKernelInvariantsV3(intent, record);
@@ -198,7 +221,7 @@ export function projectTask(
 			fresh_acceptance_ids: [],
 			missing_acceptance_ids: intent.acceptance.map((item) => item.id),
 			stale_attestation_ids: record.attestations.map((item) => item.id),
-			missing_approval_kinds: REQUIRED_ATTESTATIONS[resolveProjectedRisk(intent, changedPaths)],
+			missing_approval_kinds: REQUIRED_ATTESTATIONS[resolveProjectedRisk(intent, changedPaths, floor)],
 			blocking_finding_ids: record.findings.filter((item) => item.kind === "blocking" && item.status !== "resolved").map((item) => item.id),
 			unresolved_user_decision_ids: record.findings.filter((item) => item.kind === "unresolved_user_decision" && item.status === "open").map((item) => item.id),
 			replan_required_ids: record.findings.filter((item) => item.kind === "replan_required" && item.status === "open").map((item) => item.id),
@@ -211,6 +234,7 @@ export function projectTask(
 		currentDiffHash,
 		currentIntentContentHash,
 		changedPaths,
+		floor,
 	);
 	const blocked =
 		decision.blocking_finding_ids.length > 0 ||

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

@@ -54,9 +54,35 @@ export interface EnrollCanaryInput {
 	capability: object;
 	capability_binding: EnrollmentCapabilityBinding;
 	batch?: EnrollBatchContext;
+	/**
+	 * The in-scope paths the confirmed Enrollment gate listed as already staged,
+	 * modified or untracked. Only these are claimed as task work; absent means
+	 * the gate listed none, so any in-scope dirt refuses the Enrollment.
+	 */
+	disclosed_scope_paths?: readonly string[];
 	now: string;
 }
 
+/**
+ * What an Enrollment gate must show about a scope that is already dirty: the
+ * paths, and the one line both Hosts print for them. A scope that cannot be
+ * inspected discloses nothing, and the Enrollment itself reports why.
+ */
+export function enrollmentScopeDisclosure(root: string, taskId: string): { paths: string[]; notice: string | null } {
+	let paths: string[] = [];
+	try {
+		paths = dirtyScopePaths(root, readTaskIntent(root, taskId).intent.scope_hint, taskId);
+	} catch {
+		return { paths: [], notice: null };
+	}
+	return {
+		paths,
+		notice: paths.length === 0
+			? null
+			: `In-scope changes that already exist (${paths.length}) and become task work on confirmation: ${paths.join(", ")}`,
+	};
+}
+
 /**
  * A rehearsal that is not ready rejects through this single typed error so the
  * "Kernel enrollment rehearsal failed" message is produced in exactly one place
@@ -80,6 +106,8 @@ export interface EnrollmentEntryRequest {
 	binding: EnrollmentCapabilityBinding;
 	/** Present only for a batch-derived child enrollment. */
 	batch?: EnrollBatchContext;
+	/** The in-scope paths the confirmed gate listed; see `EnrollCanaryInput`. */
+	disclosed_scope_paths?: readonly string[];
 	now: string;
 	/**
 	 * Optional caller checkpoint run after a ready rehearsal and before the
@@ -111,6 +139,8 @@ type EnrollmentPreconditionState = {
 	workspace: ReturnType<typeof readWorkspaceStateRaw> | null;
 	intent: Awaited<ReturnType<typeof readTaskIntent>> | null;
 	gitBaseHead: string | null;
+	/** In-scope dirt the confirmed gate listed; left out of the Enrollment baseline. */
+	claimedScopePaths: string[];
 };
 
 type EnrollmentPreconditionResult = EnrollmentPreconditionState & {
@@ -160,6 +190,7 @@ function runEnrollmentPreconditionChecks<T>(
 		let workspace: EnrollmentPreconditionState["workspace"] = null;
 		let intent: EnrollmentPreconditionState["intent"] = null;
 		let gitBaseHead: string | null = null;
+		let claimedScopePaths: string[] = [];
 		const fail = (report: string, error: unknown) => {
 			if (mode === "fail_fast")
 				throw error instanceof Error ? error : new Error(String(error));
@@ -210,16 +241,20 @@ function runEnrollmentPreconditionChecks<T>(
 		} catch (error) {
 			fail(`git base: ${error instanceof Error ? error.message : String(error)}`, error);
 		}
-		// In-scope dirt present now would be recorded in the Enrollment baseline as
-		// user dirt and withheld from every later task snapshot, so the task could
-		// never deliver it. Refuse before the capability is consumed.
+		// In-scope dirt the confirmed gate listed is claimed: it is left out of the
+		// Enrollment baseline and becomes task work. Any other in-scope dirt would
+		// be recorded there as user dirt and withheld from every later task
+		// snapshot, so the task could never deliver it. Refuse that before the
+		// capability is consumed; nothing is claimed that the gate did not show.
 		if (intent && gitBaseHead) {
 			try {
+				const disclosed = new Set(input.disclosed_scope_paths ?? []);
 				const dirty = dirtyScopePaths(root, intent.intent.scope_hint, input.task_id);
-				if (dirty.length > 0) {
-					const message = `task scope is already dirty before Enrollment: ${dirty.join(", ")}; commit, stash or revert these paths first`;
+				const unlisted = dirty.filter((path) => !disclosed.has(path));
+				if (unlisted.length > 0) {
+					const message = `task scope is already dirty before Enrollment: ${unlisted.join(", ")}; the confirmed Enrollment gate did not list these paths, so enroll again from the Host to review them`;
 					fail(message, new Error(message));
-				}
+				} else claimedScopePaths = dirty;
 			} catch (error) {
 				fail(`scope: ${error instanceof Error ? error.message : String(error)}`, error);
 			}
@@ -231,6 +266,7 @@ function runEnrollmentPreconditionChecks<T>(
 			workspace,
 			intent,
 			gitBaseHead,
+			claimedScopePaths,
 		};
 		return onReady ? onReady(state) : { ...state, blockers };
 	});
@@ -276,6 +312,8 @@ export function runEnrollmentRehearsal(
 		task_id: string;
 		outcome: "ready" | "not_ready";
 		blockers: string[];
+		/** In-scope dirt the gate listed, which this Enrollment would claim as task work. */
+		claimed_scope_paths: string[];
 		generated_at: string;
 	};
 } {
@@ -295,6 +333,7 @@ export function runEnrollmentRehearsal(
 			task_id: input.task_id,
 			outcome: preconditions.blockers.length === 0 ? "ready" : "not_ready",
 			blockers: preconditions.blockers,
+			claimed_scope_paths: preconditions.claimedScopePaths,
 			generated_at: input.now,
 		},
 	};
@@ -357,7 +396,7 @@ export async function enrollTask(
 	registry: EnrollmentAuthorityRegistry,
 	request: EnrollmentEntryRequest,
 ): Promise<EnrollCanaryResult | EnrollmentEntryOutcome> {
-	const { binding, batch, now, checkpoint } = request;
+	const { binding, batch, now, checkpoint, disclosed_scope_paths } = request;
 	// (1) Issue the capability for the supplied binding.
 	const capability = registry.issue(binding);
 	const input: EnrollCanaryInput = {
@@ -368,6 +407,7 @@ export async function enrollTask(
 		capability,
 		capability_binding: binding,
 		...(batch ? { batch } : {}),
+		...(disclosed_scope_paths ? { disclosed_scope_paths } : {}),
 		now,
 	};
 	// Replay of a lost Enrollment: the exact request already committed here, so
@@ -554,7 +594,7 @@ export function enrollCanaryTask(
 				claim as unknown as Record<string, unknown>,
 				digest,
 			);
-			writeEnrollmentBaseline(root);
+			writeEnrollmentBaseline(root, checks.claimedScopePaths);
 			return {
 				record: mutation.record,
 				backend_claim: claim,