immune-brain 2.8.2

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

@@ -0,0 +1,300 @@
+// TaskRecord v3 mutation port. The single locked application path that
+// rereads and consumes Intent identity, validates action/record/diff/CAS
+// identity, consumes authority when privileged, reduces, and commits through
+// the dedicated recoverable workspace transaction. Consumed by the Pi canary
+// host adapter via canary_application.
+
+import {
+	type MutationAuthorityRegistry,
+	type ValidatedAuthorityV2,
+} from "./authority_port";
+import { canonicalIntentHash, readTaskIntent } from "./intent";
+import {
+	inspectIntentTokenPair,
+	consumeIntentToken,
+	type TaskIntentIdentityToken,
+} from "./intent_token_registry";
+import {
+	reduceTask,
+	canonicalRecordHash,
+	findingsDigestV2,
+	isReducedMutation,
+} from "./reducer";
+import {
+	commitTaskRecordLocked,
+	commitTerminalLocked,
+	readTaskRecordRaw,
+	readWorkspaceStateRaw,
+	revisionForContent,
+	serializeWorkspace,
+	withKernelStoreLock,
+	type WorkspaceState,
+	type WorkspaceTransactionV2,
+	type ArtifactRelocationV1,
+} from "./storage";
+import type {
+	AuthorityAuditDescriptor,
+	MutationAuthorityCapabilityV2,
+	StoredTaskMutationV3,
+	TaskAction,
+	TaskIntentV1,
+} from "./types";
+import { TASK_TOMBSTONE_CONTRACT, type TaskTombstone } from "./backend_claim";
+import { KernelInvariantError, parseTaskAction } from "./validation";
+
+export interface ApplyTaskActionInput {
+	root: string;
+	task_id: string;
+	action: unknown;
+	prior_intent_token: TaskIntentIdentityToken;
+	/** Paired mutation authority registry that must recognize every supplied capability. */
+	registry: MutationAuthorityRegistry;
+	capability?: MutationAuthorityCapabilityV2;
+	/** Trusted injected diff provider; the action's diff_hash is only an expectation. */
+	diffProvider: (root: string, intent: TaskIntentV1) => string;
+	now?: number;
+	/**
+	 * Terminal commit mode: record + workspace + active-claim removal + task
+	 * tombstone converge through one recoverable terminal transaction marker
+	 * instead of the ordinary v2 transaction.
+	 */
+	terminal?: {
+		terminalized_at: string;
+	};
+	artifact_transition?: {
+		relocations: ArtifactRelocationV1[];
+		next_intent_path: string;
+		next_artifact_state: "active" | "frozen";
+	};
+}
+
+export function applyTaskAction(
+	input: ApplyTaskActionInput,
+): StoredTaskMutationV3 {
+	const { root, task_id, prior_intent_token, registry, capability, diffProvider, now } =
+		input;
+	return withKernelStoreLock(root, () => {
+		const current = readTaskRecordRaw(root, task_id);
+		if (!current.record)
+			throw new KernelInvariantError([
+				`task ${task_id} has no TaskRecord v3`,
+			]);
+		const workspace = readWorkspaceStateRaw(root);
+		const action = parseTaskAction(input.action);
+
+		// Expected-hash CAS and workspace ownership are validated after the
+		// preflight reduction: exact committed replay returns before these
+		// checks (the action carries the pre-commit expected hashes), while
+		// new events must carry the exact current identities and must fail
+		// closed before any token or capability is consumed.
+
+		// Trusted diff provider is the only diff authority.
+		const diffHash = diffProvider(root, current.record.intent_snapshot);
+		if (diffHash !== action.diff_hash)
+			throw new KernelInvariantError([
+				`action diff_hash ${action.diff_hash} does not match the trusted diff ${diffHash}`,
+			]);
+
+		// Fresh secure reread of the sidecar inside the same lock.
+		const freshRead = readTaskIntent(root, task_id, current.record.intent_ref.path);
+		const { prior: priorIdentity, current: currentIdentity } =
+			inspectIntentTokenPair(prior_intent_token, freshRead.token);
+		if (
+			priorIdentity.sidecar_path !== freshRead.intent_ref.path ||
+			currentIdentity.sidecar_path !== freshRead.intent_ref.path
+		)
+			throw new KernelInvariantError([
+				"intent token sidecar path mismatch",
+			]);
+		// A→B→A swap detection: the prior token must represent the same file
+		// identity as the fresh reread, even when the content hash is equal.
+		if (
+			priorIdentity.path_dev !== currentIdentity.path_dev ||
+			priorIdentity.path_ino !== currentIdentity.path_ino ||
+			priorIdentity.fd_dev !== currentIdentity.fd_dev ||
+			priorIdentity.fd_ino !== currentIdentity.fd_ino
+		)
+			throw new KernelInvariantError([
+				"intent sidecar identity changed between reads",
+			]);
+
+		const isRevisionAction =
+			action.type === "revise_intent" ||
+			action.type === "approve_breaking_intent_revision";
+
+		if (isRevisionAction) {
+			// Prior token must bind the old committed record identity.
+			if (
+				priorIdentity.intent_content_hash !==
+				current.record.intent_ref.content_hash
+			)
+				throw new KernelInvariantError([
+					"prior intent token does not match the committed record intent",
+				]);
+			// Fresh token must bind the next intent carried by the action.
+			if (
+				freshRead.content_hash !==
+					canonicalIntentHash(action.next_intent) ||
+				action.next_intent_ref.content_hash !== freshRead.content_hash ||
+				action.next_intent.revision !== freshRead.intent.revision
+			)
+				throw new KernelInvariantError([
+					"fresh intent token does not match the requested next intent",
+				]);
+		} else {
+			// Both tokens must bind the committed record intent identity.
+			if (
+				priorIdentity.intent_content_hash !==
+					current.record.intent_ref.content_hash ||
+				currentIdentity.intent_content_hash !==
+					current.record.intent_ref.content_hash
+			)
+				throw new KernelInvariantError([
+					"intent token does not match the committed record intent",
+				]);
+		}
+
+		const privileged =
+			action.type === "record_approval" ||
+			action.type === "record_user_approval" ||
+			action.type === "approve_breaking_intent_revision" ||
+			action.type === "request_rework" ||
+			action.type === "stop" ||
+			action.type === "resolve_user_decision";
+
+		const expectedAuthority = privileged
+			? {
+					task_id,
+					action,
+					expected_record_hash: current.revision,
+					intent_revision: isRevisionAction
+						? action.next_intent.revision
+						: current.record.intent_snapshot.revision,
+					intent_content_hash: isRevisionAction
+						? freshRead.content_hash
+						: current.record.intent_ref.content_hash,
+					diff_hash: diffHash,
+					...(action.type === "request_rework"
+						? { findings_digest: findingsDigestV2(action.findings) }
+						: {}),
+				}
+			: null;
+
+		// Preflight reduction with inspected (not consumed) authority. The pure
+		// reducer enforces expected-hash equality for new events, lifecycle rules,
+		// replay identity, and conflicting reuse, so any throw is a zero-write
+		// failure (including stale record/workspace CAS).
+		const inspectedAudit = expectedAuthority
+			? registry.inspect(capability, expectedAuthority, now)
+			: null;
+		const mutation = reduceTask(
+			current.record,
+			action,
+			inspectedAudit ? (inspectedAudit.audit as AuthorityAuditDescriptor) : null,
+		);
+		if (!isReducedMutation(mutation))
+			throw new KernelInvariantError(["reducer returned an invalid mutation"]);
+
+		// Exact committed replay: identical record -> return committed snapshot
+		// without consuming tokens or authority.
+		if (canonicalRecordHash(mutation.record) === current.revision)
+			return {
+				revision: current.revision,
+				record: current.record,
+				workspace,
+			};
+
+		// New event: enforce stale CAS and workspace ownership preflight.
+		if (action.expected_record_hash !== current.revision)
+			throw new KernelInvariantError([
+				`expected record hash mismatch: ${action.expected_record_hash} != ${current.revision}`,
+			]);
+		if (action.expected_workspace_hash !== workspace.revision)
+			throw new KernelInvariantError([
+				`expected workspace hash mismatch: ${action.expected_workspace_hash} != ${workspace.revision}`,
+			]);
+		if (
+			workspace.state.current_working !== null &&
+			workspace.state.current_working !== task_id
+		)
+			throw new KernelInvariantError([
+				`workspace is already owned by ${workspace.state.current_working}`,
+			]);
+
+		// All preflight passed: consume tokens and authority, then commit.
+		consumeIntentToken(prior_intent_token);
+		consumeIntentToken(freshRead.token);
+		let consumedAudit: ValidatedAuthorityV2 | null = null;
+		if (expectedAuthority) {
+			consumedAudit = registry.consume(
+				capability as MutationAuthorityCapabilityV2,
+				expectedAuthority,
+				now,
+			);
+		}
+
+		const nextWorking = mutation.next_workspace_working;
+		const nextRecord = input.artifact_transition
+			? {
+					...mutation.record,
+					intent_ref: {
+						...mutation.record.intent_ref,
+						path: input.artifact_transition.next_intent_path,
+					},
+					artifact_state: input.artifact_transition.next_artifact_state,
+				}
+			: mutation.record;
+		let nextWorkspaceState: WorkspaceState = workspace.state;
+		if (nextWorking !== null) {
+			nextWorkspaceState = {
+				...workspace.state,
+				current_working: task_id,
+			};
+		} else if (workspace.state.current_working === task_id) {
+			nextWorkspaceState = {
+				...workspace.state,
+				current_working: null,
+			};
+		}
+
+		if (input.terminal) {
+			const tombstone: TaskTombstone = {
+				contract: TASK_TOMBSTONE_CONTRACT,
+				task_id,
+				lifecycle_status: "terminal",
+				terminal_lifecycle: nextRecord.lifecycle,
+				terminal_event_id: action.event_id,
+				final_record_hash: canonicalRecordHash(nextRecord),
+				terminalized_at: input.terminal.terminalized_at,
+			};
+			const transaction: WorkspaceTransactionV2 = {
+				contract: "assurance_kernel/workspace_transaction/v2",
+				task_id,
+				expected_record_hash: current.revision,
+				next_record_content: `${JSON.stringify(nextRecord, null, 2)}\n`,
+				expected_workspace_hash: workspace.revision,
+				next_workspace_content: serializeWorkspace(nextWorkspaceState),
+				...(input.artifact_transition ? { artifact_relocations: input.artifact_transition.relocations } : {}),
+			};
+			commitTerminalLocked(root, task_id, transaction, tombstone);
+			return {
+				revision: canonicalRecordHash(nextRecord),
+				record: nextRecord,
+				workspace: {
+					revision: revisionForContent(serializeWorkspace(nextWorkspaceState)),
+					state: nextWorkspaceState,
+				},
+			};
+		}
+
+		return commitTaskRecordLocked(
+			root,
+			task_id,
+			current.revision,
+			nextRecord,
+			workspace.revision,
+			nextWorkspaceState,
+			input.artifact_transition?.relocations,
+		);
+	});
+}

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

