@gajae-code/coding-agent 0.12.4 → 0.12.6

package/src/gjc-runtime/ultragoal-change-set.ts

@@ -1,8 +1,6 @@
 import {
 	categorizeComputerChangePath,
-	isSettingsSchemaPath,
-	normalizeRepoPath,
-	type UltragoalChangeCategory,
+	normalizeChangeSetPath,
 	type UltragoalChangeSet,
 	type UltragoalChangeSetPath,
 	type UltragoalChangeStatus,
@@ -15,12 +13,19 @@ export async function spawnText(
 	try {
 		const proc = Bun.spawn(command, { cwd: options.cwd, stdout: "pipe", stderr: "pipe" });
 		const timeout = setTimeout(() => proc.kill(), options.timeoutMs ?? 5000);
-		const [stdout, stderr, exitCode] = await Promise.all([
-			new Response(proc.stdout).text(),
-			new Response(proc.stderr).text(),
+		const [stdoutBytes, stderrBytes, exitCode] = await Promise.all([
+			new Response(proc.stdout).arrayBuffer(),
+			new Response(proc.stderr).arrayBuffer(),
 			proc.exited,
 		]);
 		clearTimeout(timeout);
+		let stdout: string;
+		try {
+			stdout = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(stdoutBytes);
+		} catch {
+			return { ok: false, stdout: "", stderr: "command stdout was not valid UTF-8" };
+		}
+		const stderr = new TextDecoder().decode(stderrBytes);
 		return { ok: exitCode === 0, stdout, stderr };
 	} catch (error) {
 		return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
@@ -55,61 +60,79 @@ export async function resolveGitBase(cwd: string, branch?: string): Promise<stri
 		}
 		if (best) return best.ref;
 	}
-	const mergeBase = await spawnText(["git", "merge-base", "HEAD", "origin/main"], { cwd, timeoutMs: 3000 });
-	if (mergeBase.ok && mergeBase.stdout.trim()) return mergeBase.stdout.trim();
-	return "HEAD~1";
+	throw new Error("unable to resolve an authoritative integration base");
 }
 
 export function parseGitNameStatus(output: string): UltragoalChangeSetPath[] {
 	const rows: UltragoalChangeSetPath[] = [];
-	for (const line of output.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		const parts = trimmed.split(/\s+/);
-		const statusCode = parts[0] ?? "";
+	const append = (statusCode: string, pathValue: string | undefined, oldPath: string | undefined): void => {
+		if (!pathValue) return;
 		let status: UltragoalChangeStatus = "unknown";
 		if (statusCode.startsWith("A")) status = "added";
 		else if (statusCode.startsWith("M")) status = "modified";
 		else if (statusCode.startsWith("D")) status = "deleted";
 		else if (statusCode.startsWith("R")) status = "renamed";
 		else if (statusCode.startsWith("C")) status = "copied";
-		const pathValue = status === "renamed" || status === "copied" ? parts[2] : parts[1];
-		if (!pathValue) continue;
-		const oldPath = status === "renamed" || status === "copied" ? parts[1] : undefined;
 		rows.push({
-			path: normalizeRepoPath(pathValue),
-			oldPath: oldPath ? normalizeRepoPath(oldPath) : undefined,
+			path: normalizeChangeSetPath(pathValue),
+			oldPath: oldPath ? normalizeChangeSetPath(oldPath) : undefined,
 			status,
 			category: categorizeComputerChangePath(pathValue),
 		});
+	};
+	if (output.includes("\0")) {
+		const tokens = output.split("\0");
+		let index = 0;
+		while (index < tokens.length) {
+			const statusCode = tokens[index++] ?? "";
+			if (!statusCode) continue;
+			if (statusCode.startsWith("R") || statusCode.startsWith("C")) {
+				const oldPath = tokens[index++];
+				append(statusCode, tokens[index++], oldPath);
+			} else {
+				append(statusCode, tokens[index++], undefined);
+			}
+		}
+		return rows;
+	}
+	for (const line of output.split("\n")) {
+		if (!line.trim()) continue;
+		const [rawStatus = "", firstPath, secondPath] = line.split("\t");
+		const statusCode = rawStatus.trim();
+		append(
+			statusCode,
+			statusCode.startsWith("R") || statusCode.startsWith("C") ? secondPath : firstPath,
+			statusCode.startsWith("R") || statusCode.startsWith("C") ? firstPath : undefined,
+		);
 	}
 	return rows;
 }
 
-function categorizeCiChangedPath(value: string): UltragoalChangeCategory {
-	// CI_DEV_CHANGED_PATHS intentionally carries path names only. Mixed registries
-	// such as settings-schema.ts require diff-level narrowing; without the diff,
-	// treating the whole registry as computer-control source forces the mandatory
-	// computer red-team suite on unrelated settings changes.
-	if (isSettingsSchemaPath(value)) return "other";
-	return categorizeComputerChangePath(value);
+export function parseGitUntrackedPaths(output: string): UltragoalChangeSetPath[] {
+	const paths = output.includes("\0") ? output.split("\0") : output.split(/\r?\n/);
+	return paths
+		.filter(pathValue => pathValue.length > 0)
+		.map(pathValue => ({
+			path: normalizeChangeSetPath(pathValue),
+			status: "added" as UltragoalChangeStatus,
+			category: categorizeComputerChangePath(pathValue),
+		}));
 }
 
-function ciDevChangedPathRows(): UltragoalChangeSetPath[] {
+export function ciDevChangedPathRows(): UltragoalChangeSetPath[] {
 	const raw = process.env.CI_DEV_CHANGED_PATHS;
 	if (!raw) return [];
 	return raw
 		.split(/\r?\n/)
-		.map(row => row.trim())
-		.filter(Boolean)
+		.filter(row => row.length > 0)
 		.map(pathValue => ({
-			path: normalizeRepoPath(pathValue),
+			path: normalizeChangeSetPath(pathValue),
 			status: "unknown" as UltragoalChangeStatus,
-			category: categorizeCiChangedPath(pathValue),
+			category: categorizeComputerChangePath(pathValue),
 		}));
 }
 
-function mergeChangeSetPaths(groups: UltragoalChangeSetPath[][]): UltragoalChangeSetPath[] {
+export function mergeChangeSetPaths(groups: UltragoalChangeSetPath[][]): UltragoalChangeSetPath[] {
 	const byKey = new Map<string, UltragoalChangeSetPath>();
 	for (const row of groups.flat()) byKey.set(`${row.oldPath ?? ""}\u0000${row.path}`, row);
 	return [...byKey.values()];
@@ -119,36 +142,59 @@ export async function computeCheckpointChangeSet(cwd: string): Promise<Ultragoal
 	const ciChangedPaths = ciDevChangedPathRows();
 	const inGit = await spawnText(["git", "rev-parse", "--is-inside-work-tree"], { cwd, timeoutMs: 3000 });
 	if (!inGit.ok || inGit.stdout.trim() !== "true") {
-		if (ciChangedPaths.length === 0) return undefined;
+		if (ciChangedPaths.length === 0)
+			return { source: "checkpoint-git", paths: [], captureIncomplete: true, trusted: true };
 		return { source: "checkpoint-git", paths: ciChangedPaths, trusted: true };
 	}
 	const baseRef = await resolveGitBase(cwd);
 	const base = baseRef;
 	const mergeBase = await spawnText(["git", "merge-base", "HEAD", baseRef], { cwd, timeoutMs: 3000 });
-	const [committed, unstaged, staged, stat, committedDiff, unstagedDiff, stagedDiff] = await Promise.all([
-		spawnText(["git", "diff", "--name-status", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", "--name-status"], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", "--cached", "--name-status"], { cwd, timeoutMs: 5000 }),
+	const [committed, unstaged, staged, untracked, stat, committedDiff, unstagedDiff, stagedDiff] = await Promise.all([
+		spawnText(["git", "diff", "--name-status", "-z", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", "--name-status", "-z"], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", "--cached", "--name-status", "-z"], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "ls-files", "--others", "--exclude-standard", "-z"], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "diff", "--stat", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "diff", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "diff"], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "diff", "--cached"], { cwd, timeoutMs: 5000 }),
 	]);
-	if (!committed.ok && !unstaged.ok && !staged.ok && ciChangedPaths.length === 0) return undefined;
-	const gitPaths = mergeChangeSetPaths([
+	if (!committed.ok || !unstaged.ok || !staged.ok || !untracked.ok) {
+		const paths = mergeChangeSetPaths([
+			committed.ok ? parseGitNameStatus(committed.stdout) : [],
+			unstaged.ok ? parseGitNameStatus(unstaged.stdout) : [],
+			staged.ok ? parseGitNameStatus(staged.stdout) : [],
+			untracked.ok ? parseGitUntrackedPaths(untracked.stdout) : [],
+			ciChangedPaths,
+		]);
+		return {
+			source: "checkpoint-git",
+			baseRef,
+			mergeBase: mergeBase.ok && mergeBase.stdout.trim() ? mergeBase.stdout.trim() : undefined,
+			headRef: "HEAD",
+			paths,
+			captureIncomplete: true,
+			trusted: true,
+		};
+	}
+	const paths = mergeChangeSetPaths([
 		parseGitNameStatus(committed.stdout),
 		parseGitNameStatus(unstaged.stdout),
 		parseGitNameStatus(staged.stdout),
+		parseGitUntrackedPaths(untracked.stdout),
+		ciChangedPaths,
 	]);
-	const paths = gitPaths.length > 0 ? gitPaths : ciChangedPaths;
 	return {
 		source: "checkpoint-git",
 		baseRef,
 		mergeBase: mergeBase.ok && mergeBase.stdout.trim() ? mergeBase.stdout.trim() : undefined,
 		headRef: "HEAD",
 		paths,
-		rawDiffStat: stat.stdout,
-		rawDiff: [committedDiff.stdout, unstagedDiff.stdout, stagedDiff.stdout].filter(Boolean).join("\n"),
+		rawDiffStat: stat.ok ? stat.stdout : undefined,
+		rawDiff:
+			committedDiff.ok && unstagedDiff.ok && stagedDiff.ok
+				? [committedDiff.stdout, unstagedDiff.stdout, stagedDiff.stdout].filter(Boolean).join("\n")
+				: undefined,
 		trusted: true,
 	};
 }
@@ -159,8 +205,8 @@ export function parseUnifiedDiffPaths(diff: string): UltragoalChangeSetPath[] {
 		if (!line.startsWith("diff --git ")) continue;
 		const match = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
 		if (!match) continue;
-		const oldPath = normalizeRepoPath(match[1]!);
-		const newPath = normalizeRepoPath(match[2]!);
+		const oldPath = normalizeChangeSetPath(match[1]!);
+		const newPath = normalizeChangeSetPath(match[2]!);
 		paths.push({
 			path: newPath,
 			oldPath: oldPath === newPath ? undefined : oldPath,

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

@@ -338,6 +338,13 @@ export function validateReceiptFreshBase(input: {
 			message: `Ultragoal ${input.goal.id} receipt ledger event is missing.`,
 			goalId: input.goal.id,
 		};
+	const eventReceipt = event.completionVerification as UltragoalCompletionVerification | undefined;
+	if (!eventReceipt || hashStructuredValue(eventReceipt) !== hashStructuredValue(input.receipt))
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt does not match its ledger event receipt.`,
+			goalId: input.goal.id,
+		};
 	const generation = computeUltragoalPlanGeneration({
 		plan: input.plan,
 		ledger: input.ledger,

package/src/gjc-runtime/ultragoal-review-source.ts

@@ -0,0 +1,378 @@
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { RepositoryBinding } from "./repository-binding";
+import { publicRepositoryBinding } from "./repository-binding";
+
+async function spawnText(
+	command: string[],
+	options: { cwd: string; timeoutMs?: number },
+): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+	try {
+		const proc = Bun.spawn(command, { cwd: options.cwd, stdout: "pipe", stderr: "pipe" });
+		const timeout = setTimeout(() => proc.kill(), options.timeoutMs ?? 5000);
+		const [stdout, stderr, exitCode] = await Promise.all([
+			new Response(proc.stdout).text(),
+			new Response(proc.stderr).text(),
+			proc.exited,
+		]);
+		clearTimeout(timeout);
+		return { ok: exitCode === 0, stdout, stderr };
+	} catch (error) {
+		return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+async function resolveGitBase(cwd: string): Promise<string> {
+	for (const candidate of ["origin/dev", "dev", "origin/main", "main", "master"]) {
+		const exists = await spawnText(["git", "rev-parse", "--verify", candidate], { cwd, timeoutMs: 3000 });
+		if (exists.ok) return candidate;
+	}
+	throw new Error("unable to resolve an authoritative integration base");
+}
+export const REVIEW_SOURCE_COHORT_SCHEMA = "gjc.review_source_cohort.v1" as const;
+
+export type ReviewSourceWorkflow = "ultragoal" | "ralplan";
+export type ReviewSourceLane = "cleaner" | "architect" | "qa" | "critic";
+export type ReviewDeliveryDisposition = "current" | "stale_review_delivery" | "invalid_provenance";
+
+export interface ReviewSourceDispatch {
+	schema: "gjc.review_source_dispatch.v1";
+	cohortId: string;
+	generation: number;
+
+	dispatchId: string;
+	taskId: string;
+	lane: ReviewSourceLane;
+	snapshotId: string;
+	repositoryBindingDigest: string;
+	stateRevision: number;
+	rerunCommand: string;
+	createdAt: string;
+}
+
+export interface ReviewSourceDelivery {
+	deliveryId: string;
+	taskId: string;
+	lane: ReviewSourceLane;
+	snapshotId: string;
+	disposition: ReviewDeliveryDisposition;
+	receivedAt: string;
+	rerunCommand?: string;
+	cohortId: string;
+	dispatchId: string;
+}
+
+export interface ReviewSourceCohort {
+	schema: typeof REVIEW_SOURCE_COHORT_SCHEMA;
+	cohortId: string;
+	workflow: ReviewSourceWorkflow;
+	generation: number;
+	snapshotId: string;
+	repositoryBindingDigest: string;
+	stateRevision: number;
+	createdAt: string;
+	status: "active" | "superseded";
+	supersededBy?: string;
+	dispatches: ReviewSourceDispatch[];
+
+	deliveries: ReviewSourceDelivery[];
+}
+
+interface CapturedReviewSource {
+	snapshotId: string;
+	repositoryBindingDigest: string;
+}
+
+function hashBytes(value: string | Uint8Array): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		return `{${Object.entries(value as Record<string, unknown>)
+			.sort(([left], [right]) => left.localeCompare(right))
+			.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value);
+}
+
+async function untrackedCommitments(
+	cwd: string,
+): Promise<Array<{ path: string; mode: number; kind: string; digest: string }>> {
+	const listed = await spawnText(["git", "ls-files", "--others", "--exclude-standard", "-z"], {
+		cwd,
+		timeoutMs: 5000,
+	});
+	if (!listed.ok) throw new Error(`review source capture failed to list untracked files: ${listed.stderr}`);
+	const rows: Array<{ path: string; mode: number; kind: string; digest: string }> = [];
+	for (const relativePath of listed.stdout.split("\0").filter(Boolean).sort()) {
+		const absolutePath = path.resolve(cwd, relativePath);
+		const stat = await fs.lstat(absolutePath);
+		if (stat.isSymbolicLink()) {
+			rows.push({
+				path: relativePath,
+				mode: stat.mode,
+				kind: "symlink",
+				digest: hashBytes(await fs.readlink(absolutePath)),
+			});
+			continue;
+		}
+		if (!stat.isFile())
+			throw new Error(`review source capture does not support untracked non-file path: ${relativePath}`);
+		rows.push({
+			path: relativePath,
+			mode: stat.mode,
+			kind: "file",
+			digest: hashBytes(await fs.readFile(absolutePath)),
+		});
+	}
+	return rows;
+}
+
+async function captureOnce(cwd: string, repositoryBinding: RepositoryBinding): Promise<CapturedReviewSource> {
+	const baseRef = await resolveGitBase(cwd);
+	const mergeBase = await spawnText(["git", "merge-base", "HEAD", baseRef], { cwd, timeoutMs: 5000 });
+	const head = await spawnText(["git", "rev-parse", "HEAD"], { cwd, timeoutMs: 5000 });
+	const indexTree = await spawnText(["git", "write-tree"], { cwd, timeoutMs: 5000 });
+	if (!mergeBase.ok || !head.ok || !indexTree.ok)
+		throw new Error("review source capture could not resolve git authority");
+	const diff = await spawnText(["git", "diff", "--binary", "--no-ext-diff", mergeBase.stdout.trim()], {
+		cwd,
+		timeoutMs: 15000,
+	});
+	if (!diff.ok) throw new Error(`review source capture failed to read canonical diff: ${diff.stderr}`);
+	const binding = publicRepositoryBinding(repositoryBinding);
+	const repositoryIdentity = {
+		schema: binding.schema,
+		worktreeRoot: binding.worktreeRoot,
+		commonDir: binding.commonDir,
+		relativeSubdir: binding.relativeSubdir,
+	};
+	const repositoryBindingDigest = `sha256:${hashBytes(stableJson(repositoryIdentity))}`;
+	const payload = {
+		schema: "gjc.review_source_snapshot.v1",
+		repositoryBindingDigest,
+		mergeBase: mergeBase.stdout.trim(),
+		head: head.stdout.trim(),
+		indexTree: indexTree.stdout.trim(),
+		binaryDiffSha256: hashBytes(diff.stdout),
+		untracked: await untrackedCommitments(cwd),
+	};
+	return { snapshotId: `sha256:${hashBytes(stableJson(payload))}`, repositoryBindingDigest };
+}
+
+export async function captureReviewSourceSnapshot(
+	cwd: string,
+	repositoryBinding: RepositoryBinding,
+): Promise<CapturedReviewSource> {
+	const first = await captureOnce(cwd, repositoryBinding);
+	const second = await captureOnce(cwd, repositoryBinding);
+	if (first.snapshotId !== second.snapshotId) {
+		throw new Error("review_source_capture_raced: repository source changed during canonical capture; rerun freeze");
+	}
+	return first;
+}
+
+export function createReviewSourceCohort(input: {
+	workflow: ReviewSourceWorkflow;
+	generation: number;
+	snapshotId: string;
+	repositoryBindingDigest: string;
+	stateRevision: number;
+	now?: string;
+}): ReviewSourceCohort {
+	return {
+		schema: REVIEW_SOURCE_COHORT_SCHEMA,
+		cohortId: randomUUID(),
+		workflow: input.workflow,
+		generation: input.generation,
+		snapshotId: input.snapshotId,
+		repositoryBindingDigest: input.repositoryBindingDigest,
+		stateRevision: input.stateRevision,
+		createdAt: input.now ?? new Date().toISOString(),
+		status: "active",
+		dispatches: [],
+
+		deliveries: [],
+	};
+}
+
+export function createReviewSourceDispatch(input: {
+	cohort: ReviewSourceCohort;
+	taskId: string;
+	lane: ReviewSourceLane;
+	rerunCommand: string;
+	now?: string;
+}): ReviewSourceDispatch {
+	if (input.cohort.status !== "active") throw new Error("cannot dispatch a superseded review source cohort");
+	if (input.cohort.dispatches.some(dispatch => dispatch.lane === input.lane)) {
+		throw new Error(`review source cohort already dispatched lane ${input.lane}`);
+	}
+	return {
+		schema: "gjc.review_source_dispatch.v1",
+		cohortId: input.cohort.cohortId,
+		generation: input.cohort.generation,
+		dispatchId: randomUUID(),
+		taskId: input.taskId,
+		lane: input.lane,
+		snapshotId: input.cohort.snapshotId,
+		repositoryBindingDigest: input.cohort.repositoryBindingDigest,
+		stateRevision: input.cohort.stateRevision,
+		rerunCommand: input.rerunCommand,
+		createdAt: input.now ?? new Date().toISOString(),
+	};
+}
+
+function isReviewSourceLane(value: unknown): value is ReviewSourceLane {
+	return value === "cleaner" || value === "architect" || value === "qa" || value === "critic";
+}
+
+function normalizeDispatch(value: unknown, cohort: Record<string, unknown>, index: number): ReviewSourceDispatch {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new Error(`Invalid ultragoal plan: malformed dispatch ${index}`);
+	const record = value as Record<string, unknown>;
+	if (
+		record.schema !== "gjc.review_source_dispatch.v1" ||
+		typeof record.dispatchId !== "string" ||
+		typeof record.cohortId !== "string" ||
+		record.cohortId !== cohort.cohortId ||
+		record.generation !== cohort.generation ||
+		typeof record.taskId !== "string" ||
+		!isReviewSourceLane(record.lane) ||
+		record.snapshotId !== cohort.snapshotId ||
+		record.repositoryBindingDigest !== cohort.repositoryBindingDigest ||
+		record.stateRevision !== cohort.stateRevision ||
+		typeof record.rerunCommand !== "string" ||
+		typeof record.createdAt !== "string"
+	)
+		throw new Error(`Invalid ultragoal plan: malformed dispatch ${index}`);
+	return record as unknown as ReviewSourceDispatch;
+}
+
+function normalizeDelivery(
+	value: unknown,
+	dispatches: readonly ReviewSourceDispatch[],
+	index: number,
+): ReviewSourceDelivery {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new Error(`Invalid ultragoal plan: malformed delivery ${index}`);
+	const record = value as Record<string, unknown>;
+	const dispatch = dispatches.find(item => item.dispatchId === record.dispatchId && item.cohortId === record.cohortId);
+
+	if (
+		typeof record.deliveryId !== "string" ||
+		!dispatch ||
+		!isReviewSourceLane(record.lane) ||
+		record.taskId !== dispatch.taskId ||
+		record.lane !== dispatch.lane ||
+		record.snapshotId !== dispatch.snapshotId ||
+		(record.disposition !== "current" &&
+			record.disposition !== "stale_review_delivery" &&
+			record.disposition !== "invalid_provenance") ||
+		typeof record.receivedAt !== "string" ||
+		(record.rerunCommand !== undefined && record.rerunCommand !== dispatch.rerunCommand)
+	)
+		throw new Error(`Invalid ultragoal plan: malformed delivery ${index}`);
+	return record as unknown as ReviewSourceDelivery;
+}
+
+export function normalizeReviewSourceCohorts(value: unknown): ReviewSourceCohort[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) throw new Error("Invalid ultragoal plan: reviewCohorts must be an array");
+	const cohorts = value.map((item, index) => {
+		if (!item || typeof item !== "object" || Array.isArray(item)) {
+			throw new Error(`Invalid ultragoal plan: reviewCohorts[${index}] must be an object`);
+		}
+		const record = item as Record<string, unknown>;
+		if (
+			record.schema !== REVIEW_SOURCE_COHORT_SCHEMA ||
+			typeof record.cohortId !== "string" ||
+			(record.workflow !== "ultragoal" && record.workflow !== "ralplan") ||
+			typeof record.generation !== "number" ||
+			!Number.isInteger(record.generation) ||
+			record.generation < 1 ||
+			typeof record.snapshotId !== "string" ||
+			!record.snapshotId.startsWith("sha256:") ||
+			typeof record.repositoryBindingDigest !== "string" ||
+			!record.repositoryBindingDigest.startsWith("sha256:") ||
+			typeof record.stateRevision !== "number" ||
+			!Number.isInteger(record.stateRevision) ||
+			typeof record.createdAt !== "string" ||
+			(record.status !== "active" && record.status !== "superseded") ||
+			!Array.isArray(record.dispatches) ||
+			!Array.isArray(record.deliveries)
+		) {
+			throw new Error(`Invalid ultragoal plan: malformed reviewCohorts[${index}]`);
+		}
+		const dispatches = record.dispatches.map((dispatch, dispatchIndex) =>
+			normalizeDispatch(dispatch, record, dispatchIndex),
+		);
+		const deliveries = record.deliveries.map((delivery, deliveryIndex) =>
+			normalizeDelivery(delivery, dispatches, deliveryIndex),
+		);
+		return { ...(record as unknown as ReviewSourceCohort), dispatches, deliveries };
+	});
+	const cohortIds = new Set<string>();
+	const dispatchIds = new Set<string>();
+	const deliveryIds = new Set<string>();
+	let activeCount = 0;
+	for (const cohort of cohorts) {
+		if (cohortIds.has(cohort.cohortId))
+			throw new Error(`Invalid ultragoal plan: duplicate cohortId ${cohort.cohortId}`);
+		cohortIds.add(cohort.cohortId);
+		if (cohort.status === "active") activeCount++;
+		const laneSet = new Set<ReviewSourceLane>();
+		const deliveredDispatches = new Set<string>();
+
+		for (const dispatch of cohort.dispatches) {
+			if (dispatchIds.has(dispatch.dispatchId))
+				throw new Error(`Invalid ultragoal plan: duplicate dispatchId ${dispatch.dispatchId}`);
+			dispatchIds.add(dispatch.dispatchId);
+			if (laneSet.has(dispatch.lane))
+				throw new Error(`Invalid ultragoal plan: duplicate lane dispatch ${dispatch.lane}`);
+			laneSet.add(dispatch.lane);
+		}
+		for (const delivery of cohort.deliveries) {
+			if (deliveryIds.has(delivery.deliveryId))
+				throw new Error(`Invalid ultragoal plan: duplicate deliveryId ${delivery.deliveryId}`);
+			deliveryIds.add(delivery.deliveryId);
+			if (deliveredDispatches.has(delivery.dispatchId)) {
+				throw new Error(`Invalid ultragoal plan: duplicate delivery for dispatch ${delivery.dispatchId}`);
+			}
+			deliveredDispatches.add(delivery.dispatchId);
+		}
+	}
+	if (activeCount > 1) throw new Error("Invalid ultragoal plan: multiple active review cohorts");
+	return cohorts;
+}
+
+export async function reconcileReviewSourceDelivery(input: {
+	cwd: string;
+	repositoryBinding: RepositoryBinding;
+	reviewSource: {
+		schema: "gjc.review_source_dispatch.v1";
+		cohortId: string;
+		generation: number;
+		lane: ReviewSourceLane;
+		snapshotId: string;
+		repositoryBindingDigest: string;
+		stateRevision: number;
+		dispatchId: string;
+		rerunCommand: string;
+	};
+}): Promise<{
+	disposition: ReviewDeliveryDisposition;
+	currentSnapshotId?: string;
+}> {
+	const current = await captureReviewSourceSnapshot(input.cwd, input.repositoryBinding);
+	if (current.repositoryBindingDigest !== input.reviewSource.repositoryBindingDigest) {
+		return { disposition: "invalid_provenance", currentSnapshotId: current.snapshotId };
+	}
+	if (current.snapshotId !== input.reviewSource.snapshotId) {
+		return { disposition: "stale_review_delivery", currentSnapshotId: current.snapshotId };
+	}
+	return { disposition: "current", currentSnapshotId: current.snapshotId };
+}