@viccydev/pi-fpa 0.5.0 → 0.6.0

package/extensions/fpa-dashboard/provenance.ts

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export const DASHBOARD_CONTRACT_VERSION = 1;
+
+const PRESET_VERSIONS = {
+	"forecast-closed-loop-v1": 1,
+} as const;
+
+const PROJECTOR_SOURCE_FILES = [
+	"extensions/fpa-artifacts/contracts.ts",
+	"extensions/fpa-artifacts/store.ts",
+	"extensions/fpa-dashboard/actuals.ts",
+	"extensions/fpa-dashboard/cycle-operating-projection.ts",
+	"extensions/fpa-dashboard/forward-outlook.ts",
+	"extensions/fpa-dashboard/forecast-accuracy.ts",
+	"extensions/fpa-dashboard/coordinator.ts",
+	"extensions/fpa-dashboard/index.ts",
+	"extensions/fpa-dashboard/projector.ts",
+	"extensions/fpa-dashboard/provenance.ts",
+	"extensions/fpa-dashboard/publisher.ts",
+	"extensions/fpa-dashboard/schema.ts",
+	"extensions/fpa-dashboard/service.ts",
+	"extensions/fpa-dashboard/source.ts",
+	"extensions/fpa-data/calc.ts",
+	"extensions/fpa-data/registry.ts",
+	"extensions/fpa-data/runtime.ts",
+	"extensions/fpa-data/sql.ts",
+	"extensions/fpa-data/supabase.ts",
+] as const;
+
+export interface DashboardProjectorProvenance {
+	package_name: "@viccydev/pi-fpa";
+	package_version: string;
+	code_sha256: string;
+	dashboard_contract_version: number;
+	preset_id: keyof typeof PRESET_VERSIONS;
+	preset_version: number;
+}
+
+export interface DashboardProjectorRuntime {
+	package_realpath_sha256: string;
+}
+
+export interface LoadedProjectorProvenance {
+	projector: DashboardProjectorProvenance;
+	runtime: DashboardProjectorRuntime;
+}
+
+interface BaseProjectorProvenance {
+	package_name: "@viccydev/pi-fpa";
+	package_version: string;
+	code_sha256: string;
+	dashboard_contract_version: number;
+	runtime: DashboardProjectorRuntime;
+}
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+
+function sha256(value: string | Uint8Array): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function record(value: unknown, path: string): Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object.`);
+	return value as Record<string, unknown>;
+}
+
+function requiredString(value: unknown, path: string): string {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
+	return value;
+}
+
+function requiredSha256(value: unknown, path: string): string {
+	const parsed = requiredString(value, path);
+	if (!SHA256_RE.test(parsed)) throw new Error(`${path} must be a SHA-256 digest.`);
+	return parsed;
+}
+
+export function validateProjectorProvenance(value: unknown): DashboardProjectorProvenance {
+	const source = record(value, "projector");
+	const packageName = requiredString(source.package_name, "projector.package_name");
+	if (packageName !== "@viccydev/pi-fpa") throw new Error("projector.package_name is unsupported.");
+	const presetId = requiredString(source.preset_id, "projector.preset_id");
+	if (!(presetId in PRESET_VERSIONS)) throw new Error("projector.preset_id is unsupported.");
+	const contractVersion = source.dashboard_contract_version;
+	if (contractVersion !== DASHBOARD_CONTRACT_VERSION) throw new Error(`projector.dashboard_contract_version must be ${DASHBOARD_CONTRACT_VERSION}.`);
+	const presetVersion = source.preset_version;
+	if (!Number.isInteger(presetVersion) || presetVersion !== PRESET_VERSIONS[presetId as keyof typeof PRESET_VERSIONS]) {
+		throw new Error("projector.preset_version does not match projector.preset_id.");
+	}
+	return {
+		package_name: "@viccydev/pi-fpa",
+		package_version: requiredString(source.package_version, "projector.package_version"),
+		code_sha256: requiredSha256(source.code_sha256, "projector.code_sha256"),
+		dashboard_contract_version: contractVersion as number,
+		preset_id: presetId as keyof typeof PRESET_VERSIONS,
+		preset_version: presetVersion as number,
+	};
+}
+
+export function validateProjectorRuntime(value: unknown): DashboardProjectorRuntime {
+	const source = record(value, "runtime");
+	return {
+		package_realpath_sha256: requiredSha256(source.package_realpath_sha256, "runtime.package_realpath_sha256"),
+	};
+}
+
+async function loadBaseProjectorProvenance(): Promise<BaseProjectorProvenance> {
+	const packageRoot = await realpath(fileURLToPath(new URL("../../", import.meta.url)));
+	const packageJson = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8")) as Record<string, unknown>;
+	if (packageJson.name !== "@viccydev/pi-fpa" || typeof packageJson.version !== "string" || packageJson.version.trim() === "") {
+		throw new Error("Could not identify the installed @viccydev/pi-fpa package.");
+	}
+	const codeHash = createHash("sha256");
+	for (const relativePath of PROJECTOR_SOURCE_FILES) {
+		const contents = await readFile(new URL(`../../${relativePath}`, import.meta.url));
+		codeHash.update(relativePath);
+		codeHash.update("\0");
+		codeHash.update(contents);
+		codeHash.update("\0");
+	}
+	return {
+		package_name: "@viccydev/pi-fpa",
+		package_version: packageJson.version,
+		code_sha256: codeHash.digest("hex"),
+		dashboard_contract_version: DASHBOARD_CONTRACT_VERSION,
+		runtime: { package_realpath_sha256: sha256(packageRoot) },
+	};
+}
+
+export async function loadProjectorProvenance(presetId: string): Promise<LoadedProjectorProvenance> {
+	if (!(presetId in PRESET_VERSIONS)) throw new Error(`Unsupported dashboard preset "${presetId}".`);
+	const base = await loadBaseProjectorProvenance();
+	return {
+		projector: {
+			package_name: base.package_name,
+			package_version: base.package_version,
+			code_sha256: base.code_sha256,
+			dashboard_contract_version: base.dashboard_contract_version,
+			preset_id: presetId as keyof typeof PRESET_VERSIONS,
+			preset_version: PRESET_VERSIONS[presetId as keyof typeof PRESET_VERSIONS],
+		},
+		runtime: base.runtime,
+	};
+}

package/extensions/fpa-dashboard/publisher.ts

@@ -1,17 +1,27 @@
 import { createHash, randomUUID } from "node:crypto";
-import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { link, lstat, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 
 import { stableJson } from "../fpa-artifacts/store.ts";
 import type { DashboardBuild, DashboardWidget } from "./projector.ts";
+import {
+	validateProjectorProvenance,
+	validateProjectorRuntime,
+	type DashboardProjectorProvenance,
+	type DashboardProjectorRuntime,
+} from "./provenance.ts";
 import { validateDatasetForWidget } from "./schema.ts";
+import { validateActualsSnapshot, type DashboardActualsSnapshot } from "./source.ts";
 
-const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}\.json$/;
+const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,191}\.json$/;
 
 export interface PublishDashboardOptions {
 	cwd: string;
 	build: DashboardBuild;
+	projector: DashboardProjectorProvenance;
+	runtime: DashboardProjectorRuntime;
 	publishedAt?: string;
+	actualsSnapshot?: DashboardActualsSnapshot;
 }
 
 export interface PublishDashboardResult {
@@ -59,7 +69,7 @@ function contentAddressDataset(widget: DashboardWidget): PublishedDataset {
 	const contents = `${JSON.stringify(widget.data, null, 2)}\n`;
 	const digest = sha256(stableJson(widget.data));
 	const logicalBase = widget.dataset.slice(0, -".json".length);
-	const filename = `${logicalBase}.${digest.slice(0, 12)}.json`;
+	const filename = `${logicalBase}.${digest}.json`;
 	if (!DATASET_FILE_RE.test(filename)) {
 		throw new Error(`Content-addressed dataset name "${filename}" exceeds the dashboard contract.`);
 	}
@@ -102,33 +112,93 @@ async function atomicWrite(destination: string, contents: string): Promise<void>
 	}
 }
 
+async function appendOnlyWrite(directory: string, destination: string, contents: string, verifyExisting = true): Promise<void> {
+	const temporary = join(directory, `.${basename(destination)}.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	try {
+		await link(temporary, destination);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		if (verifyExisting && await readFile(destination, "utf8") !== contents) throw new Error(`Append-only dashboard object ${basename(destination)} already exists with different content.`);
+	} finally {
+		await unlink(temporary).catch(() => undefined);
+	}
+}
+
 export async function resolveDashboardDir(cwd: string): Promise<string> {
 	const projectRoot = await realpath(cwd);
 	return join(dirname(projectRoot), ".fpa-dashboard");
 }
 
