immune-brain 2.8.2

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

@@ -0,0 +1,208 @@
+// P2B2 mutation authority consumption port. NOT exported from kernel/index.ts.
+// Registry/application pairing: each registry owns its capability state in a
+// closure-private WeakMap, and capabilities are only recognized by the
+// registry that issued them. No module-level singleton and no test issuer
+// exist here; the production registry/application pair is created inside the
+// Pi lifecycle extension activation closure, and tests issue capabilities
+// through tests/fixtures/mutation-authority-test-seam.ts.
+
+import { createHash } from "node:crypto";
+
+import {
+	MUTATION_AUTHORITY_CAPABILITY_BRAND,
+	type AuthorityAuditDescriptor,
+	type MutationAuthorityCapabilityV2,
+	type MutationAuthorityKind,
+	type TaskAction,
+} from "./types";
+
+export interface CapabilityBindingV2 {
+	authority_kind: MutationAuthorityKind;
+	task_id: string;
+	action_digest: string;
+	expected_record_hash: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	diff_hash: string;
+	actor_id: string;
+	confirmation_ref: string;
+	expires_at: string;
+	/** Normalized findings digest required for request_rework; null for other operations. */
+	findings_digest: string | null;
+}
+
+interface CapabilityState extends CapabilityBindingV2 {
+	issued_at: string;
+	consumed: boolean;
+}
+
+export interface ValidatedAuthorityV2 {
+	audit: AuthorityAuditDescriptor;
+	action_digest: string;
+	expected_record_hash: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	diff_hash: string;
+	task_id: string;
+}
+
+export interface MutationAuthorityInspection {
+	task_id: string;
+	action: TaskAction;
+	expected_record_hash: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	diff_hash: string;
+	/** Present only for request_rework bindings. */
+	findings_digest?: string;
+}
+
+export interface MutationAuthorityRegistry {
+	readonly brand: symbol;
+	/** Issue one capability bound to an exact binding. Library primitive; no production caller in P2B2. */
+	issue(binding: CapabilityBindingV2, issuedAt?: string): MutationAuthorityCapabilityV2;
+	/** Inspect without consuming. Fails on missing, expired, mismatched, or reused capability. */
+	inspect(
+		capability: MutationAuthorityCapabilityV2 | undefined,
+		expected: MutationAuthorityInspection,
+		now?: number,
+	): ValidatedAuthorityV2;
+	/** Consume irreversibly. Returns the validated authority. */
+	consume(
+		capability: MutationAuthorityCapabilityV2,
+		expected: MutationAuthorityInspection,
+		now?: number,
+	): ValidatedAuthorityV2;
+	isConsumed(capability: MutationAuthorityCapabilityV2): boolean;
+}
+
+export function digestOfAction(action: TaskAction): string {
+	const { expected_record_hash: _r, expected_workspace_hash: _w, diff_hash: _d, ...rest } = action;
+	return createHash("sha256")
+		.update(JSON.stringify(rest))
+		.digest("hex");
+}
+
+export function createMutationAuthorityRegistry(): MutationAuthorityRegistry {
+	const states = new WeakMap<object, CapabilityState>();
+	const brand = Symbol("assurance-kernel-mutation-authority-registry");
+
+	function isCapability(value: unknown): value is MutationAuthorityCapabilityV2 {
+		return (
+			!!value &&
+			typeof value === "object" &&
+			(value as Record<symbol, unknown>)[MUTATION_AUTHORITY_CAPABILITY_BRAND] === true &&
+			(value as Record<symbol, unknown>)[brand] === true
+		);
+	}
+
+	function stateOf(capability: MutationAuthorityCapabilityV2): CapabilityState {
+		const state = states.get(capability);
+		if (!state) throw new Error("authority capability is not recognized by this registry");
+		return state;
+	}
+
+	function validateBinding(binding: CapabilityBindingV2, issuedAt: string): void {
+		const missing: string[] = [];
+		for (const [key, value] of Object.entries(binding)) {
+			if (key === "findings_digest") continue;
+			if (value === undefined || value === null || value === "") missing.push(key);
+		}
+		if (missing.length > 0)
+			throw new Error(`authority capability binding is incomplete: ${missing.join(", ")}`);
+		if (binding.findings_digest !== null && !/^sha256:[a-f0-9]{64}$/.test(binding.findings_digest))
+			throw new Error("authority capability findings_digest must be a canonical sha256 hash");
+		if (Number.isNaN(Date.parse(binding.expires_at)) || Date.parse(binding.expires_at) <= Date.parse(issuedAt))
+			throw new Error("authority capability must have a future expiry");
+	}
+
+	return {
+		brand,
+		issue(binding: CapabilityBindingV2, issuedAt = new Date().toISOString()): MutationAuthorityCapabilityV2 {
+			validateBinding(binding, issuedAt);
+			const capability = Object.freeze(
+				Object.defineProperties(
+					{},
+					{
+						[MUTATION_AUTHORITY_CAPABILITY_BRAND]: {
+							value: true,
+							enumerable: false,
+							writable: false,
+							configurable: false,
+						},
+						[brand]: {
+							value: true,
+							enumerable: false,
+							writable: false,
+							configurable: false,
+						},
+					},
+				),
+			) as MutationAuthorityCapabilityV2;
+			states.set(capability, {
+				...binding,
+				issued_at: issuedAt,
+				consumed: false,
+			});
+			return capability;
+		},
+		inspect(
+			capability: MutationAuthorityCapabilityV2 | undefined,
+			expected: MutationAuthorityInspection,
+			now = Date.now(),
+		): ValidatedAuthorityV2 {
+			if (!capability || !isCapability(capability))
+				throw new Error("privileged action requires an opaque authority capability");
+			const state = stateOf(capability);
+			if (state.consumed) throw new Error("authority capability is already consumed");
+			if (Date.parse(state.expires_at) <= now)
+				throw new Error("authority capability has expired");
+			const actionDigest = digestOfAction(expected.action);
+			if (state.action_digest !== actionDigest)
+				throw new Error("authority capability action digest mismatch");
+			if (state.task_id !== expected.task_id)
+				throw new Error("authority capability task mismatch");
+			if (state.expected_record_hash !== expected.expected_record_hash)
+				throw new Error("authority capability record hash mismatch");
+			if (state.intent_revision !== expected.intent_revision)
+				throw new Error("authority capability intent revision mismatch");
+			if (state.intent_content_hash !== expected.intent_content_hash)
+				throw new Error("authority capability intent hash mismatch");
+			if (state.diff_hash !== expected.diff_hash)
+				throw new Error("authority capability diff hash mismatch");
+			if (expected.findings_digest !== undefined) {
+				if (state.findings_digest === null)
+					throw new Error("authority capability is not bound to findings");
+				if (state.findings_digest !== expected.findings_digest)
+					throw new Error("authority capability findings digest mismatch");
+			}
+			return {
+				audit: {
+					authority_kind: state.authority_kind,
+					actor_id: state.actor_id,
+					confirmation_ref: state.confirmation_ref,
+					issued_at: state.issued_at,
+					expires_at: state.expires_at,
+				},
+				action_digest: actionDigest,
+				expected_record_hash: state.expected_record_hash,
+				intent_revision: state.intent_revision,
+				intent_content_hash: state.intent_content_hash,
+				diff_hash: state.diff_hash,
+				task_id: state.task_id,
+			};
+		},
+		consume(
+			capability: MutationAuthorityCapabilityV2,
+			expected: MutationAuthorityInspection,
+			now = Date.now(),
+		): ValidatedAuthorityV2 {
+			const validated = this.inspect(capability, expected, now);
+			stateOf(capability).consumed = true;
+			return validated;
+		},
+		isConsumed(capability: MutationAuthorityCapabilityV2): boolean {
+			return stateOf(capability).consumed;
+		},
+	};
+}

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

