@viccydev/pi-fpa 0.4.1 → 0.5.0

package/extensions/fpa-artifacts/compose.ts

@@ -0,0 +1,414 @@
+import { runStructuredQuery } from "../fpa-data/runtime.ts";
+import {
+	ALLOCATION_ACTIONS,
+	canonicalForecastWindow,
+	sliceKey,
+	type AllocationAction,
+	type ApprovedCycleForecastInput,
+	type ForecastAllocation,
+	type ForecastSlice,
+	type Period,
+	type ScenarioMetric,
+} from "./contracts.ts";
+
+// ============================================================================
+// Composing an approved forecast from a compact plan.
+//
+// Authoring a full `approved_cycle_forecast` by hand means writing three
+// scenarios x three metrics x N slices, plus a consolidated roll-up, plus the
+// unit and window string on every one of them — tens of thousands of tokens of
+// pure transcription in which every arithmetic identity the contract checks has
+// to come out exact. In practice it does not: rounding a ROAS to four decimals
+// misses the reconciliation tolerance, a consolidated total drifts from the sum
+// of its slices, a slice loses its partner row, and each failure costs a
+// re-draft.
+//
+// None of that is judgement. The only judgement in a forecast is the
+// allocation and the ROAS assumption behind each slice; everything else is
+// derived. So the plan carries just those, and this module computes the rest —
+// which makes the identities true by construction rather than true if checked.
+//
+// Deliberately returns the artifact instead of writing it. A node that writes
+// is a mutating node, and the engine bars mutating nodes from automatic retry
+// and from failure routes that lead back to themselves. Keeping composition
+// read-only is what lets a bad plan be repaired and recomposed automatically,
+// while the irreversible freeze stays in its own node.
+// ============================================================================
+
+/** Distinct dimension values a plan's slice keys must be drawn from. */
+export interface UaDimensionValues {
+	app_code: Set<string>;
+	platform: Set<string>;
+	media_source: Set<string>;
+}
+
+export interface PlanSliceRoas {
+	downside: number | null;
+	base: number | null;
+	upside: number | null;
+}
+
+export interface PlanSlice {
+	app_id: string;
+	store: string;
+	channel_group: string;
+	baseline_spend: number | null;
+	approved_spend: number;
+	action: AllocationAction;
+	roas: PlanSliceRoas;
+}
+
+const SCENARIOS = ["downside", "base", "upside"] as const;
+type Scenario = (typeof SCENARIOS)[number];
+
+const PLAN_KEYS = [
+	"status",
+	"forecast_version",
+	"strategy_version",
+	"strategy_review_id",
+	"human_approval_id",
+	"approval_conditions_satisfied",
+	"target_period",
+	"data_as_of",
+	"source_snapshot_ids",
+	"assumption_version",
+	"model_version",
+	"reporting_currency",
+	"calibration_policy",
+	"unsupported_metrics",
+	"reconciliation_checks",
+	"slices",
+] as const;
+const OPTIONAL_PLAN_KEYS = ["artifact_type", "consolidated_extra_metrics", "frozen_at"] as const;
+
+function record(value: unknown, path: string): Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object.`);
+	return value as Record<string, unknown>;
+}
+
+function requireKeys(value: Record<string, unknown>, path: string): void {
+	const allowed = new Set<string>([...PLAN_KEYS, ...OPTIONAL_PLAN_KEYS]);
+	const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+	if (unknown.length > 0) {
+		throw new Error(
+			`${path} has unsupported keys: ${unknown.join(", ")}. `
+				+ "A plan carries only the decision and its assumptions; derived metrics are computed here, not supplied.",
+		);
+	}
+	const missing = PLAN_KEYS.filter((key) => !(key in value));
+	if (missing.length > 0) throw new Error(`${path} is missing required keys: ${missing.join(", ")}.`);
+}
+
+function finite(value: unknown, path: string, nullable = false): number | null {
+	if (nullable && value === null) return null;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${path} must be a finite number${nullable ? " or null" : ""}.`);
+	return value;
+}
+
+function nonNegative(value: unknown, path: string, nullable = false): number | null {
+	const parsed = finite(value, path, nullable);
+	if (parsed !== null && parsed < 0) throw new Error(`${path} must be non-negative.`);
+	return parsed;
+}
+
+function text(value: unknown, path: string): string {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
+	return value;
+}
+
+function planSlice(value: unknown, index: number): PlanSlice {
+	const path = `plan.slices[${index}]`;
+	const source = record(value, path);
+	const allowed = new Set(["app_id", "store", "channel_group", "baseline_spend", "approved_spend", "action", "roas"]);
+	const unknown = Object.keys(source).filter((key) => !allowed.has(key));
+	if (unknown.length > 0) throw new Error(`${path} has unsupported keys: ${unknown.join(", ")}.`);
+	const action = source.action;
+	if (typeof action !== "string" || !ALLOCATION_ACTIONS.includes(action as AllocationAction)) {
+		throw new Error(`${path}.action must be one of: ${ALLOCATION_ACTIONS.join(", ")}.`);
+	}
+	const roasSource = record(source.roas, `${path}.roas`);
+	const roasUnknown = Object.keys(roasSource).filter((key) => !SCENARIOS.includes(key as Scenario));
+	if (roasUnknown.length > 0) throw new Error(`${path}.roas has unsupported keys: ${roasUnknown.join(", ")}.`);
+	return {
+		app_id: text(source.app_id, `${path}.app_id`),
+		store: text(source.store, `${path}.store`),
+		channel_group: text(source.channel_group, `${path}.channel_group`),
+		baseline_spend: nonNegative(source.baseline_spend, `${path}.baseline_spend`, true),
+		approved_spend: nonNegative(source.approved_spend, `${path}.approved_spend`) as number,
+		action: action as AllocationAction,
+		roas: {
+			downside: nonNegative(roasSource.downside, `${path}.roas.downside`, true),
+			base: nonNegative(roasSource.base, `${path}.roas.base`, true),
+			upside: nonNegative(roasSource.upside, `${path}.roas.upside`, true),
+		},
+	};
+}
+
+function scenarioMetric(values: Record<Scenario, number | null>, unit: string, window: string): ScenarioMetric {
+	return { downside: values.downside, base: values.base, upside: values.upside, unit, window };
+}
+
+/**
+ * Revenue implied by an approved spend and a ROAS assumption.
+ *
+ * A stopped slice spends nothing, so it earns nothing and its ROAS is not a
+ * number — the contract derives ROAS as revenue/spend and treats a zero
+ * denominator as null, so anything else fails reconciliation. Hand-written
+ * forecasts get this wrong precisely because 0 looks like a reasonable answer.
+ */
+function sliceScenario(spend: number, roas: number | null): { revenue: number | null; roas: number | null } {
+	if (spend === 0) return { revenue: 0, roas: null };
+	if (roas === null) return { revenue: null, roas: null };
+	return { revenue: spend * roas, roas };
+}
+
+function sumScenario(values: Array<number | null>): number | null {
+	if (values.some((value) => value === null)) return null;
+	return values.reduce<number>((total, value) => total + (value as number), 0);
+}
+
+export interface ComposeDiagnostics {
+	slice_count: number;
+	stopped_slice_count: number;
+	total_approved_spend: number;
+	validated_dimensions: boolean;
+	portfolio_placeholder_app_id: string | null;
+}
+
+export interface ComposeResult {
+	artifact: ApprovedCycleForecastInput;
+	diagnostics: ComposeDiagnostics;
+}
+
+/**
+ * Every distinct app_code / platform / media_source ua_spend actually uses.
+ *
+ * Read once and compared as sets: a plan that names `google_play` where the
+ * mart only ever says `android` produces a forecast whose every slice silently
+ * matches nothing, and the dashboard built from it is correct-looking and
+ * entirely empty. That is worth one query to prevent.
+ */
+export async function loadUaDimensionValues(signal?: AbortSignal): Promise<UaDimensionValues> {
+	const result = await runStructuredQuery(
+		{ dataset: "ua_spend", metrics: ["spend"], dimensions: ["app_code", "platform", "media_source"], limit: 5000 },
+		signal,
+	);
+	const values: UaDimensionValues = { app_code: new Set(), platform: new Set(), media_source: new Set() };
+	for (const row of result.rows) {
+		if (row.app_code != null) values.app_code.add(String(row.app_code));
+		if (row.platform != null) values.platform.add(String(row.platform));
+		if (row.media_source != null) values.media_source.add(String(row.media_source));
+	}
+	return values;
+}
+
+function sample(values: Set<string>, limit = 8): string {
+	const list = [...values].sort();
+	return list.length <= limit ? list.join(", ") : `${list.slice(0, limit).join(", ")}, … (${list.length} total)`;
+}
+
+/**
+ * Check plan slice keys against the values ua_spend really uses.
+ *
+ * The App axis has one legitimate exception: a forecast whose App dimension was
+ * scoped out carries a single placeholder app_id for the whole portfolio, which
+ * by design appears nowhere in the mart. That is the same collapsed-single-app
+ * test the dashboard applies, so the two agree on what "portfolio mode" means.
+ * Store and channel have no such mode — a value the mart never uses is an error.
+ */
+export function validateSliceKeys(slices: PlanSlice[], values: UaDimensionValues): { portfolioAppId: string | null } {
+	const appIds = new Set(slices.map((slice) => slice.app_id));
+	const collapsed = appIds.size === 1 ? [...appIds][0] : null;
+	const portfolioAppId = collapsed !== null && !values.app_code.has(collapsed) ? collapsed : null;
+
+	const problems: string[] = [];
+	const badStores = [...new Set(slices.map((slice) => slice.store).filter((store) => !values.platform.has(store)))];
+	if (badStores.length > 0) {
+		problems.push(`store ${badStores.map((value) => JSON.stringify(value)).join(", ")} is not a ua_spend.platform value. Valid values: ${sample(values.platform)}.`);
+	}
+	const badChannels = [...new Set(slices.map((slice) => slice.channel_group).filter((channel) => !values.media_source.has(channel)))];
+	if (badChannels.length > 0) {
+		problems.push(`channel_group ${badChannels.map((value) => JSON.stringify(value)).join(", ")} is not a ua_spend.media_source value. Valid values: ${sample(values.media_source)}.`);
+	}
+	if (portfolioAppId === null) {
+		const badApps = [...new Set(slices.map((slice) => slice.app_id).filter((appId) => !values.app_code.has(appId)))];
+		if (badApps.length > 0) {
+			problems.push(`app_id ${badApps.map((value) => JSON.stringify(value)).join(", ")} is not a ua_spend.app_code value. Valid values: ${sample(values.app_code)}.`);
+		}
+	}
+	if (problems.length > 0) {
+		throw new Error(
+			`Plan slice keys do not exist in ua_spend, so every Actuals lookup for this forecast would match nothing:\n`
+				+ problems.map((problem) => `- ${problem}`).join("\n"),
+		);
+	}
+	return { portfolioAppId };
+}
+
+export interface ComposeOptions {
+	/** Test injection point; defaults to reading the values out of ua_spend. */
+	loadDimensionValues?: (signal?: AbortSignal) => Promise<UaDimensionValues>;
+	signal?: AbortSignal;
+	/** Stamped onto the artifact when the plan does not carry one. */
+	now?: () => Date;
+}
+
+export async function composeApprovedForecast(plan: unknown, options: ComposeOptions = {}): Promise<ComposeResult> {
+	const source = record(plan, "plan");
+	requireKeys(source, "plan");
+	if (source.artifact_type !== undefined && source.artifact_type !== "approved_cycle_forecast") {
+		throw new Error('plan.artifact_type must be "approved_cycle_forecast" when supplied.');
+	}
+	if (!Array.isArray(source.slices) || source.slices.length === 0) throw new Error("plan.slices must be a non-empty array.");
+	const slices = source.slices.map((value, index) => planSlice(value, index));
+
+	const seen = new Set<string>();
+	for (const slice of slices) {
+		const key = sliceKey({ app_id: slice.app_id, store: slice.store, channel_group: slice.channel_group });
+		if (seen.has(key)) throw new Error(`plan.slices contains duplicate slice ${key.replaceAll("", " / ")}.`);
+		seen.add(key);
+	}
+
+	const status = source.status;
+	if (status !== "complete" && status !== "complete_with_limits" && status !== "blocked") {
+		throw new Error("plan.status must be complete, complete_with_limits, or blocked.");
+	}
+	const unsupported = source.unsupported_metrics;
+	if (!Array.isArray(unsupported)) throw new Error("plan.unsupported_metrics must be an array.");
+	// The status and the list of undelivered metrics are two statements about the
+	// same fact, and a forecast that disagrees with itself is what the publish
+	// gate later rejects with no explanation of which half was wrong.
+	if (status === "complete" && unsupported.length > 0) {
+		throw new Error("plan.status is complete but unsupported_metrics is not empty; a forecast with undelivered metrics is complete_with_limits.");
+	}
+	if (status === "complete_with_limits" && unsupported.length === 0) {
+		throw new Error(
+			"plan.status is complete_with_limits but unsupported_metrics is empty. "
+				+ "Scope deliberately excluded upstream is not a limit — if nothing in scope is missing, the status is complete.",
+		);
+	}
+
+	const loadValues = options.loadDimensionValues ?? loadUaDimensionValues;
+	const { portfolioAppId } = validateSliceKeys(slices, await loadValues(options.signal));
+
+	const period = record(source.target_period, "plan.target_period") as unknown as Period;
+	const currency = text(source.reporting_currency, "plan.reporting_currency").toUpperCase();
+	const window = canonicalForecastWindow(period);
+
+	const approvedAllocation: ForecastAllocation[] = slices.map((slice) => ({
+		app_id: slice.app_id,
+		store: slice.store,
+		channel_group: slice.channel_group,
+		baseline_spend: slice.baseline_spend,
+		approved_spend: slice.approved_spend,
+		action: slice.action,
+	}));
+
+	// Spend is the decision, not a prediction: an approved allocation is the same
+	// number in every scenario. Only revenue moves, through the ROAS assumption.
+	const forecastBySlice: ForecastSlice[] = slices.map((slice) => {
+		const derived = Object.fromEntries(
+			SCENARIOS.map((scenario) => [scenario, sliceScenario(slice.approved_spend, slice.roas[scenario])]),
+		) as Record<Scenario, { revenue: number | null; roas: number | null }>;
+		return {
+			app_id: slice.app_id,
+			store: slice.store,
+			channel_group: slice.channel_group,
+			metrics: {
+				spend: scenarioMetric(
+					{ downside: slice.approved_spend, base: slice.approved_spend, upside: slice.approved_spend },
+					currency,
+					window,
+				),
+				revenue: scenarioMetric(
+					{ downside: derived.downside.revenue, base: derived.base.revenue, upside: derived.upside.revenue },
+					currency,
+					window,
+				),
+				roas: scenarioMetric(
+					{ downside: derived.downside.roas, base: derived.base.roas, upside: derived.upside.roas },
+					"ratio",
+					window,
+				),
+			},
+		};
+	});
+
+	const consolidatedSpend = Object.fromEntries(
+		SCENARIOS.map((scenario) => [scenario, sumScenario(forecastBySlice.map((slice) => slice.metrics.spend[scenario]))]),
+	) as Record<Scenario, number | null>;
+	const consolidatedRevenue = Object.fromEntries(
+		SCENARIOS.map((scenario) => [scenario, sumScenario(forecastBySlice.map((slice) => slice.metrics.revenue[scenario]))]),
+	) as Record<Scenario, number | null>;
+	const consolidatedRoas = Object.fromEntries(
+		SCENARIOS.map((scenario) => {
+			const spend = consolidatedSpend[scenario];
+			const revenue = consolidatedRevenue[scenario];
+			return [scenario, spend === null || revenue === null || spend === 0 ? null : revenue / spend];
+		}),
+	) as Record<Scenario, number | null>;
+
+	const consolidated: Record<string, ScenarioMetric> = {
+		spend: scenarioMetric(consolidatedSpend, currency, window),
+		revenue: scenarioMetric(consolidatedRevenue, currency, window),
+		roas: scenarioMetric(consolidatedRoas, "ratio", window),
+	};
+
+	// Portfolio-level series the model measured rather than derived — organic
+	// revenue and the like. They pass through untouched apart from the window,
+	// which is the artifact's to define, not the plan's.
+	if (source.consolidated_extra_metrics !== undefined) {
+		const extra = record(source.consolidated_extra_metrics, "plan.consolidated_extra_metrics");
+		for (const [name, value] of Object.entries(extra)) {
+			if (name === "spend" || name === "revenue" || name === "roas") {
+				throw new Error(`plan.consolidated_extra_metrics.${name} is derived from the slices and cannot be supplied.`);
+			}
+			const metricSource = record(value, `plan.consolidated_extra_metrics.${name}`);
+			consolidated[name] = scenarioMetric(
+				{
+					downside: finite(metricSource.downside, `plan.consolidated_extra_metrics.${name}.downside`, true),
+					base: finite(metricSource.base, `plan.consolidated_extra_metrics.${name}.base`, true),
+					upside: finite(metricSource.upside, `plan.consolidated_extra_metrics.${name}.upside`, true),
+				},
+				text(metricSource.unit, `plan.consolidated_extra_metrics.${name}.unit`),
+				window,
+			);
+		}
+	}
+
+	const artifact = {
+		artifact_type: "approved_cycle_forecast",
+		status,
+		forecast_version: text(source.forecast_version, "plan.forecast_version"),
+		strategy_version: text(source.strategy_version, "plan.strategy_version"),
+		strategy_review_id: text(source.strategy_review_id, "plan.strategy_review_id"),
+		human_approval_id: text(source.human_approval_id, "plan.human_approval_id"),
+		approval_conditions_satisfied: source.approval_conditions_satisfied,
+		target_period: period,
+		data_as_of: source.data_as_of,
+		source_snapshot_ids: source.source_snapshot_ids,
+		assumption_version: text(source.assumption_version, "plan.assumption_version"),
+		model_version: text(source.model_version, "plan.model_version"),
+		reporting_currency: currency,
+		approved_allocation: approvedAllocation,
+		forecast_by_slice: forecastBySlice,
+		consolidated_forecast: consolidated,
+		calibration_policy: source.calibration_policy,
+		unsupported_metrics: unsupported,
+		reconciliation_checks: source.reconciliation_checks,
+		frozen_at: typeof source.frozen_at === "string" && source.frozen_at.trim()
+			? source.frozen_at
+			: (options.now?.() ?? new Date()).toISOString().replace(/\.\d{3}Z$/, "Z"),
+	} as unknown as ApprovedCycleForecastInput;
+
+	return {
+		artifact,
+		diagnostics: {
+			slice_count: slices.length,
+			stopped_slice_count: slices.filter((slice) => slice.approved_spend === 0).length,
+			total_approved_spend: slices.reduce((total, slice) => total + slice.approved_spend, 0),
+			validated_dimensions: true,
+			portfolio_placeholder_app_id: portfolioAppId,
+		},
+	};
+}

