immune-brain 3.6.9 → 4.0.0

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

@@ -14,16 +14,19 @@
  * migration_uncommitted | recovery_required | invalid.
  */
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import {
 	constants as FS_CONSTANTS,
 	lstatSync,
 	openSync,
 	readFileSync,
+	realpathSync,
 	readdirSync,
 	closeSync,
 	fstatSync,
 } from "node:fs";
 import { resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
 
 // ---------------------------------------------------------------------------
 // New permanent layout paths
@@ -36,6 +39,56 @@ export const JOURNAL_RELATIVE = ".imm/state/journal.jsonl";
 export const MIGRATION_MARKER_RELATIVE =
 	".imm/state/transactions/storage-layout-migration.json";
 
+/** The single worktree authority database (never committed; `.imm/state` is ignored). */
+export const KERNEL_DB_RELATIVE = ".imm/state/kernel.sqlite";
+export const KERNEL_STORE_SCHEMA_VERSION = 1;
+export const KERNEL_DB_SIDECARS = [
+	".imm/state/kernel.sqlite-wal",
+	".imm/state/kernel.sqlite-shm",
+] as const;
+
+/**
+ * The retired file-store authority layout (`.imm/state/*.json`) written by the
+ * previous runtime. Recognized only so inspection can require the SQLite
+ * importer; no current runtime reads or writes mutable authority here.
+ */
+export const FILE_STORE_CLAIM_RELATIVE = ".imm/state/active-claim.json";
+export const FILE_STORE_WORKSPACE_RELATIVE = ".imm/state/workspace.json";
+export const FILE_STORE_TASKS_RELATIVE = ".imm/state/tasks";
+export const FILE_STORE_TRANSACTIONS_RELATIVE = ".imm/state/transactions";
+export const FILE_STORE_LOCKS_RELATIVE = ".imm/state/locks";
+/** Session observation receipts: inert output, never authority. */
+export const FILE_STORE_OBSERVATIONS_RELATIVE = ".imm/state/observations";
+/**
+ * Unattended batch run state (`.imm/state/batches/<batch_id>.json`). It is
+ * written by the batch runner, not by the retired file-store writer, so the
+ * layout inspector must recognize it instead of failing the worktree closed.
+ */
+export const BATCH_STATE_RELATIVE = ".imm/state/batches";
+
+/** Inert file-store entries that carry no authority after the cutover. */
+export const FILE_STORE_INERT_FILES = [
+	".imm/state/journal.jsonl",
+	".imm/state/locks/kernel-store.lock",
+	".imm/state/enrollment-baseline.json",
+	// The explicit importer's candidate store, its SQLite sidecars and its
+	// import receipt: all import-time machinery, and the published database is
+	// the only authority. A transaction that died mid-import leaves a rollback
+	// journal or a write-ahead log beside the candidate, and the layout must stay
+	// migratable so the retry can rebuild it.
+	".imm/state/kernel.sqlite.importing",
+	".imm/state/kernel.sqlite.importing-journal",
+	".imm/state/kernel.sqlite.importing-wal",
+	".imm/state/kernel.sqlite.importing-shm",
+	".imm/state/migration-receipt.json",
+	// The importer's cross-process lock: inert by itself, and a crashed holder
+	// must not leave the worktree permanently unmigratable.
+	".imm/state/migration.lock",
+] as const;
+
+/** A file-store migration manifest left by the retired migrator. */
+export const FILE_STORE_MIGRATION_MARKER = MIGRATION_MARKER_RELATIVE;
+
 /* Transaction marker file names under `.imm/state/transactions/`. */
 export const KERNEL_TRANSACTION_MARKERS = [
 	"workspace-transaction-v2.json",
@@ -45,6 +98,19 @@ export const KERNEL_TRANSACTION_MARKERS = [
 	"authority-repair-transaction.json",
 ] as const;
 
+export function stateDatabasePath(): string {
+	return KERNEL_DB_RELATIVE;
+}
+
+/**
+ * Worktree binding digest: a store is bound to the canonical worktree path it
+ * was created in, so a database copied from another worktree is refused
+ * instead of granting authority.
+ */
+export function kernelStoreBindingDigest(canonicalRoot: string, workspaceId: string): string {
+	return createHash("sha256").update(`${canonicalRoot}\0${workspaceId}`).digest("hex");
+}
+
 function validateTaskId(taskId: string): void {
 	if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId))
 		throw new Error(
@@ -65,6 +131,18 @@ export function stateClaimPath(): string {
 	return `${STATE_RELATIVE}/active-claim.json`;
 }
 
+/**
+ * Creation marker for the worktree store, written once when the database is
+ * first initialized. A worktree keeps its identity even if the database is
+ * truncated: the marker is what distinguishes "brand-new store" from "store
+ * that lost its contents", so corruption fails closed instead of reading as an
+ * idle unowned worktree. The storage migration (mws-migration-release) carries
+ * it together with the database and retires it when it does.
+ */
+export function kernelStoreIdentityPath(): string {
+	return `${STATE_RELATIVE}/kernel.identity.json`;
+}
+
 export function stateStoreLockPath(): string {
 	return `${STATE_RELATIVE}/locks/kernel-store.lock`;
 }
@@ -80,6 +158,52 @@ export function auditTaskDirPath(taskId: string): string {
 	return `${AUDIT_RELATIVE}/${taskId}`;
 }
 
+/**
+ * Per-run audit evidence: `.imm/audit/<task-id>/<run-id>/`.
+ *
+ * Two worktrees may each run the same logical task with distinct run
+ * identities, so the export is keyed by task *and* run. The flat task
+ * directory above stays readable as historical evidence; the storage migration
+ * (mws-migration-release) is what retires it.
+ */
+export function auditRunDirPath(taskId: string, runId: string): string {
+	validateTaskId(taskId);
+	if (!/^run-[A-Za-z0-9-]+$/.test(runId)) throw new Error(`invalid run identity: ${runId}`);
+	return `${auditTaskDirPath(taskId)}/${runId}`;
+}
+
+export function auditRunRecordPath(taskId: string, runId: string): string {
+	return `${auditRunDirPath(taskId, runId)}/task-record.json`;
+}
+
+export function auditRunTerminalProofPath(taskId: string, runId: string): string {
+	return `${auditRunDirPath(taskId, runId)}/terminal-proof.json`;
+}
+
+/**
+ * Where this task's audit evidence lives: its single run directory, or the flat
+ * historical task directory when no run-scoped export exists. Several run
+ * directories mean only an explicit run identity can decide, so the flat path
+ * is returned and the caller's own validation decides what is readable.
+ */
+export function auditEvidencePaths(root: string, taskId: string): {
+	record: string;
+	proof: string;
+} {
+	validateTaskId(taskId);
+	const runs = (listEntries(root, auditTaskDirPath(taskId)) ?? []).filter((entry) =>
+		/^run-[A-Za-z0-9-]+$/.test(entry),
+	);
+	if (runs.length === 1) {
+		const runId = runs[0];
+		return {
+			record: auditRunRecordPath(taskId, runId),
+			proof: auditRunTerminalProofPath(taskId, runId),
+		};
+	}
+	return { record: auditTaskRecordPath(taskId), proof: auditTerminalProofPath(taskId) };
+}
+
 export function auditTaskRecordPath(taskId: string): string {
 	return `${auditTaskDirPath(taskId)}/task-record.json`;
 }
@@ -129,6 +253,55 @@ export const LEGACY_KNOWN_FILES = {
 	".imm/templates/review-report-template.md": "retired",
 } as const;
 
+/**
+ * Retired artifacts that carry no authority but must survive as historical
+ * evidence. The importer copies each present source byte-for-byte into its
+ * `evidence` path — `.imm/audit/legacy-v3/` is the layout the read-only legacy
+ * audit reads — and only then retires the old path.
+ *
+ * The v3 Ledger keeps its own name because `legacy_audit.ts` reads exactly that
+ * path; every other artifact keeps its basename under the same evidence root.
+ */
+export const LEGACY_ARTIFACT_RETIREMENT: ReadonlyArray<{ source: string; evidence: string }> = [
+	{ source: ".imm/memory/current_iteration.json", evidence: ".imm/audit/legacy-v3/current_iteration.json" },
+	{ source: ".imm/memory/current_iteration_history.jsonl", evidence: ".imm/audit/legacy-v3/current_iteration_history.jsonl" },
+	{ source: ".imm/memory/dispatch_telemetry.jsonl", evidence: ".imm/audit/legacy-v3/dispatch_telemetry.jsonl" },
+	{ source: ".imm/memory/.current_iteration.authority_commit_receipts.jsonl", evidence: ".imm/audit/legacy-v3/.current_iteration.authority_commit_receipts.jsonl" },
+	{ source: ".imm/memory/.current_iteration.automatic_observations.jsonl", evidence: ".imm/audit/legacy-v3/.current_iteration.automatic_observations.jsonl" },
+	{ source: ".imm/memory/.current_iteration.automatic_observations.lock", evidence: ".imm/audit/legacy-v3/.current_iteration.automatic_observations.lock" },
+	{ source: ".imm/memory/MEMORY.md", evidence: ".imm/audit/legacy-v3/MEMORY.md" },
+	{ source: ".imm/templates/iteration-plan-template.md", evidence: ".imm/audit/legacy-v3/iteration-plan-template.md" },
+	{ source: ".imm/templates/review-report-template.md", evidence: ".imm/audit/legacy-v3/review-report-template.md" },
+	{ source: ".imm/journal.jsonl", evidence: ".imm/audit/legacy-v3/journal.jsonl" },
+	{ source: ".imm/tasks/.workspace.lock", evidence: ".imm/audit/legacy-v3/.workspace.lock" },
+	{ source: ".imm/tasks/.journal.lock", evidence: ".imm/audit/legacy-v3/.journal.lock" },
+] as const;
+
+/**
+ * Retired transaction markers. They are never deleted by the import: each one
+ * records a transaction the prior runtime must settle, so their presence blocks
+ * retirement (and the layout inspector already treats them as a live owner).
+ */
+export const LEGACY_TRANSACTION_MARKERS: ReadonlyArray<string> = [
+	".imm/tasks/.workspace-transaction.json",
+	".imm/tasks/.workspace-transaction-v2.json",
+	".imm/tasks/.enrollment-marker.json",
+	".imm/tasks/.drain-transaction.json",
+	".imm/tasks/.terminal-transaction.json",
+	".imm/tasks/.authority-repair-transaction.json",
+] as const;
+
+/**
+ * Directories that only ever held retired artifacts. Only an empty one is
+ * removed, so a directory this import cannot interpret stays reported instead of
+ * being deleted.
+ */
+export const LEGACY_RETIRED_DIRECTORIES: ReadonlyArray<string> = [
+	".imm/memory",
+	".imm/templates",
+	".imm/authority",
+] as const;
+
 /** Old task-scoped owner files: `<task-id>.json` and `<task-id>.backend-claim.json`. */
 const TASK_OWNER_FILE = /^([A-Za-z0-9][A-Za-z0-9._-]{0,127})\.(json|backend-claim\.json)$/;
 
@@ -352,48 +525,164 @@ function gitDirtyAffected(root: string): string[] | null {
 	return [...dirty].sort();
 }
 
+/**
+ * A pending transaction under the retired file store: a Kernel transaction
+ * marker needing the runtime that wrote it, or an interrupted file-target
+ * migration manifest. Either way the next mutation must stop and diagnose.
+ */
 function pendingNewMarker(root: string): string | null {
-	const entries = listEntries(root, ".imm/state/transactions");
+	const entries = listEntries(root, FILE_STORE_TRANSACTIONS_RELATIVE);
 	if (!entries) return null;
-	for (const entry of entries) {
-		if (entry === "storage-layout-migration.json") return `.imm/state/transactions/${entry}`;
-		if ((KERNEL_TRANSACTION_MARKERS as readonly string[]).includes(entry))
-			return `.imm/state/transactions/${entry}`;
-	}
-	return entries.find((entry) => entry.endsWith(".json"))
-		? `.imm/state/transactions/${entries.find((entry) => entry.endsWith(".json")) ?? ""}`
-		: null;
+	const first = entries.find((entry) => entry.endsWith(".json"));
+	return first ? `${FILE_STORE_TRANSACTIONS_RELATIVE}/${first}` : null;
 }
 
-/** Validate that the new-layout roots are not symlinked outside the
- *  repository (review-10). Called before any lock acquisition or write. */
-function assertNewLayoutRootsSafe(root: string): string | null {
-	for (const relative of [STATE_RELATIVE, AUDIT_RELATIVE]) {
-		const path = resolve(root, relative);
-		let stat;
+/** Read one `store_meta` value without opening the runtime store module. */
+function readStoreMeta(db: DatabaseSync, key: string): string | null {
+	const row = db.prepare("SELECT value FROM store_meta WHERE key = ?").get(key) as
+		| { value?: unknown }
+		| undefined;
+	return row && typeof row.value === "string" ? row.value : null;
+}
+
+/**
+ * SQLite authority store facts: presence plus schema/binding validity. The
+ * inspector stays read-only and never repairs; an incompatible or foreign
+ * store reports `invalid` so no worktree silently mixes authority stores.
+ */
+function readKernelStoreFacts(root: string): { present: boolean; reason: string | null } {
+	const status = entryStatus(root, KERNEL_DB_RELATIVE);
+	if (status === "absent") return { present: false, reason: null };
+	if (status !== "file")
+		return { present: true, reason: `${KERNEL_DB_RELATIVE} is ${status}` };
+	let db: DatabaseSync | null = null;
+	try {
+		db = new DatabaseSync(resolve(root, KERNEL_DB_RELATIVE), { readOnly: true });
+		const version = readStoreMeta(db, "schema_version");
+		if (version !== String(KERNEL_STORE_SCHEMA_VERSION))
+			return {
+				present: true,
+				reason: `kernel store schema version ${version ?? "missing"} is incompatible with this runtime (${KERNEL_STORE_SCHEMA_VERSION})`,
+			};
+		const workspaceId = readStoreMeta(db, "workspace_id");
+		const binding = readStoreMeta(db, "workspace_binding");
+		if (!workspaceId || !binding)
+			return { present: true, reason: "kernel store identity metadata is missing" };
+		if (kernelStoreBindingDigest(realpathSync(root), workspaceId) !== binding)
+			return {
+				present: true,
+				reason: "kernel store belongs to a different worktree; restore it into its binding worktree or run the supported rebinding",
+			};
+		return { present: true, reason: null };
+	} catch (error) {
+		return {
+			present: true,
+			reason: `kernel store is unreadable: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	} finally {
 		try {
-			stat = lstatSync(path);
-		} catch (error) {
-			const code = (error as NodeJS.ErrnoException).code;
-			if (code === "ENOENT" || code === "ENOTDIR") continue;
-			return `${relative} is unreadable`;
+			db?.close();
+		} catch {
+			// The connection is already closed.
 		}
-		if (stat.isSymbolicLink())
-			return `${relative} is a symlink`;
-		// Walk parent segments to detect symlinked ancestors.
-		let cursor = resolve(root);
-		for (const segment of relative.split("/")) {
-			cursor = resolve(cursor, segment);
-			try {
-				const parentStat = lstatSync(cursor);
-				if (parentStat.isSymbolicLink())
-					return `${relative} traverses a symlink parent`;
-			} catch {
+	}
+}
+
+interface FileStoreFacts {
+	present: boolean;
+	/** Retired per-task TaskRecords: authority no migration may ignore. */
+	records_present: boolean;
+	blocked_active: boolean;
+	pending_marker: string | null;
+	fail_reason: string | null;
+}
+
+const KERNEL_DB_ENTRIES = [
+	"kernel.sqlite",
+	"kernel.sqlite-wal",
+	"kernel.sqlite-shm",
+	// The store's creation marker: it travels with the database and is what
+	// distinguishes a new worktree store from a damaged one.
+	"kernel.identity.json",
+];
+
+/**
+ * Facts about the retired `.imm/state/*.json` file store. Its authority must be
+ * imported through the supported migration before this runtime may mutate the
+ * worktree; the inspector only describes what it finds.
+ */
+function inspectFileStoreLayout(root: string): FileStoreFacts {
+	const facts: FileStoreFacts = {
+		present: false,
+		records_present: false,
+		blocked_active: false,
+		pending_marker: null,
+		fail_reason: null,
+	};
+	try {
+		const stateStatus = entryStatus(root, STATE_RELATIVE);
+		if (stateStatus === "symlink" || stateStatus === "other")
+			throw new Error(`${STATE_RELATIVE} is ${stateStatus}`);
+		if (stateStatus !== "directory") return facts;
+		for (const entry of listEntries(root, STATE_RELATIVE) ?? []) {
+			const full = `${STATE_RELATIVE}/${entry}`;
+			const status = entryStatus(root, full);
+			if (status === "symlink" || status === "other")
+				throw new Error(`${full} is ${status}`);
+			if (KERNEL_DB_ENTRIES.includes(entry)) {
+				if (status !== "file") throw new Error(`${full} is not a regular file`);
+				continue;
+			}
+			if (status === "directory") {
+				if (
+					![
+						FILE_STORE_TASKS_RELATIVE,
+						FILE_STORE_TRANSACTIONS_RELATIVE,
+						FILE_STORE_LOCKS_RELATIVE,
+						FILE_STORE_OBSERVATIONS_RELATIVE,
+						BATCH_STATE_RELATIVE,
+					].includes(full)
+				)
+					throw new Error(`unknown directory under ${STATE_RELATIVE}: ${entry}`);
 				continue;
 			}
+			if ((FILE_STORE_INERT_FILES as readonly string[]).includes(full)) continue;
+			facts.present = true;
+			if (full === FILE_STORE_CLAIM_RELATIVE) {
+				// The file-store claim is the workspace owner regardless of contents.
+				facts.blocked_active = true;
+				continue;
+			}
+			if (full === FILE_STORE_WORKSPACE_RELATIVE) {
+				const owner = readJsonField(root, full, "current_working");
+				if (typeof owner === "string" && owner.length > 0) facts.blocked_active = true;
+				continue;
+			}
+			throw new Error(`unknown file under ${STATE_RELATIVE}: ${entry}`);
 		}
+		for (const entry of listEntries(root, FILE_STORE_TASKS_RELATIVE) ?? []) {
+			const full = `${FILE_STORE_TASKS_RELATIVE}/${entry}`;
+			const status = entryStatus(root, full);
+			if (status === "symlink" || status === "other")
+				throw new Error(`${full} is ${status}`);
+			if (status !== "file") throw new Error(`${full} is not a regular file`);
+			if (!entry.endsWith(".json"))
+				throw new Error(`unknown file under ${FILE_STORE_TASKS_RELATIVE}: ${entry}`);
+			facts.present = true;
+			facts.records_present = true;
+			const lifecycle =
+				readJsonField(root, full, "lifecycle") ?? readJsonField(root, full, "phase");
+			if (lifecycle !== "done" && lifecycle !== "stopped") facts.blocked_active = true;
+		}
+		const marker = pendingNewMarker(root);
+		if (marker) {
+			facts.present = true;
+			facts.pending_marker = marker;
+		}
+	} catch (error) {
+		facts.fail_reason = error instanceof Error ? error.message : String(error);
 	}
-	return null;
+	return facts;
 }
 
 export function inspectStorageLayout(root: string): StorageLayoutInspection {
@@ -419,52 +708,105 @@ export function inspectStorageLayout(root: string): StorageLayoutInspection {
 			reason: oldFacts.fail_reason,
 		};
 	}
+	const fileFacts = inspectFileStoreLayout(root);
+	if (fileFacts.fail_reason) {
+		return {
+			contract: "assurance_kernel/storage_layout_inspection/v1",
+			layout: "invalid",
+			old_authority_present: fileFacts.present,
+			pending_marker: null,
+			dirty_affected_paths: [],
+			reason: fileFacts.fail_reason,
+		};
+	}
 
-	const newMarker = pendingNewMarker(root);
+	const store = readKernelStoreFacts(root);
 	const auditPresent = entryStatus(root, AUDIT_RELATIVE) !== "absent";
 	const dirty = gitDirtyAffected(root);
+	const legacyAuthority = oldFacts.old_authority_present || fileFacts.present;
+	// With a SQLite store present, a derived claim/owner file is decided by the
+	// task-scoped mutation path (which refuses a foreign owner), so only retired
+	// TaskRecords and pending markers make the layout itself invalid.
+	const storeConflictAuthority =
+		oldFacts.old_authority_present ||
+		fileFacts.records_present ||
+		fileFacts.pending_marker !== null;
+
+	if (store.present) {
+		if (store.reason) {
+			return {
+				contract: "assurance_kernel/storage_layout_inspection/v1",
+				layout: "invalid",
+				old_authority_present: legacyAuthority,
+				pending_marker: null,
+				dirty_affected_paths: dirty ?? [],
+				reason: store.reason,
+			};
+		}
+		if (storeConflictAuthority) {
+			return {
+				contract: "assurance_kernel/storage_layout_inspection/v1",
+				layout: "invalid",
+				old_authority_present: true,
+				pending_marker: fileFacts.pending_marker,
+				dirty_affected_paths: dirty ?? [],
+				reason:
+					"both a SQLite authority store and retired file-store authority exist; import or remove the retired store with the supported migration before mutating",
+			};
+		}
+		return {
+			contract: "assurance_kernel/storage_layout_inspection/v1",
+			layout: "ready",
+			old_authority_present: false,
+			pending_marker: null,
+			dirty_affected_paths: [],
+			reason: null,
+		};
+	}
 
-	if (oldFacts.pending_marker || newMarker) {
+	if (fileFacts.pending_marker || oldFacts.pending_marker) {
 		return {
 			contract: "assurance_kernel/storage_layout_inspection/v1",
 			layout: "recovery_required",
-			old_authority_present: oldFacts.old_authority_present,
-			pending_marker: oldFacts.pending_marker ?? newMarker,
+			old_authority_present: legacyAuthority,
+			pending_marker: fileFacts.pending_marker ?? oldFacts.pending_marker,
 			dirty_affected_paths: dirty ?? [],
-			reason: "a recoverable migration or Kernel transaction marker exists; mutation must recover it under lock first",
+			reason:
+				"a retired transaction marker exists; settle it with the runtime that wrote it before importing authority into SQLite",
 		};
 	}
-	if (oldFacts.blocked_active) {
+	if (fileFacts.blocked_active || oldFacts.blocked_active) {
 		return {
 			contract: "assurance_kernel/storage_layout_inspection/v1",
 			layout: "migration_blocked_active",
 			old_authority_present: true,
 			pending_marker: null,
 			dirty_affected_paths: dirty ?? [],
-			reason: "an active claim, nonterminal TaskRecord, non-null workspace owner, or non-idle v3 Ledger exists in the old layout; settle or stop it with the prior runtime first",
+			reason:
+				"an active claim, nonterminal TaskRecord or non-null workspace owner exists in the retired file store; settle or stop it with the prior runtime first",
 		};
 	}
-	if (oldFacts.old_authority_present) {
+	if (legacyAuthority) {
 		return {
 			contract: "assurance_kernel/storage_layout_inspection/v1",
 			layout: "migration_required",
 			old_authority_present: true,
 			pending_marker: null,
 			dirty_affected_paths: dirty ?? [],
-			reason: "an owner-free legacy layout exists; the next eligible stateful mutation runs the one-release migration and stops",
+			reason:
+				"an owner-free retired file store exists; it must be imported into the SQLite authority store by the supported migration",
 		};
 	}
 	if (dirty !== null && dirty.length > 0) {
-		// review-2: cleanup-only migrations (deleted templates, MEMORY.md,
-		// owner-free workspace) still leave an affected diff that must be
-		// committed before the layout can be ready.
+		// Cleanup-only migrations (deleted templates, MEMORY.md, owner-free
+		// workspace) still leave an affected diff that must be committed first.
 		return {
 			contract: "assurance_kernel/storage_layout_inspection/v1",
 			layout: "migration_uncommitted",
 			old_authority_present: false,
 			pending_marker: null,
 			dirty_affected_paths: dirty,
-			reason: "affected audit or retired legacy paths differ from HEAD; commit the migration diff before any managed mutation",
+			reason: "affected audit or retired legacy paths differ from HEAD; commit the diff before any managed mutation",
 		};
 	}
 	if (auditPresent && dirty === null) {
@@ -485,4 +827,35 @@ export function inspectStorageLayout(root: string): StorageLayoutInspection {
 		dirty_affected_paths: [],
 		reason: null,
 	};
-}
+}
+
+/** Validate that the new-layout roots are not symlinked outside the
+ *  repository (review-10). Called before any lock acquisition or write. */
+function assertNewLayoutRootsSafe(root: string): string | null {
+	for (const relative of [STATE_RELATIVE, AUDIT_RELATIVE]) {
+		const path = resolve(root, relative);
+		let stat;
+		try {
+			stat = lstatSync(path);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT" || code === "ENOTDIR") continue;
+			return `${relative} is unreadable`;
+		}
+		if (stat.isSymbolicLink())
+			return `${relative} is a symlink`;
+		// Walk parent segments to detect symlinked ancestors.
+		let cursor = resolve(root);
+		for (const segment of relative.split("/")) {
+			cursor = resolve(cursor, segment);
+			try {
+				const parentStat = lstatSync(cursor);
+				if (parentStat.isSymbolicLink())
+					return `${relative} traverses a symlink parent`;
+			} catch {
+				continue;
+			}
+		}
+	}
+	return null;
+}

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

@@ -158,15 +158,16 @@ export interface TaskIntentRefV3 {
 	content_hash: string;
 }
 
-export interface TaskEvidenceV2 {
+/**
+ * One non-blocking Review note. Advisories travel inside the attestation itself
+ * so a crash can never commit a pass verdict without its notes.
+ */
+export interface ReviewAdvisoryFindingV1 {
 	id: string;
-	acceptance_id: string;
-	task_revision: number;
-	intent_content_hash: string;
-	diff_hash: string;
-	status: EvidenceStatus;
-	actor_id: string;
+	acceptance_id: string | null;
 	summary: string;
+	anchor: string | null;
+	evidence: FindingEvidence | null;
 }
 
 export interface TaskApprovalV2 {
@@ -184,6 +185,8 @@ export interface TaskApprovalV2 {
 	 * anywhere else, so QA and user attestations never carry revision bytes.
 	 */
 	review_revision?: ReviewRevisionIdentityV1;
+	/** Legal only on a review attestation, alongside its revision identity. */
+	advisory_findings?: ReviewAdvisoryFindingV1[];
 }
 
 export interface ReviewRevisionIdentityV1 {
@@ -194,16 +197,6 @@ export interface ReviewRevisionIdentityV1 {
 	manifest_digest: string;
 }
 
-export interface TaskHistoryEntryV2 {
-	id: string;
-	at: string;
-	type: string;
-	from_phase: TaskPhase;
-	to_phase: TaskPhase;
-	reason: string;
-	authority?: AuthorityAuditDescriptor;
-}
-
 export interface TaskAttestationV3 extends TaskApprovalV2 {
 	acceptance_results: Array<{
 		acceptance_id: string;
@@ -222,21 +215,6 @@ export interface TaskHistoryEntryV3 {
 	authority?: AuthorityAuditDescriptor;
 }
 
-export interface TaskRecordV2 {
-	contract: typeof TASK_RECORD_CONTRACT_V2;
-	task_id: string;
-	intent_revision: number;
-	intent_snapshot: TaskIntentV1;
-	intent_ref: TaskIntentRefV1;
-	artifact_ref?: { state: "active" | "frozen"; spec_path?: string };
-	phase: TaskPhase;
-	baseline: string;
-	evidence: TaskEvidenceV2[];
-	findings: TaskFinding[];
-	approvals: TaskApprovalV2[];
-	history: TaskHistoryEntryV2[];
-}
-
 export interface TaskRecordV3 {
 	contract: typeof TASK_RECORD_CONTRACT_V3;
 	task_id: string;
@@ -260,17 +238,8 @@ export interface TaskRecordV4 extends Omit<TaskRecordV3, "contract"> {
 	git_base_head: string;
 }
 
-/** 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;
-}
+/** The live record shape every Kernel owner passes around. The v3 drain window is closed: `TaskRecordV2`/`TaskRecordV3` remain only as the frozen historical shapes `readAuditTaskPair` reads from `.imm/audit/`. */
+export type TaskRecord = TaskRecordV4;
 
 export interface TaskProjectionV3 extends CompletionDecision {
 	contract: "assurance_kernel/projection/v3";