immune-brain 3.6.8 → 4.0.0

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

@@ -3,8 +3,17 @@
 // eligible when its Git-tracked TaskIntent is readable and no Kernel owner
 // (workspace, backend claim, TaskRecord v2, tombstone) blocks enrollment.
 
-import type { ReadinessReport } from "./readiness";
-import type { ReadinessEvidenceInput } from "./readiness_evidence";
+// The readiness/evidence pipeline is retired with the authority-observation
+// island. These two derived inputs stay on the eligibility input for caller
+// compatibility only: they are ignored below and are never authority, so they
+// are read structurally instead of importing the deleted modules.
+export interface RetiredReadinessInput {
+	status: string;
+}
+
+export interface RetiredReadinessEvidenceInput {
+	status: string;
+}
 
 export type WaivableGate = "observation_window_days";
 
@@ -26,8 +35,8 @@ export interface CanaryTaskIdentity {
 }
 
 export interface CanaryEligibilityInput {
-	readiness?: ReadinessReport;
-	evidence?: ReadinessEvidenceInput;
+	readiness?: RetiredReadinessInput;
+	evidence?: RetiredReadinessEvidenceInput;
 	task: CanaryTaskIdentity;
 	waiver?: CanaryWaiver;
 	now: string;

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

@@ -1,4 +1,5 @@
 import { classifyTaskRisk } from "./intent";
+import { archivePath, boundSpecPath } from "./spec_binding";
 import type {
 	ApprovalKind,
 	CompletionDecision,
@@ -7,7 +8,7 @@ import type {
 	TaskProjectionV3,
 	TaskRecord,
 } from "./types";
-import { assertKernelInvariantsV3, KernelInvariantError } from "./validation";
+import { assertKernelInvariantsV3 } from "./validation";
 import { refutationIsLive } from "./refutation";
 
 const REQUIRED_ATTESTATIONS: Record<TaskIntentV1["risk"], ApprovalKind[]> = {
@@ -23,23 +24,13 @@ function archiveActivePlanningPath(path: string): string | 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]);
+	const archivedIntent = archiveActivePlanningPath(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];
+	const spec = boundSpecPath(intent);
 	if (spec) {
 		excluded.add(spec);
-		const archived = archiveActivePlanningPath(spec);
-		if (archived) excluded.add(archived);
+		excluded.add(archivePath(spec));
 	}
 	return excluded;
 }

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

@@ -3,7 +3,9 @@
 // for one confirmed canary task. Requires a valid EnrollmentCapability.
 // No CLI, runtime route, or production issuer exists in P2B0.
 
