@viccydev/pi-fpa 0.4.1 → 0.6.0

package/README.md

@@ -54,14 +54,31 @@ Extension 内置的关键防护：
 
 `fpa-artifacts` 提供 `fpa_artifact_commit`，对 `approved_cycle_forecast` 和 `execution_receipt` 做严格字段校验、对账、稳定指纹和原子落盘。只有工具返回成功后的 JSON 才是冻结产物，Markdown 不是正式数据源。
 
-`fpa-dashboard` 提供两个工具：
+`fpa-dashboard` 提供三个工具：
 
 | 工具 | 作用 |
 | --- | --- |
 | `fpa_dashboard_status` | 只读检查当前 manifest、构建回执和各数据集是否可读 |
 | `fpa_dashboard_refresh` | 从冻结预测、可选执行回执和实时 Actuals 生成固定的闭环看板；先 preview，再携带相同指纹原子 publish |
+| `fpa_dashboard_refresh_queue` | 检查或处理持久刷新队列；Forecast/Execution commit 自动入队，Actuals watermark 按 SLA 轮询并幂等发布 |
 
-看板按 `app_id + store + channel_group` 精确限定同口径 Actuals，比率全部在聚合后重算，缺值保持 `NULL`；未获批的付费分片只形成告警，不混入预测对比，上周期对比按当前 Actuals 已覆盖的等长日历窗口计算。发布器写内容寻址的数据集，并最后原子提升 `manifest.json`，不会让 Web 端读到半成品代际。
+持续刷新由 package 自带的独立 worker 驱动，Web 保持严格只读：
+
+```bash
+fpa-dashboard-worker --workspace /absolute/path/to/workspace
+```
+
+使用 `--once` 可接 cron/systemd timer；常驻运行时默认每 30 秒检查队列，并按内部 5 分钟 Actuals 水位 SLA 轮询。worker 只消费精确 immutable artifact refs，执行有界重试，并通过与交互工具相同的原子 publisher 发布。
+
+周期关账不按“过了若干小时”推断。ETL 必须原子写入一份有界、非 group/world-writable 的 JSON 关账信号，并同时配置 `FPA_ACTUALS_CLOSE_SIGNAL_PATH` 与 `FPA_ACTUALS_CLOSE_SIGNAL_ROOT`。可信根必须位于 Agent workspace 之外，且文件及其目录链必须由 Agent 运行身份之外的控制面身份拥有；否则 worker 会拒绝把周期判为已关账：
+
+```json
+{"kind":"fpa.actuals.source-close","schema_version":1,"dataset":"ua_spend","signal_id":"ua-close-2026-08-v1","closed_through":"2026-08-31","emitted_at":"2026-09-01T03:00:00Z"}
+```
+
+缺少该信号时，完整日期覆盖仍只算累计 Actual，不开放整周期 Forecast vs Actual 差异。
+
+看板按 `app_id + store + channel_group` 精确限定同口径 Actuals，比率全部在聚合后重算，缺值保持 `NULL`；未获批的付费分片只形成告警，不混入预测对比。整周期 Forecast vs Actual 只在 Actuals 提供统一、完整、可勾稽的单快照，且比较基线是周期开始前冻结的 `original` Forecast 时开放；EAC、稀疏覆盖和多查询未核验快照都不会生成伪差异。发布器写内容寻址的数据集、不可变 generation catalog，并最后原子提升 `manifest.json`，不会让 Web 端读到半成品代际。
 
 ### 凭证配置
 
