immune-brain 3.6.8 → 4.0.0

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

@@ -0,0 +1,323 @@
+/**
+ * Frozen historical TaskRecord reader. TaskRecord v2 and v3 are no longer
+ * live contracts: nothing in the reducer/validation/coordinator dispatch
+ * accepts them. This module exists solely so `readAuditTaskPair` can keep
+ * reading `.imm/audit/` evidence written before the v3 drain window closed.
+ * Nothing here changes; it is relocated, not reimplemented.
+ */
+import {
+	TASK_PHASES,
+	TASK_RECORD_CONTRACT_V2,
+	type ApprovalAuthorityRole,
+	type ApprovalKind,
+	type AuthorityAuditDescriptor,
+	type EvidenceStatus,
+	type TaskFinding,
+	type TaskIntentRefV1,
+	type TaskIntentV1,
+	type TaskApprovalV2,
+	type TaskPhase,
+	type TaskRecordV3,
+} from "./types";
+import { canonicalIntentHash, parseTaskIntentV1 } from "./intent";
+import {
+	EVIDENCE_STATUSES,
+	KernelInvariantError,
+	KernelValidationError,
+	SHA256_HEX,
+	arrayAt,
+	enumAt,
+	objectAt,
+	parseApprovalV2,
+	parseFinding,
+	parseTaskRecordAtVersion,
+	positiveInteger,
+	rejectUnknown,
+	stringAt,
+	uniqueIds,
+} from "./validation";
+
+export interface TaskEvidenceV2 {
+	id: string;
+	acceptance_id: string;
+	task_revision: number;
+	intent_content_hash: string;
+	diff_hash: string;
+	status: EvidenceStatus;
+	actor_id: string;
+	summary: string;
+}
+
+export interface TaskHistoryEntryV2 {
+	id: string;
+	at: string;
+	type: string;
+	from_phase: TaskPhase;
+	to_phase: TaskPhase;
+	reason: string;
+	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[];
+}
+
+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 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),
+	};
+}
+
+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 !== activeIntentPath && refPath !== frozenIntentPath)
+		violations.push("frozen artifact_ref 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");
+
+	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,
+	};
+}
+
+/** Strict v3 drain parser: unknown fields and revision identity stay illegal. */
+export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
+	return parseTaskRecordAtVersion(raw, 3) as TaskRecordV3;
+}
+
+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);
+}

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

@@ -12,8 +12,9 @@ import {
 	readTaskRecordRaw,
 	readWorkspaceStateRaw,
 } from "./storage";
+import { stateDatabasePath } from "./storage_paths";
 
-const SOURCE_PATH = ".imm/state/workspace.json";
+const SOURCE_PATH = stateDatabasePath();
 const GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 
 /**
@@ -64,6 +65,13 @@ export interface PiCanaryPreparation {
 	git_error: string | null;
 	workspace: {
 		current_working: string | null;
+		/**
+		 * The workspace CAS token at preparation time. A workspace can return to
+		 * the same owner value at a different revision (another task enrolled and
+		 * settled in between), so the owner alone cannot prove the confirmed
+		 * state is still current.
+		 */
+		revision: string;
 	};
 	digest: string;
 }