-import { canonicalIntentHash, readTaskIntent } from "./intent";
+import { readRunRowByTask, withKernelRead } from "./sqlite_store";
+import { readTaskIntent } from "./intent";
+import { inspectSpecBinding } from "./spec_binding";
 import {
 	type EnrollmentAuthorityRegistry,
 	type EnrollmentCapabilityBinding,
@@ -12,12 +14,16 @@ import type {
 	BatchAuthorityRegistry,
 	BatchAuthorizationBinding,
 } from "./batch_authority";
-import { readTaskTombstone, type BackendClaim } from "./backend_claim";
+import type { BackendClaim } from "./backend_claim";
 import { preparePiCanary, readGitHead } from "./pi_canary_prepare";
+import { writeEnrollmentBaseline } from "../workspace_scope";
+import { enrollmentRequestDigest } from "./run_identity";
 import {
 	commitEnrollmentLocked,
+	readCommittedEnrollmentResult,
 	readTaskRecordRaw,
 	readWorkspaceStateRaw,
+	reconcileKernelAuthority,
 	withKernelStoreLock,
 } from "./storage";
 import type { TaskRecord, TaskRecordV4, WorkspaceStateLike } from "./types";
@@ -113,10 +119,18 @@ function runEnrollmentPreconditionChecks<T>(
 			blockers.push(report);
 		};
 
-		const tombstone = readTaskTombstone(root, input.task_id);
-		if (tombstone) {
+		// Terminal protection is the *local* committed run, never the audit
+		// evidence: another worktree's run of the same logical task exports its
+		// own audit directory, and that evidence must not forbid a first
+		// enrollment here. Audit files remain readable as historical evidence for
+		// tasks this worktree has no run for (see reconcileKernelAuthority).
+		const localRun = reconcileKernelAuthority(root, input.task_id);
+		const localTerminal =
+			localRun.state === "terminal_owner" &&
+			withKernelRead(root, (db) => readRunRowByTask(db, input.task_id)) !== null;
+		if (localTerminal) {
 			fail(
-				"task tombstone exists; same-task re-enrollment is forbidden",
+				"local run is terminal; same-task re-enrollment is forbidden",
 				new Error(`task ${input.task_id} is terminal; same-task re-enrollment is forbidden`),
 			);
 		} else {
@@ -138,6 +152,12 @@ function runEnrollmentPreconditionChecks<T>(
 		} catch (error) {
 			fail(`intent: ${error instanceof Error ? error.message : String(error)}`, error);
 		}
+		// A simple Intent binds no Spec. A complex binding that names a Spec must
+		// be complete and unambiguous before any Executor turn.
+		if (intent) {
+			const binding = inspectSpecBinding(intent.intent);
+			if (!binding.ok) fail(binding.message, new Error(binding.message));
+		}
 		try {
 			gitBaseHead = readGitHead(root);
 		} catch (error) {
@@ -219,20 +239,65 @@ export function runEnrollmentRehearsal(
 	};
 }
 
+function enrollmentEventId(taskId: string, now: string): string {
+	return `enroll-${taskId}-${now}`;
+}
+
+function digestForEnrollment(input: EnrollCanaryInput): {
+	eventId: string;
+	digest: string;
+} {
+	const eventId = enrollmentEventId(input.task_id, input.now);
+	return {
+		eventId,
+		digest: enrollmentRequestDigest({
+			task_id: input.task_id,
+			intent_path: input.intent_path,
+			intent_revision: input.intent_revision,
+			intent_content_hash: input.capability_binding.intent_content_hash,
+			preparation_digest: input.preparation_digest,
+			enrollment_event_id: eventId,
+			actor_id: input.capability_binding.actor_id,
+			confirmation_ref: input.capability_binding.confirmation_ref,
+			nonce: input.capability_binding.nonce,
+		}),
+	};
+}
+
 /**
  * Atomic canary enrollment. Runs inside the same store lock as v1/v2
  * transactions; consumes the capability only after every precondition
- * passes, immediately before writing the enrollment marker.
+ * passes, immediately before writing the enrollment marker. A lost
+ * response of the exact same request returns the committed result
+ * without repeating those first-execution checks.
  */
 export function enrollCanaryTask(
 	root: string,
 	input: EnrollCanaryInput,
 	registry: EnrollmentAuthorityRegistry,
 ): EnrollCanaryResult {
+	const { eventId, digest } = digestForEnrollment(input);
+	// A committed enrollment answers the exact same request: the retry cannot
+	// pass the first-execution checks (the capability is consumed and the
+	// record now exists), so the durable operation is the only correct answer.
+	const replayed = readCommittedEnrollmentResult(root, input.task_id, eventId, digest);
+	if (replayed)
+		return {
+			record: replayed.record,
+			backend_claim: replayed.claim,
+			workspace: { revision: "", state: replayed.workspace },
+		};
+
 	let gitBaseHead: string | null = null;
-	return runEnrollmentPreconditionChecks(
-		root,
-		input,
+	// The batch child slot is consumed with the capability and handed back when
+	// the enrollment call fails. The commit happens at the outer store
+	// transaction, so any throw from this call means nothing was committed and
+	// the release has to wrap the whole call rather than only the record write.
+	let consumed = false;
+	try {
+		return runEnrollmentPreconditionChecks(
+			root,
+			input,
 		input.capability,
 		registry,
 		"fail_fast",
@@ -250,6 +315,12 @@ export function enrollCanaryTask(
 		(checks) => {
 			if (!checks.validated || !checks.intent || !checks.workspace || !checks.current)
 				throw new Error("enrollment precondition state incomplete");
+			// Recompute under the store lock: a confirmation bound to an older
+			// workspace revision must not commit after another enrollment and
+			// settlement raced between beforeLock and this callback.
+			const locked = preparePiCanary(root, { task_id: input.task_id, now: input.now });
+			if (locked.digest !== input.preparation_digest)
+				throw new Error("enrollment preparation digest mismatch");
 			if (checks.intent.intent.revision !== input.intent_revision)
 				throw new Error("intent revision mismatch");
 			if (checks.intent.content_hash !== checks.validated.intent_content_hash)
@@ -285,8 +356,9 @@ export function enrollCanaryTask(
 					);
 			}
 
-			// consume immediately before the marker write
+			// consume immediately before the store transaction
 			registry.consume(input.capability, input.capability_binding);
+			consumed = true;
 			if (input.batch)
 				input.batch.registry.consumeChild(
 					input.batch.capability,
@@ -310,37 +382,55 @@ export function enrollCanaryTask(
 				task_id: input.task_id,
 				intent_revision: input.intent_revision,
 				intent_content_hash: checks.intent.content_hash,
-				enrollment_event_id: `enroll-${input.task_id}-${input.now}`,
+				enrollment_event_id: eventId,
 				lifecycle_status: "active",
 				created_at: input.now,
 				updated_at: input.now,
 			};
-			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;
-			}
+			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>,
+				digest,
+			);
+			writeEnrollmentBaseline(root);
 			return {
 				record: mutation.record,
 				backend_claim: claim,
 				workspace: { revision: "", state: mutation.workspace },
 			};
-		},
-	);
+			},
+		);
+	} catch (error) {
+		// A child slot is released only when the enrollment provably did not
+		// commit. The envelope can also fail *after* the Kernel transaction
+		// committed — a follow-up transaction that cannot start, for example —
+		// and releasing then would leave the batch view ahead of an owner the
+		// Kernel already recorded. The committed run decides, not the throw.
+		const ownership = (() => {
+			try {
+				return {
+					known: true,
+					owned:
+						reconcileKernelAuthority(root, input.task_id).owner_task_id === input.task_id,
+				};
+			} catch {
+				return { known: false, owned: false };
+			}
+		})();
+		// Unknown is not "not committed". When the store cannot be read the slot
+		// stays consumed, so the batch view never runs ahead of a run that may
+		// exist, and the operator reconciles from the Kernel's own state.
+		if (consumed && input.batch && ownership.known && !ownership.owned)
+			input.batch.registry.releaseChild(input.batch.capability, input.task_id);
+		throw error;
+	}
 }

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

@@ -3,19 +3,27 @@
 // validation and projection remain here.
 
 import { createCapabilityRegistry } from "./capability_registry";
-import { MUTATION_AUTHORITY_CAPABILITY_BRAND } from "./types";
 
 export const ENROLLMENT_CAPABILITY_BRAND = Symbol.for("assurance-kernel.enrollment-capability-brand");
 
-export interface EnrollmentCapabilityBinding {
+/**
+ * The three fields every capability binding shares, whichever authority issues
+ * it. `nonce` is deliberately not part of this base: the enrollment and batch
+ * bindings carry it for their own replay digest, while `CapabilityBindingV2`
+ * uses `action_digest` instead and has no `nonce` field at all.
+ */
+export interface BaseCapabilityBinding {
+	actor_id: string;
+	confirmation_ref: string;
+	expires_at: string;
+}
+
+export interface EnrollmentCapabilityBinding extends BaseCapabilityBinding {
 	task_id: string;
 	intent_path: string;
 	intent_revision: number;
 	intent_content_hash: string;
 	preparation_digest: string;
-	actor_id: string;
-	confirmation_ref: string;
-	expires_at: string;
 	nonce: string;
 }
 

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

@@ -1,8 +1,8 @@
 export * from "./types";
 export * from "./intent";
 export * from "./validation";
+export * from "./legacy_task_record";
 export * from "./completion";
-export * from "./legacy";
 // v4 storage retirement: the v1 TaskRecord storage entry points are no
 // longer part of the production kernel surface. Only the v2 store read/commit
 // primitives (used by enrollment/rehearsal/audit) remain exported from
@@ -14,6 +14,8 @@ export {
 	readSecureProjectFile,
 	commitTaskRecordLocked,
 	withKernelStoreLock,
+	withKernelStoreLockForTask,
+	probeKernelStore,
 	serializeWorkspace,
 	revisionForContent,
 	appendJournalEntry,

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

@@ -118,7 +118,6 @@ function riskFloorForScope(scopeHint: string[]): TaskRisk | null {
 		: null;
 }
 
-const SHA256_HEX = /^sha256:[a-f0-9]{64}$/;
 const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const portablePathCollator = new Intl.Collator("und", {
 	usage: "search",
@@ -486,11 +485,9 @@ function resolveCanonicalRoot(root: string): string {
 
 // Resolve a path-less read to the sidecar that actually exists.
 //
-// The active path stays authoritative whenever it is present: that is the
-// pre-freeze layout every path-less caller assumes, and a leftover archived
-// sidecar from an earlier task reusing the same id must never shadow it. Only
-// when the active path is gone — the post-`freeze_artifacts` layout — does the
-// archive answer, which is exactly the case that used to fail with a raw ENOENT.
+// The active path stays authoritative whenever it is present. A leftover
+// archived sidecar from an earlier task reusing the same id must never shadow
+// it. Only when the active path is gone does the historical archive answer.
 function resolveSidecarPath(
 	canonicalRoot: string,
 	activePath: string,
@@ -554,11 +551,10 @@ function readTaskIntentSource(
 	const canonicalRoot = resolveCanonicalRoot(root);
 	const activePath = `${INTENT_SIDECAR_RELATIVE_PREFIX}${taskId}.intent.json`;
 	const archivedPath = `${INTENT_SIDECAR_RELATIVE_PREFIX}archive/${taskId}.intent.json`;
-	// `freeze_artifacts` relocates the sidecar from the active path to the archive
-	// path, so the caller's TaskRecord `intent_ref.path` is the authority. When no
-	// path is requested, resolve the single sidecar that exists rather than
-	// assuming the pre-freeze layout; a missing or ambiguous sidecar is a stable
-	// contract failure, not a raw `lstat` ENOENT.
+	// Freeze binds the sidecar in place. The caller's TaskRecord `intent_ref.path`
+	// is the authority. When no path is requested, resolve the sidecar that exists
+	// (active, else historical archive). A missing sidecar is a stable contract
+	// failure, not a raw `lstat` ENOENT.
 	const sidecarPath = requestedPath ?? resolveSidecarPath(canonicalRoot, activePath, archivedPath);
 	if (sidecarPath !== activePath && sidecarPath !== archivedPath)
 		throw new Error("intent sidecar path is not the active or archived task path");

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

@@ -7,13 +7,16 @@
  * observation, TaskRecord, or workspace state. It never imports, synthesizes,
  * or activates a Kernel TaskRecord from legacy data.
  *
+ * Removal milestone: read-only transitional code. It is deleted in the next
+ * major release, after the release that removes the retired file store.
+ *
  * Not exported from kernel/index.ts; reached only through the v4 CLI
  * `imm-kernel audit --legacy` surface.
  */
 import { createHash } from "node:crypto";
 import { lstatSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { LEGACY_V3_RELATIVE, legacyV3Path } from "./storage_paths";
+import { legacyV3Path } from "./storage_paths";
 
 const MAX_BYTES = 2 * 1024 * 1024;