@sayknow-cli/coding-agent 0.3.7 → 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,
@@ -176,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[];
@@ -210,55 +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 (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");

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,
+	};
+}