@@ -0,0 +1,451 @@
+import { createHash } from "node:crypto";
+import {
+	closeSync,
+	constants,
+	existsSync,
+	fstatSync,
+	fsyncSync,
+	lstatSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { stableStringify } from "../canonical_json";
+import {
+	AUTHORITY_OBSERVATION_GENERATION_V2,
+	AUTHORITY_OBSERVER_VERSION_V2,
+} from "../authority_commit_receipts";
+import type { LegacyMapping, V3CommitSourceEvent } from "./types";
+
+const JOURNAL_RELATIVE_PATH =
+	".imm/state/observations/automatic_observations.jsonl";
+const LOCK_RELATIVE_PATH =
+	".imm/state/observations/automatic_observations.lock";
+const MAX_JOURNAL_BYTES = 64 * 1024 * 1024;
+
+export interface V3AuthorityObservationV2 {
+	contract: "assurance_kernel/v3_authority_observation/v2";
+	observation_id: string;
+	receipt_record_id: string;
+	receipt_attempt_id: string;
+	receipt_protocol: "assurance_kernel/authority_commit_receipt/v2";
+	receipt_status: "committed" | "recovered_committed";
+	source_kind: "state_mutation" | "project_migration";
+	source_ref: string;
+	state_path_identity: string;
+	committed_bytes_sha256: string;
+	ledger_revision: string;
+	plan_path: string | null;
+	plan_signature: string | null;
+	source_events: V3CommitSourceEvent[];
+	shadow: LegacyMapping;
+	divergence: { detected: boolean; fields: string[] };
+	observer_generation: typeof AUTHORITY_OBSERVATION_GENERATION_V2;
+	observer_version: typeof AUTHORITY_OBSERVER_VERSION_V2;
+	committed_at: string;
+	observed_at: string;
+}
+
+export class AutomaticObservationSecurityError extends Error {}
+export class AutomaticObservationConflictError extends Error {}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function digest(domain: string, payload: string): string {
+	return `sha256:${sha256(`${domain}\0${payload}`)}`;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new AutomaticObservationSecurityError(
+			"automatic observation must be an object",
+		);
+	return value as Record<string, unknown>;
+}
+
+function exactKeys(record: Record<string, unknown>, expected: string[]): void {
+	if (
+		JSON.stringify(Object.keys(record).sort()) !==
+		JSON.stringify([...expected].sort())
+	)
+		throw new AutomaticObservationSecurityError(
+			"automatic observation v2 has unknown or missing fields",
+		);
+}
+
+function nonEmptyString(record: Record<string, unknown>, key: string): string {
+	const value = record[key];
+	if (typeof value !== "string" || !value)
+		throw new AutomaticObservationSecurityError(
+			`automatic observation v2 ${key} is invalid`,
+		);
+	return value;
+}
+
+function parseSourceEvents(value: unknown): V3CommitSourceEvent[] {
+	if (!Array.isArray(value))
+		throw new AutomaticObservationSecurityError(
+			"automatic observation v2 source_events is invalid",
+		);
+	return value.map((entry) => {
+		const record = asRecord(entry);
+		exactKeys(record, ["action", "at", "id"]);
+		const id = nonEmptyString(record, "id");
+		const action = nonEmptyString(record, "action");
+		if (record.at !== null && typeof record.at !== "string")
+			throw new AutomaticObservationSecurityError(
+				"automatic observation v2 source event time is invalid",
+			);
+		return { id, action, at: record.at as string | null };
+	});
+}
+
+function parseLegacyMapping(value: unknown): LegacyMapping {
+	const record = asRecord(value);
+	exactKeys(record, ["ambiguous", "phase", "reason", "source_states"]);
+	if (
+		(record.phase !== null &&
+			!(["working", "review", "done", "stopped"] as unknown[]).includes(
+				record.phase,
+			)) ||
+		typeof record.reason !== "string" ||
+		typeof record.ambiguous !== "boolean" ||
+		!Array.isArray(record.source_states) ||
+		record.source_states.some((entry) => typeof entry !== "string")
+	)
+		throw new AutomaticObservationSecurityError(
+			"automatic observation v2 shadow is invalid",
+		);
+	return record as unknown as LegacyMapping;
+}
+
+function parseDivergence(
+	value: unknown,
+): { detected: boolean; fields: string[] } {
+	const record = asRecord(value);
+	exactKeys(record, ["detected", "fields"]);
+	if (
+		typeof record.detected !== "boolean" ||
+		!Array.isArray(record.fields) ||
+		record.fields.some((entry) => typeof entry !== "string") ||
+		record.detected !== (record.fields.length > 0)
+	)
+		throw new AutomaticObservationSecurityError(
+			"automatic observation v2 divergence is invalid",
+		);
+	return { detected: record.detected, fields: [...record.fields] as string[] };
+}
+
+export function parseAutomaticObservationV2(
+	raw: unknown,
+): V3AuthorityObservationV2 {
+	const record = asRecord(raw);
+	exactKeys(record, [
+		"committed_at",
+		"committed_bytes_sha256",
+		"contract",
+		"divergence",
+		"ledger_revision",
+		"observation_id",
+		"observed_at",
+		"observer_generation",
+		"observer_version",
+		"plan_path",
+		"plan_signature",
+		"receipt_attempt_id",
+		"receipt_protocol",
+		"receipt_record_id",
+		"receipt_status",
+		"shadow",
+		"source_events",
+		"source_kind",
+		"source_ref",
+		"state_path_identity",
+	]);
+	if (
+		record.contract !== "assurance_kernel/v3_authority_observation/v2" ||
+		record.receipt_protocol !==
+			"assurance_kernel/authority_commit_receipt/v2" ||
+		(record.receipt_status !== "committed" &&
+			record.receipt_status !== "recovered_committed") ||
+		record.observer_generation !== AUTHORITY_OBSERVATION_GENERATION_V2 ||
+		record.observer_version !== AUTHORITY_OBSERVER_VERSION_V2 ||
+		(record.source_kind !== "state_mutation" &&
+			record.source_kind !== "project_migration")
+	)
+		throw new AutomaticObservationSecurityError(
+			"automatic observation v2 identity is invalid",
+		);
+	for (const key of [
+		"observation_id",
+		"receipt_record_id",
+		"receipt_attempt_id",
+		"source_ref",
+		"state_path_identity",
+		"committed_bytes_sha256",
+		"ledger_revision",
+		"committed_at",
+		"observed_at",
+	])
+		nonEmptyString(record, key);
+	if (
+		(record.plan_path !== null && typeof record.plan_path !== "string") ||
+		(record.plan_signature !== null &&
+			typeof record.plan_signature !== "string")
+	)
+		throw new AutomaticObservationSecurityError(
+			"automatic observation v2 Plan identity is invalid",
+		);
+	const observation: V3AuthorityObservationV2 = {
+		...(record as unknown as V3AuthorityObservationV2),
+		source_events: parseSourceEvents(record.source_events),
+		shadow: parseLegacyMapping(record.shadow),
+		divergence: parseDivergence(record.divergence),
+	};
+	const { observation_id: _observationId, ...core } = observation;
+	if (
+		observation.observation_id !==
+		digest(
+			"assurance-kernel-v3-observation/v2",
+			stableStringify(core),
+		)
+	)
+		throw new AutomaticObservationSecurityError(
+			"automatic observation v2 identity mismatch",
+		);
+	return observation;
+}
+
+function canonicalRoot(root: string): string {
+	const resolved = resolve(root);
+	const stat = lstatSync(resolved);
+	if (stat.isSymbolicLink() || !stat.isDirectory())
+		throw new AutomaticObservationSecurityError(
+			"automatic observation root must be a real directory",
+		);
+	return realpathSync(resolved);
+}
+
+function insideRoot(root: string, candidate: string): boolean {
+	return candidate === root || candidate.startsWith(`${root}${sep}`);
+}
+
+function ensureMemoryDirectory(root: string): { root: string; memory: string } {
+	// Storage-layout cutover: automatic observations are active runtime state
+	// and live under the ignored .imm/state/observations/ directory.
+	const canonical = canonicalRoot(root);
+	let cursor = canonical;
+	for (const segment of [".imm", "state", "observations"]) {
+		cursor = resolve(cursor, segment);
+		if (!existsSync(cursor)) mkdirSync(cursor, { mode: 0o700 });
+		const stat = lstatSync(cursor);
+		if (stat.isSymbolicLink() || !stat.isDirectory())
+			throw new AutomaticObservationSecurityError(
+				"automatic observation directory is not a real directory",
+			);
+		const real = realpathSync(cursor);
+		if (!insideRoot(canonical, real))
+			throw new AutomaticObservationSecurityError(
+				"automatic observation directory escapes the project",
+			);
+		cursor = real;
+	}
+	return { root: canonical, memory: cursor };
+}
+
+function journalPath(root: string): string {
+	return resolve(canonicalRoot(root), JOURNAL_RELATIVE_PATH);
+}
+
+export function automaticObservationJournalPath(root: string): string {
+	return journalPath(root);
+}
+
+function assertRegularPathOrMissing(path: string): void {
+	if (!existsSync(path)) return;
+	const stat = lstatSync(path);
+	if (stat.isSymbolicLink() || !stat.isFile())
+		throw new AutomaticObservationSecurityError(
+			"automatic observation path is not a regular file",
+		);
+}
+
+function processIsAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+function clearStaleLock(path: string): boolean {
+	if (!existsSync(path)) return true;
+	const before = lstatSync(path);
+	if (before.isSymbolicLink() || !before.isFile())
+		throw new AutomaticObservationSecurityError(
+			"automatic observation lock is not a regular file",
+		);
+	let stale = false;
+	try {
+		const record = JSON.parse(readFileSync(path, "utf8")) as {
+			pid?: unknown;
+		};
+		stale =
+			Number.isInteger(record.pid) &&
+			Number(record.pid) > 0 &&
+			!processIsAlive(Number(record.pid));
+	} catch {
+		stale = Date.now() - before.mtimeMs > 30_000;
+	}
+	if (!stale) return false;
+	const after = lstatSync(path);
+	if (
+		after.isSymbolicLink() ||
+		after.dev !== before.dev ||
+		after.ino !== before.ino
+	)
+		throw new AutomaticObservationSecurityError(
+			"automatic observation lock identity changed",
+		);
+	rmSync(path);
+	return true;
+}
+
+function withLock<T>(root: string, operation: () => T): T {
+	const { memory } = ensureMemoryDirectory(root);
+	const path = resolve(memory, LOCK_RELATIVE_PATH.split("/").at(-1)!);
+	let fd: number | null = null;
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		try {
+			fd = openSync(
+				path,
+				constants.O_WRONLY |
+					constants.O_CREAT |
+					constants.O_EXCL |
+					(constants.O_NOFOLLOW ?? 0),
+				0o600,
+			);
+			break;
+		} catch (error) {
+			if (
+				attempt === 0 &&
+				(error as NodeJS.ErrnoException).code === "EEXIST" &&
+				clearStaleLock(path)
+			)
+				continue;
+			throw new AutomaticObservationConflictError(
+				`automatic observation lock is busy: ${error instanceof Error ? error.message : error}`,
+			);
+		}
+	}
+	if (fd === null)
+		throw new AutomaticObservationConflictError(
+			"automatic observation lock could not be acquired",
+		);
+	const identity = fstatSync(fd);
+	try {
+		writeFileSync(
+			fd,
+			`${JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() })}\n`,
+			"utf8",
+		);
+		fsyncSync(fd);
+		return operation();
+	} finally {
+		closeSync(fd);
+		if (existsSync(path)) {
+			const current = lstatSync(path);
+			if (
+				!current.isSymbolicLink() &&
+				current.dev === identity.dev &&
+				current.ino === identity.ino
+			)
+				rmSync(path);
+		}
+	}
+}
+
+export function readAutomaticObservationsV2(
+	root: string,
+): V3AuthorityObservationV2[] {
+	const path = journalPath(root);
+	assertRegularPathOrMissing(path);
+	if (!existsSync(path)) return [];
+	const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+	try {
+		const before = fstatSync(fd);
+		if (before.size > MAX_JOURNAL_BYTES)
+			throw new AutomaticObservationSecurityError(
+				"automatic observation journal exceeds the read limit",
+			);
+		const content = readFileSync(fd, "utf8");
+		const after = fstatSync(fd);
+		if (before.dev !== after.dev || before.ino !== after.ino)
+			throw new AutomaticObservationSecurityError(
+				"automatic observation journal identity changed",
+			);
+		return content
+			.split("\n")
+			.filter((line) => line.trim())
+			.map((line, index) => {
+				try {
+					return parseAutomaticObservationV2(JSON.parse(line));
+				} catch (error) {
+					throw new AutomaticObservationSecurityError(
+						`automatic observation line ${index + 1} is invalid: ${error instanceof Error ? error.message : error}`,
+					);
+				}
+			});
+	} finally {
+		closeSync(fd);
+	}
+}
+
+export function appendAutomaticObservationV2(
+	root: string,
+	input: V3AuthorityObservationV2,
+): "appended" | "duplicate" {
+	const observation = parseAutomaticObservationV2(input);
+	return withLock(root, () => {
+		for (const existing of readAutomaticObservationsV2(root)) {
+			if (existing.receipt_record_id !== observation.receipt_record_id)
+				continue;
+			if (existing.observation_id === observation.observation_id)
+				return "duplicate";
+			throw new AutomaticObservationConflictError(
+				`automatic observation receipt identity conflict: ${observation.receipt_record_id}`,
+			);
+		}
+		ensureMemoryDirectory(root);
+		const path = resolve(root, JOURNAL_RELATIVE_PATH);
+		assertRegularPathOrMissing(path);
+		const fd = openSync(
+			path,
+			constants.O_WRONLY |
+				constants.O_CREAT |
+				constants.O_APPEND |
+				(constants.O_NOFOLLOW ?? 0),
+			0o600,
+		);
+		try {
+			writeFileSync(fd, `${JSON.stringify(observation)}\n`, "utf8");
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		const directoryFd = openSync(dirname(path), constants.O_RDONLY);
+		try {
+			fsyncSync(directoryFd);
+		} finally {
+			closeSync(directoryFd);
+		}
+		return "appended";
+	});
+}