package/extensions/fpa-artifacts/index.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { commitArtifact, commitArtifactFromPath } from "./store.ts";
+import { composeApprovedForecast } from "./compose.ts";
+import { commitArtifact, commitArtifactFromPath, readProjectJsonFile } from "./store.ts";
 
 function toolResult(value: Record<string, unknown>) {
 	return {
@@ -52,4 +53,37 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 			});
 		},
 	});
+
+	pi.registerTool({
+		name: "fpa_forecast_compose",
+		label: "Compose Approved Forecast",
+		description:
+			"Derive a complete, self-consistent approved_cycle_forecast from a compact plan file holding only the approved allocation and its per-slice ROAS assumptions. " +
+			"Computes every scenario metric, the consolidated roll-up, units, windows, and frozen_at, and checks the plan's slice keys against the dimension values ua_spend actually uses. " +
+			"Returns the artifact for fpa_artifact_commit to freeze; writes nothing.",
+		promptSnippet: "Derive a complete approved forecast from a compact plan",
+		promptGuidelines: [
+			"Author the compact plan, not the full artifact: supply the allocation and each slice's ROAS assumption and let this tool derive the rest.",
+			"Do not compute revenue, ROAS, or consolidated totals by hand; hand-rounded values fail the commit reconciliation.",
+		],
+		parameters: Type.Object(
+			{
+				plan_path: Type.String({
+					minLength: 1,
+					description: "Project-relative path to the compact forecast plan JSON file.",
+				}),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const plan = await readProjectJsonFile(ctx.cwd, params.plan_path, "plan_path");
+			const composed = await composeApprovedForecast(plan, { signal });
+			return toolResult({
+				status: "composed",
+				artifact: composed.artifact as unknown as Record<string, unknown>,
+				diagnostics: composed.diagnostics as unknown as Record<string, unknown>,
+			});
+		},
+	});
 }

