@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/skc-runtime/ultragoal-guard.ts

@@ -1,17 +1,15 @@
 import * as fs from "node:fs/promises";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
 import { resolveSkcSessionForRead, SessionResolutionError } from "./session-resolution";
+import { validateDeferredMemberReceiptFresh, validateReceiptFreshBase } from "./ultragoal-receipt-freshness";
 import {
-	computeUltragoalPlanGeneration,
 	getUltragoalPaths,
 	getUltragoalRunCompletionState,
-	hashStructuredValue,
 	readUltragoalLedger,
 	readUltragoalPlan,
 	recordUltragoalNudgeIfBudgetRemaining,
 	resolveUltragoalNudgeBudget,
 	selectUltragoalNudgeTarget,
-	type UltragoalCompletionVerification,
 	type UltragoalGoal,
 	type UltragoalLedgerEvent,
 	type UltragoalNudgeSurface,
@@ -69,9 +67,12 @@ function isKnownUltragoalObjective(currentObjective: string): boolean {
 	);
 }
 
-async function ultragoalReadPaths(cwd: string): Promise<{ paths: UltragoalPaths; sessionId: string | null }> {
-	const envSessionId = process.env.SKC_SESSION_ID?.trim();
-	if (envSessionId) return { paths: getUltragoalPaths(cwd, envSessionId), sessionId: envSessionId };
+async function ultragoalReadPaths(
+	cwd: string,
+	options: { sessionId?: string | null } = {},
+): Promise<{ paths: UltragoalPaths; sessionId: string | null }> {
+	const explicitSessionId = options.sessionId?.trim() || process.env.SKC_SESSION_ID?.trim();
+	if (explicitSessionId) return { paths: getUltragoalPaths(cwd, explicitSessionId), sessionId: explicitSessionId };
 	try {
 		const session = await resolveSkcSessionForRead(cwd, { envSessionId: process.env.SKC_SESSION_ID });
 		return { paths: getUltragoalPaths(cwd, session.skcSessionId), sessionId: session.skcSessionId };
@@ -173,26 +174,6 @@ function findReceiptGoal(
 	return storyGoal ? { goal: storyGoal, receiptKind: "per-goal" } : null;
 }
 
-function findLedgerReceiptEvent(
-	ledger: readonly UltragoalLedgerEvent[],
-	receipt: UltragoalCompletionVerification,
-): UltragoalLedgerEvent | null {
-	return (
-		ledger.find(event => {
-			if (event.eventId !== receipt.checkpointLedgerEventId) return false;
-			if (event.event !== "goal_checkpointed") return false;
-			if (event.goalId !== receipt.goalId) return false;
-			const eventReceipt = event.completionVerification as UltragoalCompletionVerification | undefined;
-			return (
-				event.status === "complete" &&
-				eventReceipt?.receiptId === receipt.receiptId &&
-				eventReceipt.receiptKind === receipt.receiptKind &&
-				eventReceipt.planGeneration === receipt.planGeneration
-			);
-		}) ?? null
-	);
-}
-
 export function validateCompletionReceipt(input: {
 	plan: UltragoalPlan;
 	ledger: readonly UltragoalLedgerEvent[];
@@ -207,62 +188,66 @@ export function validateCompletionReceipt(input: {
 			goalId: input.goal.id,
 		};
 	}
-	if (
-		receipt.schemaVersion !== 1 ||
-		receipt.goalId !== input.goal.id ||
-		receipt.receiptKind !== input.receiptKind ||
-		!receipt.planGeneration ||
-		!receipt.checkpointLedgerEventId
-	) {
-		return {
-			state: "active_stale_receipt",
-			message: `Ultragoal ${input.goal.id} receipt is malformed or stale.`,
-			goalId: input.goal.id,
-		};
-	}
-	const event = findLedgerReceiptEvent(input.ledger, receipt);
-	if (!event) {
-		return {
-			state: "active_stale_receipt",
-			message: `Ultragoal ${input.goal.id} receipt ledger event is missing.`,
-			goalId: input.goal.id,
-		};
+	if (receipt.validationBatch?.role === "deferred-member") {
+		return validateDeferredMemberReceiptFresh({
+			plan: input.plan,
+			ledger: input.ledger,
+			goal: input.goal,
+			receipt,
+			receiptKind: input.receiptKind,
+			requireClose: true,
+		});
 	}
-	const generation = computeUltragoalPlanGeneration({
+	const baseDiagnostic = validateReceiptFreshBase({
 		plan: input.plan,
 		ledger: input.ledger,
 		goal: input.goal,
+		receipt,
 		receiptKind: input.receiptKind,
-		beforeStatus: receipt.goalStatusBeforeCheckpoint,
-		excludeEventId: receipt.checkpointLedgerEventId,
 	});
-	if (generation.planGeneration !== receipt.planGeneration) {
-		return {
-			state: "active_stale_receipt",
-			message: `Ultragoal ${input.goal.id} receipt generation is stale.`,
-			goalId: input.goal.id,
-		};
-	}
-	if (hashStructuredValue(event.qualityGateJson) !== receipt.qualityGateHash) {
-		return {
-			state: "active_dirty_quality_gate",
-			message: `Ultragoal ${input.goal.id} receipt quality-gate hash does not match ledger.`,
-			goalId: input.goal.id,
-		};
-	}
-	if (hashStructuredValue(event.skcGoalJson) !== receipt.skcGoalSnapshotHash) {
-		return {
-			state: "active_stale_receipt",
-			message: `Ultragoal ${input.goal.id} receipt goal({"op":"get"}) snapshot hash does not match ledger.`,
-			goalId: input.goal.id,
-		};
-	}
-	if (input.goal.updatedAt !== receipt.verifiedAt) {
-		return {
-			state: "active_stale_receipt",
-			message: `Ultragoal ${input.goal.id} receipt target changed after verification.`,
-			goalId: input.goal.id,
-		};
+	if (baseDiagnostic) return baseDiagnostic;
+	if (receipt.validationBatch?.role === "batch-close") {
+		for (const memberId of receipt.validationBatch.memberIds) {
+			const member = input.plan.goals.find(goal => goal.id === memberId);
+			if (
+				!member?.validationBatch ||
+				member.validationBatch.metadataHash !== receipt.validationBatch.memberMetadataHashes[memberId]
+			) {
+				return {
+					state: "active_stale_receipt",
+					message: `Ultragoal ${input.goal.id} batch-close receipt has stale member metadata for ${memberId}.`,
+					goalId: input.goal.id,
+				};
+			}
+			if (memberId === receipt.validationBatch.finalGoalId) continue;
+			const memberReceipt = member.completionVerification;
+			if (memberReceipt?.validationBatch?.role !== "deferred-member") {
+				return {
+					state: "active_missing_final_receipt",
+					message: `Ultragoal ${input.goal.id} batch-close receipt requires deferred member receipt for ${memberId}.`,
+					goalId: input.goal.id,
+				};
+			}
+			const memberDiagnostic = validateDeferredMemberReceiptFresh({
+				plan: input.plan,
+				ledger: input.ledger,
+				goal: member,
+				receipt: memberReceipt,
+				receiptKind: "per-goal",
+				requireClose: false,
+			});
+			if (memberDiagnostic.state !== "active_verified_complete") return memberDiagnostic;
+			if (
+				receipt.validationBatch.memberReceiptIds[memberId] !== memberReceipt.receiptId ||
+				receipt.validationBatch.memberChangeSetHashes[memberId] !== memberReceipt.validationBatch.changeSetHash
+			) {
+				return {
+					state: "active_stale_receipt",
+					message: `Ultragoal ${input.goal.id} batch-close receipt is stale for deferred member ${memberId}.`,
+					goalId: input.goal.id,
+				};
+			}
+		}
 	}
 	if (input.receiptKind === "final-aggregate") {
 		const incomplete = requiredGoals(input.plan).filter(goal => goal.status !== "complete");
@@ -273,15 +258,28 @@ export function validateCompletionReceipt(input: {
 				goalId: input.goal.id,
 			};
 		}
-		const missingReceipts = requiredGoals(input.plan).filter(
-			goal => goal.id !== input.goal.id && !goal.completionVerification,
-		);
-		if (missingReceipts.length > 0) {
-			return {
-				state: "active_missing_receipt",
-				message: `Ultragoal final receipt is missing per-goal evidence for: ${missingReceipts.map(goal => goal.id).join(", ")}.`,
-				goalId: input.goal.id,
-			};
+		for (const priorGoal of requiredGoals(input.plan)) {
+			if (priorGoal.id === input.goal.id) continue;
+			if (!priorGoal.completionVerification) {
+				return {
+					state: "active_missing_receipt",
+					message: `Ultragoal final receipt is missing per-goal evidence for: ${priorGoal.id}.`,
+					goalId: input.goal.id,
+				};
+			}
+			const priorDiagnostic = validateCompletionReceipt({
+				plan: input.plan,
+				ledger: input.ledger,
+				goal: priorGoal,
+				receiptKind: "per-goal",
+			});
+			if (priorDiagnostic.state !== "active_verified_complete") {
+				return {
+					state: priorDiagnostic.state,
+					message: `Ultragoal final receipt requires a valid per-goal receipt for ${priorGoal.id}: ${priorDiagnostic.message}`,
+					goalId: input.goal.id,
+				};
+			}
 		}
 	}
 	return {
@@ -372,11 +370,128 @@ export async function readUltragoalVerificationState(input: {
 	return receiptDiagnostic;
 }
 
-export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBlockDiagnostic> {
+export async function verifyUltragoalDurableCompletionState(input: {
+	cwd: string;
+	sessionId?: string | null;
+}): Promise<UltragoalGuardDiagnostic> {
+	let paths: UltragoalPaths;
+	let sessionId: string | null;
+	try {
+		({ paths, sessionId } = await ultragoalReadPaths(input.cwd, { sessionId: input.sessionId }));
+	} catch (error) {
+		return {
+			state: "unreadable_fail_closed",
+			message: `Unable to resolve durable Ultragoal state: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	if (sessionId === null)
+		return { state: "inactive", message: "No active SKC session resolved; ultragoal is inactive." };
+	try {
+		await fs.stat(paths.dir);
+	} catch (error) {
+		if (isEnoent(error)) return { state: "inactive", message: "No durable .skc/ultragoal state exists." };
+		return {
+			state: "unreadable_fail_closed",
+			message: `Durable .skc/ultragoal state is present but unreadable: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+
+	let plan: UltragoalPlan | null;
+	let ledger: UltragoalLedgerEvent[];
+	try {
+		plan = await readUltragoalPlan(input.cwd, sessionId);
+		ledger = await readUltragoalLedger(input.cwd, sessionId);
+	} catch (error) {
+		return {
+			state: "unreadable_fail_closed",
+			message: `Unable to read durable Ultragoal state: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	if (!plan) return { state: "inactive", message: "No Ultragoal plan exists." };
+
+	if (plan.goals.some(goal => goal.status === "review_blocked")) {
+		return {
+			state: "active_review_blocked_recorded",
+			message: "Ultragoal has recorded review blockers; complete blocker work and rerun verification.",
+		};
+	}
+
+	const runState = getUltragoalRunCompletionState(plan);
+	if (runState.incompleteGoals.some(goal => goal.status === "blocked" || goal.status === "failed")) {
+		return {
+			state: "active_dirty_quality_gate",
+			message: "Ultragoal has blocked or failed goals; record blockers or rerun verification.",
+		};
+	}
+
+	if (plan.skcGoalMode === "per-story") {
+		const incomplete = requiredGoals(plan).filter(goal => goal.status !== "complete");
+		if (incomplete.length > 0) {
+			return {
+				state: "active_missing_receipt",
+				message: `Ultragoal per-story completion requires all required stories to be complete; incomplete: ${incomplete.map(goal => goal.id).join(", ")}.`,
+				goalId: incomplete[0]?.id,
+			};
+		}
+		for (const goal of requiredGoals(plan)) {
+			const diagnostic = validateCompletionReceipt({
+				plan,
+				ledger,
+				goal,
+				receiptKind: "per-goal",
+			});
+			if (diagnostic.state !== "active_verified_complete") return diagnostic;
+		}
+		return {
+			state: "active_verified_complete",
+			message: "Ultragoal per-story run is verified complete.",
+		};
+	}
+
+	const ask = await isUltragoalAskBlocked(input.cwd, { sessionId });
+	if (!ask.active) {
+		return {
+			state: "active_verified_complete",
+			message: ask.reason,
+			goalId: ask.goalIds?.at(0),
+		};
+	}
+	if (ask.source === "durable_state_unreadable") {
+		return {
+			state: "unreadable_fail_closed",
+			message: ask.reason,
+			goalId: ask.goalIds?.at(0),
+		};
+	}
+	if (ask.reason.includes("recorded review blockers")) {
+		return {
+			state: "active_review_blocked_recorded",
+			message: ask.reason,
+			goalId: ask.goalIds?.at(0),
+		};
+	}
+	if (ask.reason.includes("incomplete required goals")) {
+		return {
+			state: "active_missing_final_receipt",
+			message: ask.reason,
+			goalId: ask.goalIds?.at(0),
+		};
+	}
+	return {
+		state: "active_missing_final_receipt",
+		message: ask.reason,
+		goalId: ask.goalIds?.at(0),
+	};
+}
+
+export async function isUltragoalAskBlocked(
+	cwd: string,
+	options: { sessionId?: string | null } = {},
+): Promise<UltragoalAskBlockDiagnostic> {
 	let paths: UltragoalPaths;
 	let sessionId: string | null;
 	try {
-		({ paths, sessionId } = await ultragoalReadPaths(cwd));
+		({ paths, sessionId } = await ultragoalReadPaths(cwd, options));
 	} catch (error) {
 		return activeAskDiagnostic({
 			reason: `Unable to resolve durable Ultragoal state: ${error instanceof Error ? error.message : String(error)}`,
@@ -594,8 +709,8 @@ export async function assertCanCompleteCurrentGoal(input: {
 	sessionId?: string | null;
 }): Promise<void> {
 	if (!input.cwd) return;
-	const diagnostic = await readUltragoalVerificationState(input);
-	if (["inactive", "unrelated_goal", "active_verified_complete"].includes(diagnostic.state)) return;
+	const diagnostic = await verifyUltragoalDurableCompletionState(input);
+	if (["inactive", "active_verified_complete"].includes(diagnostic.state)) return;
 	const nudge = await consumeUltragoalNudge({
 		cwd: input.cwd,
 		surface: "premature_complete",
@@ -604,7 +719,7 @@ export async function assertCanCompleteCurrentGoal(input: {
 	});
 	if (nudge.nudged) throw new Error(nudge.message);
 	throw new Error(
-		`${diagnostic.message} Run strict \`skc ultragoal checkpoint --status complete --quality-gate-json <file> --skc-goal-json <file>\` first, or record review blockers and rerun verification.`,
+		`${diagnostic.message} Run \`skc ultragoal checkpoint --status complete --quality-gate-json <file>\` first, or record review blockers and rerun verification.`,
 	);
 }
 

package/src/skc-runtime/ultragoal-receipt-freshness.ts

@@ -0,0 +1,315 @@
+import * as crypto from "node:crypto";
+import type {
+	UltragoalCompletionVerification,
+	UltragoalGoal,
+	UltragoalGoalStatus,
+	UltragoalLedgerEvent,
+	UltragoalPlan,
+	UltragoalReceiptKind,
+} from "./ultragoal-runtime";
+
+export type UltragoalReceiptFreshnessDiagnostic = {
+	state:
+		| "inactive"
+		| "unrelated_goal"
+		| "active_verified_complete"
+		| "active_missing_receipt"
+		| "active_stale_receipt"
+		| "active_missing_final_receipt"
+		| "active_dirty_quality_gate"
+		| "active_review_blocked_unrecorded"
+		| "active_review_blocked_recorded"
+		| "unreadable_fail_closed";
+	message: string;
+	goalId?: string;
+};
+function stableStructuredValue(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(item => stableStructuredValue(item));
+	if (typeof value !== "object" || value === null) return value;
+	const record = value as Record<string, unknown>;
+	const sorted: Record<string, unknown> = {};
+	for (const key of Object.keys(record).sort()) {
+		const item = record[key];
+		if (item !== undefined) sorted[key] = stableStructuredValue(item);
+	}
+	return sorted;
+}
+
+function hashStructuredValue(value: unknown): string {
+	return crypto
+		.createHash("sha256")
+		.update(JSON.stringify(stableStructuredValue(value)))
+		.digest("hex");
+}
+
+export function requiredUltragoalGoals(plan: UltragoalPlan): UltragoalGoal[] {
+	return plan.goals.filter(goal => goal.status !== "superseded");
+}
+
+export function receiptRelevantGoals(
+	plan: UltragoalPlan,
+	goal: UltragoalGoal,
+	receiptKind: UltragoalReceiptKind,
+): UltragoalGoal[] {
+	if (goal.validationBatch?.finalGoalId === goal.id) {
+		return goal.validationBatch.memberIds.map(memberId => {
+			const member = plan.goals.find(item => item.id === memberId);
+			if (!member)
+				throw new Error(`validation batch ${goal.validationBatch?.batchId} references missing goal ${memberId}`);
+			return member;
+		});
+	}
+	return receiptKind === "final-aggregate" ? requiredUltragoalGoals(plan) : [goal];
+}
+
+function ledgerEventId(event: UltragoalLedgerEvent): string | null {
+	return typeof event.eventId === "string" && event.eventId.trim().length > 0 ? event.eventId : null;
+}
+
+function isReceiptFreshnessBookkeepingEvent(event: UltragoalLedgerEvent): boolean {
+	return event.event === "nudge";
+}
+
+function latestRelevantLedgerEventId(
+	ledger: readonly UltragoalLedgerEvent[],
+	relevantGoalIds: readonly string[],
+	excludeEventId?: string,
+): string | null {
+	const relevant = new Set(relevantGoalIds);
+	for (const event of [...ledger].reverse()) {
+		const eventId = ledgerEventId(event);
+		if (eventId && eventId === excludeEventId) continue;
+		if (isReceiptFreshnessBookkeepingEvent(event)) continue;
+		const goalId = typeof event.goalId === "string" ? event.goalId.trim() : "";
+		if (goalId && relevant.has(goalId)) return eventId;
+	}
+	return null;
+}
+
+function planSnapshotForReceipt(input: {
+	plan: UltragoalPlan;
+	goal: UltragoalGoal;
+	beforeStatus: UltragoalGoalStatus;
+	targetGoalUpdatedAt: string;
+	receiptKind: UltragoalReceiptKind;
+}): unknown {
+	const targetGoalSnapshot = {
+		...input.goal,
+		status: input.beforeStatus,
+		updatedAt: input.targetGoalUpdatedAt,
+		evidence: undefined,
+		completedAt: undefined,
+		completionVerification: undefined,
+	};
+	const goals =
+		input.receiptKind === "final-aggregate"
+			? input.plan.goals.map(goal => ({
+					...goal,
+					status: goal.id === input.goal.id ? input.beforeStatus : goal.status,
+					updatedAt: goal.id === input.goal.id ? input.targetGoalUpdatedAt : goal.updatedAt,
+					evidence: goal.id === input.goal.id ? undefined : goal.evidence,
+					completedAt: goal.id === input.goal.id ? undefined : goal.completedAt,
+					completionVerification: undefined,
+				}))
+			: [targetGoalSnapshot];
+	return {
+		version: input.plan.version,
+		brief: input.plan.brief,
+		skcGoalMode: input.plan.skcGoalMode,
+		skcObjective: input.plan.skcObjective,
+		skcObjectiveAliases: input.plan.skcObjectiveAliases,
+		createdAt: input.plan.createdAt,
+		goals,
+	};
+}
+
+export function computeUltragoalPlanGeneration(input: {
+	plan: UltragoalPlan;
+	ledger: readonly UltragoalLedgerEvent[];
+	goal: UltragoalGoal;
+	receiptKind: UltragoalReceiptKind;
+	beforeStatus: UltragoalGoalStatus;
+	excludeEventId?: string;
+	targetGoalUpdatedAt?: string;
+}): {
+	planGeneration: string;
+	basis: UltragoalCompletionVerification["basis"];
+} {
+	const relevantGoals = receiptRelevantGoals(input.plan, input.goal, input.receiptKind);
+	const relevantGoalIds = relevantGoals.map(goal => goal.id);
+	const targetGoalUpdatedAt = input.targetGoalUpdatedAt ?? input.goal.updatedAt;
+	const planHashBeforeCheckpoint = hashStructuredValue(
+		planSnapshotForReceipt({
+			plan: input.plan,
+			goal: input.goal,
+			beforeStatus: input.beforeStatus,
+			targetGoalUpdatedAt,
+			receiptKind: input.receiptKind,
+		}),
+	);
+	const requiredGoalSetHashBeforeCheckpoint = hashStructuredValue(
+		relevantGoals.map(goal => ({
+			id: goal.id,
+			status: goal.id === input.goal.id ? input.beforeStatus : goal.status,
+			updatedAt: goal.id === input.goal.id ? targetGoalUpdatedAt : goal.updatedAt,
+		})),
+	);
+	const basis: UltragoalCompletionVerification["basis"] = {
+		planHashBeforeCheckpoint,
+		latestRelevantLedgerEventIdBeforeCheckpoint: latestRelevantLedgerEventId(
+			input.ledger,
+			relevantGoalIds,
+			input.excludeEventId,
+		),
+		goalUpdatedAtBeforeCheckpoint: targetGoalUpdatedAt,
+		relevantGoalIdsBeforeCheckpoint: relevantGoalIds,
+		requiredGoalSetHashBeforeCheckpoint,
+	};
+	return { planGeneration: hashStructuredValue(basis), basis };
+}
+
+export function findLedgerReceiptEvent(
+	ledger: readonly UltragoalLedgerEvent[],
+	receipt: UltragoalCompletionVerification,
+): UltragoalLedgerEvent | null {
+	return (
+		ledger.find(event => {
+			if (event.eventId !== receipt.checkpointLedgerEventId) return false;
+			if (event.event !== "goal_checkpointed") return false;
+			if (event.goalId !== receipt.goalId) return false;
+			const eventReceipt = event.completionVerification as UltragoalCompletionVerification | undefined;
+			return (
+				event.status === "complete" &&
+				eventReceipt?.receiptId === receipt.receiptId &&
+				eventReceipt.receiptKind === receipt.receiptKind &&
+				eventReceipt.planGeneration === receipt.planGeneration
+			);
+		}) ?? null
+	);
+}
+
+export function validateReceiptFreshBase(input: {
+	plan: UltragoalPlan;
+	ledger: readonly UltragoalLedgerEvent[];
+	goal: UltragoalGoal;
+	receipt: UltragoalCompletionVerification;
+	receiptKind: UltragoalReceiptKind;
+}): UltragoalReceiptFreshnessDiagnostic | null {
+	if (
+		input.receipt.schemaVersion !== 1 ||
+		input.receipt.goalId !== input.goal.id ||
+		input.receipt.receiptKind !== input.receiptKind ||
+		!input.receipt.planGeneration ||
+		!input.receipt.checkpointLedgerEventId
+	) {
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt is malformed or stale.`,
+			goalId: input.goal.id,
+		};
+	}
+	const event = findLedgerReceiptEvent(input.ledger, input.receipt);
+	if (!event)
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt ledger event is missing.`,
+			goalId: input.goal.id,
+		};
+	const generation = computeUltragoalPlanGeneration({
+		plan: input.plan,
+		ledger: input.ledger,
+		goal: input.goal,
+		receiptKind: input.receiptKind,
+		beforeStatus: input.receipt.goalStatusBeforeCheckpoint,
+		excludeEventId: input.receipt.checkpointLedgerEventId,
+	});
+	if (generation.planGeneration !== input.receipt.planGeneration)
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt generation is stale.`,
+			goalId: input.goal.id,
+		};
+	if (hashStructuredValue(event.qualityGateJson) !== input.receipt.qualityGateHash)
+		return {
+			state: "active_dirty_quality_gate",
+			message: `Ultragoal ${input.goal.id} receipt quality-gate hash does not match ledger.`,
+			goalId: input.goal.id,
+		};
+	if (input.goal.updatedAt !== input.receipt.verifiedAt)
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt target changed after verification.`,
+			goalId: input.goal.id,
+		};
+	return null;
+}
+
+export function findFreshBatchCloseReceipt(input: {
+	plan: UltragoalPlan;
+	ledger: readonly UltragoalLedgerEvent[];
+	deferredGoal: UltragoalGoal;
+	deferredReceipt: UltragoalCompletionVerification;
+}): UltragoalCompletionVerification | null {
+	const batch = input.deferredReceipt.validationBatch;
+	if (batch?.role !== "deferred-member") return null;
+	const finalGoal = input.plan.goals.find(goal => goal.id === batch.finalGoalId);
+	const finalReceipt = finalGoal?.completionVerification;
+	if (!finalGoal || finalReceipt?.validationBatch?.role !== "batch-close") return null;
+	if (
+		finalReceipt.validationBatch.batchId !== batch.batchId ||
+		finalReceipt.validationBatch.memberReceiptIds[input.deferredGoal.id] !== input.deferredReceipt.receiptId
+	)
+		return null;
+	const diagnostic = validateReceiptFreshBase({
+		plan: input.plan,
+		ledger: input.ledger,
+		goal: finalGoal,
+		receipt: finalReceipt,
+		receiptKind: finalReceipt.receiptKind,
+	});
+	return diagnostic ? null : finalReceipt;
+}
+
+export function validateDeferredMemberReceiptFresh(input: {
+	plan: UltragoalPlan;
+	ledger: readonly UltragoalLedgerEvent[];
+	goal: UltragoalGoal;
+	receipt: UltragoalCompletionVerification;
+	receiptKind: UltragoalReceiptKind;
+	requireClose: boolean;
+}): UltragoalReceiptFreshnessDiagnostic {
+	const batch = input.receipt.validationBatch;
+	if (
+		batch?.role !== "deferred-member" ||
+		input.goal.validationBatch?.metadataHash !== batch.metadataHash ||
+		input.goal.validationBatch.batchId !== batch.batchId
+	) {
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} deferred receipt is malformed or stale.`,
+			goalId: input.goal.id,
+		};
+	}
+	const base = validateReceiptFreshBase(input);
+	if (base) return base;
+	if (
+		input.requireClose &&
+		!findFreshBatchCloseReceipt({
+			plan: input.plan,
+			ledger: input.ledger,
+			deferredGoal: input.goal,
+			deferredReceipt: input.receipt,
+		})
+	) {
+		return {
+			state: "active_missing_final_receipt",
+			message: `Ultragoal ${input.goal.id} is deferred to validation batch ${batch.batchId} until final goal ${batch.finalGoalId} closes the batch`,
+			goalId: input.goal.id,
+		};
+	}
+	return {
+		state: "active_verified_complete",
+		message: `Ultragoal ${input.goal.id} has a fresh deferred validation batch receipt.`,
+		goalId: input.goal.id,
+	};
+}