@viccydev/pi-fpa 0.9.4 → 0.9.6

package/extensions/fpa-dashboard/finance-projector.ts

@@ -0,0 +1,375 @@
+import { realpath } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import { runStructuredQuery } from "../fpa-data/runtime.ts";
+import type { DashboardModuleBuild } from "./module-publisher.ts";
+import type { DashboardWidget, TableCell, WaterfallDataset } from "./projector.ts";
+
+// ============================================================================
+// The portfolio overview module.
+//
+// Answers "how is the business doing" from the finance datasets, which the UA
+// mart cannot reach: cash, cost structure, unit economics.
+//
+// Three constraints from the data contract are load-bearing here, and every
+// one of them exists because breaking it produces a number that looks right
+// and is wrong:
+//
+//   * Opex is a company-level cost. Per-app figures stop at contribution
+//     margin; only the portfolio has FCF. Allocating opex across apps would
+//     manufacture precision nobody measured.
+//
+//   * Runway is cash over fixed outflow, not over net burn. A burn-based
+//     runway is null or infinite while FCF is positive, which tells a reader
+//     nothing on the one screen where they came to ask the question.
+//
+//   * A month whose source rows were incomplete is reported as incomplete.
+//     Its total is understated, and presenting it as a clean aggregate hides
+//     that.
+// ============================================================================
+
+const MONEY_FIELDS = [
+	"gross_billings", "refunds", "platform_fee", "net_proceeds",
+	"ua_spend", "contribution_margin", "tax", "opex_total", "net_fcf",
+] as const;
+
+export interface FinanceProjectionOptions {
+	/** Inclusive month bounds, YYYY-MM. Defaults to the last 13 months present. */
+	months?: number;
+	locale?: string;
+	signal?: AbortSignal;
+	/**
+	 * The project directory. Its workspace owns the finance CSVs, so one
+	 * tenant can never project another tenant's financials.
+	 */
+	cwd?: string;
+}
+
+export interface FinanceProjection {
+	module: DashboardModuleBuild;
+	/** The latest closed month the projection reports on. */
+	closedMonth: string | null;
+	/** The open month, when the source carries one. */
+	openMonth: string | null;
+}
+
+function currency(value: number | null, locale: string, maximumFractionDigits = 0): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "currency", currency: "USD", maximumFractionDigits }).format(value);
+}
+
+function percent(value: number | null, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 }).format(value);
+}
+
+function ratio(value: number | null, locale: string): string | null {
+	if (value === null) return null;
+	return `${new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(value)}x`;
+}
+
+function toned(value: string | null, tone?: "positive" | "negative" | "warning" | "neutral"): TableCell {
+	return tone ? { value, tone } : value;
+}
+
+function num(row: Record<string, unknown> | undefined, key: string): number | null {
+	const value = row?.[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function text(row: Record<string, unknown> | undefined, key: string): string | null {
+	const value = row?.[key];
+	return typeof value === "string" && value !== "" ? value : null;
+}
+
+/**
+ * The P&L bridge for one month.
+ *
+ * Deductions are emitted as negative deltas so the chart never has to infer a
+ * sign, and the two anchors are marked `total` so they are drawn from zero
+ * rather than floating on the step before them.
+ */
+function pnlWaterfall(row: Record<string, unknown>, month: string, locale: string): WaterfallDataset {
+	const step = (key: string, label: string, negate: boolean, kind: "total" | "delta", tone?: "positive" | "negative" | "warning" | "neutral") => {
+		const raw = num(row, key);
+		const value = raw === null ? null : negate ? -raw : raw;
+		return { label, value, display: currency(value, locale), kind, ...(tone ? { tone } : {}) };
+	};
+	return {
+		label: "利润桥",
+		description: "从流水到净自由现金流，逐项拆解",
+		coverage: month,
+		steps: [
+			step("gross_billings", "流水", false, "total"),
+			step("refunds", "退款", true, "delta"),
+			step("platform_fee", "平台分成", true, "delta"),
+			step("tax", "税费", true, "delta"),
+			step("ua_spend", "广告投放", true, "delta"),
+			step("opex_total", "运营成本", true, "delta"),
+			step("net_fcf", "净自由现金流", false, "total", "positive"),
+		],
+	};
+}
+
+export async function projectPortfolioOverview(options: FinanceProjectionOptions = {}): Promise<FinanceProjection> {
+	const locale = options.locale ?? "zh-CN";
+	const workspaceRoot = options.cwd ? dirname(await realpath(options.cwd)) : undefined;
+	const limit = options.months ?? 24;
+	const warnings: string[] = [];
+
+	const pnl = await runStructuredQuery({
+		dataset: "pnl_monthly",
+		metrics: [...MONEY_FIELDS, "fcf_margin", "roas_blended"],
+		dimensions: ["month", "close_status", "data_completeness"],
+		limit,
+	}, options.signal, workspaceRoot);
+	const months = pnl.rows.slice().sort((left, right) => String(left.month).localeCompare(String(right.month)));
+	if (months.length === 0) throw new Error("The finance source contains no P&L months; nothing can be projected.");
+
+	const closedRows = months.filter((row) => text(row, "close_status") === "closed");
+	const openRow = months.find((row) => text(row, "close_status") === "open");
+	const latestClosed = closedRows.at(-1);
+	const closedMonth = latestClosed ? String(latestClosed.month) : null;
+	const priorClosed = closedRows.at(-2);
+
+	// An incomplete month is named, not silently totalled.
+	for (const row of months) {
+		if (text(row, "data_completeness") === "partial") {
+			warnings.push(`${String(row.month)} 的组合合计不完整：有来源明细缺失，该月总额被低估。`);
+		}
+	}
+	if (openRow) {
+		warnings.push(`${String(openRow.month)} 尚未结账，其税费、运营成本与净自由现金流显示为缺失而非零。`);
+	}
+
+	const cash = await runStructuredQuery({
+		dataset: "cash_position_monthly",
+		metrics: ["closing_cash", "runway_months", "monthly_fixed_outflow"],
+		dimensions: ["month"],
+		filters: { close_status: "closed" },
+		limit,
+	}, options.signal, workspaceRoot);
+	const latestCash = cash.rows.slice().sort((left, right) => String(left.month).localeCompare(String(right.month))).at(-1);
+
+	const byApp = await runStructuredQuery({
+		dataset: "pnl_by_app_monthly",
+		metrics: ["net_proceeds", "ua_spend", "contribution_margin", "app_roas"],
+		dimensions: ["app_id", "app_name", "store"],
+		...(closedMonth ? { filters: { month: closedMonth } } : {}),
+		sort: { by: "contribution_margin", direction: "desc" },
+		limit: 100,
+	}, options.signal, workspaceRoot);
+
+	const opex = await runStructuredQuery({
+		dataset: "opex_monthly",
+		metrics: ["amount_usd"],
+		dimensions: ["category"],
+		...(closedMonth ? { filters: { month: closedMonth, close_status: "closed" } } : {}),
+		limit: 20,
+	}, options.signal, workspaceRoot);
+
+	const cohorts = await runStructuredQuery({
+		dataset: "cohort_ltv",
+		metrics: ["installs", "ua_spend", "cac", "ltv_180", "roas_d180", "ltv_to_cac"],
+		dimensions: ["store", "maturity"],
+		filters: { maturity: "mature" },
+		limit: 20,
+	}, options.signal, workspaceRoot);
+	if (cohorts.rows.length === 0) {
+		warnings.push("尚无成熟 cohort，LTV 与回收期显示为缺失。");
+	}
+
+	const fcf = num(latestClosed, "net_fcf");
+	const priorFcf = num(priorClosed, "net_fcf");
+	const fcfDelta = fcf !== null && priorFcf !== null && priorFcf !== 0 ? fcf / priorFcf - 1 : null;
+
+	const widgets: DashboardWidget[] = [
+		{
+			id: "portfolio-fcf",
+			type: "stat",
+			span: "quarter",
+			dataset: "portfolio-fcf.json",
+			data: {
+				label: "净自由现金流",
+				value: currency(fcf, locale),
+				...(fcf === null ? { missingReason: "最近月份尚未结账。" } : {}),
+				...(fcfDelta !== null
+					? { delta: { direction: fcfDelta >= 0 ? "up" as const : "down" as const, label: `${fcfDelta > 0 ? "+" : ""}${percent(fcfDelta, locale)}`, sentiment: fcfDelta >= 0 ? "positive" as const : "negative" as const } }
+					: {}),
+				...(closedMonth ? { footnote: `${closedMonth} 已结账` } : {}),
+			},
+		},
+		{
+			id: "portfolio-runway",
+			type: "stat",
+			span: "quarter",
+			dataset: "portfolio-runway.json",
+			data: {
+				label: "现金 Runway",
+				value: num(latestCash, "runway_months") === null ? null : `${num(latestCash, "runway_months")!.toFixed(1)} 月`,
+				...(num(latestCash, "runway_months") === null ? { missingReason: "尚无已结账的现金头寸。" } : {}),
+				description: `期末现金 ${currency(num(latestCash, "closing_cash"), locale) ?? "—"}`,
+				// Naming the definition on the card stops it being read as
+				// burn-based runway, which would be a much shorter number.
+				footnote: "口径：期末现金 ÷ 月固定支出（运营成本 + 投放）",
+			},
+		},
+		{
+			id: "portfolio-contribution",
+			type: "stat",
+			span: "quarter",
+			dataset: "portfolio-contribution.json",
+			data: {
+				label: "贡献毛利",
+				value: currency(num(latestClosed, "contribution_margin"), locale),
+				description: "净收入 − 广告投放",
+				footnote: "运营成本为公司级，不摊到 App",
+			},
+		},
+		{
+			id: "portfolio-fcf-margin",
+			type: "stat",
+			span: "quarter",
+			dataset: "portfolio-fcf-margin.json",
+			data: {
+				label: "现金流利润率",
+				value: percent(num(latestClosed, "fcf_margin"), locale),
+				...(num(latestClosed, "fcf_margin") === null ? { missingReason: "该月尚未结账。" } : {}),
+				...(num(latestClosed, "fcf_margin") !== null
+					? {
+						progress: {
+							fraction: Math.max(0, Math.min(1, num(latestClosed, "fcf_margin")!)),
+							label: percent(num(latestClosed, "fcf_margin"), locale) ?? "—",
+							tone: (num(latestClosed, "fcf_margin")! >= 0.3 ? "positive" : "warning") as "positive" | "warning",
+						},
+					}
+					: {}),
+			},
+		},
+	];
+
+	if (latestClosed) {
+		widgets.push({
+			id: "portfolio-pnl-bridge",
+			type: "waterfall",
+			span: "full",
+			dataset: "portfolio-pnl-bridge.json",
+			data: pnlWaterfall(latestClosed, closedMonth ?? "", locale),
+		});
+	}
+
+	widgets.push({
+		id: "portfolio-fcf-trend",
+		type: "timeseries",
+		span: "full",
+		dataset: "portfolio-fcf-trend.json",
+		data: {
+			label: "净收入与现金流走势",
+			description: "按月，未结账月份留空",
+			coverage: `${String(months[0].month)} → ${String(months.at(-1)!.month)}`,
+			series: [
+				{ name: "净收入", points: months.map((row) => ({ x: String(row.month), y: num(row, "net_proceeds") })) },
+				{ name: "净自由现金流", points: months.map((row) => ({ x: String(row.month), y: num(row, "net_fcf") })) },
+			],
+		},
+	});
+
+	if (opex.rows.length > 0) {
+		widgets.push({
+			id: "portfolio-cost-structure",
+			type: "stacked-bar",
+			span: "half",
+			dataset: "portfolio-cost-structure.json",
+			data: {
+				label: "成本结构",
+				description: closedMonth ? `${closedMonth} 运营成本构成` : "运营成本构成",
+				bars: [{
+					label: closedMonth ?? "最近已结账月",
+					total: currency(num(latestClosed, "opex_total"), locale),
+					segments: opex.rows.map((row) => ({
+						name: String(row.category),
+						value: num(row, "amount_usd"),
+						display: currency(num(row, "amount_usd"), locale),
+					})),
+				}],
+			},
+		});
+	}
+
+	widgets.push({
+		id: "portfolio-unit-economics",
+		type: "table",
+		span: "half",
+		dataset: "portfolio-unit-economics.json",
+		data: {
+			label: "单位经济（成熟 cohort）",
+			description: "仅统计满 180 天的 cohort；未成熟的显示为缺失",
+			columns: [
+				{ key: "store", label: "商店" },
+				{ key: "installs", label: "安装", align: "right" },
+				{ key: "cac", label: "CAC", align: "right" },
+				{ key: "ltv", label: "LTV 180", align: "right" },
+				{ key: "ltv_cac", label: "LTV/CAC", align: "right" },
+				{ key: "roas", label: "ROAS 180", align: "right" },
+			],
+			rows: cohorts.rows.map((row) => ({
+				store: String(row.store),
+				installs: num(row, "installs") === null ? null : new Intl.NumberFormat(locale).format(num(row, "installs")!),
+				cac: currency(num(row, "cac"), locale, 2),
+				ltv: currency(num(row, "ltv_180"), locale, 2),
+				ltv_cac: toned(ratio(num(row, "ltv_to_cac"), locale), num(row, "ltv_to_cac") === null ? undefined : num(row, "ltv_to_cac")! >= 1.5 ? "positive" : "warning"),
+				roas: ratio(num(row, "roas_d180"), locale),
+			})),
+		},
+	});
+
+	widgets.push({
+		id: "portfolio-by-app",
+		type: "table",
+		span: "full",
+		dataset: "portfolio-by-app.json",
+		data: {
+			label: "App 贡献",
+			description: closedMonth ? `${closedMonth}，按贡献毛利排序。运营成本为公司级，故此处不含 FCF。` : "按贡献毛利排序",
+			columns: [
+				{ key: "app", label: "App" },
+				{ key: "store", label: "商店" },
+				{ key: "net_proceeds", label: "净收入", align: "right" },
+				{ key: "ua_spend", label: "投放", align: "right" },
+				{ key: "contribution", label: "贡献毛利", align: "right" },
+				{ key: "roas", label: "ROAS", align: "right" },
+			],
+			rows: byApp.rows.map((row) => ({
+				app: `${text(row, "app_name") ?? String(row.app_id)}（${String(row.app_id)}）`,
+				store: String(row.store),
+				net_proceeds: currency(num(row, "net_proceeds"), locale),
+				ua_spend: currency(num(row, "ua_spend"), locale),
+				contribution: toned(
+					currency(num(row, "contribution_margin"), locale),
+					num(row, "contribution_margin") === null ? undefined : num(row, "contribution_margin")! < 0 ? "negative" : "positive",
+				),
+				roas: ratio(num(row, "app_roas"), locale),
+			})),
+		},
+	});
+
+	return {
+		module: {
+			id: "portfolio-overview",
+			title: "组合总览",
+			status: "published",
+			source: {
+				artifact_type: "finance_csv",
+				closed_month: closedMonth,
+				open_month: openRow ? String(openRow.month) : null,
+				month_count: months.length,
+				datasets: ["pnl_monthly", "pnl_by_app_monthly", "opex_monthly", "cash_position_monthly", "cohort_ltv"],
+				data_as_of: closedMonth,
+			},
+			warnings,
+			widgets,
+		},
+		closedMonth,
+		openMonth: openRow ? String(openRow.month) : null,
+	};
+}

package/extensions/fpa-dashboard/index.ts

@@ -13,6 +13,10 @@ import {
 	transitionStrategyModule,
 } from "./module-publisher.ts";
 import { projectForecastModule, projectReviewModule, projectStrategyModule } from "./stage-projector.ts";
+import { projectDecisionLedger } from "./decision-ledger-projector.ts";
+import { projectPortfolioOverview } from "./finance-projector.ts";
+import { projectCalibration } from "./calibration-projector.ts";
+import { listDecisionPackages, readDecisionEvents } from "./decision-package.ts";
 import type { ApprovedCycleForecast } from "../fpa-artifacts/contracts.ts";
 import { commitStrategyDecision, createStrategyDecisionRequest, readCommittedStrategyDecision } from "./strategy-decision.ts";
 import {
@@ -262,6 +266,188 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "fpa_dashboard_publish_decisions",
+		label: "Publish FP&A Decision Ledger Module",
+		description: "Preview or publish only the decision-ledger module from committed decision packages and their append-only event logs. Other dashboard modules are preserved.",
+		promptSnippet: "Publish the approved decision packages and their execution tracking",
+		promptGuidelines: [
+			"This tool is called by the main Agent; never add it to a Graph tool allowlist.",
+			"Preview first, then publish with the exact preview fingerprint and dashboard revision.",
+			"Supply measured spend only from an execution receipt or the actuals source. Never estimate it — an unmeasured decision must stay null, because a zero reads as 'nobody acted on this'.",
+		],
+		parameters: Type.Object({
+			mode: StringEnum(["preview", "publish"] as const),
+			expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+			expected_dashboard_revision: Type.Optional(Type.Union([Type.String({ pattern: "^[a-f0-9]{64}$" }), Type.Null()])),
+			dashboard_title: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+			/** Measured spend per decision. Omitted decisions render as unmeasured. */
+			spend: Type.Optional(Type.Array(Type.Object({
+				decision_id: Type.String({ pattern: "^DEC-\\d{4}-\\d{4}-[a-f0-9]{8}$" }),
+				actual_spend_usd: Type.Union([Type.Number(), Type.Null()]),
+				progress: Type.Optional(Type.Union([Type.Number({ minimum: 0, maximum: 1 }), Type.Null()])),
+				source: Type.Optional(Type.String({ minLength: 1, maxLength: 512 })),
+			}, { additionalProperties: false }), { maxItems: 500 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const packages = await listDecisionPackages(ctx.cwd);
+			if (packages.length === 0) throw new Error("No decision packages exist yet; confirm a strategy before publishing the decision ledger.");
+			const events: Record<string, Awaited<ReturnType<typeof readDecisionEvents>>> = {};
+			for (const pkg of packages) events[pkg.decision_id] = await readDecisionEvents(ctx.cwd, pkg.decision_id);
+			const known = new Set(packages.map((pkg) => pkg.decision_id));
+			for (const entry of params.spend ?? []) {
+				if (!known.has(entry.decision_id)) throw new Error(`spend references unknown decision package ${entry.decision_id}.`);
+			}
+			const { module, breaches } = projectDecisionLedger({ packages, events, spend: params.spend ?? [] });
+			const previewFingerprint = dashboardModuleBuildFingerprint(module);
+			const current = await readDashboardModuleManifest(ctx.cwd);
+			if (params.mode === "preview") return toolResult({
+				status: "ready",
+				module_id: module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: current?.dashboardRevision ?? null,
+				widget_count: module.widgets.length,
+				package_count: packages.length,
+				threshold_breaches: breaches,
+				warnings: module.warnings ?? [],
+			});
+			if (params.expected_preview_fingerprint !== previewFingerprint) throw new Error("Decision ledger inputs changed after preview; preview again before publishing.");
+			if (params.expected_dashboard_revision === undefined) throw new Error("Publish requires expected_dashboard_revision from preview, including null for a new dashboard.");
+			const published = await publishDashboardModule({
+				cwd: ctx.cwd,
+				module,
+				dashboardTitle: params.dashboard_title,
+				expectedDashboardRevision: params.expected_dashboard_revision,
+			});
+			return toolResult({
+				status: "published",
+				module_id: module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: published.dashboardRevision,
+				module_revision: published.moduleRevision,
+				threshold_breaches: breaches,
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_dashboard_publish_portfolio",
+		label: "Publish FP&A Portfolio Overview Module",
+		description: "Preview or publish only the portfolio-overview module from the finance datasets (P&L, cash, opex, cohorts). Other dashboard modules are preserved.",
+		promptSnippet: "Publish the portfolio financial overview",
+		promptGuidelines: [
+			"This tool is called by the main Agent; never add it to a Graph tool allowlist.",
+			"Preview first, then publish with the exact preview fingerprint and dashboard revision.",
+			"Requires FPA_FINANCE_CSV_ROOT to point at the finance data directory.",
+			"Report the module's warnings to the user: an unclosed month and an incomplete total are limits on the decision, not formatting details.",
+		],
+		parameters: Type.Object({
+			mode: StringEnum(["preview", "publish"] as const),
+			expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+			expected_dashboard_revision: Type.Optional(Type.Union([Type.String({ pattern: "^[a-f0-9]{64}$" }), Type.Null()])),
+			dashboard_title: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+			months: Type.Optional(Type.Integer({ minimum: 2, maximum: 120 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const projection = await projectPortfolioOverview({
+				cwd: ctx.cwd,
+				...(params.months !== undefined ? { months: params.months } : {}),
+				...(signal ? { signal } : {}),
+			});
+			const previewFingerprint = dashboardModuleBuildFingerprint(projection.module);
+			const current = await readDashboardModuleManifest(ctx.cwd);
+			if (params.mode === "preview") return toolResult({
+				status: "ready",
+				module_id: projection.module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: current?.dashboardRevision ?? null,
+				widget_count: projection.module.widgets.length,
+				closed_month: projection.closedMonth,
+				open_month: projection.openMonth,
+				warnings: projection.module.warnings ?? [],
+			});
+			if (params.expected_preview_fingerprint !== previewFingerprint) throw new Error("Portfolio inputs changed after preview; preview again before publishing.");
+			if (params.expected_dashboard_revision === undefined) throw new Error("Publish requires expected_dashboard_revision from preview, including null for a new dashboard.");
+			const published = await publishDashboardModule({
+				cwd: ctx.cwd,
+				module: projection.module,
+				dashboardTitle: params.dashboard_title,
+				expectedDashboardRevision: params.expected_dashboard_revision,
+			});
+			return toolResult({
+				status: "published",
+				module_id: projection.module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: published.dashboardRevision,
+				module_revision: published.moduleRevision,
+				warnings: projection.module.warnings ?? [],
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_dashboard_publish_calibration",
+		label: "Publish FP&A Calibration Module",
+		description: "Preview or publish only the forecast-accuracy module: model error, bias direction, variance attribution, and the baseline corrections detected against it. Other dashboard modules are preserved.",
+		promptSnippet: "Publish forecast accuracy and the baseline corrections it implies",
+		promptGuidelines: [
+			"This tool is called by the main Agent; never add it to a Graph tool allowlist.",
+			"Preview first, then publish with the exact preview fingerprint and dashboard revision.",
+			"A suggested baseline is a proposal awaiting its approver. Never apply one to a forecast before it is approved, and never describe a pending correction as if it were in force.",
+			"Report the bias run and the attribution coverage to the user: a partly-explained variance is a limit on the conclusion, not a rounding detail.",
+		],
+		parameters: Type.Object({
+			mode: StringEnum(["preview", "publish"] as const),
+			metric: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
+			horizon_months: Type.Optional(Type.Integer({ minimum: 1, maximum: 24 })),
+			month: Type.Optional(Type.String({ pattern: "^\\d{4}-\\d{2}$" })),
+			expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+			expected_dashboard_revision: Type.Optional(Type.Union([Type.String({ pattern: "^[a-f0-9]{64}$" }), Type.Null()])),
+			dashboard_title: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const projection = await projectCalibration({
+				cwd: ctx.cwd,
+				...(params.metric !== undefined ? { metric: params.metric } : {}),
+				...(params.horizon_months !== undefined ? { horizonMonths: params.horizon_months } : {}),
+				...(params.month !== undefined ? { month: params.month } : {}),
+				...(signal ? { signal } : {}),
+			});
+			const previewFingerprint = dashboardModuleBuildFingerprint(projection.module);
+			const current = await readDashboardModuleManifest(ctx.cwd);
+			if (params.mode === "preview") return toolResult({
+				status: "ready",
+				module_id: projection.module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: current?.dashboardRevision ?? null,
+				widget_count: projection.module.widgets.length,
+				mape: projection.mape,
+				bias_run: projection.biasRun,
+				pending_corrections: projection.pendingCorrections,
+				warnings: projection.module.warnings ?? [],
+			});
+			if (params.expected_preview_fingerprint !== previewFingerprint) throw new Error("Calibration inputs changed after preview; preview again before publishing.");
+			if (params.expected_dashboard_revision === undefined) throw new Error("Publish requires expected_dashboard_revision from preview, including null for a new dashboard.");
+			const published = await publishDashboardModule({
+				cwd: ctx.cwd,
+				module: projection.module,
+				dashboardTitle: params.dashboard_title,
+				expectedDashboardRevision: params.expected_dashboard_revision,
+			});
+			return toolResult({
+				status: "published",
+				module_id: projection.module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: published.dashboardRevision,
+				module_revision: published.moduleRevision,
+				warnings: projection.module.warnings ?? [],
+			});
+		},
+	});
+
 	pi.registerTool({
 		name: "fpa_dashboard_status",
 		label: "FP&A Dashboard Status",

package/extensions/fpa-dashboard/projector.ts

@@ -52,11 +52,36 @@ export interface GroupedTableDataset {
 	}>;
 }
 
+export interface WaterfallDataset {
+	label: string;
+	description?: string;
+	coverage?: string;
+	steps: Array<{
+		label: string;
+		value: number | null;
+		display: string | null;
+		kind?: "total" | "delta";
+		tone?: "positive" | "negative" | "warning" | "neutral";
+	}>;
+}
+
+export interface StackedBarDataset {
+	label: string;
+	description?: string;
+	bars: Array<{
+		label: string;
+		total: string | null;
+		segments: Array<{ name: string; value: number | null; display: string | null }>;
+	}>;
+}
+
 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 };
+	| { id: string; type: "grouped-table"; span: "quarter" | "half" | "full"; dataset: string; data: GroupedTableDataset }
+	| { id: string; type: "waterfall"; span: "quarter" | "half" | "full"; dataset: string; data: WaterfallDataset }
+	| { id: string; type: "stacked-bar"; span: "quarter" | "half" | "full"; dataset: string; data: StackedBarDataset };
 
 export interface DashboardBuild {
 	title: string;