immune-brain 3.6.5 → 3.6.7

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

@@ -49,6 +49,7 @@ export type CanaryOperation =
 	| { op: "freeze_artifacts"; actor_id: string }
 	| { op: "record_finding"; finding: Omit<TaskFinding, "status" | "source" | "review_round">; actor_id: string }
 	| { op: "resolve_finding"; finding_id: string; actor_id: string }
+	| { op: "refute_finding"; finding_id: string; attestation_id: string; actor_id: string }
 	| { op: "request_rework"; capability: object; findings: TaskFinding[]; actor_id: string }
 	| { op: "record_approval"; capability: object; approval: TaskApprovalV2; actor_id: string }
 	| { op: "revise_intent"; next_intent: TaskIntentV1; actor_id: string }
@@ -367,6 +368,14 @@ export function createCanaryApplication(
 			case "resolve_finding":
 				action = { ...base, type: "resolve_finding", finding_id: operation.finding_id };
 				break;
+			case "refute_finding":
+				action = {
+					...base,
+					type: "refute_finding",
+					finding_id: operation.finding_id,
+					attestation_id: operation.attestation_id,
+				};
+				break;
 			case "request_rework":
 				capability = operation.capability;
 				action = { ...base, type: "request_rework", findings: operation.findings };
@@ -381,7 +390,13 @@ export function createCanaryApplication(
 					type: "revise_intent",
 					next_intent: operation.next_intent,
 					next_intent_ref: {
-						path: `docs/plans/${operation.next_intent.task_id}.intent.json`,
+						// revise_intent never unfreezes artifacts, so a revision
+						// while frozen must keep the archived sidecar path that
+						// record validation enforces (active path otherwise).
+						path:
+							snapshot.record.artifact_state === "frozen"
+								? `docs/plans/archive/${operation.next_intent.task_id}.intent.json`
+								: `docs/plans/${operation.next_intent.task_id}.intent.json`,
 						content_hash: canonicalIntentHash(operation.next_intent),
 					},
 				};

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

@@ -8,6 +8,7 @@ import type {
 	TaskRecord,
 } from "./types";
 import { assertKernelInvariantsV3, KernelInvariantError } from "./validation";
+import { refutationIsLive } from "./refutation";
 
 const REQUIRED_ATTESTATIONS: Record<TaskIntentV1["risk"], ApprovalKind[]> = {
 	routine: ["qa"],
@@ -137,8 +138,25 @@ export function completionDecision(
 		.filter((item) => repeatedActors.has(item.actor_id))
 		.map((item) => item.id);
 
+	// A refutation is live only while its bound QA attestation is still fresh
+	// for this diff and intent hash. When it goes stale the refuted finding
+	// counts as blocking again; nothing stored is rewritten by that
+	// invalidation, so the append-only invariant survives. The identity is the
+	// one `freshAttestations` filters on, including the caller's current intent
+	// hash, so a drifted intent revives the gate with the attestation.
+	const refutationState = {
+		intent_revision: intent.revision,
+		intent_content_hash: currentIntentContentHash,
+		diff_hash: currentDiffHash,
+	};
 	const blockingFindingIds = record.findings
-		.filter((item) => item.status === "open" && item.kind === "blocking")
+		.filter(
+			(item) =>
+				item.kind === "blocking" &&
+				(item.status === "open" ||
+					(item.status === "refuted" &&
+						!refutationIsLive(item, record.attestations, refutationState))),
+		)
 		.map((item) => item.id);
 	const unresolvedUserDecisionIds = record.findings
 		.filter((item) => item.status === "open" && item.kind === "unresolved_user_decision")

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

@@ -4,6 +4,7 @@
 
 import { createHash } from "node:crypto";
 import { completionDecision } from "./completion";
+import { anchorForEvidence, isFreshPassingQaAttestation, refutationIdentity, refutationIsLive } from "./refutation";
 import {
 	REDUCED_MUTATION_BRAND,
 	TASK_RECORD_CONTRACT_V4,
@@ -167,8 +168,10 @@ function sha256Hex(value: string): string {
 }
 
 function intentRefMatches(intent: TaskIntentV1, ref: TaskIntentRefV3): boolean {
+	const activePath = `docs/plans/${intent.task_id}.intent.json`;
+	const archivedPath = `docs/plans/archive/${intent.task_id}.intent.json`;
 	return (
-		ref.path === `docs/plans/${intent.task_id}.intent.json` &&
+		(ref.path === activePath || ref.path === archivedPath) &&
 		ref.content_hash === canonicalIntentHash(intent)
 	);
 }
@@ -191,15 +194,35 @@ function hasPrivilegedKind(action: TaskAction): boolean {
  * set and applied to another.
  */
 export function findingsDigestV2(findings: TaskFinding[]): string {
+	// Anchor and evidence are included only when the finding actually carries
+	// them, so a pre-extension findings set keeps its historical bytes while a
+	// capability minted over one anchor set cannot be spent on another.
 	const normalized = findings.map((finding) => ({
 		id: finding.id,
 		kind: finding.kind,
 		acceptance_id: finding.acceptance_id,
 		summary: finding.summary,
+		...(finding.anchor !== undefined ? { anchor: finding.anchor ?? null } : {}),
+		...(finding.evidence !== undefined ? { evidence: finding.evidence ?? null } : {}),
 	}));
 	return `sha256:${createHash("sha256").update(stableJson(normalized)).digest("hex")}`;
 }
 
+/**
+ * Two findings share an acceptance boundary when they name the same
+ * acceptance, or when neither does and their review evidence names the same
+ * violated reference. Null boundaries without comparable evidence are not
+ * shared, so a second-round finding can no longer park the task by accident.
+ */
+function sharesAcceptanceBoundary(left: TaskFinding, right: TaskFinding): boolean {
+	if (left.acceptance_id !== null && right.acceptance_id !== null)
+		return left.acceptance_id === right.acceptance_id;
+	if (left.acceptance_id !== null || right.acceptance_id !== null) return false;
+	const leftRef = left.evidence?.violated.ref ?? null;
+	const rightRef = right.evidence?.violated.ref ?? null;
+	return leftRef !== null && leftRef === rightRef;
+}
+
 export function reduceTask(
 	recordRaw: TaskRecord,
 	actionRaw: TaskAction,
@@ -309,10 +332,81 @@ export function reduceTask(
 				throw new KernelInvariantError([
 					`finding ${action.finding_id} is already resolved`,
 				]);
+			// A live refutation already suppresses the finding, so resolving it
+			// would make that suppression permanent. Only a refutation whose bound
+			// evidence went stale may still be resolved.
+			if (
+				finding.status === "refuted" &&
+				refutationIsLive(
+					finding,
+					record.attestations,
+					refutationIdentity(record, action.diff_hash),
+				)
+			)
+				throw new KernelInvariantError([
+					`finding ${action.finding_id} is still refuted by live counterevidence`,
+				]);
 			finding.status = "resolved";
 			appendHistory(record, action, from, action.finding_id, authorityAudit);
 			break;
 		}
+		case "refute_finding": {
+			if (record.lifecycle !== "active")
+				throw new KernelInvariantError([
+					`cannot refute findings while lifecycle is ${record.lifecycle}`,
+				]);
+			const finding = record.findings.find(
+				(item) => item.id === action.finding_id,
+			);
+			if (!finding)
+				throw new KernelInvariantError([
+					`finding ${action.finding_id} does not exist`,
+				]);
+			if (finding.kind === "unresolved_user_decision" || finding.kind === "replan_required")
+				throw new KernelInvariantError([
+					"refute_finding cannot refute a user decision or replan boundary",
+				]);
+			if (finding.status === "resolved")
+				throw new KernelInvariantError([
+					`finding ${action.finding_id} is already resolved`,
+				]);
+			if (!finding.acceptance_id)
+				throw new KernelInvariantError([
+					"refute_finding requires a finding bound to an acceptance id",
+				]);
+			if (
+				finding.status === "refuted" &&
+				refutationIsLive(
+					finding,
+					record.attestations,
+					refutationIdentity(record, action.diff_hash),
+				)
+			)
+				throw new KernelInvariantError([
+					`finding ${action.finding_id} is already refuted by live counterevidence`,
+				]);
+			// The actor cannot assert a refutation; it can only bind a QA
+			// attestation the Kernel already validated as fresh and passing for
+			// this acceptance. A stale binding is rebindable with new evidence,
+			// which is how a refutation is renewed after a diff or intent change.
+			if (
+				!isFreshPassingQaAttestation(
+					record.attestations.find((item) => item.id === action.attestation_id),
+					finding.acceptance_id,
+					refutationIdentity(record, action.diff_hash),
+				)
+			)
+				throw new KernelInvariantError([
+					`refute_finding requires a fresh passing QA attestation covering ${finding.acceptance_id ?? "null"}`,
+				]);
+			finding.status = "refuted";
+			finding.counterevidence = {
+				attestation_id: action.attestation_id,
+				acceptance_id: finding.acceptance_id,
+			};
+			appendHistory(record, action, from, action.finding_id, authorityAudit);
+			break;
+		}
 		case "record_approval": {
 			if (record.lifecycle !== "active" || record.artifact_state !== "frozen")
 				throw new KernelInvariantError([
@@ -450,32 +544,94 @@ export function reduceTask(
 					"request_rework requires review, qa, or user authority",
 				]);
 			const round = reviewRound(record);
-			const hasPriorBlockingReviewRework = record.findings.some(
+			// An anchor is authority: it decides whether this claim inherits an
+			// existing refutation. The Kernel recomputes it from the finding's own
+			// evidence, so a caller cannot bind one claim's identity to another
+			// claim's provenance.
+			for (const finding of action.findings) {
+				const anchor = finding.anchor ?? null;
+				const evidence = finding.evidence ?? null;
+				if ((anchor === null) !== (evidence === null))
+					throw new KernelInvariantError([
+						`finding ${finding.id} must carry anchor and evidence together`,
+					]);
+				if (evidence && anchor !== anchorForEvidence(evidence))
+					throw new KernelInvariantError([
+						`finding ${finding.id} anchor must equal the digest of its evidence`,
+					]);
+				// Only a Review rework carries reviewer provenance; a QA or user
+				// rework that does would be a caller asserting review identity.
+				if (anchor !== null && authorityAudit.authority_kind !== "review")
+					throw new KernelInvariantError([
+						`${authorityAudit.authority_kind} rework cannot carry review provenance`,
+					]);
+			}
+			const identity = refutationIdentity(record, action.diff_hash);
+			// A prior finding that is still refuted by live evidence is not an
+			// outstanding dispute, so a new claim on its boundary is not a repeat
+			// offence. Once its evidence goes stale it blocks again and counts.
+			const priorBlockingReviewFindings = record.findings.filter(
 				(finding) =>
 					finding.source === "review" &&
 					finding.kind === "blocking" &&
-					finding.review_round !== null,
+					finding.review_round !== null &&
+					!(
+						finding.status === "refuted" &&
+						refutationIsLive(finding, record.attestations, identity)
+					),
 			);
+			// Anchor reconciliation: a new Review finding whose anchor matches a
+			// Review finding that is still live-refuted is admitted as refuted with
+			// the inherited counterevidence binding, for blocking and advisory
+			// claims alike. The claim's identity is the anchor, so the inherited
+			// binding keeps the acceptance its QA evidence was actually proved on.
+			// A refutation whose evidence went stale no longer suppresses anything,
+			// so the same claim is admitted as open and blocks again.
+			const admissions = action.findings.map((finding) => {
+				const inherited =
+					finding.anchor != null
+						? record.findings.find(
+								(prior) =>
+									prior.source === "review" &&
+									prior.status === "refuted" &&
+									prior.anchor === finding.anchor &&
+									refutationIsLive(prior, record.attestations, identity),
+							)
+						: undefined;
+				return { finding, inherited };
+			});
+			const disputed = admissions.find(
+				({ finding, inherited }) =>
+					finding.kind === "blocking" &&
+					inherited === undefined &&
+					priorBlockingReviewFindings.some((prior) =>
+						sharesAcceptanceBoundary(finding, prior),
+					),
+			)?.finding;
 			const parkForReplan =
-				authorityAudit.authority_kind === "review" &&
-				hasPriorBlockingReviewRework &&
-				action.findings.some((finding) => finding.kind === "blocking");
+				authorityAudit.authority_kind === "review" && disputed !== undefined;
 			if (!parkForReplan) {
 				record.artifact_state = "active";
 				record.intent_ref.path = `docs/plans/${record.task_id}.intent.json`;
 			}
 			const findingIds = new Set(record.findings.map((item) => item.id));
-			for (const finding of action.findings) {
+			for (const { finding, inherited } of admissions) {
 				if (findingIds.has(finding.id))
 					throw new KernelInvariantError([
 						`findings contains duplicate id ${finding.id}`,
 					]);
 				findingIds.add(finding.id);
 				record.findings.push({
-					...finding,
-					status: "open",
+					id: finding.id,
+					kind: finding.kind,
+					status: inherited ? "refuted" : "open",
+					acceptance_id: finding.acceptance_id,
 					source: authorityAudit.authority_kind === "review" ? "review" : "execution",
 					review_round: authorityAudit.authority_kind === "review" ? round : null,
+					summary: finding.summary,
+					...(finding.anchor !== undefined ? { anchor: finding.anchor } : {}),
+					...(finding.evidence !== undefined ? { evidence: finding.evidence } : {}),
+					counterevidence: inherited ? { ...inherited.counterevidence! } : null,
 				});
 			}
 			if (
@@ -484,9 +640,6 @@ export function reduceTask(
 					(item) => item.status === "open" && item.kind === "replan_required",
 				)
 			) {
-				const disputed =
-					action.findings.find((item: TaskFinding) => item.kind === "blocking") ??
-					action.findings[0];
 				const boundary = {
 					id: `${action.event_id}:replan-required`,
 					kind: "replan_required" as const,

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

@@ -0,0 +1,82 @@
+// Derived refutation liveness. One predicate shared by the reducer, the
+// completion projection and the TaskRecord update invariants, so the rule that
+// decides whether a refuted finding still blocks cannot drift between them.
+
+import { createHash } from "node:crypto";
+import { stableStringify } from "../canonical_json";
+import type { FindingEvidence, TaskAttestationV3, TaskFinding } from "./types";
+
+export interface RefutationIdentity {
+	intent_revision: number;
+	intent_content_hash: string;
+	diff_hash: string;
+}
+
+export function refutationIdentity(
+	record: {
+		intent_snapshot: { revision: number };
+		intent_ref: { content_hash: string };
+	},
+	diffHash: string,
+): RefutationIdentity {
+	return {
+		intent_revision: record.intent_snapshot.revision,
+		intent_content_hash: record.intent_ref.content_hash,
+		diff_hash: diffHash,
+	};
+}
+
+/**
+ * Kernel-side derivation of a review claim's anchor. The Host parses the
+ * reviewer's prose into evidence, but the digest that decides refutation
+ * inheritance is recomputed from that evidence, so a caller can never bind one
+ * claim's identity to another claim's bytes.
+ */
+export function anchorForEvidence(evidence: FindingEvidence): string {
+	return `sha256:${createHash("sha256")
+		.update(
+			stableStringify({
+				violated: evidence.violated,
+				caller_chain: evidence.caller_chain,
+			}),
+		)
+		.digest("hex")}`;
+}
+
+/**
+ * Freshness of one QA attestation for one acceptance: the single rule shared
+ * by the refutation predicate and the `refute_finding` transition guard.
+ */
+export function isFreshPassingQaAttestation(
+	attestation: TaskAttestationV3 | undefined,
+	acceptanceId: string,
+	identity: RefutationIdentity,
+): boolean {
+	if (!attestation || attestation.kind !== "qa") return false;
+	if (attestation.task_revision !== identity.intent_revision) return false;
+	if (attestation.intent_content_hash !== identity.intent_content_hash) return false;
+	if (attestation.diff_hash !== identity.diff_hash) return false;
+	return attestation.acceptance_results.some(
+		(result) => result.acceptance_id === acceptanceId && result.status === "passed",
+	);
+}
+
+/**
+ * A refutation is live only while the QA attestation it bound is still fresh
+ * for the record's current intent revision, intent hash and diff identity, and
+ * still passes the acceptance it was bound to. Liveness is derived here and
+ * never stored, so an invalidated refutation counts as blocking again.
+ */
+export function refutationIsLive(
+	finding: TaskFinding,
+	attestations: readonly TaskAttestationV3[],
+	identity: RefutationIdentity,
+): boolean {
+	const counterevidence = finding.counterevidence ?? null;
+	if (!counterevidence?.attestation_id || !counterevidence.acceptance_id) return false;
+	return isFreshPassingQaAttestation(
+		attestations.find((item) => item.id === counterevidence.attestation_id),
+		counterevidence.acceptance_id,
+		identity,
+	);
+}

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

@@ -16,9 +16,24 @@ export type FindingKind =
 	| "advisory"
 	| "unresolved_user_decision"
 	| "replan_required";
-export type FindingStatus = "open" | "resolved";
+export type FindingStatus = "open" | "resolved" | "refuted";
 export type FindingSource = "execution" | "review" | "kernel" | "migration";
 
+/** Machine-checkable provenance a Review finding must carry at the verdict boundary. */
+export interface FindingEvidence {
+	trigger: string;
+	caller_chain: string[];
+	violated: {
+		kind: "acceptance" | "security_boundary";
+		ref: string;
+	};
+}
+
+export interface FindingCounterevidence {
+	attestation_id: string;
+	acceptance_id: string;
+}
+
 export interface TaskFinding {
 	id: string;
 	kind: FindingKind;
@@ -27,6 +42,19 @@ export interface TaskFinding {
 	source: FindingSource;
 	review_round: number | null;
 	summary: string;
+	/**
+	 * Additive v4 fields. Absent on records written before this contract
+	 * extension, so the TaskRecord contract is not bumped; `parseFinding`
+	 * normalizes them to null.
+	 *
+	 * `anchor` identifies the claim (sha256 over violated + caller_chain),
+	 * `evidence` is the reviewer-supplied provenance that produced it, and
+	 * `counterevidence` binds a refutation to the Kernel-validated QA
+	 * attestation that contradicted the claim.
+	 */
+	anchor?: string | null;
+	evidence?: FindingEvidence | null;
+	counterevidence?: FindingCounterevidence | null;
 }
 
 export type ApprovalKind = "review" | "qa" | "user";
@@ -283,6 +311,11 @@ export interface TaskActionBase {
 export type TaskAction =
 	| (TaskActionBase & { type: "record_finding"; finding: TaskFinding })
 	| (TaskActionBase & { type: "resolve_finding"; finding_id: string })
+	| (TaskActionBase & {
+			type: "refute_finding";
+			finding_id: string;
+			attestation_id: string;
+	  })
 	| (TaskActionBase & { type: "record_approval"; approval: TaskApprovalV2 })
 	| (TaskActionBase & {
 			type: "revise_intent";