-export function dashboardBuildFingerprint(build: DashboardBuild): string {
+function generationSource(source: DashboardBuild["source"]): Record<string, unknown> {
+	const {
+		actuals_snapshot_ref: _actualsSnapshotRef,
+		actuals_snapshot_evidence: evidence,
+		...stableSource
+	} = source;
+	const stableEvidence = evidence ? Object.fromEntries(Object.entries({
+		consistency: evidence.consistency,
+		source_close_signal_id: evidence.source_close_signal_id,
+		source_closed_through: evidence.source_closed_through,
+		source_close_emitted_at: evidence.source_close_emitted_at,
+		source_close_signal_sha256: evidence.source_close_signal_sha256,
+		period_complete: evidence.period_complete,
+		reconciled: evidence.reconciled,
+	}).filter(([, value]) => value !== undefined)) : undefined;
+	return {
+		...stableSource,
+		...(stableEvidence ? { actuals_snapshot_evidence: stableEvidence } : {}),
+	};
+}
+
+export function dashboardBuildFingerprint(build: DashboardBuild, projector: DashboardProjectorProvenance): string {
 	assertBuild(build);
+	const validatedProjector = validateProjectorProvenance(projector);
 	return sha256(stableJson({
 		title: build.title,
 		widgets: build.widgets,
-		source: build.source,
+		// Observation metadata proves when/how a query ran, but it is not business
+		// content. Keep it in the receipt while excluding it from generation identity
+		// so preview and publish of unchanged Actuals remain byte-stable.
+		source: generationSource(build.source),
 		warnings: build.warnings,
+		...(build.operating_projection ? { operating_projection: build.operating_projection } : {}),
+		...(build.forward_outlook ? { forward_outlook: build.forward_outlook } : {}),
+		...(build.forecast_accuracy ? { forecast_accuracy: build.forecast_accuracy } : {}),
+		projector: validatedProjector,
 	}));
 }
 
 export async function publishDashboard(options: PublishDashboardOptions): Promise<PublishDashboardResult> {
 	assertBuild(options.build);
+	const projector = validateProjectorProvenance(options.projector);
+	const runtime = validateProjectorRuntime(options.runtime);
 	const dashboardDir = await resolveDashboardDir(options.cwd);
 	await ensureOwnedDirectory(dashboardDir, "Dashboard directory");
 	const datasetsDir = join(dashboardDir, "datasets");
 	await ensureOwnedDirectory(datasetsDir, "Dashboard datasets directory");
+	const generationsDir = join(dashboardDir, "generations");
+	await ensureOwnedDirectory(generationsDir, "Dashboard generations directory");
+	if (options.actualsSnapshot) {
+		const actuals = validateActualsSnapshot(options.actualsSnapshot);
+		const actualsDigest = sha256(stableJson(actuals));
+		if (options.build.source.actuals_snapshot_ref !== actualsDigest) throw new Error("Dashboard Actuals snapshot ref does not match the supplied immutable snapshot.");
+		const actualsDir = join(dashboardDir, "actuals");
+		await ensureOwnedDirectory(actualsDir, "Dashboard Actuals snapshot directory");
+		await appendOnlyWrite(actualsDir, join(actualsDir, `${actualsDigest}.json`), `${JSON.stringify(actuals, null, 2)}\n`);
+	}
 
 	const publishedAt = options.publishedAt ?? new Date().toISOString();
-	const fingerprint = dashboardBuildFingerprint(options.build);
+	const fingerprint = dashboardBuildFingerprint(options.build, projector);
 	const datasets = options.build.widgets.map(contentAddressDataset);
 	for (const dataset of datasets) {
-		await atomicWrite(join(datasetsDir, dataset.filename), dataset.contents);
+		await appendOnlyWrite(datasetsDir, join(datasetsDir, dataset.filename), dataset.contents);
 	}
 
 	const receipt = {
@@ -138,12 +208,17 @@ export async function publishDashboard(options: PublishDashboardOptions): Promis
 		published_at: publishedAt,
 		source: options.build.source,
 		warnings: options.build.warnings,
+		...(options.build.operating_projection ? { operating_projection: options.build.operating_projection } : {}),
+		...(options.build.forward_outlook ? { forward_outlook: options.build.forward_outlook } : {}),
+		...(options.build.forecast_accuracy ? { forecast_accuracy: options.build.forecast_accuracy } : {}),
+		projector,
+		runtime,
 		datasets: datasets.map(({ logical, filename, sha256 }) => ({ logical, filename, sha256 })),
 	};
 	const receiptContents = `${JSON.stringify(receipt, null, 2)}\n`;
 	const receiptDigest = sha256(stableJson(receipt));
-	const receiptFilename = `build-receipt.${fingerprint.slice(0, 12)}.${receiptDigest.slice(0, 12)}.json`;
-	await atomicWrite(join(dashboardDir, receiptFilename), receiptContents);
+	const receiptFilename = `build-receipt.${fingerprint}.${receiptDigest}.json`;
+	await appendOnlyWrite(dashboardDir, join(dashboardDir, receiptFilename), receiptContents);
 	// Compatibility pointer for older diagnostics. The manifest below points to
 	// the generation-specific receipt, so concurrent publishers cannot mix lineage.
 	await atomicWrite(join(dashboardDir, "build-receipt.json"), receiptContents);
@@ -163,6 +238,21 @@ export async function publishDashboard(options: PublishDashboardOptions): Promis
 			dataset: byLogical.get(widget.dataset),
 		})),
 	};