package/extensions/fpa-artifacts/store.ts

@@ -66,20 +66,36 @@ async function existingArtifactDirectory(projectRoot: string): Promise<string> {
  * Same fail-closed posture as the committed artifacts themselves: no escaping
  * the project root, no symlinks, no unbounded reads.
  */
-async function resolveDraftPath(projectRoot: string, artifactPath: string): Promise<string> {
-	if (!artifactPath.trim()) throw new Error("artifact_path must be a non-empty path.");
+async function resolveDraftPath(projectRoot: string, artifactPath: string, label = "artifact_path"): Promise<string> {
+	if (!artifactPath.trim()) throw new Error(`${label} must be a non-empty path.`);
 	const root = await realpath(projectRoot);
 	const resolved = resolve(root, artifactPath);
 	const relation = relative(root, resolved);
 	if (relation === "" || relation.startsWith("..") || isAbsolute(relation)) {
-		throw new Error("artifact_path must stay inside the project directory.");
+		throw new Error(`${label} must stay inside the project directory.`);
 	}
 	const stat = await lstat(resolved);
-	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("artifact_path must point at a regular file, not a symlink.");
-	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`artifact_path exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${label} must point at a regular file, not a symlink.`);
+	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`${label} exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
 	return resolved;
 }
 
+/**
+ * Read and parse a JSON file the agent wrote somewhere inside the project.
+ *
+ * Shared by every by-path entry point so they all get the same fail-closed
+ * posture, and so a malformed file is reported as a parse error against the
+ * caller's own path rather than as something deeper and less obvious.
+ */
+export async function readProjectJsonFile(projectRoot: string, artifactPath: string, label = "artifact_path"): Promise<unknown> {
+	const path = await resolveDraftPath(projectRoot, artifactPath, label);
+	try {
+		return JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		throw new Error(`${label} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
 /**
  * Commit a canonical artifact an agent wrote to disk instead of passing inline.
  *
@@ -91,16 +107,10 @@ async function resolveDraftPath(projectRoot: string, artifactPath: string): Prom
  * reconciliation, fingerprinting, and atomic write identical to the inline path.
  */
 export async function commitArtifactFromPath(projectRoot: string, artifactPath: string): Promise<CommitArtifactResult> {
-	const path = await resolveDraftPath(projectRoot, artifactPath);
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(await readFile(path, "utf8"));
-	} catch (error) {
-		throw new Error(`artifact_path is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	return commitArtifact(projectRoot, parsed);
+	return commitArtifact(projectRoot, await readProjectJsonFile(projectRoot, artifactPath));
 }
 
+
 export async function commitArtifact(projectRoot: string, input: unknown): Promise<CommitArtifactResult> {
 	const artifact = validateArtifact(input);
 	if (artifact.artifact_type === "execution_receipt") {

package/extensions/fpa-dashboard/actuals.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 
 import type { Period } from "../fpa-artifacts/contracts.ts";
+import { sliceKey } 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";
@@ -97,6 +98,32 @@ export interface DashboardActualsScope {
 	slices: Array<{ app_id: string; store: string; channel_group: string }>;
 }
 
+/**
+ * Why every approved slice can be missing, and which of the two reasons it is.
+ *
+ * An early cycle and a forecast keyed on values ua_spend never uses produce
+ * byte-identical Actuals: nothing. The difference is only visible next to the
+ * unscoped probe — if the window holds paid rows that no approved key matched,
+ * the keys are wrong. Returns the operator-facing explanation, or null when the
+ * evidence does not support that conclusion.
+ */
+export function detectSliceKeyMismatch(
+	allocation: Array<{ app_id: string; store: string; channel_group: string }>,
+	actuals: Pick<DashboardActualsSnapshot, "slices" | "period_has_unscoped_actuals" | "period">,
+): string | null {
+	if (allocation.length === 0) return null;
+	if (!actuals.period_has_unscoped_actuals) return null;
+	const actualKeys = new Set(actuals.slices.map(sliceKey));
+	const missing = allocation.filter((slice) => !actualKeys.has(sliceKey(slice)));
+	if (missing.length < allocation.length) return null;
+	return (
+		`All ${allocation.length} approved slices have no Actuals, yet ua_spend holds paid rows in `
+		+ `${actuals.period.start_inclusive.slice(0, 10)}..${actuals.period.end_exclusive.slice(0, 10)}. `
+		+ "The frozen slice keys do not match the dimension values ua_spend uses — check store against "
+		+ "ua_spend.platform and channel_group against ua_spend.media_source, then re-freeze the forecast."
+	);
+}
+
 /**
  * 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.
@@ -198,12 +225,23 @@ export async function loadDashboardActuals(
 	]);
 
 	const comparisonRow = comparison?.rows[0];
+	// Only worth asking when the scoped queries came back empty, which is the one
+	// case where "no Actuals" is ambiguous between an early cycle and slice keys
+	// that match nothing.
+	const scopedFoundNothing = coverageMax === null || approvedSlices.rows.length === 0;
+	const unscopedProbe = scopedFoundNothing
+		? await runStructuredQuery({ ...common, dateFrom: dates.currentFrom, dateTo: dates.currentTo, limit: 1 }, signal)
+		: null;
+	const unscopedRow = unscopedProbe?.rows[0];
+	const periodHasUnscopedActuals = unscopedProbe !== null && unscopedRow?.date_max != null;
+
 	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),
+		...(unscopedProbe ? [receipt("ua_spend.period.unscoped", unscopedProbe.built.sql, periodHasUnscopedActuals ? 1 : 0)] : []),
 	];
 	const approvedKeys = new Set(
 		portfolio
@@ -222,6 +260,7 @@ export async function loadDashboardActuals(
 		data_as_of: coverageMax ?? ACTUALS_DATA_AS_OF_UNAVAILABLE,
 		reporting_currency: "USD",
 		scope_mode: mode,
+		period_has_unscoped_actuals: periodHasUnscopedActuals,
 		coverage: {
 			date_min: coverageMin,
 			date_max: coverageMax,

package/extensions/fpa-dashboard/index.ts

@@ -15,7 +15,7 @@ import type {
 	ExecutionReceiptInput,
 } from "../fpa-artifacts/contracts.ts";
 import { isExecutionReceiptForForecast, sliceKey } from "../fpa-artifacts/contracts.ts";
-import { loadDashboardActuals } from "./actuals.ts";
+import { detectSliceKeyMismatch, loadDashboardActuals } from "./actuals.ts";
 import { projectDashboard, type DashboardBuild } from "./projector.ts";
 import { dashboardBuildFingerprint, publishDashboard } from "./publisher.ts";
 import { inspectDashboard } from "./status.ts";
@@ -41,6 +41,7 @@ async function buildDashboard(
 	forecast: ApprovedCycleForecast;
 	forecastRead: ReadArtifactResult;
 	executionRead: ReadArtifactResult | null;
+	sliceKeyMismatch: string | 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.");
@@ -77,7 +78,14 @@ async function buildDashboard(
 	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 };
+
+	// Every approved slice missing while the window demonstrably holds paid rows is
+	// not an early cycle — it is a forecast keyed on values ua_spend never uses, and
+	// the dashboard it produces looks complete while being entirely empty. Publishing
+	// that is worse than publishing nothing, so it is named here and refused below.
+	const sliceKeyMismatch = detectSliceKeyMismatch(forecast.approved_allocation, actuals);
+	if (sliceKeyMismatch) build.warnings.push(sliceKeyMismatch);
+	return { build, forecast, forecastRead, executionRead, sliceKeyMismatch };
 }
 
 export default function fpaDashboardExtension(pi: ExtensionAPI): void {
@@ -115,7 +123,7 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		),
 		executionMode: "sequential",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const { build, forecast } = await buildDashboard(ctx.cwd, params.locale ?? "zh-CN", signal);
+			const { build, forecast, sliceKeyMismatch } = await buildDashboard(ctx.cwd, params.locale ?? "zh-CN", signal);
 			const previewFingerprint = dashboardBuildFingerprint(build);
 			const summary = {
 				preset: params.preset,
@@ -129,8 +137,15 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 				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 (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.");
 			}

package/extensions/fpa-dashboard/source.ts

@@ -39,6 +39,18 @@ export interface DashboardActualsSnapshot {
 	data_as_of: string;
 	reporting_currency: string;
 	scope_mode: DashboardScopeMode;
+	/**
+	 * Whether ua_spend holds any paid rows in the target window at all, ignoring
+	 * the approved slice keys.
+	 *
+	 * A forecast whose slice keys do not exist in the mart produces exactly the
+	 * same empty Actuals as a cycle that simply has not started yet, and the two
+	 * are indistinguishable from the scoped queries alone — the scoped query is
+	 * what determines coverage, so a wrong key erases its own evidence. Probing
+	 * once without the key predicate separates them: data in the window plus no
+	 * matching slice means the keys are wrong, not that the period is early.
+	 */
+	period_has_unscoped_actuals: boolean;
 	coverage: {
 		date_min: string | null;
 		date_max: string | null;
@@ -143,11 +155,17 @@ export function validateActualsSnapshot(value: unknown): DashboardActualsSnapsho
 	if (!/^[A-Z]{3}$/.test(reportingCurrency)) throw new Error("actuals.reporting_currency must be an ISO-4217 currency code.");
 	const scopeMode = source.scope_mode === undefined ? "app" : string(source.scope_mode, "actuals.scope_mode");
 	if (scopeMode !== "app" && scopeMode !== "portfolio") throw new Error('actuals.scope_mode must be "app" or "portfolio".');
+	if (source.period_has_unscoped_actuals !== undefined && typeof source.period_has_unscoped_actuals !== "boolean") {
+		throw new Error("actuals.period_has_unscoped_actuals must be a boolean.");
+	}
 	return {
 		period: period(source.period, "actuals.period"),
 		data_as_of: string(source.data_as_of, "actuals.data_as_of"),
 		reporting_currency: reportingCurrency,
 		scope_mode: scopeMode,
+		// Absent means the probe was never run, which is only ever the benign
+		// reading: nothing here may invent evidence that the keys are wrong.
+		period_has_unscoped_actuals: source.period_has_unscoped_actuals === true,
 		coverage: {
 			date_min: coverage.date_min === null ? null : string(coverage.date_min, "actuals.coverage.date_min"),
 			date_max: coverage.date_max === null ? null : string(coverage.date_max, "actuals.coverage.date_max"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -23,9 +23,9 @@
     "extensions"
   ],
   "scripts": {
-    "test": "node tests/package-structure.test.mjs && node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs && node tests/pi-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
+    "test": "node tests/package-structure.test.mjs && node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs && node tests/pi-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
     "test:structure": "node tests/package-structure.test.mjs",
-    "test:unit": "node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs",
+    "test:unit": "node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs",
     "test:loader": "node tests/pi-loader-smoke.mjs",
     "test:live": "node tests/live-smoke.mjs",
     "pack:check": "npm pack --dry-run"

package/skills/fpa-forecast-approved-strategy/SKILL.md

@@ -25,17 +25,22 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 3. Recalculate future-period operating outcomes from that allocation using the declared model.
 4. Provide downside, base, and upside values for each supported KPI.
 5. Reconcile allocation totals, formulas, and cross-metric identities.
-6. Build the canonical `approved_cycle_forecast` input using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/approved_cycle_forecast.input.json`.
-7. Commit it with `fpa_artifact_commit` using `artifact_path`.
-
-## Why the draft file
-
-A full forecast is far too large to emit as a single inline tool argument: the
-call gets cut off at the model output limit, and what is left behind reads like
-a finished turn. Write the draft with the file tools instead — across as many
-turns and corrections as it takes — then commit the finished file by path. If a
-later step in this graph already commits the draft for you, stop after writing
-it and say so; do not claim a fingerprint you were not handed.
+6. Write the forecast plan to `artifacts/forecast_plan.json` using [artifact-contract.md](references/artifact-contract.md).
+7. Derive the artifact with `fpa_forecast_compose`, then freeze it with `fpa_artifact_commit`.
+
+## Write the decision, not the arithmetic
+
+The only judgement in a forecast is the allocation and each slice's ROAS
+assumption. Revenue, the consolidated roll-up, units, windows, and `frozen_at`
+all follow from those, and `fpa_forecast_compose` derives them — which is what
+makes the identities the commit checks true by construction rather than
+dependent on transcribing several hundred numbers without a slip.
+
+So do not hand-compute revenue, totals, or ratios, and do not emit the full
+artifact as one tool argument: that is the shape that gets cut off at the model
+output limit and leaves a turn that reads finished but committed nothing. If a
+later node in this graph composes and commits for you, stop after writing the
+plan and say so; never claim a fingerprint you were not handed.
 
 ## Status and the publish gate
 

package/skills/fpa-forecast-approved-strategy/references/artifact-contract.md

@@ -45,11 +45,60 @@ frozen_at: timestamp
 
 Do not include `immutable_fingerprint` in the tool input; a draft that carries one is rejected. `fpa_artifact_commit` validates exact fields, approval state, allocation totals, every scenario's slice-to-consolidated totals, and supplied ROAS against aggregated revenue/spend. It computes the fingerprint and returns it after durable storage. The agent must not claim the artifact is frozen until that tool succeeds.
 
-Pass this artifact by path, not inline:
+## Author the plan, not the artifact
 
+Almost none of the artifact above is a decision. The decision is the allocation
+and the ROAS assumption behind each slice; revenue, the ROAS write-back, the
+consolidated roll-up, every unit and window string, and `frozen_at` all follow
+from those by arithmetic. Write the plan and let `fpa_forecast_compose` derive
+the rest — it makes the identities the commit checks true by construction
+instead of true if you typed them correctly.
+
+```yaml
+# artifacts/forecast_plan.json
+status: complete | complete_with_limits | blocked
+forecast_version: string
+strategy_version: string
+strategy_review_id: string
+human_approval_id: string
+approval_conditions_satisfied: boolean
+target_period: {start_inclusive: timestamp, end_exclusive: timestamp, timezone: string}
+data_as_of: timestamp
+source_snapshot_ids: []
+assumption_version: string
+model_version: string
+reporting_currency: string
+calibration_policy: {stop_loss_roas_lt, deviation_warning_abs_gte, deviation_trigger_abs_gt, policy_version}
+unsupported_metrics: []
+reconciliation_checks: []
+slices:
+  - app_id: string          # ua_spend.app_code
+    store: string           # ua_spend.platform — ios | android, never a store name
+    channel_group: string   # ua_spend.media_source, verbatim
+    baseline_spend: number | null
+    approved_spend: number
+    action: stop | decrease | hold | increase | explore
+    roas: {downside: number|null, base: number|null, upside: number|null}
+consolidated_extra_metrics:   # optional; measured portfolio series only
+  metric_name: {downside, base, upside, unit}
 ```
-write  artifacts/approved_cycle_forecast.input.json
-fpa_artifact_commit  { "artifact_path": "artifacts/approved_cycle_forecast.input.json" }
+
+Then:
+
+```
+write  artifacts/forecast_plan.json
+fpa_forecast_compose  { "plan_path": "artifacts/forecast_plan.json" }
+fpa_artifact_commit   { "artifact": <the artifact compose returned> }
 ```
 
-`artifact_path` is project-relative, must stay inside the project, and must be a regular file. The inline `artifact` parameter still works and is fine for small artifacts, but a forecast of any real size will be truncated at the model output limit if you try to emit it in one call.
+Rules the plan has to respect, because compose enforces them:
+
+- **Spend is a decision, not a prediction.** It is identical in all three scenarios, so a slice carries one `approved_spend`. Only revenue moves, through `roas`.
+- **A stopped slice has no ROAS.** `approved_spend: 0` means revenue 0 and `roas` null in all three scenarios — the contract derives ROAS as revenue/spend and calls a zero denominator null.
+- **Slice keys must be values `ua_spend` actually uses.** A plan naming `google_play` where the mart says `android` is rejected with the valid values listed. The single-placeholder App axis for a scoped-out portfolio is the one permitted exception.
+- **`status` and `unsupported_metrics` must agree.** `complete` requires an empty list; `complete_with_limits` requires a non-empty one. Scope excluded upstream is neither.
+- **Do not hand-compute anything derived.** A ROAS rounded to four decimals misses the commit tolerance and costs a re-draft.
+
+## Committing an artifact you already hold
+
+`fpa_artifact_commit` also takes `artifact_path` for an artifact written to disk, and `artifact` for one passed inline. Both are project-relative and fail closed. Emitting a full artifact by hand in a single tool call is what gets cut off at the model output limit — prefer the plan above.

package/skills/fpa-refresh-dashboard/SKILL.md

@@ -20,6 +20,17 @@ Require a committed `approved_cycle_forecast` for the target project. Treat a co
 5. Publish only when the user explicitly asked to rebuild or publish the dashboard. Call the same tool with `mode: publish` and the exact preview fingerprint.
 6. Report the published generation, source forecast fingerprint, data cutoff, warnings, and dashboard path.
 
+## When preview returns `blocked_slice_key_mismatch`
+
+Every approved slice is missing its Actuals while the target window demonstrably
+holds paid rows. That is not an early cycle and not a scope limitation: the
+frozen forecast is keyed on dimension values `ua_spend` never uses, so the
+dashboard would publish complete-looking and entirely empty. Publish is refused.
+
+Report it as a failure, name the offending key axis, and send the work back to
+the node that froze the forecast. Do not re-preview hoping for a different
+answer, and do not describe it as "the period has no data yet".
+
 ## Boundaries
 
 - Never write `.fpa-dashboard` with generic file or shell tools.