@@ -110,12 +127,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.4.1
+pi install git:github.com/linyqh/pi-fpa@v0.6.0
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.4.1` 对应 `v0.4.1`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.6.0` 对应 `v0.6.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/bin/fpa-dashboard-worker.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import { readdir, realpath } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createJiti } from "jiti";
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write([
+    "Usage: fpa-dashboard-worker (--project <project-cwd> | --workspace <workspace-root>) [--once] [--interval-ms <milliseconds>]",
+    "",
+    "Runs the package-owned durable dashboard refresh coordinator.",
+    "The Web application remains read-only and must not invoke this worker in-process.",
+    "",
+  ].join("\n"));
+  process.exit(0);
+}
+
+function option(name) {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+}
+
+const projectArg = option("--project");
+const workspaceArg = option("--workspace");
+if ((!projectArg && !workspaceArg) || (projectArg && workspaceArg)) {
+  process.stderr.write("fpa-dashboard-worker requires exactly one of --project or --workspace.\n");
+  process.exit(2);
+}
+const configuredProject = projectArg ? resolve(projectArg) : null;
+const workspace = workspaceArg ? resolve(workspaceArg) : null;
+const interval = Number(option("--interval-ms") ?? 30_000);
+if (!Number.isInteger(interval) || interval < 5_000 || interval > 3_600_000) {
+  process.stderr.write("--interval-ms must be an integer between 5000 and 3600000.\n");
+  process.exit(2);
+}
+
+// Node does not strip TypeScript under node_modules. Use the same runtime
+// loader as Pi itself so the published package works from an installed tree.
+const jiti = createJiti(import.meta.url);
+const { runDashboardRefreshCoordinator } = await jiti.import("../extensions/fpa-dashboard/coordinator.ts");
+let stopping = false;
+const abortController = new AbortController();
+let wakeSleep = null;
+for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => {
+	stopping = true;
+	abortController.abort(new Error(`Dashboard worker received ${signal}.`));
+	wakeSleep?.();
+});
+
+async function runOnce() {
+  const project = configuredProject ?? await selectWorkspaceProject(workspace);
+  if (!project) {
+    process.stdout.write(`${JSON.stringify({ at: new Date().toISOString(), workspace, status: "no_project" })}\n`);
+    return;
+  }
+  const result = await runDashboardRefreshCoordinator(project, { limit: 32, signal: abortController.signal });
+  process.stdout.write(`${JSON.stringify({ at: new Date().toISOString(), project, ...result })}\n`);
+}
+
+async function selectWorkspaceProject(root) {
+  const canonicalRoot = await realpath(root);
+  const entries = await readdir(canonicalRoot, { withFileTypes: true });
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name === ".fpa-dashboard") continue;
+    const project = await realpath(resolve(canonicalRoot, entry.name));
+    if (dirname(project) === canonicalRoot) return project;
+  }
+  return null;
+}
+
+if (args.includes("--once")) {
+  try {
+    await runOnce();
+  } catch (error) {
+    if (!abortController.signal.aborted) throw error;
+  }
+} else {
+  while (!stopping) {
+    try {
+	  await runOnce();
+    } catch (error) {
+	  if (abortController.signal.aborted) break;
+	  process.stderr.write(`${new Date().toISOString()} ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    }
+    if (!stopping) await new Promise((resolveWait) => {
+	  const timer = setTimeout(() => {
+		wakeSleep = null;
+		resolveWait();
+	  }, interval);
+	  wakeSleep = () => {
+		clearTimeout(timer);
+		wakeSleep = null;
+		resolveWait();
+	  };
+    });
+  }
+}

package/extensions/fpa-artifacts/compose.ts

@@ -0,0 +1,417 @@
+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;
+	owner?: string;
+	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", "owner", "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,
+		...(source.owner === undefined ? {} : { owner: text(source.owner, `${path}.owner`) }),
+		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,
+		...(slice.owner ? { owner: slice.owner } : {}),
+	}));
+
+	// 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/contracts.ts

@@ -25,6 +25,7 @@ export interface ForecastAllocation {
 	baseline_spend: number | null;
 	approved_spend: number;
 	action: AllocationAction;
+	owner?: string;
 }
 
 export interface ForecastSlice {
@@ -187,6 +188,12 @@ function exactKeys(value: Record<string, unknown>, allowed: readonly string[], p
 	}
 }
 
+function requiredAndOptionalKeys(value: Record<string, unknown>, required: readonly string[], optional: readonly string[], path: string): void {
+	const allowed = new Set([...required, ...optional]);
+	for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`${path}.${key} is not allowed.`);
+	for (const key of required) if (!(key in value)) throw new Error(`${path}.${key} is required.`);
+}
+
 function string(value: unknown, path: string): string {
 	if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
 	return value;
@@ -364,7 +371,7 @@ function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycl
 	const allocations = array(source.approved_allocation, "artifact.approved_allocation").map((value, index) => {
 		const path = `artifact.approved_allocation[${index}]`;
 		const item = record(value, path);
-		exactKeys(item, ["app_id", "store", "channel_group", "baseline_spend", "approved_spend", "action"], path);
+		requiredAndOptionalKeys(item, ["app_id", "store", "channel_group", "baseline_spend", "approved_spend", "action"], ["owner"], path);
 		return {
 			app_id: string(item.app_id, `${path}.app_id`),
 			store: string(item.store, `${path}.store`),
@@ -372,6 +379,7 @@ function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycl
 			baseline_spend: nonNegative(item.baseline_spend, `${path}.baseline_spend`, true),
 			approved_spend: nonNegative(item.approved_spend, `${path}.approved_spend`) as number,
 			action: enumValue(item.action, ALLOCATION_ACTIONS, `${path}.action`),
+			...(item.owner === undefined ? {} : { owner: string(item.owner, `${path}.owner`) }),
 		};
 	});
 	if (allocations.length === 0) throw new Error("artifact.approved_allocation must not be empty.");