+	const generationRecord = {
+		kind: "fpa.dashboard.generation",
+		schema_version: 1,
+		generation_id: fingerprint,
+		published_at: publishedAt,
+		title: options.build.title,
+		build_receipt: receiptFilename,
+		source: options.build.source,
+		warnings: options.build.warnings,
+		projector,
+		widgets: manifest.widgets,
+	};
+	// One immutable catalog entry per content generation. Re-publishing the same
+	// deterministic generation never rewrites its historical identity.
+	await appendOnlyWrite(generationsDir, join(generationsDir, `${fingerprint}.json`), `${JSON.stringify(generationRecord, null, 2)}\n`, false);
 	// This is the commit point: every referenced dataset and receipt is
 	// generation-specific, so concurrent publishers remain atomic without locks.
 	await atomicWrite(join(dashboardDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);

package/extensions/fpa-dashboard/service.ts

@@ -0,0 +1,179 @@
+import {
+	readArtifactByRef,
+	readCommittedArtifact,
+	readOptionalCommittedArtifact,
+	type ArtifactRefV2,
+	type ReadArtifactResult,
+} from "../fpa-artifacts/store.ts";
+import { realpath } from "node:fs/promises";
+import { basename } from "node:path";
+import {
+	isExecutionReceiptForForecast,
+	sliceKey,
+	type ApprovedCycleForecast,
+	type ApprovedCycleForecastInput,
+	type CanonicalArtifact,
+	type ExecutionReceipt,
+	type ExecutionReceiptInput,
+} from "../fpa-artifacts/contracts.ts";
+import { dashboardActualsSnapshotFingerprint, dashboardActualsWatermark, detectSliceKeyMismatch, loadDashboardActuals } from "./actuals.ts";
+import type { DashboardActualsSnapshot } from "./source.ts";
+import { projectCycleDecisionWidgets, projectCycleOperatingProjection } from "./cycle-operating-projection.ts";
+import { projectDashboard, type DashboardBuild } from "./projector.ts";
+import { projectForwardOutlook, projectForwardOutlookWidgets } from "./forward-outlook.ts";
+import { loadHistoricalOperatingProjections, projectForecastAccuracy, projectForecastAccuracyWidgets } from "./forecast-accuracy.ts";
+import {
+	loadProjectorProvenance,
+	type DashboardProjectorProvenance,
+	type DashboardProjectorRuntime,
+} from "./provenance.ts";
+
+export interface ExactDashboardInputs {
+	scopeId: string;
+	cycleId: string;
+	forecastRef: ArtifactRefV2;
+	executionRef?: ArtifactRefV2;
+	nextForecastRef?: ArtifactRefV2;
+	forwardForecastRefs?: ArtifactRefV2[];
+}
+
+export interface DashboardProjectionResult {
+	build: DashboardBuild;
+	forecast: ApprovedCycleForecast;
+	forecastRead: ReadArtifactResult;
+	executionRead: ReadArtifactResult | null;
+	sliceKeyMismatch: string | null;
+	projector: DashboardProjectorProvenance;
+	runtime: DashboardProjectorRuntime;
+	actuals: DashboardActualsSnapshot;
+}
+
+function withoutFingerprint<T extends CanonicalArtifact>(artifact: T): Omit<T, "immutable_fingerprint"> {
+	const { immutable_fingerprint: _fingerprint, ...input } = artifact;
+	return input;
+}
+
+/**
+ * The single business projection entry point used by the interactive tool and
+ * the durable coordinator. Hosts may schedule it, but never reproduce its FP&A
+ * calculations or write dashboard files themselves.
+ */
+export async function buildDashboardProjection(
+	cwd: string,
+	preset: string,
+	locale: string,
+	exact?: ExactDashboardInputs,
+	signal?: AbortSignal,
+): Promise<DashboardProjectionResult> {
+	const [forecastRead, provenance, projectRoot] = await Promise.all([
+		exact ? readArtifactByRef(cwd, exact.forecastRef) : readCommittedArtifact(cwd, "approved_cycle_forecast"),
+		loadProjectorProvenance(preset),
+		realpath(cwd),
+	]);
+	if (forecastRead.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("Committed approved forecast has the wrong artifact type.");
+	if (exact && (exact.forecastRef.scope_id !== exact.scopeId || exact.forecastRef.cycle_id !== exact.cycleId || exact.forecastRef.artifact_type !== "approved_cycle_forecast")) {
+		throw new Error("forecast_ref must identify an approved forecast in the requested scope_id and cycle_id.");
+	}
+	const forecast = forecastRead.artifact as ApprovedCycleForecast;
+	const forwardRefs = exact?.forwardForecastRefs ?? (exact?.nextForecastRef ? [exact.nextForecastRef] : []);
+	if (forwardRefs.length > 6) throw new Error("forwardForecastRefs must contain at most six forecasts.");
+	if (exact?.nextForecastRef && forwardRefs.length > 0 && forwardRefs[0].entry_id !== exact.nextForecastRef.entry_id) {
+		throw new Error("nextForecastRef must equal the first forwardForecastRefs entry.");
+	}
+	const forwardForecastReads = await Promise.all(forwardRefs.map((ref) => readArtifactByRef(cwd, ref)));
+	const nextForecastRead = forwardForecastReads[0] ?? null;
+	if (exact?.nextForecastRef && (exact.nextForecastRef.scope_id !== exact.scopeId || exact.nextForecastRef.artifact_type !== "approved_cycle_forecast")) {
+		throw new Error("next_forecast_ref must identify an approved forecast in the requested scope_id.");
+	}
+	if (nextForecastRead && nextForecastRead.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("next_forecast_ref resolved to the wrong artifact type.");
+	const committedExecutionRead = exact
+		? exact.executionRef ? await readArtifactByRef(cwd, exact.executionRef) : null
+		: await readOptionalCommittedArtifact(cwd, "execution_receipt");
+	if (exact?.executionRef && (exact.executionRef.scope_id !== exact.scopeId || exact.executionRef.cycle_id !== exact.cycleId || exact.executionRef.artifact_type !== "execution_receipt")) {
+		throw new Error("execution_ref must identify an execution receipt in the requested scope_id and cycle_id.");
+	}
+	const executionRead = committedExecutionRead?.artifact.artifact_type === "execution_receipt" && isExecutionReceiptForForecast(committedExecutionRead.artifact, forecast)
+		? committedExecutionRead
+		: null;
+	const execution = executionRead?.artifact.artifact_type === "execution_receipt"
+		? executionRead.artifact as ExecutionReceipt
+		: null;
+	const actuals = await loadDashboardActuals(forecast.target_period, { slices: forecast.approved_allocation }, signal);
+	const build = projectDashboard({
+		forecast: withoutFingerprint(forecast) as ApprovedCycleForecastInput,
+		actuals,
+		...(execution ? { execution: withoutFingerprint(execution) as ExecutionReceiptInput } : {}),
+		locale,
+	});
+	build.source.project_name = basename(projectRoot);
+	build.source.actuals_watermark = dashboardActualsWatermark(actuals);
+	build.source.actuals_snapshot_ref = dashboardActualsSnapshotFingerprint(actuals);
+	build.source.forecast_fingerprint = forecastRead.fingerprint;
+	if (executionRead) build.source.execution_fingerprint = executionRead.fingerprint;
+	if (exact) {
+		build.source.scope_id = exact.scopeId;
+		build.source.cycle_id = exact.cycleId;
+		build.source.forecast_ref = exact.forecastRef.entry_id;
+		if (forecastRead.ledgerContext?.forecast_role) build.source.forecast_role = forecastRead.ledgerContext.forecast_role;
+		build.source.actuals_snapshot_evidence = actuals.snapshot_evidence;
+		if (exact.executionRef) build.source.execution_ref = exact.executionRef.entry_id;
+		if (forwardRefs[0]) {
+			build.source.next_forecast_ref = forwardRefs[0].entry_id;
+			build.source.next_forecast_fingerprint = forwardRefs[0].body_fingerprint;
+		}
+		if (forwardRefs.length > 0) {
+			for (const [index, ref] of forwardRefs.entries()) {
+				if (ref.scope_id !== exact.scopeId || ref.artifact_type !== "approved_cycle_forecast") throw new Error(`forwardForecastRefs[${index}] must be an approved forecast in the requested scope.`);
+			}
+			build.source.forward_forecast_refs = forwardRefs.map((ref) => ref.entry_id);
+			build.source.forward_forecast_fingerprints = forwardRefs.map((ref) => ref.body_fingerprint);
+		}
+		build.operating_projection = projectCycleOperatingProjection({
+			scope_id: exact.scopeId,
+			cycle_id: exact.cycleId,
+			current_forecast: withoutFingerprint(forecast),
+			current_forecast_role: forecastRead.ledgerContext?.forecast_role,
+			actuals,
+			...(execution ? { execution: withoutFingerprint(execution) } : {}),
+			...(nextForecastRead?.artifact.artifact_type === "approved_cycle_forecast"
+				? {
+					next_forecast: withoutFingerprint(nextForecastRead.artifact),
+					next_forecast_role: nextForecastRead.ledgerContext?.forecast_role,
+				}
+				: {}),
+		});
+		const baseWidgets = build.widgets;
+		const decisionWidgets = projectCycleDecisionWidgets(build.operating_projection, locale);
+		build.warnings.push(...build.operating_projection.warnings);
+		build.forward_outlook = projectForwardOutlook({
+			current_forecast: withoutFingerprint(forecast),
+			forward_forecasts: forwardForecastReads.map((read, index) => ({ ref: forwardRefs[index], forecast: withoutFingerprint(read.artifact) })),
+		});
+		build.forecast_accuracy = projectForecastAccuracy([
+			...await loadHistoricalOperatingProjections(cwd, exact.scopeId),
+			build.operating_projection,
+		]);
+		build.widgets = [
+			...decisionWidgets,
+			...projectForwardOutlookWidgets(build.forward_outlook, locale),
+			...projectForecastAccuracyWidgets(build.forecast_accuracy, locale),
+			...baseWidgets,
+		];
+		build.warnings.push(...build.forward_outlook.warnings);
+		build.warnings.push(...build.forecast_accuracy.warnings);
+	}
+
+	const plannedKeys = new Set(forecast.approved_allocation.map(sliceKey));
+	const actualKeys = new Set(actuals.slices.map(sliceKey));
+	const unplanned = actuals.slices.filter((slice) => !plannedKeys.has(sliceKey(slice)) && ((slice.spend ?? 0) > 0 || (slice.revenue ?? 0) !== 0));
+	const missing = forecast.approved_allocation.filter((slice) => !actualKeys.has(sliceKey(slice)));
+	if (unplanned.length > 0) build.warnings.push(`${unplanned.length} paid Actuals slices are outside the approved allocation and were excluded from like-for-like forecast totals and the strategy table.`);
+	if (missing.length > 0) build.warnings.push(`${missing.length} approved slices have no current-period Actuals row; their values remain null.`);
+	if (committedExecutionRead && !executionRead) build.warnings.push(`Ignored stale execution receipt for forecast ${committedExecutionRead.artifact.forecast_version}; current forecast is ${forecast.forecast_version}.`);
+	if (actuals.query_receipts.some((receipt) => receipt.dataset === "ua_spend.slices.discovery" && receipt.row_count >= 1000)) build.warnings.push("Unplanned-slice discovery reached its 1000-row safety limit; approved slices and like-for-like totals remain complete, but additional warnings may be omitted.");
+	if (actuals.data_as_of === "unavailable") build.warnings.push("No current-period UA Actuals are available.");
+
+	const sliceKeyMismatch = detectSliceKeyMismatch(forecast.approved_allocation, actuals);
+	if (sliceKeyMismatch) build.warnings.push(sliceKeyMismatch);
+	return { build, forecast, forecastRead, executionRead, actuals, sliceKeyMismatch, ...provenance };
+}

package/extensions/fpa-dashboard/source.ts

@@ -1,4 +1,7 @@
+import { createHash } from "node:crypto";
+
 import { sliceKey, type Period } from "../fpa-artifacts/contracts.ts";
+import { stableJson } from "../fpa-artifacts/store.ts";
 
 export interface QueryReceipt {
 	dataset: string;
@@ -18,6 +21,27 @@ export interface DashboardActualSlice {
 /** Sentinel used when no Actuals row exists yet, so no calendar date can be reported. */
 export const ACTUALS_DATA_AS_OF_UNAVAILABLE = "unavailable";
 
+function canonicalCalendarDate(value: string, label: string): string {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) throw new Error(`${label} must use YYYY-MM-DD.`);
+	const parsed = new Date(`${value}T00:00:00Z`);
+	if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== value) {
+		throw new Error(`${label} must be a real canonical calendar date.`);
+	}
+	return value;
+}
+
+function finalPeriodDate(value: Period): string {
+	const finalInstant = new Date(Date.parse(value.end_exclusive) - 1);
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone: value.timezone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).formatToParts(finalInstant);
+	const byType = new Map(parts.map((part) => [part.type, part.value]));
+	return `${byType.get("year")}-${byType.get("month")}-${byType.get("day")}`;
+}
+
 /**
  * How Actuals were scoped against the frozen forecast.
  *
@@ -37,6 +61,18 @@ export interface DashboardDailyPoint {
 export interface DashboardActualsSnapshot {
 	period: Period;
 	data_as_of: string;
+	snapshot_evidence: {
+		snapshot_id: string | null;
+		available_at: string | null;
+		consistency: "single_statement" | "multi_query_unverified" | "legacy_unverified";
+		/** Explicit close signal emitted by the source ETL; time elapsed is never treated as closure. */
+		source_close_signal_id: string | null;
+		source_closed_through: string | null;
+		source_close_emitted_at: string | null;
+		source_close_signal_sha256: string | null;
+		period_complete: boolean;
+		reconciled: boolean;
+	};
 	reporting_currency: string;
 	scope_mode: DashboardScopeMode;
 	/**
@@ -112,10 +148,12 @@ function period(value: unknown, path: string): Period {
 
 export function validateActualsSnapshot(value: unknown): DashboardActualsSnapshot {
 	const source = record(value, "actuals");
+	const snapshotPeriod = period(source.period, "actuals.period");
 	const coverage = record(source.coverage, "actuals.coverage");
 	const dailySource = source.daily;
 	const slicesSource = source.slices;
 	const receiptsSource = source.query_receipts;
+	const evidenceSource = source.snapshot_evidence === undefined ? null : record(source.snapshot_evidence, "actuals.snapshot_evidence");
 	if (!Array.isArray(dailySource)) throw new Error("actuals.daily must be an array.");
 	if (!Array.isArray(slicesSource)) throw new Error("actuals.slices must be an array.");
 	if (!Array.isArray(receiptsSource)) throw new Error("actuals.query_receipts must be an array.");
@@ -158,9 +196,88 @@ export function validateActualsSnapshot(value: unknown): DashboardActualsSnapsho
 	if (source.period_has_unscoped_actuals !== undefined && typeof source.period_has_unscoped_actuals !== "boolean") {
 		throw new Error("actuals.period_has_unscoped_actuals must be a boolean.");
 	}
+	let snapshotEvidence: DashboardActualsSnapshot["snapshot_evidence"] = {
+		snapshot_id: null,
+		available_at: null,
+		consistency: "legacy_unverified",
+		source_close_signal_id: null,
+		source_closed_through: null,
+		source_close_emitted_at: null,
+		source_close_signal_sha256: null,
+		period_complete: false,
+		reconciled: false,
+	};
+	if (evidenceSource) {
+		const consistency = string(evidenceSource.consistency, "actuals.snapshot_evidence.consistency");
+		if (consistency !== "single_statement" && consistency !== "multi_query_unverified" && consistency !== "legacy_unverified") {
+			throw new Error("actuals.snapshot_evidence.consistency is unsupported.");
+		}
+		if (evidenceSource.snapshot_id !== null && typeof evidenceSource.snapshot_id !== "string") throw new Error("actuals.snapshot_evidence.snapshot_id must be a string or null.");
+		if (evidenceSource.available_at !== null && (typeof evidenceSource.available_at !== "string" || Number.isNaN(Date.parse(evidenceSource.available_at)))) {
+			throw new Error("actuals.snapshot_evidence.available_at must be an ISO timestamp or null.");
+		}
+		if (typeof evidenceSource.period_complete !== "boolean" || typeof evidenceSource.reconciled !== "boolean") {
+			throw new Error("actuals.snapshot_evidence period_complete and reconciled must be booleans.");
+		}
+		const sourceCloseSignalId = evidenceSource.source_close_signal_id === undefined || evidenceSource.source_close_signal_id === null
+			? null
+			: string(evidenceSource.source_close_signal_id, "actuals.snapshot_evidence.source_close_signal_id");
+		const sourceClosedThrough = evidenceSource.source_closed_through === undefined || evidenceSource.source_closed_through === null
+			? null
+			: string(evidenceSource.source_closed_through, "actuals.snapshot_evidence.source_closed_through");
+		if (sourceClosedThrough !== null) canonicalCalendarDate(sourceClosedThrough, "actuals.snapshot_evidence.source_closed_through");
+		const sourceCloseEmittedAt = evidenceSource.source_close_emitted_at === undefined || evidenceSource.source_close_emitted_at === null
+			? null
+			: string(evidenceSource.source_close_emitted_at, "actuals.snapshot_evidence.source_close_emitted_at");
+		if (sourceCloseEmittedAt !== null && (Number.isNaN(Date.parse(sourceCloseEmittedAt)) || new Date(sourceCloseEmittedAt).toISOString() !== sourceCloseEmittedAt)) {
+			throw new Error("actuals.snapshot_evidence.source_close_emitted_at must be a canonical ISO timestamp or null.");
+		}
+		const sourceCloseSignalSha256 = evidenceSource.source_close_signal_sha256 === undefined || evidenceSource.source_close_signal_sha256 === null
+			? null
+			: string(evidenceSource.source_close_signal_sha256, "actuals.snapshot_evidence.source_close_signal_sha256");
+		if (sourceCloseSignalSha256 !== null && !/^[a-f0-9]{64}$/.test(sourceCloseSignalSha256)) throw new Error("actuals.snapshot_evidence.source_close_signal_sha256 must be a SHA-256 digest or null.");
+		const closeTuple = [sourceCloseSignalId, sourceClosedThrough, sourceCloseEmittedAt, sourceCloseSignalSha256];
+		if (closeTuple.some((item) => item !== null) && closeTuple.some((item) => item === null)) {
+			throw new Error("actuals.snapshot_evidence source close evidence must be entirely present or entirely null.");
+		}
+		if (sourceCloseSignalId && sourceClosedThrough && sourceCloseEmittedAt && sourceCloseSignalSha256) {
+			const expectedDigest = createHash("sha256").update(stableJson({
+				kind: "fpa.actuals.source-close",
+				schema_version: 1,
+				dataset: "ua_spend",
+				signal_id: sourceCloseSignalId,
+				closed_through: sourceClosedThrough,
+				emitted_at: sourceCloseEmittedAt,
+			})).digest("hex");
+			if (sourceCloseSignalSha256 !== expectedDigest) throw new Error("actuals.snapshot_evidence source close digest does not match its canonical evidence.");
+		}
+		if (evidenceSource.period_complete && (!sourceCloseSignalId || !sourceClosedThrough || !sourceCloseEmittedAt || !sourceCloseSignalSha256)) {
+			throw new Error("period_complete requires complete explicit source close evidence.");
+		}
+		if (evidenceSource.period_complete && (
+			consistency !== "single_statement"
+			|| evidenceSource.available_at === null
+			|| (sourceClosedThrough as string) < finalPeriodDate(snapshotPeriod)
+			|| Date.parse(evidenceSource.available_at as string) < Date.parse(sourceCloseEmittedAt as string)
+		)) {
+			throw new Error("period_complete requires single-statement evidence observed after a source close signal covering the target period.");
+		}
+		snapshotEvidence = {
+			snapshot_id: evidenceSource.snapshot_id as string | null,
+			available_at: evidenceSource.available_at as string | null,
+			consistency,
+			source_close_signal_id: sourceCloseSignalId,
+			source_closed_through: sourceClosedThrough,
+			source_close_emitted_at: sourceCloseEmittedAt,
+			source_close_signal_sha256: sourceCloseSignalSha256,
+			period_complete: evidenceSource.period_complete,
+			reconciled: evidenceSource.reconciled,
+		};
+	}
 	return {
-		period: period(source.period, "actuals.period"),
+		period: snapshotPeriod,
 		data_as_of: string(source.data_as_of, "actuals.data_as_of"),
+		snapshot_evidence: snapshotEvidence,
 		reporting_currency: reportingCurrency,
 		scope_mode: scopeMode,
 		// Absent means the probe was never run, which is only ever the benign