@viccydev/pi-fpa 0.2.1 → 0.3.1

package/extensions/fpa-artifacts/index.ts

@@ -0,0 +1,42 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { commitArtifact } from "./store.ts";
+
+function toolResult(value: Record<string, unknown>) {
+	return {
+		content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }],
+		details: value,
+	};
+}
+
+export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "fpa_artifact_commit",
+		label: "Commit FP&A Artifact",
+		description:
+			"Validate, reconcile, fingerprint, and atomically commit a canonical FP&A artifact under the current project's artifacts directory. " +
+			"Use this instead of claiming a Markdown report is frozen. Supported v1 artifacts are approved_cycle_forecast and execution_receipt.",
+		promptSnippet: "Validate and durably freeze a canonical FP&A artifact",
+		promptGuidelines: [
+			"Use fpa_artifact_commit before calling an approved forecast immutable or using it to publish a dashboard.",
+			"Do not supply immutable_fingerprint; the tool calculates it after validation and reconciliation.",
+		],
+		parameters: Type.Object(
+			{
+				artifact: Type.Unknown({ description: "Canonical artifact object matching the referenced FP&A artifact contract" }),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const committed = await commitArtifact(ctx.cwd, params.artifact);
+			return toolResult({
+				status: "committed",
+				artifact_type: committed.artifactType,
+				immutable_fingerprint: committed.fingerprint,
+				path: committed.path,
+			});
+		},
+	});
+}

package/extensions/fpa-artifacts/store.ts

