immune-brain 3.6.9 → 4.0.0

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

@@ -12,8 +12,9 @@ import {
 	readTaskRecordRaw,
 	readWorkspaceStateRaw,
 } from "./storage";
+import { stateDatabasePath } from "./storage_paths";
 
-const SOURCE_PATH = ".imm/state/workspace.json";
+const SOURCE_PATH = stateDatabasePath();
 const GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 
 /**
@@ -64,6 +65,13 @@ export interface PiCanaryPreparation {
 	git_error: string | null;
 	workspace: {
 		current_working: string | null;
+		/**
+		 * The workspace CAS token at preparation time. A workspace can return to
+		 * the same owner value at a different revision (another task enrolled and
+		 * settled in between), so the owner alone cannot prove the confirmed
+		 * state is still current.
+		 */
+		revision: string;
 	};
 	digest: string;
 }
@@ -152,6 +160,7 @@ export function preparePiCanary(root: string, input: PiCanaryPrepareInput): PiCa
 	const state = readWorkspaceStateRaw(canonicalRoot);
 	const workspace: PiCanaryPreparation["workspace"] = {
 		current_working: state.state.current_working,
+		revision: state.revision,
 	};
 	if (claim && state.state.current_working !== claim.task_id)
 		throw new Error(

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

@@ -1,4 +1,4 @@
-// Pure TaskRecord v3 reducer with a closed factual action vocabulary.
+// Pure TaskRecord v4 reducer with a closed factual action vocabulary.
 // Never reads files, Git, workspace, or host context. Returns a branded
 // ReducedTaskMutation; the caller cannot construct or serialize it.
 
@@ -7,7 +7,6 @@ import { completionDecision } from "./completion";
 import { anchorForEvidence, isFreshPassingQaAttestation, refutationIdentity, refutationIsLive } from "./refutation";
 import {
 	REDUCED_MUTATION_BRAND,
-	TASK_RECORD_CONTRACT_V4,
 	type AuthorityAuditDescriptor,
 	type ReducedTaskMutation,
 	type TaskAction,
@@ -163,10 +162,6 @@ function appendHistory(
 	record.history.push(entry as (typeof record.history)[number]);
 }
 
-function sha256Hex(value: string): string {
-	return createHash("sha256").update(value).digest("hex");
-}
-
 function intentRefMatches(intent: TaskIntentV1, ref: TaskIntentRefV3): boolean {
 	const activePath = `docs/plans/${intent.task_id}.intent.json`;
 	const archivedPath = `docs/plans/archive/${intent.task_id}.intent.json`;
@@ -209,19 +204,11 @@ export function findingsDigestV2(findings: TaskFinding[]): string {
 }
 
 /**
- * Two findings share an acceptance boundary when they name the same
- * acceptance, or when neither does and their review evidence names the same
- * violated reference. Null boundaries without comparable evidence are not
- * shared, so a second-round finding can no longer park the task by accident.
+ * Rework rounds one Review run may demand before the Kernel pauses the task for
+ * a human decision. Ordinary defects return to execution without a user gate,
+ * but an unbounded repair/review cycle is not progress either.
  */
-function sharesAcceptanceBoundary(left: TaskFinding, right: TaskFinding): boolean {
-	if (left.acceptance_id !== null && right.acceptance_id !== null)
-		return left.acceptance_id === right.acceptance_id;
-	if (left.acceptance_id !== null || right.acceptance_id !== null) return false;
-	const leftRef = left.evidence?.violated.ref ?? null;
-	const rightRef = right.evidence?.violated.ref ?? null;
-	return leftRef !== null && leftRef === rightRef;
-}
+export const REVIEW_REWORK_ROUND_BUDGET = 5;
 
 export function reduceTask(
 	recordRaw: TaskRecord,
@@ -444,10 +431,7 @@ export function reduceTask(
 			const reviewRevision = approval.review_revision;
 			if (reviewRevision && approval.kind !== "review")
 				throw new KernelInvariantError(["review_revision is only valid on review approvals"]);
-			if (record.contract !== TASK_RECORD_CONTRACT_V4) {
-				if (reviewRevision)
-					throw new KernelInvariantError(["review_revision requires a TaskRecord v4"]);
-			} else if (approval.kind === "review") {
+			if (approval.kind === "review") {
 				if (!reviewRevision)
 					throw new KernelInvariantError(["v4 review approval requires review_revision"]);
 				if (reviewRevision.base_head !== record.git_base_head)
@@ -567,9 +551,11 @@ export function reduceTask(
 					]);
 			}
 			const identity = refutationIdentity(record, action.diff_hash);
-			// A prior finding that is still refuted by live evidence is not an
-			// outstanding dispute, so a new claim on its boundary is not a repeat
-			// offence. Once its evidence goes stale it blocks again and counts.
+			// A prior blocking Review claim is only a repeat offence when it names the
+			// same security boundary. Ordinary defects on an already-covered
+			// acceptance return to execution: changing the plan is a human decision,
+			// fixing a bug is not. A claim still refuted by live evidence is not an
+			// outstanding dispute at all.
 			const priorBlockingReviewFindings = record.findings.filter(
 				(finding) =>
 					finding.source === "review" &&
@@ -604,12 +590,26 @@ export function reduceTask(
 				({ finding, inherited }) =>
 					finding.kind === "blocking" &&
 					inherited === undefined &&
-					priorBlockingReviewFindings.some((prior) =>
-						sharesAcceptanceBoundary(finding, prior),
+					finding.evidence?.violated.kind === "security_boundary" &&
+					priorBlockingReviewFindings.some(
+						(prior) =>
+							prior.evidence?.violated.kind === "security_boundary" &&
+							prior.evidence?.violated.ref === finding.evidence?.violated.ref,
 					),
 			)?.finding;
+			// Only rounds that actually raised an unrefuted blocking claim count
+			// against the budget: a claim live QA evidence already answers is not
+			// progress lost, so repeating it can never park the task.
+			const effectiveBlockingRounds = new Set(
+				priorBlockingReviewFindings.map((finding) => finding.review_round),
+			).size;
+			const hasEffectiveBlockingNow = admissions.some(
+				({ finding, inherited }) => finding.kind === "blocking" && inherited === undefined,
+			);
 			const parkForReplan =
-				authorityAudit.authority_kind === "review" && disputed !== undefined;
+				authorityAudit.authority_kind === "review" &&
+				(disputed !== undefined ||
+					(hasEffectiveBlockingNow && effectiveBlockingRounds >= REVIEW_REWORK_ROUND_BUDGET));
 			if (!parkForReplan) {
 				record.artifact_state = "active";
 				record.intent_ref.path = `docs/plans/${record.task_id}.intent.json`;
@@ -644,11 +644,13 @@ export function reduceTask(
 					id: `${action.event_id}:replan-required`,
 					kind: "replan_required" as const,
 					status: "open" as const,
-					acceptance_id: disputed.acceptance_id,
+					acceptance_id: disputed?.acceptance_id ?? null,
 					source: "kernel" as const,
 					review_round: round,
 					summary:
-						"Review returned this acceptance boundary twice; a durable replan is required.",
+						disputed !== undefined
+							? "Review returned the same security boundary twice; a durable replan is required."
+							: `Review exhausted its ${REVIEW_REWORK_ROUND_BUDGET}-round rework budget; a durable replan is required.`,
 				};
 				if (findingIds.has(boundary.id))
 					throw new KernelInvariantError([
@@ -708,7 +710,6 @@ export function reduceTask(
 				throw new KernelInvariantError(["stop requires a reason"]);
 			transitionLifecycle(record, "stopped");
 			record.artifact_state = "frozen";
-			record.intent_ref.path = `docs/plans/archive/${record.task_id}.intent.json`;
 			appendHistory(record, action, from, action.reason, authorityAudit);
 			break;
 		}

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

@@ -0,0 +1,121 @@
+/**
+ * Exact execution identity.
+ *
+ * A worktree owns one storage identity (`workspace_id`) and every enrolled
+ * execution owns one `run_id`. Authority mutations bind the exact run instead
+ * of resolving "the latest task occurrence", and every replayable operation
+ * derives its identity from committed facts so a replayed call returns the
+ * recorded result instead of writing again.
+ *
+ * `task_id` names the logical task: different worktrees may each run the same
+ * logical task with distinct run identities, and a terminal task cannot be
+ * re-enrolled in the same worktree.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+
+import { KernelStoreSecurityError, workspaceIdentity } from "./sqlite_store";
+
+export interface RunIdentity {
+	workspace_id: string;
+	task_id: string;
+	run_id: string;
+}
+
+export interface RunRowIdentity {
+	task_id: string;
+	run_id: string;
+}
+
+export function mintRunId(): string {
+	return `run-${randomUUID()}`;
+}
+
+export function runIdentity(db: DatabaseSync, row: RunRowIdentity): RunIdentity {
+	return { workspace_id: workspaceIdentity(db), task_id: row.task_id, run_id: row.run_id };
+}
+
+/** Bind a mutation to one exact run; a mismatch fails before any write. */
+export function assertRunBinding(
+	identity: RunIdentity,
+	expected: RunRowIdentity,
+	operation: string,
+): void {
+	if (identity.run_id !== expected.run_id || identity.task_id !== expected.task_id)
+		throw new KernelStoreSecurityError(
+			`${operation} is bound to run ${expected.run_id} (task ${expected.task_id}) but the store holds run ${identity.run_id} (task ${identity.task_id})`,
+		);
+}
+
+/**
+ * Deterministic replay identity for the authority operations that can lose a
+ * response. The event identifier is part of the committed authority bytes, so
+ * an identical request maps to an identical operation id and a replayed call
+ * returns the recorded result instead of writing again.
+ */
+export function enrollmentOperationId(taskId: string, eventId: string): string {
+	return `enroll:${taskId}:${eventId}`;
+}
+
+/**
+ * Digest of an enrollment request's own content. The capability object is
+ * opaque and excluded, so a lost-response retry of the *same* confirmation
+ * matches, while a different path, digest, actor, nonce or event time is a
+ * different request and must not be answered from the committed operation.
+ */
+export function enrollmentRequestDigest(request: {
+	task_id: string;
+	intent_path: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	preparation_digest: string;
+	enrollment_event_id: string;
+	actor_id: string;
+	confirmation_ref: string;
+	nonce: string;
+}): string {
+	const canonical = JSON.stringify({
+		task_id: request.task_id,
+		intent_path: request.intent_path,
+		intent_revision: request.intent_revision,
+		intent_content_hash: request.intent_content_hash,
+		preparation_digest: request.preparation_digest,
+		enrollment_event_id: request.enrollment_event_id,
+		actor_id: request.actor_id,
+		confirmation_ref: request.confirmation_ref,
+		nonce: request.nonce,
+	});
+	return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+export function drainOperationId(taskId: string, updatedAt: string): string {
+	return `drain:${taskId}:${updatedAt}`;
+}
+
+/**
+ * Digest of a terminal request's own content. The capability is deliberately
+ * opaque and excluded, so a retry that re-mints authority for the *same*
+ * request produces the same digest, while a different reason, actor or event
+ * time produces a different one and must be authorized again instead of being
+ * answered from the committed operation.
+ */
+export function terminalRequestDigest(action: {
+	type: string;
+	event_id: string;
+	at: string;
+	actor_id: string;
+	reason?: unknown;
+}): string {
+	const canonical = JSON.stringify({
+		type: action.type,
+		event_id: action.event_id,
+		at: action.at,
+		actor_id: action.actor_id,
+		reason: typeof action.reason === "string" ? action.reason : null,
+	});
+	return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+export function terminalOperationId(taskId: string, eventId: string): string {
+	return `terminal:${taskId}:${eventId}`;
+}

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

@@ -0,0 +1,100 @@
+// Spec binding ownership. A simple TaskIntent binds no Spec. A complex
+// TaskIntent binds at most one active Spec by path; freeze records Git
+// content identity without relocating source files. Archive paths are
+// historical evidence, not a freeze requirement.
+
+import type { TaskIntentV1 } from "./types";
+import { readSecureProjectFile } from "./storage";
+import { KernelInvariantError } from "./validation";
+
+const ACTIVE_SPEC_RE = /^docs\/specs\/(?!archive\/)[^/]+\.spec\.md$/;
+const ARCHIVED_SPEC_RE = /^docs\/specs\/archive\/[^/]+\.spec\.md$/;
+
+/** The archive counterpart of an active planning-artifact path. */
+export function archivePath(path: string): string {
+	const matched = path.match(/^docs\/(plans|specs)\/([^/]+)$/);
+	if (!matched) throw new KernelInvariantError([`artifact path is not active: ${path}`]);
+	return `docs/${matched[1]}/archive/${matched[2]}`;
+}
+
+/** The inverse of `archivePath`, for an already-archived Spec path. */
+export function activePath(path: string): string {
+	const matched = path.match(/^docs\/(plans|specs)\/archive\/([^/]+)$/);
+	if (!matched) throw new KernelInvariantError([`artifact path is not archived: ${path}`]);
+	return `docs/${matched[1]}/${matched[2]}`;
+}
+
+/**
+ * The active Spec the intent binds, or `undefined` when it binds none.
+ * Archive counterparts are not part of the binding predicate.
+ */
+export function boundSpecPath(intent: TaskIntentV1): string | undefined {
+	const candidates = intent.scope_hint.filter((path) => ACTIVE_SPEC_RE.test(path));
+	if (candidates.length > 1)
+		throw new KernelInvariantError([`artifact transition requires at most one scope-bound Spec; found ${candidates.length}`]);
+	return candidates[0];
+}
+
+/**
+ * Bound Spec bytes when the intent names one. Simple intents have none.
+ * `required` still fails closed for callers that demand a Spec.
+ */
+export function readBoundActiveSpec(
+	root: string,
+	intent: TaskIntentV1,
+	required = false,
+): { path: string; content: string } | undefined {
+	const specPath = boundSpecPath(intent);
+	if (!specPath) {
+		if (required) throw new KernelInvariantError(["artifact freeze requires one scope-bound active Spec"]);
+		return undefined;
+	}
+	try {
+		return { path: specPath, content: readSecureProjectFile(root, specPath) };
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith("source_missing:") && !required) return undefined;
+		throw error;
+	}
+}
+
+export interface BoundSpec {
+	active: string;
+	archive: string;
+}
+
+export type SpecBindingInspection =
+	| { ok: true; binding: BoundSpec | null }
+	| {
+			ok: false;
+			code: "binding_missing" | "binding_incomplete" | "binding_ambiguous";
+			missing: string[];
+			message: string;
+	  };
+
+/**
+ * Enrollment and validate caller: a missing Spec is a simple task; a
+ * malformed or incomplete complex binding is refused before any write.
+ */
+export function inspectSpecBinding(intent: TaskIntentV1): SpecBindingInspection {
+	const active = intent.scope_hint.filter((path) => ACTIVE_SPEC_RE.test(path));
+	const archived = intent.scope_hint.filter((path) => ARCHIVED_SPEC_RE.test(path));
+	if (active.length === 0 && archived.length === 0)
+		return { ok: true, binding: null };
+	if (active.length > 1)
+		return {
+			ok: false,
+			code: "binding_ambiguous",
+			missing: [],
+			message: `enrollment requires at most one scope-bound Spec; found ${active.length}: ${active.join(", ")}`,
+		};
+	if (active.length === 0) {
+		const missing = archived.map((path) => activePath(path));
+		return {
+			ok: false,
+			code: "binding_incomplete",
+			missing,
+			message: `complex Spec binding is incomplete; add ${missing.join(", ")}`,
+		};
+	}
+	return { ok: true, binding: { active: active[0]!, archive: archivePath(active[0]!) } };
+}