immune-brain 3.6.3 → 3.6.5

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

@@ -55,6 +55,7 @@ export type CanaryOperation =
 	| { 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: "resolve_user_decision"; capability: object; finding_id: string; resolution: string; actor_id: string };
 
 export interface CanaryExecuteInput {
@@ -142,6 +143,8 @@ export function capabilityActionFor(input: {
 			return { ...base, approval: input.approval } as TaskAction;
 		case "request_rework":
 			return { ...base, findings: input.findings } as TaskAction;
+		case "authorize_rework":
+			return { ...base, type: "authorize_rework" } as TaskAction;
 		case "stop":
 			return { ...base, reason: input.reason } as TaskAction;
 		case "approve_breaking_intent_revision":
@@ -326,15 +329,17 @@ export function createCanaryApplication(
 		);
 		if (operation.op === "complete" && hasBoundSpec && snapshot.record.artifact_state !== "frozen")
 			throw new KernelInvariantError(["complete requires frozen planning artifacts"]);
-		const artifactTransition = snapshot.record.artifact_state === "frozen"
-			&& (
-				operation.op === "request_rework"
-				|| operation.op === "approve_breaking_intent_revision"
+		const artifactTransition =
+			snapshot.record.artifact_state === "frozen" &&
+			(
+				operation.op === "request_rework" ||
+				operation.op === "authorize_rework" ||
+				operation.op === "approve_breaking_intent_revision"
 			)
-			? transitionFor(input.root, snapshot.record, "restore")
-			: operation.op === "stop" && snapshot.record.artifact_state !== "frozen"
-				? transitionFor(input.root, snapshot.record, "freeze", true)
-				: undefined;
+				? transitionFor(input.root, snapshot.record, "restore")
+				: operation.op === "stop" && snapshot.record.artifact_state !== "frozen"
+					? transitionFor(input.root, snapshot.record, "freeze", true)
+					: undefined;
 		const event_id = `${operation.op}:${input.task_id}:${at}`;
 		const base = {
 			event_id,
@@ -400,6 +405,10 @@ export function createCanaryApplication(
 				capability = operation.capability;
 				action = { ...base, type: "stop", reason: operation.reason };
 				break;
+			case "authorize_rework":
+				capability = operation.capability;
+				action = { ...base, type: "authorize_rework" };
+				break;
 			case "resolve_user_decision":
 				capability = operation.capability;
 				action = {

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

@@ -8,6 +8,10 @@ import {
 	type EnrollmentAuthorityRegistry,
 	type EnrollmentCapabilityBinding,
 } from "./enrollment_authority";
+import type {
+	BatchAuthorityRegistry,
+	BatchAuthorizationBinding,
+} from "./batch_authority";
 import { readTaskTombstone, type BackendClaim } from "./backend_claim";
 import { preparePiCanary, readGitHead } from "./pi_canary_prepare";
 import {
@@ -18,6 +22,19 @@ import {
 } from "./storage";
 import type { TaskRecord, TaskRecordV4, WorkspaceStateLike } from "./types";
 
+/**
+ * Present only for a batch-derived enrollment. The child slot is consumed
+ * inside the same store lock as the TaskRecord write and released again if that
+ * write does not commit, so a consumed slot and a TaskRecord always agree.
+ */
+export interface EnrollBatchContext {
+	registry: BatchAuthorityRegistry;
+	capability: object;
+	binding: BatchAuthorizationBinding;
+	/** base_head, then each commit this batch created on its own branch. */
+	expected_head: string;
+}
+
 export interface EnrollCanaryInput {
 	task_id: string;
 	intent_path: string;
@@ -25,6 +42,7 @@ export interface EnrollCanaryInput {
 	preparation_digest: string;
 	capability: object;
 	capability_binding: EnrollmentCapabilityBinding;
+	batch?: EnrollBatchContext;
 	now: string;
 }
 
@@ -241,9 +259,46 @@ export function enrollCanaryTask(
 			if (checks.gitBaseHead !== gitBaseHead)
 				throw new Error("Git HEAD moved after the enrollment confirmation");
 
+			// A batch-derived enrollment must still stand on the lineage the
+			// literal user confirmed: child N's base is the commit child N-1
+			// produced on the batch branch, and child 1's base is base_head.
+			// expected_head is caller-supplied, so anchor its origin here rather
+			// than trusting the caller's own assertion: before this batch has
+			// consumed any slot it has created no commit, so the only lineage
+			// value it can hold is the confirmed base_head.
+			if (input.batch) {
+				const batch = input.batch.registry.inspect(
+					input.batch.capability,
+					input.batch.binding,
+					Date.parse(input.now),
+				);
+				if (
+					input.batch.registry.consumedChildren(input.batch.capability).length === 0 &&
+					input.batch.expected_head !== batch.base_head
+				)
+					throw new Error(
+						`batch_head_lineage_broken: the first child must enroll on the confirmed base_head ${batch.base_head}, not ${input.batch.expected_head}`,
+					);
+				if (checks.gitBaseHead !== input.batch.expected_head)
+					throw new Error(
+						`batch_head_lineage_broken: expected ${input.batch.expected_head}, found ${checks.gitBaseHead}`,
+					);
+			}
+
 			// consume immediately before the marker write
 			registry.consume(input.capability, input.capability_binding);
+			if (input.batch)
+				input.batch.registry.consumeChild(
+					input.batch.capability,
+					input.batch.binding,
+					input.task_id,
+					Date.parse(input.now),
+				);
 
+			// Set by beforeLock above, which throws when the repository has no
+			// committed HEAD. Re-assert it here: the compiler cannot carry a
+			// closure's narrowing across to this one.
+			if (!gitBaseHead) throw new Error("enrollment requires a committed Git HEAD");
 			const record = buildTaskRecordV4(input, checks.intent, gitBaseHead);
 			const nextWorkspace: WorkspaceStateLike = {
 				...checks.workspace.state,
@@ -260,19 +315,27 @@ export function enrollCanaryTask(
 				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>,
-			);
+			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;
+			}
 			return {
 				record: mutation.record,
 				backend_claim: claim,

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

@@ -19,6 +19,8 @@ export {
 	appendJournalEntry,
 	KernelStoreSecurityError,
 	setAfterTaskTransactionWriteForTest,
+	type JournalEntry,
+	type JournalReasonCode,
 } from "./storage";
 export {
 	reduceTask,

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

@@ -27,6 +27,7 @@ import {
 import {
 	mintToken,
 	type TaskIntentIdentityToken,
+	type TokenIdentity,
 } from "./intent_token_registry";
 
 export const INTENT_MAX_BYTES = 64 * 1024;
@@ -406,6 +407,26 @@ export interface ReadTaskIntentResult {
 	token: TaskIntentIdentityToken;
 }
 
+export interface ObservedTaskIntent {
+	intent: TaskIntentV1;
+	content_hash: string;
+	intent_ref: TaskIntentRefV1;
+}
+
+export class TaskIntentObservationError extends Error {
+	readonly code: "missing" | "invalid";
+
+	constructor(code: "missing" | "invalid", message: string) {
+		super(message);
+		this.name = "TaskIntentObservationError";
+		this.code = code;
+	}
+}
+
+interface TaskIntentReadSource extends ObservedTaskIntent {
+	identity: TokenIdentity;
+}
+
 export function setIntentReaderTestHook(
 	hook: { onBeforeDescriptorRead?: () => void } | null,
 ): void {
@@ -523,11 +544,11 @@ function assertIdentitiesUnchanged(
 	}
 }
 
-export function readTaskIntent(
+function readTaskIntentSource(
 	root: string,
 	taskId: string,
 	requestedPath?: string,
-): ReadTaskIntentResult {
+): TaskIntentReadSource {
 	validateTaskId(taskId);
 
 	const canonicalRoot = resolveCanonicalRoot(root);
@@ -545,7 +566,7 @@ export function readTaskIntent(
 	if (!target.startsWith(canonicalRoot + sep))
 		throw new Error("intent sidecar escapes project root");
 	if (!sidecarPresent(canonicalRoot, sidecarPath))
-		throw new Error(`TaskIntent sidecar is missing at ${sidecarPath}`);
+		throw new TaskIntentObservationError("missing", `TaskIntent sidecar is missing at ${sidecarPath}`);
 
 	const pathIdentities = collectPathIdentities(canonicalRoot, sidecarPath);
 	const fileIdentity = pathIdentities[pathIdentities.length - 1];
@@ -557,13 +578,19 @@ export function readTaskIntent(
 			["ls-files", "--error-unmatch", "--", sidecarPath],
 			{ cwd: canonicalRoot, stdio: ["ignore", "pipe", "pipe"] },
 		);
-	} catch {
-		throw new Error("TaskIntent sidecar is not Git-tracked");
+	} catch (error) {
+		if (
+			typeof error === "object"
+			&& error !== null
+			&& "status" in error
+			&& (error as { status?: unknown }).status === 1
+		) throw new TaskIntentObservationError("invalid", "TaskIntent sidecar is not Git-tracked");
+		throw error;
 	}
 
 	const before = lstatSync(target);
 	if (!before.isFile() || before.size > INTENT_MAX_BYTES)
-		throw new Error("TaskIntent sidecar must be a regular file no larger than 64 KiB");
+		throw new TaskIntentObservationError("invalid", "TaskIntent sidecar must be a regular file no larger than 64 KiB");
 
 	const fd = openSync(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
 	let bytes: Buffer;
@@ -576,7 +603,7 @@ export function readTaskIntent(
 		closeSync(fd);
 	}
 	if (bytes.byteLength > INTENT_MAX_BYTES)
-		throw new Error("TaskIntent sidecar exceeds 64 KiB");
+		throw new TaskIntentObservationError("invalid", "TaskIntent sidecar exceeds 64 KiB");
 
 	// Post-read identity re-verification without a second path read as the
 	// source of bytes.
@@ -594,27 +621,15 @@ export function readTaskIntent(
 	try {
 		intent = parseTaskIntentV1(JSON.parse(bytes.toString("utf8")));
 	} catch (error) {
-		throw new Error(
+		throw new TaskIntentObservationError(
+			"invalid",
 			`TaskIntent sidecar is invalid: ${error instanceof Error ? error.message : String(error)}`,
 		);
 	}
 	if (intent.task_id !== taskId)
-		throw new Error("intent.task_id does not match the sidecar filename task id");
+		throw new TaskIntentObservationError("invalid", "intent.task_id does not match the sidecar filename task id");
 
 	const contentHash = canonicalIntentHash(intent);
-	const token = mintToken({
-		canonical_root: canonicalRoot,
-		sidecar_path: sidecarPath,
-		path_dev: fileIdentity.dev,
-		path_ino: fileIdentity.ino,
-		fd_dev: before.dev,
-		fd_ino: before.ino,
-		fd_size: before.size,
-		fd_mtime_ms: before.mtimeMs,
-		source_bytes_sha256: sourceBytesSha256,
-		intent_content_hash: contentHash,
-	});
-
 	return {
 		intent,
 		content_hash: contentHash,
@@ -623,6 +638,35 @@ export function readTaskIntent(
 			revision: intent.revision,
 			content_hash: contentHash,
 		},
-		token,
+		identity: {
+			canonical_root: canonicalRoot,
+			sidecar_path: sidecarPath,
+			path_dev: fileIdentity.dev,
+			path_ino: fileIdentity.ino,
+			fd_dev: before.dev,
+			fd_ino: before.ino,
+			fd_size: before.size,
+			fd_mtime_ms: before.mtimeMs,
+			source_bytes_sha256: sourceBytesSha256,
+			intent_content_hash: contentHash,
+		},
 	};
 }
+
+export function observeTaskIntent(
+	root: string,
+	taskId: string,
+	requestedPath?: string,
+): ObservedTaskIntent {
+	const { identity: _identity, ...observed } = readTaskIntentSource(root, taskId, requestedPath);
+	return observed;
+}
+
+export function readTaskIntent(
+	root: string,
+	taskId: string,
+	requestedPath?: string,
+): ReadTaskIntentResult {
+	const { identity, ...observed } = readTaskIntentSource(root, taskId, requestedPath);
+	return { ...observed, token: mintToken(identity) };
+}

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

@@ -229,10 +229,12 @@ export function buildAuthorityObservationSeedV2(
 function committedReceiptV2(
 	receipt: AuthorityCommitReceipt,
 ): receipt is AuthorityCommitReceipt & {
+	contract: "assurance_kernel/authority_commit_receipt/v2";
 	status: "committed" | "recovered_committed";
 	observation_seed: AuthorityObservationSeedV2;
 } {
 	return (
+		receipt.contract === "assurance_kernel/authority_commit_receipt/v2" &&
 		(receipt.status === "committed" ||
 			receipt.status === "recovered_committed") &&
 		receipt.observation_seed !== undefined

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

@@ -178,6 +178,7 @@ function hasPrivilegedKind(action: TaskAction): boolean {
 		action.type === "record_approval" ||
 		action.type === "approve_breaking_intent_revision" ||
 		action.type === "request_rework" ||
+		action.type === "authorize_rework" ||
 		action.type === "stop" ||
 		action.type === "resolve_user_decision"
 	);
@@ -449,13 +450,16 @@ export function reduceTask(
 					"request_rework requires review, qa, or user authority",
 				]);
 			const round = reviewRound(record);
-			const reviewAuthorityReworks = record.history.filter(
-				(entry) =>
-					entry.type === "request_rework" &&
-					entry.authority?.authority_kind === "review",
-			).length;
+			const hasPriorBlockingReviewRework = record.findings.some(
+				(finding) =>
+					finding.source === "review" &&
+					finding.kind === "blocking" &&
+					finding.review_round !== null,
+			);
 			const parkForReplan =
-				authorityAudit.authority_kind === "review" && reviewAuthorityReworks >= 1;
+				authorityAudit.authority_kind === "review" &&
+				hasPriorBlockingReviewRework &&
+				action.findings.some((finding) => finding.kind === "blocking");
 			if (!parkForReplan) {
 				record.artifact_state = "active";
 				record.intent_ref.path = `docs/plans/${record.task_id}.intent.json`;
@@ -470,8 +474,8 @@ export function reduceTask(
 				record.findings.push({
 					...finding,
 					status: "open",
-					source: "review",
-					review_round: round,
+					source: authorityAudit.authority_kind === "review" ? "review" : "execution",
+					review_round: authorityAudit.authority_kind === "review" ? round : null,
 				});
 			}
 			if (
@@ -502,6 +506,28 @@ export function reduceTask(
 			appendHistory(record, action, from, `review_round_${round}`, authorityAudit);
 			break;
 		}
+		case "authorize_rework": {
+			if (record.lifecycle !== "active")
+				throw new KernelInvariantError([
+					`cannot authorize rework while lifecycle is ${record.lifecycle}`,
+				]);
+			if (authorityAudit?.authority_kind !== "user")
+				throw new KernelInvariantError([
+					"authorize_rework requires literal-user authority",
+				]);
+			const open = record.findings.filter(
+				(finding) => finding.kind === "replan_required" && finding.status === "open",
+			);
+			if (open.length === 0)
+				throw new KernelInvariantError([
+					"authorize_rework requires an open replan boundary",
+				]);
+			for (const finding of open) finding.status = "resolved";
+			record.artifact_state = "active";
+			record.intent_ref.path = `docs/plans/${record.task_id}.intent.json`;
+			appendHistory(record, action, from, open.map((finding) => finding.id).join(","), authorityAudit);
+			break;
+		}
 		case "complete": {
 			if (record.lifecycle !== "active" || record.artifact_state !== "frozen")
 				throw new KernelInvariantError([

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

@@ -78,7 +78,22 @@ export type JournalReasonCode =
 	| "source_read_failed"
 	| "shadow_divergence"
 	| "migration_ambiguous"
-	| "readiness_query_nonqualifying";
+	| "readiness_query_nonqualifying"
+	// Emitted by runtime/commands/kernel.ts. Absent from this union until the
+	// journal types were first exported and type checked.
+	| "routing_policy_invalid"
+	| "routing_unavailable"
+	| "kernel_owner_active"
+	| "v3_owner_nonterminal"
+	| "input_oversize"
+	| "input_invalid"
+	| "intent_invalid"
+	| "task_path_mismatch"
+	| "destination_invalid"
+	| "destination_parent_invalid"
+	| "destination_parent_missing"
+	| "destination_exists"
+	| "destination_write_failed";
 
 export interface JournalEntry {
 	contract: "assurance_kernel/journal/v1";
@@ -1337,7 +1352,7 @@ export function commitEnrollmentLocked(
 	taskId: string,
 	transaction: WorkspaceTransactionV2,
 	claim: Record<string, unknown>,
-): { record: TaskRecordV2; workspace: WorkspaceState } {
+): { record: TaskRecord; workspace: WorkspaceState } {
 	const marker: EnrollmentMarker = {
 		contract: "assurance_kernel/enrollment_transaction/v1",
 		task_id: taskId,

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

@@ -700,7 +700,7 @@ export function migrateLegacyLayout(root: string): MigrationOutcome {
 			affected_paths: initial.dirty_affected_paths,
 			reason: initial.reason,
 		};
-	if (["migration_blocked_active", "invalid"].includes(initial.layout))
+	if (initial.layout === "migration_blocked_active" || initial.layout === "invalid")
 		return {
 			contract: "immune_brain/storage_layout_migration_result/v1",
 			outcome: initial.layout,

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

@@ -242,10 +242,6 @@ function inspectOldLayout(root: string): OldLayoutFacts {
 				facts.blocked_active = true;
 				continue;
 			}
-			if (kind === "marker") {
-				facts.pending_marker ??= path;
-				continue;
-			}
 			if (kind === "claim") {
 				facts.blocked_active = true;
 				continue;

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

@@ -235,6 +235,15 @@ export interface TaskRecordV4 extends Omit<TaskRecordV3, "contract"> {
 /** The record shape every Kernel owner passes around during the v3 drain window. */
 export type TaskRecord = TaskRecordV3 | TaskRecordV4;
 
+/**
+ * Narrow the stored record union before reading a v4-only field such as
+ * `git_base_head`. Comparing `record.contract` into a plain boolean does not
+ * narrow, which let adapters read v4 fields off a v3-shaped value unchecked.
+ */
+export function isTaskRecordV4(record: TaskRecord): record is TaskRecordV4 {
+	return record.contract === TASK_RECORD_CONTRACT_V4;
+}
+
 export interface TaskProjectionV3 extends CompletionDecision {
 	contract: "assurance_kernel/projection/v3";
 	task_id: string;
@@ -288,6 +297,7 @@ export type TaskAction =
 	| (TaskActionBase & { type: "request_rework"; findings: TaskFinding[] })
 	| (TaskActionBase & { type: "complete" })
 	| (TaskActionBase & { type: "stop"; reason: string })
+	| (TaskActionBase & { type: "authorize_rework" })
 	| (TaskActionBase & { type: "resolve_user_decision"; finding_id: string; resolution: string });
 
 

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

@@ -735,6 +735,7 @@ const ACTION_V2_TYPES = [
 	"request_rework",
 	"complete",
 	"stop",
+	"authorize_rework",
 	"resolve_user_decision",
 ] as const;
 
@@ -897,7 +898,8 @@ export function parseTaskAction(raw: unknown): TaskAction {
 			};
 			break;
 		}
-		case "complete": {
+		case "complete":
+		case "authorize_rework": {
 			rejectUnknown(value, [...ACTION_BASE_FIELDS], "action", violations);
 			action = { ...base, type: base.type };
 			break;
@@ -1002,6 +1004,7 @@ export function assertTaskRecordUpdateV3(
 		if (
 			next.intent_ref.path !== previous.intent_ref.path &&
 			action.type !== "request_rework" &&
+			action.type !== "authorize_rework" &&
 			action.type !== "stop"
 		)
 			violations.push("only artifact transitions may change intent_ref path");
@@ -1023,11 +1026,12 @@ export function assertTaskRecordUpdateV3(
 			? [action.finding_id]
 			: action.type === "resolve_user_decision"
 				? [action.finding_id]
-				: action.type === "approve_breaking_intent_revision"
-					? previous.findings
-						.filter((item) => item.kind === "replan_required" && item.status === "open")
-						.map((item) => item.id)
-					: [];
+			: action.type === "authorize_rework" ||
+				  action.type === "approve_breaking_intent_revision"
+				? previous.findings
+					.filter((item) => item.kind === "replan_required" && item.status === "open")
+					.map((item) => item.id)
+				: [];
 	const reworkFindingIds =
 		action.type === "request_rework"
 			? new Set(action.findings.map((item) => item.id))

package/plugins/immune-brain/runtime/managed_task_routing_policy.ts

@@ -26,7 +26,7 @@
 
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import {
+import { type Stats,
 	closeSync,
 	constants as fsConstants,
 	fstatSync,
@@ -145,7 +145,7 @@ export function setRoutingPolicyReaderTestHook(
 	routingPolicyReaderTestHook = hook;
 }
 
-function statIdentity(stat: ReturnType<typeof statSync>): {
+function statIdentity(stat: Stats): {
 	dev: number;
 	ino: number;
 	size: number;

package/plugins/immune-brain/runtime/plugin_version.ts

@@ -1,2 +1,2 @@
 // Generated by scripts/plugin_versioning.ts from the root package.json.
-export const PLUGIN_VERSION = "3.6.3" as const;
+export const PLUGIN_VERSION = "3.6.5" as const;