immune-brain 3.6.9 → 4.0.0

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

@@ -1,8 +1,6 @@
 import {
 	TASK_ARTIFACT_STATES,
 	TASK_LIFECYCLES,
-	TASK_PHASES,
-	TASK_RECORD_CONTRACT_V2,
 	TASK_RECORD_CONTRACT_V3,
 	TASK_RECORD_CONTRACT_V4,
 	REVIEW_REVISION_IDENTITY_CONTRACT,
@@ -15,17 +13,15 @@ import {
 	type FindingSource,
 	type FindingStatus,
 	type TaskAction,
+	type ReviewAdvisoryFindingV1,
 	type TaskApprovalV2,
 	type TaskAttestationV3,
 	type AuthorityAuditDescriptor,
-	type TaskEvidenceV2,
 	type TaskFinding,
-	type TaskHistoryEntryV2,
 	type TaskHistoryEntryV3,
 	type TaskIntentV1,
 	type ReviewRevisionIdentityV1,
 	type TaskRecord,
-	type TaskRecordV2,
 	type TaskRecordV3,
 	type TaskRecordV4,
 } from "./types";
@@ -52,7 +48,7 @@ export class KernelInvariantError extends Error {
 	}
 }
 
-function objectAt(
+export function objectAt(
 	value: unknown,
 	path: string,
 	violations: string[],
@@ -64,7 +60,7 @@ function objectAt(
 	return value as Record<string, unknown>;
 }
 
-function rejectUnknown(
+export function rejectUnknown(
 	record: Record<string, unknown>,
 	allowed: readonly string[],
 	path: string,
@@ -78,7 +74,7 @@ function rejectUnknown(
 	}
 }
 
-function stringAt(
+export function stringAt(
 	value: unknown,
 	path: string,
 	violations: string[],
@@ -90,7 +86,7 @@ function stringAt(
 	return value;
 }
 
-function positiveInteger(
+export function positiveInteger(
 	value: unknown,
 	path: string,
 	violations: string[],
@@ -120,7 +116,7 @@ function nullablePositiveInteger(
 	return positiveInteger(value, path, violations);
 }
 
-function enumAt<T extends string>(
+export function enumAt<T extends string>(
 	value: unknown,
 	allowed: readonly T[],
 	path: string,
@@ -133,7 +129,7 @@ function enumAt<T extends string>(
 	return value as T;
 }
 
-function arrayAt(value: unknown, path: string, violations: string[]): unknown[] {
+export function arrayAt(value: unknown, path: string, violations: string[]): unknown[] {
 	if (!Array.isArray(value)) {
 		violations.push(`${path} must be an array`);
 		return [];
@@ -141,7 +137,7 @@ function arrayAt(value: unknown, path: string, violations: string[]): unknown[]
 	return value;
 }
 
-function uniqueIds(
+export function uniqueIds(
 	items: Array<{ id: string }>,
 	path: string,
 	violations: string[],
@@ -153,7 +149,7 @@ function uniqueIds(
 	}
 }
 
-const EVIDENCE_STATUSES: EvidenceStatus[] = ["passed", "failed", "blocked"];
+export const EVIDENCE_STATUSES: EvidenceStatus[] = ["passed", "failed", "blocked"];
 const FINDING_KINDS: FindingKind[] = [
 	"blocking",
 	"advisory",
@@ -224,7 +220,7 @@ function parseFindingCounterevidence(
 	};
 }
 
-function parseFinding(
+export function parseFinding(
 	value: unknown,
 	index: number,
 	violations: string[],
@@ -274,53 +270,6 @@ function parseFinding(
 	};
 }
 
-function parseHistoryV2(
-	value: unknown,
-	index: number,
-	violations: string[],
-): TaskHistoryEntryV2 {
-	const item = objectAt(value, `record.history[${index}]`, violations);
-	rejectUnknown(
-		item,
-		["id", "at", "type", "from_phase", "to_phase", "reason", "authority"],
-		`record.history[${index}]`,
-		violations,
-	);
-	let authority: AuthorityAuditDescriptor | undefined;
-	if (item.authority !== undefined) {
-		const auth = objectAt(item.authority, `record.history[${index}].authority`, violations);
-		rejectUnknown(
-			auth,
-			["authority_kind", "actor_id", "confirmation_ref", "issued_at", "expires_at"],
-			`record.history[${index}].authority`,
-			violations,
-		);
-		const kind = enumAt(
-			auth.authority_kind,
-			["review", "qa", "user"],
-			`record.history[${index}].authority.authority_kind`,
-			violations,
-		);
-		authority = {
-			authority_kind: kind as AuthorityAuditDescriptor["authority_kind"],
-			actor_id: stringAt(auth.actor_id, `record.history[${index}].authority.actor_id`, violations),
-			confirmation_ref: stringAt(auth.confirmation_ref, `record.history[${index}].authority.confirmation_ref`, violations),
-			issued_at: stringAt(auth.issued_at, `record.history[${index}].authority.issued_at`, violations),
-			expires_at: stringAt(auth.expires_at, `record.history[${index}].authority.expires_at`, violations),
-		};
-	}
-	return {
-		id: stringAt(item.id, `record.history[${index}].id`, violations),
-		at: stringAt(item.at, `record.history[${index}].at`, violations),
-		type: stringAt(item.type, `record.history[${index}].type`, violations),
-		from_phase: enumAt(item.from_phase, TASK_PHASES, `record.history[${index}].from_phase`, violations),
-		to_phase: enumAt(item.to_phase, TASK_PHASES, `record.history[${index}].to_phase`, violations),
-		reason: stringAt(item.reason, `record.history[${index}].reason`, violations),
-		...(authority ? { authority } : {}),
-	};
-}
-
-
 function parseHistoryV3(
 	value: unknown,
 	index: number,
@@ -352,57 +301,9 @@ function parseHistoryV3(
 	};
 }
 
-const SHA256_HEX = /^sha256:[a-f0-9]{64}$/;
+export const SHA256_HEX = /^sha256:[a-f0-9]{64}$/;
 
-function parseEvidenceV2(
-	value: unknown,
-	index: number,
-	acceptanceIds: Set<string> | null,
-	violations: string[],
-): TaskEvidenceV2 {
-	const item = objectAt(value, `record.evidence[${index}]`, violations);
-	rejectUnknown(
-		item,
-		["id", "acceptance_id", "task_revision", "intent_content_hash", "diff_hash", "status", "actor_id", "summary"],
-		`record.evidence[${index}]`,
-		violations,
-	);
-	const acceptanceId = stringAt(
-		item.acceptance_id,
-		`record.evidence[${index}].acceptance_id`,
-		violations,
-	);
-	if (acceptanceIds && !acceptanceIds.has(acceptanceId))
-		violations.push(
-			`evidence ${String(item.id)} references unknown acceptance ${acceptanceId}`,
-		);
-	const intentContentHash = stringAt(
-		item.intent_content_hash,
-		`record.evidence[${index}].intent_content_hash`,
-		violations,
-	);
-	if (!SHA256_HEX.test(intentContentHash))
-		violations.push(`record.evidence[${index}].intent_content_hash must be sha256:<64 hex>`);
-	const diffHash = stringAt(item.diff_hash, `record.evidence[${index}].diff_hash`, violations);
-	if (!SHA256_HEX.test(diffHash))
-		violations.push(`record.evidence[${index}].diff_hash must be sha256:<64 hex>`);
-	return {
-		id: stringAt(item.id, `record.evidence[${index}].id`, violations),
-		acceptance_id: acceptanceId,
-		task_revision: positiveInteger(
-			item.task_revision,
-			`record.evidence[${index}].task_revision`,
-			violations,
-		),
-		intent_content_hash: intentContentHash,
-		diff_hash: diffHash,
-		status: enumAt(item.status, EVIDENCE_STATUSES, `record.evidence[${index}].status`, violations),
-		actor_id: stringAt(item.actor_id, `record.evidence[${index}].actor_id`, violations),
-		summary: stringAt(item.summary, `record.evidence[${index}].summary`, violations),
-	};
-}
-
-function parseApprovalV2(
+export function parseApprovalV2(
 	value: unknown,
 	index: number,
 	violations: string[],
@@ -411,7 +312,7 @@ function parseApprovalV2(
 	const item = objectAt(value, `record.approvals[${index}]`, violations);
 	rejectUnknown(
 		item,
-		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary",
+		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "advisory_findings",
 			...(allowReviewRevision ? ["review_revision"] : [])],
 		`record.approvals[${index}]`,
 		violations,
@@ -447,6 +348,37 @@ function parseApprovalV2(
 		...(allowReviewRevision && item.review_revision !== undefined
 			? { review_revision: parseReviewRevisionIdentity(item.review_revision, `record.approvals[${index}].review_revision`, violations) }
 			: {}),
+		...(item.advisory_findings !== undefined
+			? {
+					advisory_findings: arrayAt(
+						item.advisory_findings,
+						`record.approvals[${index}].advisory_findings`,
+						violations,
+					).map((entry, advisoryIndex) =>
+						parseAdvisoryFinding(
+							entry,
+							`record.approvals[${index}].advisory_findings[${advisoryIndex}]`,
+							violations,
+						),
+					),
+				}
+			: {}),
+	};
+}
+
+/**
+ * An advisory is recorded inside the review attestation, so it needs the same
+ * machine-checkable provenance a blocking finding carries but no lifecycle.
+ */
+function parseAdvisoryFinding(value: unknown, path: string, violations: string[]): ReviewAdvisoryFindingV1 {
+	const item = objectAt(value, path, violations);
+	rejectUnknown(item, ["id", "acceptance_id", "summary", "anchor", "evidence"], path, violations);
+	return {
+		id: stringAt(item.id, `${path}.id`, violations),
+		acceptance_id: nullableString(item.acceptance_id, `${path}.acceptance_id`, violations),
+		summary: stringAt(item.summary, `${path}.summary`, violations),
+		anchor: item.anchor === undefined ? null : nullableAnchor(item.anchor, `${path}.anchor`, violations),
+		evidence: parseFindingEvidence(item.evidence ?? null, `${path}.evidence`, violations),
 	};
 }
 
@@ -485,7 +417,7 @@ function parseAttestationV3(
 	const item = objectAt(value, path, violations);
 	rejectUnknown(
 		item,
-		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "acceptance_results",
+		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "acceptance_results", "advisory_findings",
 			...(allowReviewRevision ? ["review_revision"] : [])],
 		path,
 		violations,
@@ -521,6 +453,13 @@ function parseAttestationV3(
 		violations.push(`${path}.review_revision is only valid on review attestations`);
 	if (allowReviewRevision && kind === "review" && !reviewRevision)
 		violations.push(`${path}.review_revision is required for v4 review attestations`);
+	const advisoryFindings = item.advisory_findings === undefined
+		? undefined
+		: arrayAt(item.advisory_findings, `${path}.advisory_findings`, violations).map((entry, advisoryIndex) =>
+				parseAdvisoryFinding(entry, `${path}.advisory_findings[${advisoryIndex}]`, violations),
+			);
+	if (advisoryFindings !== undefined && kind !== "review")
+		violations.push(`${path}.advisory_findings is only valid on review attestations`);
 	return {
 		id: stringAt(item.id, `${path}.id`, violations),
 		kind,
@@ -532,133 +471,11 @@ function parseAttestationV3(
 		summary: stringAt(item.summary, `${path}.summary`, violations),
 		acceptance_results: acceptanceResults,
 		...(reviewRevision ? { review_revision: reviewRevision } : {}),
+		...(advisoryFindings !== undefined ? { advisory_findings: advisoryFindings } : {}),
 	};
 }
 
-export function parseTaskRecordV2(raw: unknown): TaskRecordV2 {
-	const violations: string[] = [];
-	const value = objectAt(raw, "record", violations);
-	rejectUnknown(
-		value,
-		["contract", "task_id", "intent_revision", "intent_snapshot", "intent_ref", "artifact_ref", "phase", "baseline", "evidence", "findings", "approvals", "history"],
-		"record",
-		violations,
-	);
-	if (value.contract !== TASK_RECORD_CONTRACT_V2)
-		violations.push(`contract must equal ${TASK_RECORD_CONTRACT_V2}`);
-
-	let snapshot: TaskIntentV1 | null = null;
-	try {
-		snapshot = parseTaskIntentV1(value.intent_snapshot);
-	} catch {
-		violations.push("record.intent_snapshot must be a valid TaskIntent v1");
-	}
-
-	const taskId = stringAt(value.task_id, "record.task_id", violations);
-	const intentRevision = positiveInteger(
-		value.intent_revision,
-		"record.intent_revision",
-		violations,
-	);
-
-	const refRaw = objectAt(value.intent_ref, "record.intent_ref", violations);
-	rejectUnknown(refRaw, ["path", "revision", "content_hash"], "record.intent_ref", violations);
-	const refPath = stringAt(refRaw.path, "record.intent_ref.path", violations);
-	const refRevision = positiveInteger(
-		refRaw.revision,
-		"record.intent_ref.revision",
-		violations,
-	);
-	const refContentHash = stringAt(
-		refRaw.content_hash,
-		"record.intent_ref.content_hash",
-		violations,
-	);
-	if (!SHA256_HEX.test(refContentHash))
-		violations.push("record.intent_ref.content_hash must be sha256:<64 hex>");
-
-	let artifactRef: TaskRecordV2["artifact_ref"];
-	if (value.artifact_ref !== undefined) {
-		const artifactRaw = objectAt(value.artifact_ref, "record.artifact_ref", violations);
-		rejectUnknown(artifactRaw, ["state", "spec_path"], "record.artifact_ref", violations);
-		const state = enumAt(artifactRaw.state, ["active", "frozen"], "record.artifact_ref.state", violations) as "active" | "frozen";
-		const specPath = artifactRaw.spec_path === undefined
-			? undefined
-			: stringAt(artifactRaw.spec_path, "record.artifact_ref.spec_path", violations);
-		if (specPath !== undefined && (!/^docs\/specs\/(?!archive\/)[A-Za-z0-9._/-]+\.spec\.md$/.test(specPath) || specPath.includes("..")))
-			violations.push("record.artifact_ref.spec_path must be one canonical active Spec path");
-		artifactRef = { state, ...(specPath === undefined ? {} : { spec_path: specPath }) };
-	}
-
-	const activeIntentPath = `docs/plans/${taskId}.intent.json`;
-	const frozenIntentPath = `docs/plans/archive/${taskId}.intent.json`;
-	if (
-		snapshot &&
-		(snapshot.task_id !== taskId ||
-			snapshot.revision !== intentRevision ||
-			snapshot.revision !== refRevision ||
-			(refPath !== activeIntentPath && refPath !== frozenIntentPath))
-	)
-		violations.push("intent_snapshot and intent_ref must match record identity");
-	if (artifactRef?.state === "active" && refPath !== activeIntentPath)
-		violations.push("active artifact_ref requires the active intent path");
-	if (artifactRef?.state === "frozen" && refPath !== frozenIntentPath)
-		violations.push("frozen artifact_ref requires the archived intent path");
-	if (
-		snapshot &&
-		refContentHash !== "" &&
-		canonicalIntentHash(snapshot) !== refContentHash
-	)
-		violations.push("intent_ref.content_hash must equal the snapshot canonical hash");
-
-	const baseline = stringAt(value.baseline, "record.baseline", violations);
-	if (!SHA256_HEX.test(baseline))
-		violations.push("record.baseline must be sha256:<64 hex>");
-
-	const acceptanceIds = new Set(
-		snapshot ? snapshot.acceptance.map((item) => item.id) : [],
-	);
-	const evidence = arrayAt(value.evidence, "record.evidence", violations).map(
-		(item, index) => parseEvidenceV2(item, index, acceptanceIds, violations),
-	);
-	const findings = arrayAt(value.findings, "record.findings", violations).map(
-		(item, index) => parseFinding(item, index, violations),
-	);
-	const approvals = arrayAt(value.approvals, "record.approvals", violations).map(
-		(item, index) => parseApprovalV2(item, index, violations),
-	);
-	const history = arrayAt(value.history, "record.history", violations).map(
-		(item, index) => parseHistoryV2(item, index, violations),
-	);
-	uniqueIds(evidence, "record.evidence", violations);
-	uniqueIds(findings, "record.findings", violations);
-	uniqueIds(approvals, "record.approvals", violations);
-	uniqueIds(history, "record.history", violations);
-
-	const phase = enumAt(value.phase, TASK_PHASES, "phase", violations);
-
-	if (violations.length > 0) throw new KernelValidationError(violations);
-	return {
-		contract: TASK_RECORD_CONTRACT_V2,
-		task_id: taskId,
-		intent_revision: intentRevision,
-		intent_snapshot: snapshot as TaskIntentV1,
-		intent_ref: {
-			path: refPath,
-			revision: refRevision,
-			content_hash: refContentHash,
-		},
-		...(artifactRef ? { artifact_ref: artifactRef } : {}),
-		phase,
-		baseline,
-		evidence,
-		findings,
-		approvals,
-		history,
-	};
-}
-
-function parseTaskRecordAtVersion(raw: unknown, version: 3 | 4): TaskRecordV3 | TaskRecordV4 {
+export function parseTaskRecordAtVersion(raw: unknown, version: 3 | 4): TaskRecordV3 | TaskRecordV4 {
 	const violations: string[] = [];
 	const value = objectAt(raw, "record", violations);
 	rejectUnknown(
@@ -693,8 +510,8 @@ function parseTaskRecordAtVersion(raw: unknown, version: 3 | 4): TaskRecordV3 |
 		violations.push("intent_snapshot and intent_ref must match record identity");
 	if (artifactState === "active" && refPath !== activeIntentPath)
 		violations.push("active artifact_state requires the active intent path");
-	if (artifactState === "frozen" && refPath !== frozenIntentPath)
-		violations.push("frozen artifact_state requires the archived intent path");
+	if (artifactState === "frozen" && refPath !== activeIntentPath && refPath !== frozenIntentPath)
+		violations.push("frozen artifact_state requires the active or archived intent path");
 	if (snapshot && refContentHash !== "" && canonicalIntentHash(snapshot) !== refContentHash)
 		violations.push("intent_ref.content_hash must equal the snapshot canonical hash");
 	if (lifecycle !== "active" && artifactState !== "frozen")
@@ -790,21 +607,17 @@ function parseTaskRecordAtVersion(raw: unknown, version: 3 | 4): TaskRecordV3 |
 	return record as TaskRecordV3 | TaskRecordV4;
 }
 
-/** Strict v3 drain parser: unknown fields and revision identity stay illegal. */
-export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
-	return parseTaskRecordAtVersion(raw, 3) as TaskRecordV3;
-}
-
 /** Strict v4 parser: the Enrollment base commit is mandatory. */
 export function parseTaskRecordV4(raw: unknown): TaskRecordV4 {
 	return parseTaskRecordAtVersion(raw, 4) as TaskRecordV4;
 }
 
-/** Version-dispatched parser used by every durable Kernel owner. */
+/** Live TaskRecord parser. The v3 drain window is closed: a non-v4 contract is rejected, not fallen back on. */
 export function parseTaskRecord(raw: unknown): TaskRecord {
 	const contract = (raw as { contract?: unknown } | null)?.contract;
-	if (contract === TASK_RECORD_CONTRACT_V4) return parseTaskRecordV4(raw);
-	return parseTaskRecordV3(raw);
+	if (contract !== TASK_RECORD_CONTRACT_V4)
+		throw new KernelValidationError([`contract must equal ${TASK_RECORD_CONTRACT_V4}`]);
+	return parseTaskRecordV4(raw);
 }
 
 export function assertKernelInvariantsV3(intentRaw: TaskIntentV1, recordRaw: TaskRecord): void {
@@ -823,33 +636,6 @@ export function assertKernelInvariantsV3(intentRaw: TaskIntentV1, recordRaw: Tas
 	if (violations.length > 0) throw new KernelInvariantError(violations);
 }
 
-export function assertKernelInvariantsV2(
-	intentRaw: TaskIntentV1,
-	recordRaw: TaskRecordV2,
-): void {
-	const intent = parseTaskIntentV1(intentRaw);
-	const record = parseTaskRecordV2(recordRaw);
-	const violations: string[] = [];
-	if (intent.task_id !== record.task_id)
-		violations.push("intent and record task_id must match");
-	if (intent.revision !== record.intent_revision)
-		violations.push("intent revision and record intent_revision must match");
-	if (canonicalIntentHash(record.intent_snapshot) !== record.intent_ref.content_hash)
-		violations.push("record intent_ref.content_hash must match its snapshot");
-	const requiredRole: Record<ApprovalKind, ApprovalAuthorityRole> = {
-		review: "reviewer",
-		qa: "qa",
-		user: "user",
-	};
-	for (const approval of record.approvals) {
-		if (approval.authority_role !== requiredRole[approval.kind])
-			violations.push(
-				`approval ${approval.id} kind ${approval.kind} requires authority_role ${requiredRole[approval.kind]}`,
-			);
-	}
-	if (violations.length > 0) throw new KernelInvariantError(violations);
-}
-
 // ---------------------------------------------------------------------------
 // R2C2 TaskAction strict parser and update invariants.
 // ---------------------------------------------------------------------------

package/plugins/immune-brain/runtime/managed_task_routing_policy.ts

@@ -34,7 +34,6 @@ import { type Stats,
 	openSync,
 	readFileSync,
 	realpathSync,
-	statSync,
 } from "node:fs";
 import { join, resolve, sep } from "node:path";