@viccydev/pi-fpa 0.4.1 → 0.6.0

package/extensions/fpa-dashboard/forecast-accuracy.ts

@@ -0,0 +1,252 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+
+import { stableJson } from "../fpa-artifacts/store.ts";
+import type { CycleOperatingProjection } from "./cycle-operating-projection.ts";
+import type { DashboardWidget } from "./projector.ts";
+import { resolveDashboardDir } from "./publisher.ts";
+import { validateActualsSnapshot, type DashboardActualsSnapshot } from "./source.ts";
+
+const MAX_FILE_BYTES = 256 * 1024;
+const GENERATION_RE = /^[a-f0-9]{64}\.json$/;
+const RECEIPT_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}\.json$/;
+
+export interface ForecastAccuracyProjection {
+	kind: "fpa.forecast-accuracy";
+	schema_version: 1;
+	status: "available" | "insufficient_history";
+	sample_size: number;
+	mean_absolute_percentage_error: number | null;
+	mean_percentage_bias: number | null;
+	mean_absolute_error: number | null;
+	weighted_absolute_percentage_error: number | null;
+	mean_absolute_scaled_error: number | null;
+	cycles: Array<{
+		cycle_id: string;
+		forecast_version: string;
+		data_as_of: string;
+		forecast_revenue: number;
+		actual_revenue: number;
+		revenue_delta: number;
+		revenue_delta_pct: number;
+	}>;
+	warnings: string[];
+}
+
+function round(value: number): number {
+	return Math.round(value * 1_000_000) / 1_000_000;
+}
+
+function closedCycle(projection: CycleOperatingProjection): ForecastAccuracyProjection["cycles"][number] | null {
+	if (!projection || typeof projection !== "object") return null;
+	const current = projection.current_cycle;
+	if (!current || typeof current !== "object") return null;
+	const variance = current.variance;
+	const forecast = current.forecast?.revenue?.base;
+	const actual = current.actual_to_date?.revenue;
+	if (
+		variance?.status !== "closed_comparable"
+		|| typeof forecast !== "number"
+		|| !Number.isFinite(forecast)
+		|| typeof actual !== "number"
+		|| !Number.isFinite(actual)
+		|| typeof variance.revenue_delta !== "number"
+		|| !Number.isFinite(variance.revenue_delta)
+		|| typeof variance.revenue_delta_pct !== "number"
+		|| !Number.isFinite(variance.revenue_delta_pct)
+		|| typeof projection.cycle_id !== "string"
+		|| typeof current.forecast_version !== "string"
+		|| typeof projection.data_as_of !== "string"
+	) return null;
+	return {
+		cycle_id: projection.cycle_id,
+		forecast_version: projection.current_cycle.forecast_version,
+		data_as_of: projection.data_as_of,
+		forecast_revenue: forecast,
+		actual_revenue: actual,
+		revenue_delta: variance.revenue_delta,
+		revenue_delta_pct: variance.revenue_delta_pct,
+	};
+}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function receiptDigestMatches(filename: string, receipt: Record<string, unknown>): boolean {
+	const match = /^build-receipt\.[a-f0-9]{12}\.([a-f0-9]{12})\.json$/.exec(filename);
+	return match !== null && sha256(stableJson(receipt)).startsWith(match[1]);
+}
+
+function boundedString(value: unknown, max = 256): value is string {
+	return typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+function finite(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+/** Validate every field consumed by the accuracy projection before casting. */
+function historicalClosedProjection(value: unknown, scopeId: string, actuals: DashboardActualsSnapshot): CycleOperatingProjection | null {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const source = value as Record<string, unknown>;
+	if (source.kind !== "fpa.cycle-operating-projection" || source.schema_version !== 1 || source.scope_id !== scopeId) return null;
+	if (!boundedString(source.cycle_id) || !boundedString(source.data_as_of) || Number.isNaN(Date.parse(`${source.data_as_of}T00:00:00Z`))) return null;
+	if (!boundedString(source.reporting_currency, 3) || !/^[A-Z]{3}$/.test(source.reporting_currency)) return null;
+	if (!source.current_cycle || typeof source.current_cycle !== "object" || Array.isArray(source.current_cycle)) return null;
+	const current = source.current_cycle as Record<string, unknown>;
+	if (!boundedString(current.forecast_version)) return null;
+	if (!current.variance || typeof current.variance !== "object" || Array.isArray(current.variance)) return null;
+	if (!current.forecast || typeof current.forecast !== "object" || Array.isArray(current.forecast)) return null;
+	if (!current.actual_to_date || typeof current.actual_to_date !== "object" || Array.isArray(current.actual_to_date)) return null;
+	const variance = current.variance as Record<string, unknown>;
+	const forecast = current.forecast as Record<string, unknown>;
+	const actual = current.actual_to_date as Record<string, unknown>;
+	if (variance.status !== "closed_comparable") return null;
+	if (!forecast.revenue || typeof forecast.revenue !== "object" || Array.isArray(forecast.revenue)) return null;
+	if (!finite((forecast.revenue as Record<string, unknown>).base) || !finite(actual.revenue) || !finite(variance.revenue_delta) || !finite(variance.revenue_delta_pct)) return null;
+	if (source.data_as_of !== actuals.data_as_of || actual.revenue !== actuals.current.revenue) return null;
+	if (actuals.snapshot_evidence.consistency !== "single_statement" || !actuals.snapshot_evidence.period_complete || !actuals.snapshot_evidence.reconciled) return null;
+	if (!current.target_period || typeof current.target_period !== "object" || Array.isArray(current.target_period)) return null;
+	const target = current.target_period as Record<string, unknown>;
+	if (target.start_inclusive !== actuals.period.start_inclusive || target.end_exclusive !== actuals.period.end_exclusive || target.timezone !== actuals.period.timezone) return null;
+	if (!Array.isArray(source.warnings) || source.warnings.length > 128 || source.warnings.some((warning) => !boundedString(warning, 4096))) return null;
+	return value as CycleOperatingProjection;
+}
+
+export function projectForecastAccuracy(projections: CycleOperatingProjection[]): ForecastAccuracyProjection {
+	const byCycle = new Map<string, ForecastAccuracyProjection["cycles"][number]>();
+	for (const projection of projections) {
+		const cycle = closedCycle(projection);
+		if (cycle) byCycle.set(cycle.cycle_id, cycle);
+	}
+	const cycles = [...byCycle.values()].sort((left, right) => left.data_as_of.localeCompare(right.data_as_of)).slice(-24);
+	const sampleSize = cycles.length;
+	const mape = sampleSize === 0 ? null : round(cycles.reduce((sum, cycle) => sum + Math.abs(cycle.revenue_delta_pct), 0) / sampleSize);
+	const bias = sampleSize === 0 ? null : round(cycles.reduce((sum, cycle) => sum + cycle.revenue_delta_pct, 0) / sampleSize);
+	const mae = sampleSize === 0 ? null : round(cycles.reduce((sum, cycle) => sum + Math.abs(cycle.revenue_delta), 0) / sampleSize);
+	const actualTotal = cycles.reduce((sum, cycle) => sum + Math.abs(cycle.actual_revenue), 0);
+	const wape = sampleSize === 0 || actualTotal === 0 ? null : round(cycles.reduce((sum, cycle) => sum + Math.abs(cycle.revenue_delta), 0) / actualTotal);
+	const naiveErrors = cycles.slice(1).map((cycle, index) => Math.abs(cycle.actual_revenue - cycles[index].actual_revenue));
+	const naiveMae = naiveErrors.length === 0 ? null : naiveErrors.reduce((sum, value) => sum + value, 0) / naiveErrors.length;
+	const mase = mae === null || naiveMae === null || naiveMae === 0 ? null : round(mae / naiveMae);
+	const warnings = sampleSize < 3 ? ["Forecast accuracy has fewer than three closed, comparable original-forecast cycles; trend conclusions are not yet reliable."] : [];
+	return {
+		kind: "fpa.forecast-accuracy",
+		schema_version: 1,
+		status: sampleSize >= 3 ? "available" : "insufficient_history",
+		sample_size: sampleSize,
+		mean_absolute_percentage_error: mape,
+		mean_percentage_bias: bias,
+		mean_absolute_error: mae,
+		weighted_absolute_percentage_error: wape,
+		mean_absolute_scaled_error: mase,
+		cycles,
+		warnings,
+	};
+}
+
+async function boundedJson(path: string, maxBytes = MAX_FILE_BYTES): Promise<Record<string, unknown> | null> {
+	try {
+		const file = await lstat(path);
+		if (file.isSymbolicLink() || !file.isFile() || file.size > maxBytes) return null;
+		const value: unknown = JSON.parse(await readFile(path, "utf8"));
+		return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+	} catch {
+		return null;
+	}
+}
+
+export async function loadHistoricalOperatingProjections(cwd: string, scopeId: string): Promise<CycleOperatingProjection[]> {
+	const dashboardDir = await resolveDashboardDir(cwd);
+	const generationsDir = join(dashboardDir, "generations");
+	let names: string[];
+	try {
+		names = (await readdir(generationsDir)).filter((name) => GENERATION_RE.test(name)).slice(0, 500);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const result: Array<{ publishedAt: string; projection: CycleOperatingProjection }> = [];
+	for (const name of names) {
+		const generation = await boundedJson(join(generationsDir, name));
+		const generationId = basename(name, ".json");
+		if (
+			!generation
+			|| generation.kind !== "fpa.dashboard.generation"
+			|| generation.schema_version !== 1
+			|| generation.generation_id !== generationId
+			|| typeof generation.published_at !== "string"
+			|| Number.isNaN(Date.parse(generation.published_at))
+			|| typeof generation.build_receipt !== "string"
+			|| !RECEIPT_RE.test(generation.build_receipt)
+		) continue;
+		const receipt = await boundedJson(join(dashboardDir, generation.build_receipt));
+		if (
+			!receipt
+			|| receipt.generation_id !== generationId
+			|| receipt.published_at !== generation.published_at
+			|| !receiptDigestMatches(generation.build_receipt, receipt)
+			|| !receipt.source
+			|| typeof receipt.source !== "object"
+			|| (receipt.source as Record<string, unknown>).scope_id !== scopeId
+		) continue;
+		const actualsRef = (receipt.source as Record<string, unknown>).actuals_snapshot_ref;
+		if (typeof actualsRef !== "string" || !/^[a-f0-9]{64}$/.test(actualsRef)) continue;
+		const actualsObject = await boundedJson(join(dashboardDir, "actuals", `${actualsRef}.json`), 2 * 1024 * 1024);
+		if (!actualsObject) continue;
+		let actuals: DashboardActualsSnapshot;
+		try {
+			actuals = validateActualsSnapshot(actualsObject);
+			if (sha256(stableJson(actuals)) !== actualsRef) continue;
+		} catch {
+			continue;
+		}
+		const candidate = historicalClosedProjection(receipt.operating_projection, scopeId, actuals);
+		if (!candidate) continue;
+		result.push({ publishedAt: generation.published_at, projection: candidate });
+	}
+	return result.sort((left, right) => left.publishedAt.localeCompare(right.publishedAt)).map((item) => item.projection);
+}
+
+function percent(value: number | null, locale: string): string | null {
+	return value === null ? null : new Intl.NumberFormat(locale, { style: "percent", minimumFractionDigits: 1, maximumFractionDigits: 1, signDisplay: "always" }).format(value);
+}
+
+function number(value: number | null, locale: string): string {
+	return value === null ? "—" : new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(value);
+}
+
+export function projectForecastAccuracyWidgets(projection: ForecastAccuracyProjection, locale = "zh-CN"): DashboardWidget[] {
+	const zh = locale.toLowerCase().startsWith("zh");
+	return [
+		{
+			id: "forecast-accuracy-mape",
+			type: "stat",
+			span: "quarter",
+			dataset: "forecast-accuracy-mape.json",
+			data: {
+				label: zh ? "历史预测误差 MAPE" : "Historical forecast MAPE",
+				value: percent(projection.mean_absolute_percentage_error, locale),
+				...(projection.sample_size === 0 ? { missingReason: zh ? "尚无可比较的已关闭周期" : "No comparable closed cycles are available." } : {}),
+				description: zh
+					? `${projection.sample_size} 个 original Forecast 样本 · WAPE ${percent(projection.weighted_absolute_percentage_error, locale) ?? "—"} · MAE ${number(projection.mean_absolute_error, locale)} · MASE ${number(projection.mean_absolute_scaled_error, locale)}`
+					: `${projection.sample_size} original-forecast cycle(s) · WAPE ${percent(projection.weighted_absolute_percentage_error, locale) ?? "—"} · MAE ${number(projection.mean_absolute_error, locale)} · MASE ${number(projection.mean_absolute_scaled_error, locale)}`,
+			},
+		},
+		{
+			id: "forecast-accuracy-history",
+			type: "timeseries",
+			span: "full",
+			dataset: "forecast-accuracy-history.json",
+			data: {
+				label: zh ? "冻结预测与最终实际收入" : "Frozen forecast vs final Actual revenue",
+				series: [
+					{ name: zh ? "原始预测" : "Original forecast", points: projection.cycles.map((cycle) => ({ x: cycle.cycle_id, y: cycle.forecast_revenue })) },
+					{ name: "Actual", points: projection.cycles.map((cycle) => ({ x: cycle.cycle_id, y: cycle.actual_revenue })) },
+				],
+			},
+		},
+	];
+}

package/extensions/fpa-dashboard/forward-outlook.ts

@@ -0,0 +1,142 @@
+import { validateArtifact, type ApprovedCycleForecastInput, type ScenarioMetric } from "../fpa-artifacts/contracts.ts";
+import type { ArtifactRefV2 } from "../fpa-artifacts/store.ts";
+import type { DashboardWidget, TableCell } from "./projector.ts";
+
+interface ForwardForecastInput {
+	ref: ArtifactRefV2;
+	forecast: unknown;
+}
+
+export interface ForwardOutlookProjection {
+	kind: "fpa.forward-outlook";
+	schema_version: 1;
+	reporting_currency: string;
+	status: "six_months_ready" | "partial" | "unavailable";
+	months: Array<{
+		artifact_ref: ArtifactRefV2;
+		forecast_version: string;
+		target_period: ApprovedCycleForecastInput["target_period"];
+		expected_spend: { downside: number | null; base: number | null; upside: number | null };
+		expected_revenue: { downside: number | null; base: number | null; upside: number | null };
+		expected_roas: { downside: number | null; base: number | null; upside: number | null };
+	}>;
+	warnings: string[];
+}
+
+function approvedForecast(value: unknown, path: string): ApprovedCycleForecastInput {
+	const artifact = validateArtifact(value);
+	if (artifact.artifact_type !== "approved_cycle_forecast") throw new Error(`${path} must be an approved_cycle_forecast.`);
+	if (artifact.status !== "complete" || !artifact.approval_conditions_satisfied) throw new Error(`${path} must be complete and approved.`);
+	return artifact;
+}
+
+function values(metric: ScenarioMetric | undefined, path: string) {
+	if (!metric) throw new Error(`${path} is required.`);
+	return { downside: metric.downside, base: metric.base, upside: metric.upside };
+}
+
+export function projectForwardOutlook(input: {
+	current_forecast: unknown;
+	forward_forecasts: ForwardForecastInput[];
+}): ForwardOutlookProjection {
+	const current = approvedForecast(input.current_forecast, "current_forecast");
+	if (!Array.isArray(input.forward_forecasts) || input.forward_forecasts.length > 6) throw new Error("forward_forecasts must contain at most six approved forecasts.");
+	const months: ForwardOutlookProjection["months"] = [];
+	let expectedStart = current.target_period.end_exclusive;
+	for (const [index, item] of input.forward_forecasts.entries()) {
+		const forecast = approvedForecast(item.forecast, `forward_forecasts[${index}].forecast`);
+		if (item.ref.artifact_type !== "approved_cycle_forecast" || item.ref.body_fingerprint === "" || item.ref.cycle_id === "") throw new Error(`forward_forecasts[${index}].ref is invalid.`);
+		if (forecast.reporting_currency !== current.reporting_currency) throw new Error(`forward_forecasts[${index}] reporting currency does not match the current forecast.`);
+		if (forecast.target_period.timezone !== current.target_period.timezone || Date.parse(forecast.target_period.start_inclusive) !== Date.parse(expectedStart)) {
+			throw new Error(`forward_forecasts[${index}] must be the exact consecutive successor in the same timezone.`);
+		}
+		expectedStart = forecast.target_period.end_exclusive;
+		months.push({
+			artifact_ref: item.ref,
+			forecast_version: forecast.forecast_version,
+			target_period: forecast.target_period,
+			expected_spend: values(forecast.consolidated_forecast.spend, `forward_forecasts[${index}].spend`),
+			expected_revenue: values(forecast.consolidated_forecast.revenue, `forward_forecasts[${index}].revenue`),
+			expected_roas: values(forecast.consolidated_forecast.roas, `forward_forecasts[${index}].roas`),
+		});
+	}
+	const warnings: string[] = [];
+	if (months.length < 6) warnings.push(`Only ${months.length} of 6 forward monthly forecasts are approved and linked.`);
+	if (months.some((month) => month.expected_revenue.base === null || month.expected_spend.base === null || month.expected_roas.base === null)) {
+		warnings.push("At least one forward month has unsupported base metrics; its expectation remains unavailable.");
+	}
+	return {
+		kind: "fpa.forward-outlook",
+		schema_version: 1,
+		reporting_currency: current.reporting_currency,
+		status: months.length === 0 ? "unavailable" : months.length === 6 ? "six_months_ready" : "partial",
+		months,
+		warnings,
+	};
+}
+
+function currency(value: number | null, code: string, locale: string): string | null {
+	return value === null ? null : new Intl.NumberFormat(locale, { style: "currency", currency: code, currencyDisplay: "narrowSymbol", maximumFractionDigits: 0 }).format(value);
+}
+
+function number(value: number | null): string | null {
+	return value === null ? null : value.toFixed(2);
+}
+
+function neutral(value: string | null): TableCell {
+	return { value, tone: "neutral" };
+}
+
+export function projectForwardOutlookWidgets(projection: ForwardOutlookProjection, locale = "zh-CN"): DashboardWidget[] {
+	const zh = locale.toLowerCase().startsWith("zh");
+	if (projection.status === "unavailable") return [{
+		id: "forward-outlook-readiness",
+		type: "stat",
+		span: "quarter",
+		dataset: "forward-outlook-readiness.json",
+		data: {
+			label: zh ? "未来六个月预测" : "Six-month outlook",
+			value: null,
+			missingReason: zh ? "尚无连续的未来周期批准预测" : "No consecutive approved future forecasts are linked.",
+		},
+	}];
+	const monthLabel = (month: ForwardOutlookProjection["months"][number]) => month.target_period.start_inclusive.slice(0, 7);
+	return [
+		{
+			id: "forward-outlook-revenue",
+			type: "timeseries",
+			span: "full",
+			dataset: "forward-outlook-revenue.json",
+			data: {
+				label: zh ? "未来六个月收入情景" : "Six-month revenue scenarios",
+				description: zh ? `已批准 ${projection.months.length}/6 个连续月份` : `${projection.months.length}/6 consecutive months approved`,
+				series: [
+					{ name: zh ? "下行" : "Downside", points: projection.months.map((month) => ({ x: monthLabel(month), y: month.expected_revenue.downside })) },
+					{ name: zh ? "基准" : "Base", points: projection.months.map((month) => ({ x: monthLabel(month), y: month.expected_revenue.base })) },
+					{ name: zh ? "上行" : "Upside", points: projection.months.map((month) => ({ x: monthLabel(month), y: month.expected_revenue.upside })) },
+				],
+			},
+		},
+		{
+			id: "forward-outlook-table",
+			type: "table",
+			span: "full",
+			dataset: "forward-outlook-table.json",
+			data: {
+				label: zh ? "未来周期批准预测" : "Approved forward forecasts",
+				columns: [
+					{ key: "period", label: zh ? "周期" : "Period" },
+					{ key: "spend", label: zh ? "预算" : "Spend", align: "right" },
+					{ key: "revenue", label: zh ? "预期收入" : "Expected revenue", align: "right" },
+					{ key: "roas", label: "ROAS", align: "right" },
+				],
+				rows: projection.months.map((month) => ({
+					period: monthLabel(month),
+					spend: currency(month.expected_spend.base, projection.reporting_currency, locale),
+					revenue: currency(month.expected_revenue.base, projection.reporting_currency, locale),
+					roas: neutral(number(month.expected_roas.base)),
+				})),
+			},
+		},
+	];
+}

package/extensions/fpa-dashboard/index.ts

@@ -2,22 +2,14 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import {
-	readCommittedArtifact,
-	readOptionalCommittedArtifact,
-	type ReadArtifactResult,
-} from "../fpa-artifacts/store.ts";
-import type {
-	ApprovedCycleForecast,
-	ApprovedCycleForecastInput,
-	CanonicalArtifact,
-	ExecutionReceipt,
-	ExecutionReceiptInput,
-} from "../fpa-artifacts/contracts.ts";
-import { isExecutionReceiptForForecast, sliceKey } from "../fpa-artifacts/contracts.ts";
-import { loadDashboardActuals } from "./actuals.ts";
-import { projectDashboard, type DashboardBuild } from "./projector.ts";
+import type { ArtifactRefV2 } from "../fpa-artifacts/store.ts";
 import { dashboardBuildFingerprint, publishDashboard } from "./publisher.ts";
+import {
+	enqueueDashboardRefresh,
+	inspectDashboardRefreshQueue,
+	processDashboardRefreshQueue,
+} from "./coordinator.ts";
+import { buildDashboardProjection } from "./service.ts";
 import { inspectDashboard } from "./status.ts";
 
 function toolResult(value: Record<string, unknown>) {
@@ -27,60 +19,14 @@ function toolResult(value: Record<string, unknown>) {
 	};
 }
 
-function withoutFingerprint<T extends CanonicalArtifact>(artifact: T): Omit<T, "immutable_fingerprint"> {
-	const { immutable_fingerprint: _fingerprint, ...input } = artifact;
-	return input;
-}
-
-async function buildDashboard(
-	cwd: string,
-	locale: string,
-	signal?: AbortSignal,
-): Promise<{
-	build: DashboardBuild;
-	forecast: ApprovedCycleForecast;
-	forecastRead: ReadArtifactResult;
-	executionRead: ReadArtifactResult | null;
-}> {
-	const forecastRead = await readCommittedArtifact(cwd, "approved_cycle_forecast");
-	if (forecastRead.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("Committed approved forecast has the wrong artifact type.");
-	const forecast = forecastRead.artifact as ApprovedCycleForecast;
-	const committedExecutionRead = await readOptionalCommittedArtifact(cwd, "execution_receipt");
-	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.forecast_fingerprint = forecastRead.fingerprint;
-	if (executionRead) build.source.execution_fingerprint = executionRead.fingerprint;
-
-	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.");
-	return { build, forecast, forecastRead, executionRead };
-}
-
 export default function fpaDashboardExtension(pi: ExtensionAPI): void {
+	const artifactRefSchema = Type.Object({
+		scope_id: Type.String({ minLength: 1, maxLength: 256 }),
+		cycle_id: Type.String({ minLength: 1, maxLength: 256 }),
+		artifact_type: Type.Union([Type.Literal("approved_cycle_forecast"), Type.Literal("execution_receipt")]),
+		entry_id: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+		body_fingerprint: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+	}, { additionalProperties: false });
 	pi.registerTool({
 		name: "fpa_dashboard_status",
 		label: "FP&A Dashboard Status",
@@ -110,13 +56,32 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 				mode: StringEnum(["preview", "publish"] as const),
 				locale: Type.Optional(StringEnum(["zh-CN", "en-US"] as const)),
 				expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+				scope_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+				cycle_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+				forecast_ref: Type.Optional(artifactRefSchema),
+				execution_ref: Type.Optional(artifactRefSchema),
+				next_forecast_ref: Type.Optional(artifactRefSchema),
+				forward_forecast_refs: Type.Optional(Type.Array(artifactRefSchema, { maxItems: 6 })),
 			},
 			{ additionalProperties: false },
 		),
 		executionMode: "sequential",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const { build, forecast } = await buildDashboard(ctx.cwd, params.locale ?? "zh-CN", signal);
-			const previewFingerprint = dashboardBuildFingerprint(build);
+			const exactFields = [params.scope_id, params.cycle_id, params.forecast_ref];
+			const hasAnyExactField = exactFields.some((value) => value !== undefined) || params.execution_ref !== undefined || params.next_forecast_ref !== undefined || params.forward_forecast_refs !== undefined;
+			if (hasAnyExactField && exactFields.some((value) => value === undefined)) {
+				throw new Error("scope_id, cycle_id, and forecast_ref must be supplied together; exact refresh never falls back to current artifacts.");
+			}
+			const exact = hasAnyExactField ? {
+				scopeId: params.scope_id as string,
+				cycleId: params.cycle_id as string,
+				forecastRef: params.forecast_ref as ArtifactRefV2,
+				...(params.execution_ref ? { executionRef: params.execution_ref as ArtifactRefV2 } : {}),
+				...(params.next_forecast_ref ? { nextForecastRef: params.next_forecast_ref as ArtifactRefV2 } : {}),
+				...(params.forward_forecast_refs ? { forwardForecastRefs: params.forward_forecast_refs as ArtifactRefV2[] } : {}),
+			} : undefined;
+			const { build, forecast, actuals, sliceKeyMismatch, projector, runtime } = await buildDashboardProjection(ctx.cwd, params.preset, params.locale ?? "zh-CN", exact, signal);
+			const previewFingerprint = dashboardBuildFingerprint(build, projector);
 			const summary = {
 				preset: params.preset,
 				preview_fingerprint: previewFingerprint,
@@ -128,9 +93,29 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 				widgets: build.widgets.map((widget) => ({ id: widget.id, type: widget.type, dataset: widget.dataset })),
 				warnings: build.warnings,
 				query_receipts: build.source.query_receipts,
+				projector,
+				runtime,
+				...(build.operating_projection ? { operating_projection: build.operating_projection } : {}),
+				...(build.forward_outlook ? { forward_outlook: build.forward_outlook } : {}),
+				...(build.forecast_accuracy ? { forecast_accuracy: build.forecast_accuracy } : {}),
+				...(exact ? {
+					scope_id: exact.scopeId,
+					cycle_id: exact.cycleId,
+					forecast_ref: exact.forecastRef,
+					...(exact.executionRef ? { execution_ref: exact.executionRef } : {}),
+					...(exact.nextForecastRef ? { next_forecast_ref: exact.nextForecastRef } : {}),
+					...(exact.forwardForecastRefs ? { forward_forecast_refs: exact.forwardForecastRefs } : {}),
+				} : {}),
 			};
-			if (params.mode === "preview") return toolResult({ status: build.warnings.length > 0 ? "ready_with_limits" : "ready", ...summary });
+			if (params.mode === "preview") {
+				return toolResult({
+					status: sliceKeyMismatch ? "blocked_slice_key_mismatch" : build.warnings.length > 0 ? "ready_with_limits" : "ready",
+					...summary,
+					...(sliceKeyMismatch ? { blocking_reason: sliceKeyMismatch } : {}),
+				});
+			}
 
+			if (sliceKeyMismatch) throw new Error(`Dashboard publish refused. ${sliceKeyMismatch}`);
 			if (forecast.status !== "complete" || !forecast.approval_conditions_satisfied) {
 				throw new Error("Dashboard publish requires a complete approved forecast with all approval conditions satisfied.");
 			}
@@ -138,8 +123,47 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			if (params.expected_preview_fingerprint !== previewFingerprint) {
 				throw new Error("Dashboard inputs changed after preview; run preview again before publishing.");
 			}
-			const published = await publishDashboard({ cwd: ctx.cwd, build });
+			const published = await publishDashboard({ cwd: ctx.cwd, build, projector, runtime, actualsSnapshot: actuals });
 			return toolResult({ status: "published", ...summary, dashboard_dir: published.dashboardDir, published_datasets: published.publishedDatasets });
 		},
 	});
+
+	pi.registerTool({
+		name: "fpa_dashboard_refresh_queue",
+		label: "FP&A Dashboard Refresh Queue",
+		description: "Inspect or drain the durable dashboard refresh queue, or enqueue an Actuals-watermark refresh against exact immutable artifact refs.",
+		promptSnippet: "Inspect or process durable FP&A dashboard refresh work",
+		parameters: Type.Object({
+			action: StringEnum(["status", "drain", "enqueue_actuals"] as const),
+			locale: Type.Optional(StringEnum(["zh-CN", "en-US"] as const)),
+			scope_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+			cycle_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+			forecast_ref: Type.Optional(artifactRefSchema),
+			execution_ref: Type.Optional(artifactRefSchema),
+			next_forecast_ref: Type.Optional(artifactRefSchema),
+			forward_forecast_refs: Type.Optional(Type.Array(artifactRefSchema, { maxItems: 6 })),
+			actuals_watermark: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+			limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			if (params.action === "status") return toolResult(await inspectDashboardRefreshQueue(ctx.cwd) as unknown as Record<string, unknown>);
+			if (params.action === "drain") return toolResult(await processDashboardRefreshQueue(ctx.cwd, { limit: params.limit, signal }) as unknown as Record<string, unknown>);
+			if (!params.scope_id || !params.cycle_id || !params.forecast_ref || !params.actuals_watermark) {
+				throw new Error("enqueue_actuals requires scope_id, cycle_id, forecast_ref, and actuals_watermark.");
+			}
+			return toolResult(await enqueueDashboardRefresh(ctx.cwd, {
+				preset: "forecast-closed-loop-v1",
+				locale: params.locale ?? "zh-CN",
+				scope_id: params.scope_id,
+				cycle_id: params.cycle_id,
+				forecast_ref: params.forecast_ref as ArtifactRefV2,
+				...(params.execution_ref ? { execution_ref: params.execution_ref as ArtifactRefV2 } : {}),
+				...(params.next_forecast_ref ? { next_forecast_ref: params.next_forecast_ref as ArtifactRefV2 } : {}),
+				...(params.forward_forecast_refs ? { forward_forecast_refs: params.forward_forecast_refs as ArtifactRefV2[] } : {}),
+				actuals_watermark: params.actuals_watermark,
+				reason: "actuals_watermark",
+			}) as unknown as Record<string, unknown>);
+		},
+	});
 }

package/extensions/fpa-dashboard/projector.ts

@@ -8,6 +8,9 @@ import {
 	type ForecastSlice,
 } from "../fpa-artifacts/contracts.ts";
 import { validateActualsSnapshot, ACTUALS_DATA_AS_OF_UNAVAILABLE, type DashboardActualsSnapshot, type DashboardActualSlice } from "./source.ts";
+import type { CycleOperatingProjection } from "./cycle-operating-projection.ts";
+import type { ForwardOutlookProjection } from "./forward-outlook.ts";
+import type { ForecastAccuracyProjection } from "./forecast-accuracy.ts";
 
 export type Tone = "positive" | "negative" | "warning" | "neutral";
 export type TableCell = string | null | { value: string | null; tone?: Tone };
@@ -58,14 +61,30 @@ export interface DashboardBuild {
 	title: string;
 	widgets: DashboardWidget[];
 	source: {
+		project_name?: string;
+		scope_id?: string;
+		cycle_id?: string;
+		forecast_ref?: string;
+		next_forecast_ref?: string;
+		execution_ref?: string;
+		forecast_role?: "original" | "eac" | "next_plan";
 		forecast_version: string;
 		forecast_fingerprint?: string;
+		next_forecast_fingerprint?: string;
+		forward_forecast_refs?: string[];
+		forward_forecast_fingerprints?: string[];
 		execution_fingerprint?: string;
 		data_as_of: string;
+		actuals_watermark?: string;
+		actuals_snapshot_ref?: string;
+		actuals_snapshot_evidence?: DashboardActualsSnapshot["snapshot_evidence"];
 		actuals_scope: { slice_keys: string[] };
 		query_receipts: DashboardActualsSnapshot["query_receipts"];
 	};
 	warnings: string[];
+	operating_projection?: CycleOperatingProjection;
+	forward_outlook?: ForwardOutlookProjection;
+	forecast_accuracy?: ForecastAccuracyProjection;
 }
 
 interface ProjectionInput {