@@ -152,6 +160,7 @@ export function preparePiCanary(root: string, input: PiCanaryPrepareInput): PiCa
 	const state = readWorkspaceStateRaw(canonicalRoot);
 	const workspace: PiCanaryPreparation["workspace"] = {
 		current_working: state.state.current_working,
+		revision: state.revision,
 	};
 	if (claim && state.state.current_working !== claim.task_id)
 		throw new Error(

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

@@ -1,4 +1,4 @@
-// Pure TaskRecord v3 reducer with a closed factual action vocabulary.
+// Pure TaskRecord v4 reducer with a closed factual action vocabulary.
 // Never reads files, Git, workspace, or host context. Returns a branded
 // ReducedTaskMutation; the caller cannot construct or serialize it.
 
@@ -7,7 +7,6 @@ import { completionDecision } from "./completion";
 import { anchorForEvidence, isFreshPassingQaAttestation, refutationIdentity, refutationIsLive } from "./refutation";
 import {
 	REDUCED_MUTATION_BRAND,
-	TASK_RECORD_CONTRACT_V4,
 	type AuthorityAuditDescriptor,
 	type ReducedTaskMutation,
 	type TaskAction,
@@ -163,10 +162,6 @@ function appendHistory(
 	record.history.push(entry as (typeof record.history)[number]);
 }
 
-function sha256Hex(value: string): string {
-	return createHash("sha256").update(value).digest("hex");
-}
-
 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`;
@@ -209,19 +204,11 @@ export function findingsDigestV2(findings: TaskFinding[]): string {
 }
 
 /**
- * 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.
+ * Rework rounds one Review run may demand before the Kernel pauses the task for
+ * a human decision. Ordinary defects return to execution without a user gate,
+ * but an unbounded repair/review cycle is not progress either.
  */
-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 const REVIEW_REWORK_ROUND_BUDGET = 5;
 
 export function reduceTask(
 	recordRaw: TaskRecord,
@@ -444,10 +431,7 @@ export function reduceTask(
 			const reviewRevision = approval.review_revision;
 			if (reviewRevision && approval.kind !== "review")
 				throw new KernelInvariantError(["review_revision is only valid on review approvals"]);
-			if (record.contract !== TASK_RECORD_CONTRACT_V4) {
-				if (reviewRevision)
-					throw new KernelInvariantError(["review_revision requires a TaskRecord v4"]);
-			} else if (approval.kind === "review") {
+			if (approval.kind === "review") {
 				if (!reviewRevision)
 					throw new KernelInvariantError(["v4 review approval requires review_revision"]);
 				if (reviewRevision.base_head !== record.git_base_head)
@@ -567,9 +551,11 @@ export function reduceTask(
 					]);
 			}
 			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.
+			// A prior blocking Review claim is only a repeat offence when it names the
+			// same security boundary. Ordinary defects on an already-covered
+			// acceptance return to execution: changing the plan is a human decision,
+			// fixing a bug is not. A claim still refuted by live evidence is not an
+			// outstanding dispute at all.
 			const priorBlockingReviewFindings = record.findings.filter(
 				(finding) =>
 					finding.source === "review" &&
@@ -604,12 +590,26 @@ export function reduceTask(
 				({ finding, inherited }) =>
 					finding.kind === "blocking" &&
 					inherited === undefined &&
-					priorBlockingReviewFindings.some((prior) =>
-						sharesAcceptanceBoundary(finding, prior),
+					finding.evidence?.violated.kind === "security_boundary" &&
+					priorBlockingReviewFindings.some(
+						(prior) =>
+							prior.evidence?.violated.kind === "security_boundary" &&
+							prior.evidence?.violated.ref === finding.evidence?.violated.ref,
 					),
 			)?.finding;
+			// Only rounds that actually raised an unrefuted blocking claim count
+			// against the budget: a claim live QA evidence already answers is not
+			// progress lost, so repeating it can never park the task.
+			const effectiveBlockingRounds = new Set(
+				priorBlockingReviewFindings.map((finding) => finding.review_round),
+			).size;
+			const hasEffectiveBlockingNow = admissions.some(
+				({ finding, inherited }) => finding.kind === "blocking" && inherited === undefined,
+			);
 			const parkForReplan =
-				authorityAudit.authority_kind === "review" && disputed !== undefined;
+				authorityAudit.authority_kind === "review" &&
+				(disputed !== undefined ||
+					(hasEffectiveBlockingNow && effectiveBlockingRounds >= REVIEW_REWORK_ROUND_BUDGET));
 			if (!parkForReplan) {
 				record.artifact_state = "active";
 				record.intent_ref.path = `docs/plans/${record.task_id}.intent.json`;
@@ -644,11 +644,13 @@ export function reduceTask(
 					id: `${action.event_id}:replan-required`,
 					kind: "replan_required" as const,
 					status: "open" as const,
-					acceptance_id: disputed.acceptance_id,
+					acceptance_id: disputed?.acceptance_id ?? null,
 					source: "kernel" as const,
 					review_round: round,
 					summary:
-						"Review returned this acceptance boundary twice; a durable replan is required.",
+						disputed !== undefined
+							? "Review returned the same security boundary twice; a durable replan is required."
+							: `Review exhausted its ${REVIEW_REWORK_ROUND_BUDGET}-round rework budget; a durable replan is required.`,
 				};
 				if (findingIds.has(boundary.id))
 					throw new KernelInvariantError([
@@ -708,7 +710,6 @@ export function reduceTask(
 				throw new KernelInvariantError(["stop requires a reason"]);
 			transitionLifecycle(record, "stopped");
 			record.artifact_state = "frozen";
-			record.intent_ref.path = `docs/plans/archive/${record.task_id}.intent.json`;
 			appendHistory(record, action, from, action.reason, authorityAudit);
 			break;
 		}

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

@@ -0,0 +1,121 @@
+/**
+ * Exact execution identity.
+ *
+ * A worktree owns one storage identity (`workspace_id`) and every enrolled
+ * execution owns one `run_id`. Authority mutations bind the exact run instead
+ * of resolving "the latest task occurrence", and every replayable operation
+ * derives its identity from committed facts so a replayed call returns the
+ * recorded result instead of writing again.
+ *
+ * `task_id` names the logical task: different worktrees may each run the same
+ * logical task with distinct run identities, and a terminal task cannot be
+ * re-enrolled in the same worktree.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+
+import { KernelStoreSecurityError, workspaceIdentity } from "./sqlite_store";
+
+export interface RunIdentity {
+	workspace_id: string;
+	task_id: string;
+	run_id: string;
+}
+
+export interface RunRowIdentity {
+	task_id: string;
+	run_id: string;
+}
+
+export function mintRunId(): string {
+	return `run-${randomUUID()}`;
+}
+
+export function runIdentity(db: DatabaseSync, row: RunRowIdentity): RunIdentity {
+	return { workspace_id: workspaceIdentity(db), task_id: row.task_id, run_id: row.run_id };
+}
+
+/** Bind a mutation to one exact run; a mismatch fails before any write. */
+export function assertRunBinding(
+	identity: RunIdentity,
+	expected: RunRowIdentity,
+	operation: string,
+): void {
+	if (identity.run_id !== expected.run_id || identity.task_id !== expected.task_id)
+		throw new KernelStoreSecurityError(
+			`${operation} is bound to run ${expected.run_id} (task ${expected.task_id}) but the store holds run ${identity.run_id} (task ${identity.task_id})`,
+		);
+}
+
+/**
+ * Deterministic replay identity for the authority operations that can lose a
+ * response. The event identifier is part of the committed authority bytes, so
+ * an identical request maps to an identical operation id and a replayed call
+ * returns the recorded result instead of writing again.
+ */
+export function enrollmentOperationId(taskId: string, eventId: string): string {
+	return `enroll:${taskId}:${eventId}`;
+}
+
+/**
+ * Digest of an enrollment request's own content. The capability object is
+ * opaque and excluded, so a lost-response retry of the *same* confirmation
+ * matches, while a different path, digest, actor, nonce or event time is a
+ * different request and must not be answered from the committed operation.
+ */
+export function enrollmentRequestDigest(request: {
+	task_id: string;
+	intent_path: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	preparation_digest: string;
+	enrollment_event_id: string;
+	actor_id: string;
+	confirmation_ref: string;
+	nonce: string;
+}): string {
+	const canonical = JSON.stringify({
+		task_id: request.task_id,
+		intent_path: request.intent_path,
+		intent_revision: request.intent_revision,
+		intent_content_hash: request.intent_content_hash,
+		preparation_digest: request.preparation_digest,
+		enrollment_event_id: request.enrollment_event_id,
+		actor_id: request.actor_id,
+		confirmation_ref: request.confirmation_ref,
+		nonce: request.nonce,
+	});
+	return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+export function drainOperationId(taskId: string, updatedAt: string): string {
+	return `drain:${taskId}:${updatedAt}`;
+}
+
+/**
+ * Digest of a terminal request's own content. The capability is deliberately
+ * opaque and excluded, so a retry that re-mints authority for the *same*
+ * request produces the same digest, while a different reason, actor or event
+ * time produces a different one and must be authorized again instead of being
+ * answered from the committed operation.
+ */
+export function terminalRequestDigest(action: {
+	type: string;
+	event_id: string;
+	at: string;
+	actor_id: string;
+	reason?: unknown;
+}): string {
+	const canonical = JSON.stringify({
+		type: action.type,
+		event_id: action.event_id,
+		at: action.at,
+		actor_id: action.actor_id,
+		reason: typeof action.reason === "string" ? action.reason : null,
+	});
+	return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+export function terminalOperationId(taskId: string, eventId: string): string {
+	return `terminal:${taskId}:${eventId}`;
+}