@@ -0,0 +1,129 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+	validateArtifact,
+	validateExecutionAgainstForecast,
+	type ArtifactType,
+	type CanonicalArtifact,
+	type CanonicalArtifactInput,
+} from "./contracts.ts";
+
+export interface CommitArtifactResult {
+	artifactType: ArtifactType;
+	fingerprint: string;
+	path: string;
+}
+
+export interface ReadArtifactResult {
+	artifact: CanonicalArtifact;
+	fingerprint: string;
+	path: string;
+}
+
+export function stableJson(value: unknown): string {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+	if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (typeof value !== "object") throw new Error("stableJson accepts only JSON-compatible values.");
+	const source = value as Record<string, unknown>;
+	return `{${Object.keys(source).sort().map((key) => `${JSON.stringify(key)}:${stableJson(source[key])}`).join(",")}}`;
+}
+
+export function artifactFingerprint(artifact: CanonicalArtifactInput): string {
+	return createHash("sha256").update(stableJson(artifact)).digest("hex");
+}
+
+async function ensureArtifactDirectory(projectRoot: string): Promise<string> {
+	const root = await realpath(projectRoot);
+	const artifactsDir = join(root, "artifacts");
+	try {
+		const stat = await lstat(artifactsDir);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Project artifacts path must be a regular directory, not a symlink.");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(artifactsDir, { mode: 0o700 });
+		const stat = await lstat(artifactsDir);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Project artifacts path must be a regular directory, not a symlink.");
+	}
+	return artifactsDir;
+}
+
+async function existingArtifactDirectory(projectRoot: string): Promise<string> {
+	const root = await realpath(projectRoot);
+	const artifactsDir = join(root, "artifacts");
+	const stat = await lstat(artifactsDir);
+	if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Project artifacts path must be a regular directory, not a symlink.");
+	return artifactsDir;
+}
+
+export async function commitArtifact(projectRoot: string, input: unknown): Promise<CommitArtifactResult> {
+	const artifact = validateArtifact(input);
+	if (artifact.artifact_type === "execution_receipt") {
+		const forecastRead = await readCommittedArtifact(projectRoot, "approved_cycle_forecast");
+		if (forecastRead.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("Committed approved forecast has the wrong artifact type.");
+		validateExecutionAgainstForecast(artifact, forecastRead.artifact);
+	}
+	const fingerprint = artifactFingerprint(artifact);
+	const committed = { ...artifact, immutable_fingerprint: fingerprint } as CanonicalArtifact;
+	const artifactsDir = await ensureArtifactDirectory(projectRoot);
+	const destination = join(artifactsDir, `${artifact.artifact_type}.json`);
+	const temporary = join(artifactsDir, `.${artifact.artifact_type}.${randomUUID()}.tmp`);
+
+	const handle = await open(temporary, "wx", 0o600);
+	let closed = false;
+	try {
+		await handle.writeFile(`${JSON.stringify(committed, null, 2)}\n`, "utf8");
+		await handle.sync();
+		await handle.close();
+		closed = true;
+		await rename(temporary, destination);
+		const directoryHandle = await open(artifactsDir, "r");
+		try {
+			await directoryHandle.sync();
+		} finally {
+			await directoryHandle.close();
+		}
+	} catch (error) {
+		if (!closed) await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+
+	return { artifactType: artifact.artifact_type, fingerprint, path: destination };
+}
+
+export async function readCommittedArtifact(projectRoot: string, artifactType: ArtifactType): Promise<ReadArtifactResult> {
+	const path = join(await existingArtifactDirectory(projectRoot), `${artifactType}.json`);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${artifactType} must be a regular file, not a symlink.`);
+	if (stat.size > 2 * 1024 * 1024) throw new Error(`${artifactType} exceeds the 2MB artifact limit.`);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		throw new Error(`${artifactType} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${artifactType} must contain a JSON object.`);
+	const source = { ...(parsed as Record<string, unknown>) };
+	const fingerprint = source.immutable_fingerprint;
+	delete source.immutable_fingerprint;
+	if (typeof fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(fingerprint)) {
+		throw new Error(`${artifactType} has no valid immutable_fingerprint.`);
+	}
+	const artifact = validateArtifact(source);
+	if (artifact.artifact_type !== artifactType) throw new Error(`${path} contains ${artifact.artifact_type}, expected ${artifactType}.`);
+	const expected = artifactFingerprint(artifact);
+	if (expected !== fingerprint) throw new Error(`${artifactType} fingerprint mismatch: the committed artifact was modified after freezing.`);
+	return { artifact: { ...artifact, immutable_fingerprint: fingerprint } as CanonicalArtifact, fingerprint, path };
+}
+
+export async function readOptionalCommittedArtifact(projectRoot: string, artifactType: ArtifactType): Promise<ReadArtifactResult | null> {
+	try {
+		return await readCommittedArtifact(projectRoot, artifactType);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+}

package/extensions/fpa-dashboard/actuals.ts

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+
+import type { Period } from "../fpa-artifacts/contracts.ts";
+import { toNumber, type NumericLike } from "../fpa-data/calc.ts";
+import { runStructuredQuery } from "../fpa-data/runtime.ts";
+import type { SqlRow } from "../fpa-data/supabase.ts";
+import type { DashboardActualsSnapshot, DashboardDailyPoint, DashboardScopeMode, QueryReceipt } from "./source.ts";
+import { ACTUALS_DATA_AS_OF_UNAVAILABLE } from "./source.ts";
+
+function dateInTimezone(timestamp: string, timezone: string, label: string): string {
+	const instant = new Date(timestamp);
+	if (Number.isNaN(instant.getTime())) throw new Error(`${label} is not a valid timestamp.`);
+	let parts: Intl.DateTimeFormatPart[];
+	try {
+		parts = new Intl.DateTimeFormat("en-US", {
+			timeZone: timezone,
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+		}).formatToParts(instant);
+	} catch {
+		throw new Error(`target_period.timezone "${timezone}" is not supported.`);
+	}
+	const byType = new Map(parts.map((part) => [part.type, part.value]));
+	return `${byType.get("year")}-${byType.get("month")}-${byType.get("day")}`;
+}
+
+function addCalendarDays(value: string, days: number): string {
+	const date = new Date(`${value}T00:00:00Z`);
+	if (Number.isNaN(date.getTime())) throw new Error(`Invalid calendar date "${value}".`);
+	date.setUTCDate(date.getUTCDate() + days);
+	return date.toISOString().slice(0, 10);
+}
+
+function calendarDayDistance(from: string, to: string): number {
+	const start = new Date(`${from}T00:00:00Z`).getTime();
+	const end = new Date(`${to}T00:00:00Z`).getTime();
+	if (!Number.isFinite(start) || !Number.isFinite(end)) throw new Error("Calendar dates must use YYYY-MM-DD.");
+	return Math.round((end - start) / 86_400_000);
+}
+
+function queryFingerprint(sql: string): string {
+	return createHash("sha256").update(sql).digest("hex");
+}
+
+function value(row: SqlRow | undefined, name: string): number | null {
+	return toNumber(row?.[name] as NumericLike);
+}
+
+function receipt(dataset: string, sql: string, rowCount: number): QueryReceipt {
+	return { dataset, query_fingerprint: queryFingerprint(sql), row_count: rowCount };
+}
+
+export function calendarQueryDates(period: Period): {
+	currentFrom: string;
+	currentTo: string;
+} {
+	const currentFrom = dateInTimezone(period.start_inclusive, period.timezone, "target_period.start_inclusive");
+	const endExclusive = dateInTimezone(period.end_exclusive, period.timezone, "target_period.end_exclusive");
+	const days = calendarDayDistance(currentFrom, endExclusive);
+	if (days < 1) throw new Error("Dashboard target period must contain at least one day.");
+	return {
+		currentFrom,
+		currentTo: addCalendarDays(endExclusive, -1),
+	};
+}
+
+export function comparisonDatesForCoverage(currentFrom: string, coverageMax: string): {
+	comparisonFrom: string;
+	comparisonTo: string;
+} {
+	const elapsedDays = calendarDayDistance(currentFrom, coverageMax) + 1;
+	if (elapsedDays < 1) throw new Error("Actuals coverage cannot end before the target period starts.");
+	const comparisonTo = addCalendarDays(currentFrom, -1);
+	return {
+		comparisonFrom: addCalendarDays(comparisonTo, -(elapsedDays - 1)),
+		comparisonTo,
+	};
+}
+
+function completeDailySeries(
+	rows: SqlRow[],
+	from: string,
+	coverageMax: string | null,
+): DashboardDailyPoint[] {
+	if (!coverageMax) return [];
+	const byDate = new Map(rows.map((row) => [String(row.period).slice(0, 10), row]));
+	const result: DashboardDailyPoint[] = [];
+	for (let date = from; date <= coverageMax; date = addCalendarDays(date, 1)) {
+		const row = byDate.get(date);
+		result.push({ date, spend: value(row, "spend"), revenue: value(row, "revenue") });
+	}
+	return result;
+}
+
+export interface DashboardActualsScope {
+	slices: Array<{ app_id: string; store: string; channel_group: string }>;
+}
+
+/**
+ * Rows carry app_code only in "app" scope mode. In "portfolio" mode the App axis was
+ * collapsed onto a placeholder before the query ran, so the caller supplies it back.
+ */
+export function mapDashboardSlices(rows: SqlRow[], portfolioAppId?: string) {
+	return rows
+		.filter((row) => row.platform != null && row.media_source != null)
+		.filter((row) => portfolioAppId !== undefined || row.app_code != null)
+		.map((row) => ({
+			app_id: portfolioAppId ?? String(row.app_code),
+			store: String(row.platform),
+			channel_group: String(row.media_source),
+			spend: value(row, "spend"),
+			revenue: value(row, "revenue"),
+			source_rows: value(row, "source_rows") ?? 0,
+		}));
+}
+
+/**
+ * The App axis carries no information when every approved slice shares one app_id.
+ * That is the only case where dropping the app_code predicate can be considered.
+ */
+export function collapsedAppId(slices: DashboardActualsScope["slices"]): string | null {
+	const appIds = new Set(slices.map((slice) => slice.app_id));
+	return appIds.size === 1 ? (slices[0]?.app_id ?? null) : null;
+}
+
+/** True when the value is never used as an app_code in ua_spend, i.e. it is a placeholder. */
+async function isPlaceholderAppId(appId: string, signal?: AbortSignal): Promise<boolean> {
+	const probe = await runStructuredQuery(
+		{ dataset: "ua_spend", metrics: ["spend"], dimensions: ["app_code"], filters: { app_code: appId }, limit: 1 },
+		signal,
+	);
+	return probe.rows.length === 0;
+}
+
+export async function resolveScopeMode(
+	slices: DashboardActualsScope["slices"],
+	signal?: AbortSignal,
+): Promise<{ mode: DashboardScopeMode; portfolioAppId: string | null }> {
+	const collapsed = collapsedAppId(slices);
+	if (collapsed === null) return { mode: "app", portfolioAppId: null };
+	// A single real app still scopes on app_code; only a value absent from the mart is a placeholder.
+	if (!(await isPlaceholderAppId(collapsed, signal))) return { mode: "app", portfolioAppId: null };
+	return { mode: "portfolio", portfolioAppId: collapsed };
+}
+
+export async function loadDashboardActuals(
+	period: Period,
+	scope: DashboardActualsScope,
+	signal?: AbortSignal,
+): Promise<DashboardActualsSnapshot> {
+	if (scope.slices.length === 0) throw new Error("Dashboard Actuals scope requires at least one approved slice.");
+	const dates = calendarQueryDates(period);
+	const uniqueSlices = [...new Map(scope.slices.map((slice) => [`${slice.app_id}\u0000${slice.store}\u0000${slice.channel_group}`, slice])).values()];
+	const common = {
+		dataset: "ua_spend" as const,
+		metrics: ["spend", "revenue", "roas"],
+	};
+	const exactUaScope = uniqueSlices.map((slice) => ({ app_code: slice.app_id, platform: slice.store, media_source: slice.channel_group }));
+	const exactUaPortfolioScope = [...new Map(uniqueSlices.map((slice) => [`${slice.app_id}\u0000${slice.store}`, { app_code: slice.app_id, platform: slice.store }])).values()];
+	const { mode, portfolioAppId } = await resolveScopeMode(uniqueSlices, signal);
+	const portfolio = mode === "portfolio";
+	// In portfolio mode the App axis is a placeholder absent from ua_spend, so scoping on
+	// app_code would match nothing. Drop it and aggregate every app at platform x media_source.
+	const sliceScope = portfolio
+		? { exactUaChannelScope: [...new Map(uniqueSlices.map((slice) => [`${slice.store}\u0000${slice.channel_group}`, { platform: slice.store, media_source: slice.channel_group }])).values()] }
+		: { exactUaScope };
+	const discoveryScope = portfolio
+		? { filters: { platform: [...new Set(uniqueSlices.map((slice) => slice.store))] } }
+		: { exactUaPortfolioScope };
+	const sliceDimensions = portfolio ? ["platform", "media_source"] : ["app_code", "platform", "media_source"];
+	const current = await runStructuredQuery({ ...common, ...sliceScope, dateFrom: dates.currentFrom, dateTo: dates.currentTo, limit: 1 }, signal);
+	const currentRow = current.rows[0];
+	const coverageMin = currentRow?.date_min == null ? null : String(currentRow.date_min);
+	const coverageMax = currentRow?.date_max == null ? null : String(currentRow.date_max);
+	const comparisonDates = coverageMax ? comparisonDatesForCoverage(dates.currentFrom, coverageMax) : null;
+	const [comparison, daily, approvedSlices, discoveredSlices] = await Promise.all([
+		comparisonDates
+			? runStructuredQuery({ ...common, ...sliceScope, dateFrom: comparisonDates.comparisonFrom, dateTo: comparisonDates.comparisonTo, limit: 1 }, signal)
+			: Promise.resolve(null),
+		runStructuredQuery({ ...common, ...sliceScope, dateFrom: dates.currentFrom, dateTo: dates.currentTo, timeGrain: "day", limit: 1000 }, signal),
+		runStructuredQuery({
+			...common,
+			dateFrom: dates.currentFrom,
+			dateTo: dates.currentTo,
+			...sliceScope,
+			dimensions: sliceDimensions,
+			limit: 500,
+		}, signal),
+		runStructuredQuery({
+			...common,
+			dateFrom: dates.currentFrom,
+			dateTo: dates.currentTo,
+			...discoveryScope,
+			dimensions: sliceDimensions,
+			limit: 1000,
+		}, signal),
+	]);
+
+	const comparisonRow = comparison?.rows[0];
+	const queryReceipts = [
+		receipt("ua_spend.current", current.built.sql, current.rows.length),
+		...(comparison ? [receipt("ua_spend.comparison", comparison.built.sql, comparison.rows.length)] : []),
+		receipt("ua_spend.daily", daily.built.sql, daily.rows.length),
+		receipt("ua_spend.slices.approved", approvedSlices.built.sql, approvedSlices.rows.length),
+		receipt("ua_spend.slices.discovery", discoveredSlices.built.sql, discoveredSlices.rows.length),
+	];
+	const approvedKeys = new Set(
+		portfolio
+			? uniqueSlices.map((slice) => `${slice.store}\u0000${slice.channel_group}`)
+			: exactUaScope.map((scope) => `${scope.app_code}\u0000${scope.platform}\u0000${scope.media_source}`),
+	);
+	const rowKey = (row: SqlRow): string =>
+		portfolio ? `${row.platform}\u0000${row.media_source}` : `${row.app_code}\u0000${row.platform}\u0000${row.media_source}`;
+	const sliceRows = [
+		...approvedSlices.rows,
+		...discoveredSlices.rows.filter((row) => !approvedKeys.has(rowKey(row))),
+	];
+
+	return {
+		period,
+		data_as_of: coverageMax ?? ACTUALS_DATA_AS_OF_UNAVAILABLE,
+		reporting_currency: "USD",
+		scope_mode: mode,
+		coverage: {
+			date_min: coverageMin,
+			date_max: coverageMax,
+			source_rows: value(currentRow, "source_rows") ?? 0,
+		},
+		current: { spend: value(currentRow, "spend"), revenue: value(currentRow, "revenue") },
+		comparison: comparisonRow
+			? { spend: value(comparisonRow, "spend"), revenue: value(comparisonRow, "revenue") }
+			: null,
+		daily: completeDailySeries(daily.rows, dates.currentFrom, coverageMax),
+		slices: mapDashboardSlices(sliceRows, portfolioAppId ?? undefined),
+		query_receipts: queryReceipts,
+	};
+}

package/extensions/fpa-dashboard/index.ts

@@ -0,0 +1,145 @@
+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 { dashboardBuildFingerprint, publishDashboard } from "./publisher.ts";
+import { inspectDashboard } from "./status.ts";
+
+function toolResult(value: Record<string, unknown>) {
+	return {
+		content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }],
+		details: value,
+	};
+}
+
+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 {
+	pi.registerTool({
+		name: "fpa_dashboard_status",
+		label: "FP&A Dashboard Status",
+		description: "Inspect the current tenant dashboard generation, datasets, build receipt, and diagnostics without changing files.",
+		promptSnippet: "Inspect the current FP&A dashboard generation and diagnostics",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		executionMode: "parallel",
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			return toolResult(await inspectDashboard(ctx.cwd) as unknown as Record<string, unknown>);
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_dashboard_refresh",
+		label: "Refresh FP&A Dashboard",
+		description:
+			"Build the forecast closed-loop dashboard from a committed approved forecast, optional committed execution receipt, and current read-only FP&A Actuals. " +
+			"Preview computes and validates without publishing; publish requires the exact preview fingerprint and atomically promotes a content-addressed generation.",
+		promptSnippet: "Preview or atomically publish the forecast closed-loop FP&A dashboard",
+		promptGuidelines: [
+			"Always call fpa_dashboard_refresh with mode=preview before mode=publish and carry forward the exact preview_fingerprint.",
+			"Never write .fpa-dashboard files with generic file or shell tools; use fpa_dashboard_refresh so calculations, lineage, and atomic publication stay consistent.",
+		],
+		parameters: Type.Object(
+			{
+				preset: StringEnum(["forecast-closed-loop-v1"] as const),
+				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}$" })),
+			},
+			{ 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 summary = {
+				preset: params.preset,
+				preview_fingerprint: previewFingerprint,
+				forecast_version: forecast.forecast_version,
+				forecast_fingerprint: build.source.forecast_fingerprint,
+				execution_fingerprint: build.source.execution_fingerprint,
+				data_as_of: build.source.data_as_of,
+				widget_count: build.widgets.length,
+				widgets: build.widgets.map((widget) => ({ id: widget.id, type: widget.type, dataset: widget.dataset })),
+				warnings: build.warnings,
+				query_receipts: build.source.query_receipts,
+			};
+			if (params.mode === "preview") return toolResult({ status: build.warnings.length > 0 ? "ready_with_limits" : "ready", ...summary });
+
+			if (forecast.status !== "complete" || !forecast.approval_conditions_satisfied) {
+				throw new Error("Dashboard publish requires a complete approved forecast with all approval conditions satisfied.");
+			}
+			if (!params.expected_preview_fingerprint) throw new Error("Publish requires expected_preview_fingerprint from a preceding preview.");
+			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 });
+			return toolResult({ status: "published", ...summary, dashboard_dir: published.dashboardDir, published_datasets: published.publishedDatasets });
+		},
+	});
+}