@viccydev/pi-fpa 0.2.1 → 0.3.0

package/extensions/fpa-dashboard/projector.ts

@@ -0,0 +1,482 @@
+import {
+	validateArtifact,
+	validateExecutionAgainstForecast,
+	sliceKey,
+	type ApprovedCycleForecastInput,
+	type ExecutionReceiptInput,
+	type ForecastAllocation,
+	type ForecastSlice,
+} from "../fpa-artifacts/contracts.ts";
+import { validateActualsSnapshot, type DashboardActualsSnapshot, type DashboardActualSlice } from "./source.ts";
+
+export type Tone = "positive" | "negative" | "warning" | "neutral";
+export type TableCell = string | null | { value: string | null; tone?: Tone };
+
+export interface StatDataset {
+	label: string;
+	value: string | null;
+	missingReason?: string;
+	delta?: { direction: "up" | "down" | "flat"; label: string; sentiment?: "positive" | "negative" | "neutral" };
+	progress?: { fraction: number; label: string; tone?: Tone };
+	description?: string;
+	footnote?: string;
+}
+
+export interface TimeseriesDataset {
+	label: string;
+	description?: string;
+	series: Array<{ name: string; points: Array<{ x: string; y: number | null }> }>;
+	coverage?: string;
+}
+
+export interface TableDataset {
+	label: string;
+	description?: string;
+	columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+	rows: Array<Record<string, TableCell>>;
+}
+
+export interface GroupedTableDataset {
+	label: string;
+	description?: string;
+	columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+	groups: Array<{
+		key: string;
+		label: string;
+		summary: Record<string, TableCell>;
+		rows: Array<Record<string, TableCell>>;
+	}>;
+}
+
+export type DashboardWidget =
+	| { id: string; type: "stat"; span: "quarter" | "half" | "full"; dataset: string; data: StatDataset }
+	| { id: string; type: "timeseries"; span: "quarter" | "half" | "full"; dataset: string; data: TimeseriesDataset }
+	| { id: string; type: "table"; span: "quarter" | "half" | "full"; dataset: string; data: TableDataset }
+	| { id: string; type: "grouped-table"; span: "quarter" | "half" | "full"; dataset: string; data: GroupedTableDataset };
+
+export interface DashboardBuild {
+	title: string;
+	widgets: DashboardWidget[];
+	source: {
+		forecast_version: string;
+		forecast_fingerprint?: string;
+		execution_fingerprint?: string;
+		data_as_of: string;
+		actuals_scope: { slice_keys: string[] };
+		query_receipts: DashboardActualsSnapshot["query_receipts"];
+	};
+	warnings: string[];
+}
+
+interface ProjectionInput {
+	forecast: unknown;
+	actuals: unknown;
+	execution?: unknown;
+	locale?: string;
+}
+
+interface JoinedSlice {
+	allocation: ForecastAllocation;
+	forecast: ForecastSlice;
+	actual: DashboardActualSlice | null;
+	execution: ExecutionReceiptInput["slices"][number] | null;
+	forecastRoas: number | null;
+	actualRoas: number | null;
+	deviation: number | null;
+}
+
+const ACTION_LABEL: Record<ForecastAllocation["action"], string> = {
+	stop: "止损",
+	decrease: "减量",
+	hold: "维持",
+	increase: "加量",
+	explore: "探索",
+};
+
+function round(value: number, precision = 3): number {
+	const factor = 10 ** precision;
+	return Math.round(value * factor) / factor;
+}
+
+function safeDiv(numerator: number | null, denominator: number | null): number | null {
+	if (numerator === null || denominator === null || denominator === 0) return null;
+	return numerator / denominator;
+}
+
+function clampFraction(value: number | null): number {
+	if (value === null || !Number.isFinite(value)) return 0;
+	return round(Math.max(0, Math.min(1, value)));
+}
+
+function formatCurrency(value: number | null, currency: string, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, {
+		style: "currency",
+		currency,
+		currencyDisplay: "narrowSymbol",
+		minimumFractionDigits: 0,
+		maximumFractionDigits: 2,
+	}).format(value);
+}
+
+function formatRoas(value: number | null): string | null {
+	return value === null ? null : value.toFixed(2);
+}
+
+function formatSignedPercent(value: number | null, suffix = ""): string | null {
+	if (value === null) return null;
+	const sign = value > 0 ? "+" : "";
+	return `${sign}${(value * 100).toFixed(1)}%${suffix}`;
+}
+
+function formatPeriodDate(timestamp: string, timezone: string, locale: string): string {
+	return new Intl.DateTimeFormat(locale, {
+		timeZone: timezone,
+		year: "numeric",
+		month: "numeric",
+		day: "numeric",
+	}).format(new Date(timestamp));
+}
+
+function samePeriod(a: ApprovedCycleForecastInput["target_period"], b: DashboardActualsSnapshot["period"]): boolean {
+	return a.start_inclusive === b.start_inclusive && a.end_exclusive === b.end_exclusive && a.timezone === b.timezone;
+}
+
+function actionCell(action: ForecastAllocation["action"]): TableCell {
+	const tone: Tone | undefined = action === "stop" ? "negative" : action === "increase" ? "positive" : action === "decrease" ? "warning" : undefined;
+	return tone ? { value: ACTION_LABEL[action], tone } : ACTION_LABEL[action];
+}
+
+function executionLabel(
+	receipt: ExecutionReceiptInput | null,
+	slice: ExecutionReceiptInput["slices"][number] | null,
+): TableCell {
+	if (!receipt) return "未提供回执";
+	if (!slice) return { value: "回执缺分片", tone: "warning" };
+	if (receipt.verification_status === "verified") return { value: "已核验", tone: "positive" };
+	if (receipt.verification_status === "failed") return { value: "执行失败", tone: "negative" };
+	return receipt.execution_mode === "manual" ? "人工已报告" : "适配器已报告";
+}
+
+function executionGroupLabel(receipt: ExecutionReceiptInput | null, slices: JoinedSlice[]): TableCell {
+	if (!receipt) return "未提供回执";
+	if (slices.some((slice) => slice.execution === null)) return { value: "回执缺分片", tone: "warning" };
+	return executionLabel(receipt, slices[0]?.execution ?? null);
+}
+
+function numericCell(value: string | null, tone?: Tone): TableCell {
+	return tone ? { value, tone } : value;
+}
+
+function progressTone(fraction: number | null): Tone {
+	if (fraction === null) return "neutral";
+	if (fraction >= 1) return "positive";
+	if (fraction >= 0.9) return "warning";
+	return "negative";
+}
+
+function joinSlices(
+	forecast: ApprovedCycleForecastInput,
+	actuals: DashboardActualsSnapshot,
+	execution: ExecutionReceiptInput | null,
+): JoinedSlice[] {
+	const forecastByKey = new Map(forecast.forecast_by_slice.map((slice) => [sliceKey(slice), slice]));
+	const actualByKey = new Map(actuals.slices.map((slice) => [sliceKey(slice), slice]));
+	const executionByKey = new Map((execution?.slices ?? []).map((slice) => [sliceKey(slice), slice]));
+	return forecast.approved_allocation.map((allocation) => {
+		const forecastSlice = forecastByKey.get(sliceKey(allocation));
+		if (!forecastSlice) throw new Error(`Forecast slice is missing for ${allocation.app_id} / ${allocation.store} / ${allocation.channel_group}.`);
+		const actual = actualByKey.get(sliceKey(allocation)) ?? null;
+		const forecastRoas = safeDiv(
+			forecastSlice.metrics.revenue?.base ?? null,
+			forecastSlice.metrics.spend?.base ?? null,
+		);
+		const actualRoas = actual ? safeDiv(actual.revenue, actual.spend) : null;
+		return {
+			allocation,
+			forecast: forecastSlice,
+			actual,
+			execution: executionByKey.get(sliceKey(allocation)) ?? null,
+			forecastRoas,
+			actualRoas,
+			deviation: forecastRoas === null || actualRoas === null ? null : safeDiv(actualRoas - forecastRoas, Math.abs(forecastRoas)),
+		};
+	});
+}
+
+function buildStrategyTable(
+	joined: JoinedSlice[],
+	executionReceipt: ExecutionReceiptInput | null,
+	forecast: ApprovedCycleForecastInput,
+): GroupedTableDataset {
+	const grouped = new Map<string, JoinedSlice[]>();
+	for (const slice of joined) grouped.set(slice.allocation.app_id, [...(grouped.get(slice.allocation.app_id) ?? []), slice]);
+	const columns = [
+		{ key: "unit", label: "App / 渠道" },
+		{ key: "forecast", label: "预测 ROAS", align: "right" as const },
+		{ key: "actual", label: "实际 ROAS", align: "right" as const },
+		{ key: "deviation", label: "偏差", align: "right" as const },
+		{ key: "decision", label: "决策" },
+		{ key: "exec", label: "执行状态" },
+	];
+	return {
+		label: "预测 vs 实际 · 执行策略（按 App）",
+		description:
+			`同周期付费 ROAS；偏差绝对值 ≥ ${(forecast.calibration_policy.deviation_warning_abs_gte * 100).toFixed(0)}% 标黄，` +
+			`> ${(forecast.calibration_policy.deviation_trigger_abs_gt * 100).toFixed(0)}% 触发校准。`,
+		columns,
+		groups: [...grouped.entries()].map(([appId, slices]) => {
+			const forecastRevenue = slices.every((slice) => slice.forecast.metrics.revenue?.base != null)
+				? slices.reduce((sum, slice) => sum + (slice.forecast.metrics.revenue?.base ?? 0), 0)
+				: null;
+			const forecastSpend = slices.every((slice) => slice.forecast.metrics.spend?.base != null)
+				? slices.reduce((sum, slice) => sum + (slice.forecast.metrics.spend?.base ?? 0), 0)
+				: null;
+			const actualRevenue = slices.every((slice) => slice.actual?.revenue != null)
+				? slices.reduce((sum, slice) => sum + (slice.actual?.revenue ?? 0), 0)
+				: null;
+			const actualSpend = slices.every((slice) => slice.actual?.spend != null)
+				? slices.reduce((sum, slice) => sum + (slice.actual?.spend ?? 0), 0)
+				: null;
+			const appForecast = safeDiv(forecastRevenue, forecastSpend);
+			const appActual = safeDiv(actualRevenue, actualSpend);
+			const appDeviation = appForecast === null || appActual === null ? null : safeDiv(appActual - appForecast, Math.abs(appForecast));
+			const actions = new Set(slices.map((slice) => slice.allocation.action));
+			const summaryAction = actions.size === 1 ? ACTION_LABEL[slices[0].allocation.action] : actions.has("stop") ? "部分止损" : "组合策略";
+			const summaryTone: Tone | undefined = actions.has("stop") ? "negative" : actions.has("increase") ? "positive" : undefined;
+
+			return {
+				key: appId,
+				label: appId,
+				summary: {
+					forecast: formatRoas(appForecast),
+					actual: formatRoas(appActual),
+					deviation: numericCell(formatSignedPercent(appDeviation), appDeviation !== null && Math.abs(appDeviation) >= forecast.calibration_policy.deviation_warning_abs_gte ? "warning" : undefined),
+					decision: summaryTone ? { value: summaryAction, tone: summaryTone } : summaryAction,
+					exec: executionGroupLabel(executionReceipt, slices),
+				},
+				rows: slices.map((slice) => {
+					const stop = slice.actualRoas !== null && slice.actualRoas < forecast.calibration_policy.stop_loss_roas_lt;
+					const warn = slice.deviation !== null && Math.abs(slice.deviation) >= forecast.calibration_policy.deviation_warning_abs_gte;
+					return {
+						unit: slice.allocation.channel_group,
+						forecast: formatRoas(slice.forecastRoas),
+						actual: numericCell(formatRoas(slice.actualRoas), stop ? "negative" : undefined),
+						deviation: numericCell(formatSignedPercent(slice.deviation), stop ? "negative" : warn ? "warning" : undefined),
+						decision: actionCell(slice.allocation.action),
+						exec: executionLabel(executionReceipt, slice.execution),
+					};
+				}),
+			};
+		}),
+	};
+}
+
+function buildAlerts(joined: JoinedSlice[], forecast: ApprovedCycleForecastInput): TableDataset {
+	const rows: Array<Record<string, TableCell>> = [];
+	for (const slice of joined) {
+		if (slice.actualRoas === null) continue;
+		const unit = `${slice.allocation.app_id} × ${slice.allocation.channel_group}`;
+		if (slice.actualRoas < forecast.calibration_policy.stop_loss_roas_lt) {
+			rows.push({
+				level: { value: "严重", tone: "negative" },
+				unit,
+				trigger: `实际 ROAS ${formatRoas(slice.actualRoas)} < ${formatRoas(forecast.calibration_policy.stop_loss_roas_lt)} 止损线`,
+				action: "执行止损规则并核验预算回流",
+			});
+			continue;
+		}
+		if (slice.deviation !== null && Math.abs(slice.deviation) >= forecast.calibration_policy.deviation_warning_abs_gte) {
+			const isTrigger = Math.abs(slice.deviation) > forecast.calibration_policy.deviation_trigger_abs_gt;
+			rows.push({
+				level: { value: isTrigger ? "严重" : "警告", tone: isTrigger ? "negative" : "warning" },
+				unit,
+				trigger: `${isTrigger ? "偏差超校准阈值" : "偏差接近阈值"}：${formatSignedPercent(slice.deviation)}`,
+				action: "更新回收假设并进入下周期复盘",
+			});
+		}
+	}
+	return {
+		label: "校准触发",
+		description: `规则版本 ${forecast.calibration_policy.policy_version}；仅基于可计算的同口径单元。`,
+		columns: [
+			{ key: "level", label: "级别" },
+			{ key: "unit", label: "对象" },
+			{ key: "trigger", label: "触发条件" },
+			{ key: "action", label: "建议动作" },
+		],
+		rows,
+	};
+}
+
+export function projectDashboard(input: ProjectionInput): DashboardBuild {
+	const normalizedForecast = validateArtifact(input.forecast);
+	if (normalizedForecast.artifact_type !== "approved_cycle_forecast") throw new Error("forecast must be an approved_cycle_forecast artifact.");
+	const forecast = normalizedForecast;
+	const actuals = validateActualsSnapshot(input.actuals);
+	const executionArtifact = input.execution === undefined ? null : validateArtifact(input.execution);
+	if (executionArtifact && executionArtifact.artifact_type !== "execution_receipt") throw new Error("execution must be an execution_receipt artifact.");
+	const execution = executionArtifact;
+	const locale = input.locale ?? "zh-CN";
+	if (!samePeriod(forecast.target_period, actuals.period)) throw new Error("Forecast and Actuals periods/timezones do not match.");
+	if (forecast.reporting_currency !== actuals.reporting_currency) throw new Error("Forecast and Actuals reporting currencies do not match.");
+	if (execution) validateExecutionAgainstForecast(execution, forecast);
+	if (execution && !samePeriod(forecast.target_period, execution.target_period)) throw new Error("Execution receipt period does not match the approved forecast.");
+	if (execution && execution.reporting_currency !== forecast.reporting_currency) throw new Error("Execution receipt currency does not match the approved forecast.");
+
+	const joined = joinSlices(forecast, actuals, execution);
+	const forecastRevenue = forecast.consolidated_forecast.revenue?.base ?? null;
+	const forecastSpend = forecast.consolidated_forecast.spend?.base ?? null;
+	const forecastRoas = safeDiv(forecastRevenue, forecastSpend);
+	const actualRoas = safeDiv(actuals.current.revenue, actuals.current.spend);
+	const revenueAttainment = safeDiv(actuals.current.revenue, forecastRevenue);
+	const spendAttainment = safeDiv(actuals.current.spend, forecastSpend);
+	const roasAttainment = safeDiv(actualRoas, forecastRoas);
+	const roasDeviation = actualRoas === null || forecastRoas === null
+		? null
+		: safeDiv(actualRoas - forecastRoas, Math.abs(forecastRoas));
+	const revenueComparison = actuals.comparison ? safeDiv(
+		actuals.current.revenue === null || actuals.comparison.revenue === null ? null : actuals.current.revenue - actuals.comparison.revenue,
+		actuals.comparison.revenue === null ? null : Math.abs(actuals.comparison.revenue),
+	) : null;
+	const alerts = buildAlerts(joined, forecast);
+	const evaluated = joined.filter((slice) => slice.actualRoas !== null).length;
+	const stopCount = joined.filter((slice) => slice.actualRoas !== null && slice.actualRoas < forecast.calibration_policy.stop_loss_roas_lt).length;
+	const deviationCount = alerts.rows.length - stopCount;
+	const window = `${formatPeriodDate(forecast.target_period.start_inclusive, forecast.target_period.timezone, locale)} → ${formatPeriodDate(forecast.target_period.end_exclusive, forecast.target_period.timezone, locale)}（end exclusive）`;
+
+	const widgets: DashboardWidget[] = [
+		{
+			id: "revenue-vs-forecast",
+			type: "stat",
+			span: "quarter",
+			dataset: "revenue-vs-forecast.json",
+			data: {
+				label: "本周期收入（付费口径）",
+				value: formatCurrency(actuals.current.revenue, forecast.reporting_currency, locale),
+				...(actuals.current.revenue === null ? { missingReason: "当前周期收入不可计算。" } : {}),
+				...(revenueComparison === null ? {} : {
+					delta: {
+						direction: revenueComparison > 0 ? "up" as const : revenueComparison < 0 ? "down" as const : "flat" as const,
+						label: formatSignedPercent(revenueComparison, " vs 等长上周期") as string,
+						sentiment: revenueComparison > 0 ? "positive" as const : revenueComparison < 0 ? "negative" as const : "neutral" as const,
+					},
+				}),
+				...(forecastRevenue === null || revenueAttainment === null ? {} : {
+					progress: { fraction: clampFraction(revenueAttainment), label: formatSignedPercent(revenueAttainment)?.replace(/^\+/, "") ?? "无数据", tone: progressTone(revenueAttainment) },
+					description: `冻结预测 ${formatCurrency(forecastRevenue, forecast.reporting_currency, locale)}`,
+				}),
+				footnote: `${window}；Actuals as of ${actuals.data_as_of}`,
+			},
+		},
+		{
+			id: "cycle-roas",
+			type: "stat",
+			span: "quarter",
+			dataset: "cycle-roas.json",
+			data: {
+				label: "本周期 ROAS",
+				value: formatRoas(actualRoas),
+				...(actualRoas === null ? { missingReason: "收入或花费缺失，无法计算 ROAS。" } : {}),
+				...(roasDeviation === null ? {} : {
+					delta: {
+						direction: actualRoas > forecastRoas ? "up" as const : actualRoas < forecastRoas ? "down" as const : "flat" as const,
+						label: `${formatSignedPercent(roasDeviation)} vs 预测`,
+						sentiment: actualRoas >= forecastRoas ? "positive" as const : "negative" as const,
+					},
+					progress: { fraction: clampFraction(roasAttainment), label: formatSignedPercent(roasAttainment)?.replace(/^\+/, "") ?? "无数据", tone: progressTone(roasAttainment) },
+					description: `冻结预测目标 ${formatRoas(forecastRoas)}`,
+				}),
+				footnote: "ROAS = 聚合后 revenue / spend，非分片 ROAS 平均值",
+			},
+		},
+		{
+			id: "paid-spend-exec",
+			type: "stat",
+			span: "quarter",
+			dataset: "paid-spend-exec.json",
+			data: {
+				label: "本周期花费（付费口径）",
+				value: formatCurrency(actuals.current.spend, forecast.reporting_currency, locale),
+				...(actuals.current.spend === null ? { missingReason: "当前周期花费不可计算。" } : {}),
+				...(forecastSpend === null || spendAttainment === null ? {} : {
+					progress: { fraction: clampFraction(spendAttainment), label: formatSignedPercent(spendAttainment)?.replace(/^\+/, "") ?? "无数据", tone: spendAttainment !== null && spendAttainment > 1 ? "negative" : progressTone(spendAttainment) },
+					description: `周期预算 ${formatCurrency(forecastSpend, forecast.reporting_currency, locale)}`,
+				}),
+				footnote: execution ? `执行回执：${execution.verification_status}` : "未提供执行回执",
+			},
+		},
+		{
+			id: "alerts-count",
+			type: "stat",
+			span: "quarter",
+			dataset: "alerts-count.json",
+			data: {
+				label: "校准预警",
+				value: String(alerts.rows.length),
+				progress: { fraction: evaluated === 0 ? 0 : round(alerts.rows.length / evaluated), label: `${alerts.rows.length}/${evaluated}`, tone: alerts.rows.length > 0 ? "negative" : "positive" },
+				description: `${stopCount} 条止损触发 · ${deviationCount} 条偏差预警`,
+				footnote: `规则版本 ${forecast.calibration_policy.policy_version}`,
+			},
+		},
+		{
+			id: "daily-trend",
+			type: "timeseries",
+			span: "full",
+			dataset: "daily-trend.json",
+			data: {
+				label: "周期内收入与花费（付费口径）",
+				description: "缺失观测保持为 null，不做填补。",
+				series: [
+					{ name: "收入", points: actuals.daily.map((point) => ({ x: point.date, y: point.revenue })) },
+					{ name: "花费", points: actuals.daily.map((point) => ({ x: point.date, y: point.spend })) },
+				],
+				...(actuals.coverage.date_min && actuals.coverage.date_max ? { coverage: `${actuals.coverage.date_min} → ${actuals.coverage.date_max}` } : {}),
+			},
+		},
+		{
+			id: "app-strategy",
+			type: "grouped-table",
+			span: "full",
+			dataset: "app-strategy.json",
+			data: buildStrategyTable(joined, execution, forecast),
+		},
+		{
+			id: "calibration-alerts",
+			type: "table",
+			span: "full",
+			dataset: "calibration-alerts.json",
+			data: alerts,
+		},
+	];
+
+	const start = new Date(forecast.target_period.start_inclusive);
+	const plannedKeys = new Set(forecast.approved_allocation.map(sliceKey));
+	const executionKeys = new Set((execution?.slices ?? []).map(sliceKey));
+	const missingExecutionSlices = execution ? [...plannedKeys].filter((planned) => !executionKeys.has(planned)).length : 0;
+	const extraExecutionSlices = execution ? [...executionKeys].filter((executed) => !plannedKeys.has(executed)).length : 0;
+	const titleMonth = new Intl.DateTimeFormat(locale, {
+		timeZone: forecast.target_period.timezone,
+		year: "numeric",
+		month: "long",
+	}).format(start);
+	return {
+		title: `${titleMonth}经营看板 · 预测闭环`,
+		widgets,
+		source: {
+			forecast_version: forecast.forecast_version,
+			data_as_of: actuals.data_as_of,
+			actuals_scope: {
+				slice_keys: forecast.approved_allocation.map((slice) => sliceKey(slice).replaceAll("\u0000", " / ")).sort(),
+			},
+			query_receipts: actuals.query_receipts,
+		},
+		warnings: [
+			...(forecast.status !== "complete" ? [`Approved forecast status is ${forecast.status}.`] : []),
+			...(!forecast.approval_conditions_satisfied ? ["Approved forecast conditions are not satisfied."] : []),
+			...(execution?.verification_status === "reported" ? ["Execution is reported and not externally verified."] : []),
+			...(missingExecutionSlices > 0 ? [`Execution receipt is missing ${missingExecutionSlices} approved slices.`] : []),
+			...(extraExecutionSlices > 0 ? [`Execution receipt contains ${extraExecutionSlices} slices outside the approved allocation.`] : []),
+		],
+	};
+}