@@ -0,0 +1,284 @@
+// Assurance projection: the single host-neutral, read-only current-facts
+// projection that binds a task's backend claim, TaskRecord v3, workspace,
+// attestations, findings, and completion facts into one closed result.
+//
+// This module is deliberately INTERNAL to the Kernel runtime: it is imported
+// by the Pi extension only through the structural runtime-stub adapter and is
+// never re-exported from ./index.ts. Hosts consume the projection without
+// reconstructing evidence/approval freshness or authorization readiness.
+//
+// It does not know about Pi session state, pending native Review verdicts,
+// Pi lifecycle actions, TUI concepts, or presentation. It never decides
+// "start QA" or "start Review"; it returns Kernel-owned facts only.
+
+import { readBackendClaim, readTaskTombstone } from "./backend_claim";
+import { readTaskRecord, readAuditTaskPair, readWorkspaceStateRaw, reconcileKernelAuthority } from "./storage";
+import { projectTask } from "./completion";
+import type { AssuranceObligation, TaskIntentV1, TaskRecordV2, TaskRecordV3 } from "./types";
+
+export interface AssuranceAuthorizationReadiness {
+	/**
+	 * Kernel-decidable authorization readiness:
+	 * - "resolve_user_decision": exactly one open unresolved-user-decision finding;
+	 * - "record_user_approval": Kernel projects authorize_user after fresh QA
+	 *   and Review attestations for a critical task;
+	 * - "none": nothing uniquely decidable from Kernel facts.
+	 * A pending Pi native Review verdict is a session fact and is NOT visible
+	 * here; the host composes it before this readiness.
+	 */
+	state: "resolve_user_decision" | "record_user_approval" | "none";
+	/** Non-null only when Kernel facts prove the authorization is blocked. */
+	blocked: string | null;
+}
+
+export interface AssuranceProjection {
+	record_revision: string;
+	workspace_revision: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	diff_hash: string;
+	lifecycle: string;
+	artifact_state: string;
+	risk: TaskIntentV1["risk"] | "";
+	next_obligation: AssuranceObligation;
+	fresh_acceptance_ids: string[];
+	missing_acceptance_ids: string[];
+	stale_attestation_ids: string[];
+	fresh_approval_kinds: string[];
+	missing_approval_kinds: string[];
+	blocking_finding_ids: string[];
+	unresolved_user_decision_ids: string[];
+	replan_required_ids: string[];
+	independence_violations: string[];
+	open_user_decision_count: number;
+	completion_ready: boolean;
+	authorization: AssuranceAuthorizationReadiness;
+}
+
+export interface AssuranceProjectionResult {
+	contract: "assurance_kernel/assurance_projection/v1";
+	task_id: string;
+	error: string | null;
+	claim: { task_id: string; lifecycle_status: string } | null;
+	projection: AssuranceProjection;
+}
+
+export function deriveAssuranceAuthorization(input: {
+	next_obligation: AssuranceObligation;
+	open_user_decision_count: number;
+}): AssuranceAuthorizationReadiness {
+	if (input.open_user_decision_count === 1)
+		return { state: "resolve_user_decision", blocked: null };
+	if (input.open_user_decision_count > 1)
+		return {
+			state: "none",
+			blocked: `resolve-user-decision requires exactly one open user decision; found ${input.open_user_decision_count}`,
+		};
+	if (input.next_obligation === "authorize_user")
+		return { state: "record_user_approval", blocked: null };
+	return { state: "none", blocked: null };
+}
+
+function emptyProjection(): AssuranceProjection {
+	return {
+		record_revision: "",
+		workspace_revision: "",
+		intent_revision: 0,
+		intent_content_hash: "",
+		diff_hash: "",
+		lifecycle: "",
+		artifact_state: "",
+		risk: "",
+		next_obligation: "none",
+		fresh_acceptance_ids: [],
+		missing_acceptance_ids: [],
+		stale_attestation_ids: [],
+		fresh_approval_kinds: [],
+		missing_approval_kinds: [],
+		blocking_finding_ids: [],
+		unresolved_user_decision_ids: [],
+		replan_required_ids: [],
+		independence_violations: [],
+		open_user_decision_count: 0,
+		completion_ready: false,
+		authorization: { state: "none", blocked: null },
+	};
+}
+
+function projectHistoricalTerminal(
+	record: TaskRecordV2,
+	recordRevision: string,
+	workspaceRevision: string,
+): AssuranceProjection {
+	const approvalKinds = [...new Set(record.approvals.map((item) => item.kind))];
+	return {
+		...emptyProjection(),
+		record_revision: recordRevision,
+		workspace_revision: workspaceRevision,
+		intent_revision: record.intent_revision,
+		intent_content_hash: record.intent_ref.content_hash,
+		lifecycle: record.phase,
+		artifact_state: "frozen",
+		risk: record.intent_snapshot.risk,
+		fresh_acceptance_ids: [...new Set(record.evidence.filter((item) => item.status === "passed").map((item) => item.acceptance_id))],
+		fresh_approval_kinds: approvalKinds,
+		completion_ready: record.phase === "done",
+	};
+}
+
+function freshApprovalKinds(
+	record: TaskRecordV3,
+	currentIntentContentHash: string,
+	diffHash: string,
+): string[] {
+	const kinds: string[] = [];
+	const seen = new Set<string>();
+	for (const approval of record.attestations) {
+		if (
+			approval.task_revision !== record.intent_snapshot.revision ||
+			approval.intent_content_hash !== currentIntentContentHash ||
+			approval.diff_hash !== diffHash
+		)
+			continue;
+		if (seen.has(approval.kind)) continue;
+		seen.add(approval.kind);
+		kinds.push(approval.kind);
+	}
+	return kinds;
+}
+
+function projectFromRecord(
+	record: TaskRecordV3,
+	recordRevision: string,
+	workspaceRevision: string,
+	diffHash: string,
+): AssuranceProjection {
+	const intent: TaskIntentV1 = record.intent_snapshot;
+	const decision = projectTask(intent, record, diffHash, record.intent_ref.content_hash);
+	const approvalKinds = freshApprovalKinds(record, record.intent_ref.content_hash, diffHash);
+	const openUserDecisionCount = record.findings.filter(
+		(finding) => finding.kind === "unresolved_user_decision" && finding.status === "open",
+	).length;
+	return {
+		record_revision: recordRevision,
+		workspace_revision: workspaceRevision,
+		intent_revision: record.intent_snapshot.revision,
+		intent_content_hash: record.intent_ref.content_hash,
+		diff_hash: diffHash,
+		lifecycle: record.lifecycle,
+		artifact_state: record.artifact_state,
+		risk: intent.risk,
+		next_obligation: decision.next_obligation,
+		fresh_acceptance_ids: decision.fresh_acceptance_ids,
+		missing_acceptance_ids: decision.missing_acceptance_ids,
+		stale_attestation_ids: decision.stale_attestation_ids,
+		fresh_approval_kinds: approvalKinds,
+		missing_approval_kinds: decision.missing_approval_kinds,
+		blocking_finding_ids: decision.blocking_finding_ids,
+		unresolved_user_decision_ids: decision.unresolved_user_decision_ids,
+		replan_required_ids: decision.replan_required_ids,
+		independence_violations: decision.independence_violations,
+		open_user_decision_count: openUserDecisionCount,
+		completion_ready: decision.complete,
+		authorization: deriveAssuranceAuthorization({
+			next_obligation: decision.next_obligation,
+			open_user_decision_count: openUserDecisionCount,
+		}),
+	};
+}
+
+/**
+ * One closed read-only projection for a task. The injected diffProvider keeps
+ * this module free of git/worktree concerns; hosts supply it from their own
+ * task-scope diff implementation.
+ *
+ * Error semantics:
+ * - no authority facts          -> error null, claim null, empty projection
+ * - matching terminal proof     -> error null, claim null, done/stopped projection
+ * - repairable stale claim      -> error requiring repair_authority_state
+ * - authority conflict          -> fail-closed authority diagnostic
+ * - missing/mismatched record   -> fail-closed identity diagnostic
+ * - any read failure            -> error message, claim null, empty projection
+ */
+export async function projectAssurance(
+	root: string,
+	taskId: string,
+	diffProvider: (root: string, intent: { scope_hint?: unknown }) => string,
+): Promise<AssuranceProjectionResult> {
+	const fail = (
+		error: string,
+		claim: AssuranceProjectionResult["claim"] = null,
+	): AssuranceProjectionResult => ({
+		contract: "assurance_kernel/assurance_projection/v1",
+		task_id: taskId,
+		error,
+		claim,
+		projection: emptyProjection(),
+	});
+	try {
+		const claim = readBackendClaim(root);
+		let terminalOwner = false;
+		if (claim?.task_id !== undefined && claim.task_id !== taskId)
+			return fail(`backend claim belongs to ${claim.task_id}, not ${taskId}`, claim);
+		if (claim) {
+			const tombstone = readTaskTombstone(root, taskId);
+			if (tombstone) {
+				const authority = reconcileKernelAuthority(root, taskId);
+				if (authority.state === "repairable_stale_claim")
+					return fail(`task ${taskId} has a repairable stale backend claim`, claim);
+				return fail(authority.diagnostic ?? `authority state conflicts for ${taskId}`, claim);
+			}
+		} else {
+			const authority = reconcileKernelAuthority(root, taskId);
+			if (authority.state === "unowned")
+				return { contract: "assurance_kernel/assurance_projection/v1", task_id: taskId, error: null, claim: null, projection: emptyProjection() };
+			if (authority.state !== "terminal_owner")
+				return fail(authority.diagnostic ?? `authority state conflicts for ${taskId}`);
+			terminalOwner = true;
+			if (readBackendClaim(root)) return fail(`authority state changed while projecting ${taskId}`);
+		}
+		let read;
+		try {
+			read = await readTaskRecord(root, taskId);
+		} catch (error) {
+			if (!terminalOwner || !(error instanceof Error) || !error.message.startsWith("TaskRecord v2")) throw error;
+			return fail(error instanceof Error ? error.message : String(error));
+		}
+		if (!read.record) {
+			if (!terminalOwner) return fail(`task ${taskId} has no TaskRecord v3`, claim);
+			const auditPair = await readAuditTaskPair(root, taskId);
+			if (!auditPair) return fail(`task ${taskId} has no terminal audit pair`, claim);
+			const workspace = await readWorkspaceStateRaw(root);
+			if (auditPair.record.contract === "assurance_kernel/task_record/v2")
+				return {
+					contract: "assurance_kernel/assurance_projection/v1",
+					task_id: taskId,
+					error: null,
+					claim: null,
+					projection: projectHistoricalTerminal(auditPair.record, auditPair.recordRevision, workspace.revision),
+				};
+			return {
+				contract: "assurance_kernel/assurance_projection/v1",
+				task_id: taskId,
+				error: null,
+				claim: null,
+				projection: projectFromRecord(auditPair.record, auditPair.recordRevision, workspace.revision, diffProvider(root, auditPair.record.intent_snapshot)),
+			};
+		}
+		if (read.record.task_id !== taskId)
+			return fail(`task record identity is inconsistent for ${taskId}`, claim);
+		if (claim && read.record.lifecycle !== "active")
+			return fail(`terminal task ${taskId} has no matching tombstone proof`, claim);
+		const workspace = await readWorkspaceStateRaw(root);
+		const diffHash = diffProvider(root, read.record.intent_snapshot);
+		return {
+			contract: "assurance_kernel/assurance_projection/v1",
+			task_id: taskId,
+			error: null,
+			claim,
+			projection: projectFromRecord(read.record, read.revision, workspace.revision, diffHash),
+		};
+	} catch (error) {
+		return fail(error instanceof Error ? error.message : String(error));
+	}
+}