package/extensions/fpa-dashboard/publisher.ts

@@ -0,0 +1,170 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, 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 { validateDatasetForWidget } from "./schema.ts";
+
+const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}\.json$/;
+
+export interface PublishDashboardOptions {
+	cwd: string;
+	build: DashboardBuild;
+	publishedAt?: string;
+}
+
+export interface PublishDashboardResult {
+	dashboardDir: string;
+	fingerprint: string;
+	publishedDatasets: number;
+}
+
+interface PublishedDataset {
+	logical: string;
+	filename: string;
+	sha256: string;
+	contents: string;
+}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function assertBuild(build: DashboardBuild): void {
+	if (!build || typeof build !== "object") throw new Error("Dashboard build is required.");
+	if (typeof build.title !== "string" || build.title.trim() === "") throw new Error("Dashboard title is required.");
+	if (!Array.isArray(build.widgets) || build.widgets.length === 0 || build.widgets.length > 64) {
+		throw new Error("Dashboard must contain between 1 and 64 widgets.");
+	}
+	const ids = new Set<string>();
+	const datasets = new Set<string>();
+	for (const widget of build.widgets) {
+		if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(widget.id) || ids.has(widget.id)) throw new Error(`Invalid or duplicate dashboard widget id "${widget.id}".`);
+		ids.add(widget.id);
+		if (widget.type !== "stat" && widget.type !== "timeseries" && widget.type !== "table" && widget.type !== "grouped-table") throw new Error(`Unsupported dashboard widget type "${widget.type}".`);
+		if (widget.span !== "quarter" && widget.span !== "half" && widget.span !== "full") throw new Error(`Unsupported dashboard widget span "${widget.span}".`);
+		if (!DATASET_FILE_RE.test(widget.dataset)) throw new Error(`Invalid logical dataset name "${widget.dataset}".`);
+		if (datasets.has(widget.dataset)) throw new Error(`Duplicate logical dataset name "${widget.dataset}".`);
+		datasets.add(widget.dataset);
+		try {
+			validateDatasetForWidget(widget.type, widget.data);
+		} catch (error) {
+			throw new Error(`Widget "${widget.id}" dataset schema is invalid: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+}
+
+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`;
+	if (!DATASET_FILE_RE.test(filename)) {
+		throw new Error(`Content-addressed dataset name "${filename}" exceeds the dashboard contract.`);
+	}
+	return { logical: widget.dataset, filename, sha256: digest, contents };
+}
+
+async function pathKind(path: string): Promise<"missing" | "directory" | "symlink" | "other"> {
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink()) return "symlink";
+		if (stat.isDirectory()) return "directory";
+		return "other";
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
+		throw error;
+	}
+}
+
+async function ensureOwnedDirectory(path: string, label: string): Promise<void> {
+	const kind = await pathKind(path);
+	if (kind === "symlink") throw new Error(`${label} must not be a symlink.`);
+	if (kind === "other") throw new Error(`${label} must be a directory.`);
+	if (kind === "missing") await mkdir(path, { recursive: true, mode: 0o700 });
+}
+
+async function atomicWrite(destination: string, contents: string): Promise<void> {
+	const temporary = join(dirname(destination), `.${basename(destination)}.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	let closed = false;
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		closed = true;
+		await rename(temporary, destination);
+	} catch (error) {
+		if (!closed) await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+}
+
+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 {
+	assertBuild(build);
+	return sha256(stableJson({
+		title: build.title,
+		widgets: build.widgets,
+		source: build.source,
+		warnings: build.warnings,
+	}));
+}
+
+export async function publishDashboard(options: PublishDashboardOptions): Promise<PublishDashboardResult> {
+	assertBuild(options.build);
+	const dashboardDir = await resolveDashboardDir(options.cwd);
+	await ensureOwnedDirectory(dashboardDir, "Dashboard directory");
+	const datasetsDir = join(dashboardDir, "datasets");
+	await ensureOwnedDirectory(datasetsDir, "Dashboard datasets directory");
+
+	const publishedAt = options.publishedAt ?? new Date().toISOString();
+	const fingerprint = dashboardBuildFingerprint(options.build);
+	const datasets = options.build.widgets.map(contentAddressDataset);
+	for (const dataset of datasets) {
+		await atomicWrite(join(datasetsDir, dataset.filename), dataset.contents);
+	}
+
+	const receipt = {
+		kind: "fpa.dashboard.build",
+		schema_version: 1,
+		generation_id: fingerprint,
+		published_at: publishedAt,
+		source: options.build.source,
+		warnings: options.build.warnings,
+		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);
+	// 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);
+
+	const byLogical = new Map(datasets.map((dataset) => [dataset.logical, dataset.filename]));
+	const manifest = {
+		kind: "fpa.dashboard",
+		schemaVersion: 1,
+		title: options.build.title,
+		updatedAt: publishedAt,
+		generationId: fingerprint,
+		buildReceipt: receiptFilename,
+		widgets: options.build.widgets.map((widget) => ({
+			id: widget.id,
+			type: widget.type,
+			span: widget.span,
+			dataset: byLogical.get(widget.dataset),
+		})),
+	};
+	// 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`);
+	return { dashboardDir, fingerprint, publishedDatasets: datasets.length };
+}