@viccydev/pi-fpa 0.2.1 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 面向 Pi 的完整 FP&A 周期资源包，目标运行时为 `@earendil-works/pi-coding-agent` 0.84.1。
 
-本包分发 Prompt Template、Skill、参考合同，以及一个只读数据 Extension（`fpa-data`）。包内不含业务数据与模型凭证，也不实现工作流状态机。多 Agent 隔离、人工审批、Artifact 持久化和真实外部执行仍由宿主运行时或独立工作流承担。
+本包分发 Prompt Template、Skill、参考合同，以及数据读取、规范化 Artifact 和看板投影三个 Extension。包内不含业务数据与模型凭证，也不实现工作流状态机。多 Agent 隔离、人工审批和真实外部执行仍由宿主运行时或独立工作流承担。
 
 ## 包含的资源
 
@@ -23,6 +23,7 @@ Skill：
 - `fpa-forecast-approved-strategy`
 - `fpa-review-cycle`
 - `fpa-execute-approved-strategy`
+- `fpa-refresh-dashboard`
 
 执行 Skill 设置了 `disable-model-invocation: true`，不会出现在模型可主动调用的 Skill 摘要中，也没有对应 Prompt。只有用户显式输入 `/skill:fpa-execute-approved-strategy` 才能加载它；即使显式加载，缺少精确批准、单独执行授权、真实 adapter、幂等键或成功 preflight 时也必须保持 `blocked`，不得产生外部变更。
 
@@ -47,6 +48,19 @@ Extension 内置的关键防护：
 - Apple 指标按来源语义聚合：COUNT 求和、AVERAGE 取日均、LATEST 取期末值。
 - cohort 规模缺失（2026-08-01 之前）时 LTV/留存分母返回 NULL。
 
+## Artifact 与看板 Extension
+
+`fpa-artifacts` 提供 `fpa_artifact_commit`，对 `approved_cycle_forecast` 和 `execution_receipt` 做严格字段校验、对账、稳定指纹和原子落盘。只有工具返回成功后的 JSON 才是冻结产物，Markdown 不是正式数据源。
+
+`fpa-dashboard` 提供两个工具：
+
+| 工具 | 作用 |
+| --- | --- |
+| `fpa_dashboard_status` | 只读检查当前 manifest、构建回执和各数据集是否可读 |
+| `fpa_dashboard_refresh` | 从冻结预测、可选执行回执和实时 Actuals 生成固定的闭环看板；先 preview，再携带相同指纹原子 publish |
+
+看板按 `app_id + store + channel_group` 精确限定同口径 Actuals，比率全部在聚合后重算，缺值保持 `NULL`；未获批的付费分片只形成告警，不混入预测对比，上周期对比按当前 Actuals 已覆盖的等长日历窗口计算。发布器写内容寻址的数据集，并最后原子提升 `manifest.json`，不会让 Web 端读到半成品代际。
+
 ### 凭证配置
 
 Extension 通过 Supabase Management API 只读查询，凭证仅从环境变量读取，绝不写入包内：
@@ -94,12 +108,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.2.0
+pi install git:github.com/linyqh/pi-fpa@v0.3.0
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如当前 `0.2.0` 对应 `v0.2.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如当前 `0.3.0` 对应 `v0.3.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 首次发布前需要完成一次仓库配置：
 
@@ -114,6 +128,7 @@ pi install git:github.com/linyqh/pi-fpa@v0.2.0
 ```text
 /fpa-plan-cycle /path/to/project 2026-Q3 "按 App、Store、Channel Group 规划；预算上限见 planning input"
 /fpa-review-cycle /path/to/project 2026-Q3 "使用已冻结 forecast 和新到达的 Actuals snapshot"
+/skill:fpa-refresh-dashboard "预览并发布当前项目的预测闭环看板"
 ```
 
 规划入口不会进入真实策略执行。需要执行获批策略时，必须在单独、已授权的运行中显式调用：

package/extensions/fpa-artifacts/contracts.ts

@@ -0,0 +1,624 @@
+export const ARTIFACT_TYPES = ["approved_cycle_forecast", "execution_receipt"] as const;
+export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
+
+export const ALLOCATION_ACTIONS = ["stop", "decrease", "hold", "increase", "explore"] as const;
+export type AllocationAction = (typeof ALLOCATION_ACTIONS)[number];
+
+export interface Period {
+	start_inclusive: string;
+	end_exclusive: string;
+	timezone: string;
+}
+
+export interface ScenarioMetric {
+	downside: number | null;
+	base: number | null;
+	upside: number | null;
+	unit: string;
+	window: string;
+}
+
+export interface ForecastAllocation {
+	app_id: string;
+	store: string;
+	channel_group: string;
+	baseline_spend: number | null;
+	approved_spend: number;
+	action: AllocationAction;
+}
+
+export interface ForecastSlice {
+	app_id: string;
+	store: string;
+	channel_group: string;
+	metrics: Record<string, ScenarioMetric>;
+}
+
+export interface CalibrationPolicy {
+	stop_loss_roas_lt: number;
+	deviation_warning_abs_gte: number;
+	deviation_trigger_abs_gt: number;
+	policy_version: string;
+}
+
+export interface ApprovedCycleForecastInput {
+	artifact_type: "approved_cycle_forecast";
+	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: Period;
+	data_as_of: string;
+	source_snapshot_ids: string[];
+	assumption_version: string;
+	model_version: string;
+	reporting_currency: string;
+	approved_allocation: ForecastAllocation[];
+	forecast_by_slice: ForecastSlice[];
+	consolidated_forecast: Record<string, ScenarioMetric>;
+	calibration_policy: CalibrationPolicy;
+	unsupported_metrics: unknown[];
+	reconciliation_checks: unknown[];
+	frozen_at: string;
+}
+
+export interface ApprovedCycleForecast extends ApprovedCycleForecastInput {
+	immutable_fingerprint: string;
+}
+
+export interface ExecutionSlice {
+	app_id: string;
+	store: string;
+	channel_group: string;
+	action: string;
+	planned_spend: number;
+	applied_spend: number | null;
+	evidence_ids: string[];
+}
+
+export interface ExecutionReceiptInput {
+	artifact_type: "execution_receipt";
+	status: "complete" | "complete_with_limits" | "blocked";
+	forecast_version: string;
+	strategy_version: string;
+	human_approval_id: string;
+	execution_request_id: string;
+	execution_mode: "manual" | "adapter";
+	verification_status: "reported" | "verified" | "failed";
+	adapter: string;
+	target_accounts: string[];
+	idempotency_key: string;
+	target_period: Period;
+	reporting_currency: string;
+	preflight: {
+		result: "pass" | "fail";
+		observed_state_fingerprint: string;
+	};
+	dry_run: {
+		supported: boolean;
+		result: "pass" | "fail" | "not_supported";
+	};
+	requested_mutations: unknown[];
+	applied_mutations: unknown[];
+	failed_mutations: unknown[];
+	reconciliation: {
+		result: "pass" | "partial" | "fail";
+		resulting_state_fingerprint: string | null;
+	};
+	executed_at: string | null;
+	slices: ExecutionSlice[];
+	external_receipt_ids: string[];
+	blockers: unknown[];
+}
+
+export interface ExecutionReceipt extends ExecutionReceiptInput {
+	immutable_fingerprint: string;
+}
+
+export type CanonicalArtifactInput = ApprovedCycleForecastInput | ExecutionReceiptInput;
+export type CanonicalArtifact = ApprovedCycleForecast | ExecutionReceipt;
+
+const TOP_LEVEL_KEYS: Record<ArtifactType, readonly string[]> = {
+	approved_cycle_forecast: [
+		"artifact_type",
+		"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",
+		"approved_allocation",
+		"forecast_by_slice",
+		"consolidated_forecast",
+		"calibration_policy",
+		"unsupported_metrics",
+		"reconciliation_checks",
+		"frozen_at",
+	],
+	execution_receipt: [
+		"artifact_type",
+		"status",
+		"forecast_version",
+		"strategy_version",
+		"human_approval_id",
+		"execution_request_id",
+		"execution_mode",
+		"verification_status",
+		"adapter",
+		"target_accounts",
+		"idempotency_key",
+		"target_period",
+		"reporting_currency",
+		"preflight",
+		"dry_run",
+		"requested_mutations",
+		"applied_mutations",
+		"failed_mutations",
+		"reconciliation",
+		"executed_at",
+		"slices",
+		"external_receipt_ids",
+		"blockers",
+	],
+};
+
+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 exactKeys(value: Record<string, unknown>, allowed: readonly string[], path: string): void {
+	const allowedSet = new Set(allowed);
+	for (const key of Object.keys(value)) {
+		if (!allowedSet.has(key)) throw new Error(`${path}.${key} is not allowed.`);
+	}
+	for (const key of allowed) {
+		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;
+}
+
+function number(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 = number(value, path, nullable);
+	if (parsed !== null && parsed < 0) throw new Error(`${path} must be non-negative.`);
+	return parsed;
+}
+
+function boolean(value: unknown, path: string): boolean {
+	if (typeof value !== "boolean") throw new Error(`${path} must be a boolean.`);
+	return value;
+}
+
+function array(value: unknown, path: string): unknown[] {
+	if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+	return value;
+}
+
+function jsonValue(value: unknown, path: string): unknown {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (Array.isArray(value)) return value.map((item, index) => jsonValue(item, `${path}[${index}]`));
+	if (typeof value === "object") {
+		return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, jsonValue(item, `${path}.${key}`)]));
+	}
+	throw new Error(`${path} must contain only JSON-compatible values.`);
+}
+
+function jsonArray(value: unknown, path: string): unknown[] {
+	return array(value, path).map((item, index) => jsonValue(item, `${path}[${index}]`));
+}
+
+function strings(value: unknown, path: string): string[] {
+	return array(value, path).map((item, index) => string(item, `${path}[${index}]`));
+}
+
+function enumValue<const T extends readonly string[]>(value: unknown, values: T, path: string): T[number] {
+	if (typeof value !== "string" || !values.includes(value)) {
+		throw new Error(`${path} must be one of: ${values.join(", ")}.`);
+	}
+	return value as T[number];
+}
+
+function isoTimestamp(value: unknown, path: string): string {
+	const parsed = string(value, path);
+	if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(parsed) || Number.isNaN(Date.parse(parsed))) {
+		throw new Error(`${path} must be an ISO timestamp with an explicit Z or UTC offset.`);
+	}
+	return parsed;
+}
+
+function period(value: unknown, path: string): Period {
+	const source = record(value, path);
+	exactKeys(source, ["start_inclusive", "end_exclusive", "timezone"], path);
+	const result = {
+		start_inclusive: isoTimestamp(source.start_inclusive, `${path}.start_inclusive`),
+		end_exclusive: isoTimestamp(source.end_exclusive, `${path}.end_exclusive`),
+		timezone: string(source.timezone, `${path}.timezone`),
+	};
+	if (Date.parse(result.start_inclusive) >= Date.parse(result.end_exclusive)) {
+		throw new Error(`${path}.end_exclusive must be after start_inclusive.`);
+	}
+	for (const [boundary, timestamp] of [["start_inclusive", result.start_inclusive], ["end_exclusive", result.end_exclusive]] as const) {
+		const instant = new Date(timestamp);
+		let parts: Intl.DateTimeFormatPart[];
+		try {
+			parts = new Intl.DateTimeFormat("en-US", {
+				timeZone: result.timezone,
+				hourCycle: "h23",
+				hour: "2-digit",
+				minute: "2-digit",
+				second: "2-digit",
+			}).formatToParts(instant);
+		} catch {
+			throw new Error(`${path}.timezone must be a supported IANA timezone.`);
+		}
+		const byType = new Map(parts.map((part) => [part.type, part.value]));
+		if (byType.get("hour") !== "00" || byType.get("minute") !== "00" || byType.get("second") !== "00" || instant.getUTCMilliseconds() !== 0) {
+			throw new Error(`${path}.${boundary} must be local midnight in ${result.timezone}.`);
+		}
+	}
+	return result;
+}
+
+export function canonicalForecastWindow(value: Period): string {
+	return `${value.start_inclusive}..${value.end_exclusive}@${value.timezone}`;
+}
+
+function currency(value: unknown, path: string): string {
+	const parsed = string(value, path).toUpperCase();
+	if (!/^[A-Z]{3}$/.test(parsed)) throw new Error(`${path} must be an ISO-4217 currency code.`);
+	return parsed;
+}
+
+function scenarioMetric(value: unknown, path: string): ScenarioMetric {
+	const source = record(value, path);
+	exactKeys(source, ["downside", "base", "upside", "unit", "window"], path);
+	return {
+		downside: number(source.downside, `${path}.downside`, true),
+		base: number(source.base, `${path}.base`, true),
+		upside: number(source.upside, `${path}.upside`, true),
+		unit: string(source.unit, `${path}.unit`),
+		window: string(source.window, `${path}.window`),
+	};
+}
+
+function scenarioMetrics(value: unknown, path: string): Record<string, ScenarioMetric> {
+	const source = record(value, path);
+	const entries = Object.entries(source);
+	if (entries.length === 0) throw new Error(`${path} must contain at least one metric.`);
+	return Object.fromEntries(entries.map(([name, metric]) => [string(name, `${path} key`), scenarioMetric(metric, `${path}.${name}`)]));
+}
+
+export function sliceKey(value: { app_id: string; store: string; channel_group: string }): string {
+	return `${value.app_id}\u0000${value.store}\u0000${value.channel_group}`;
+}
+
+const SCENARIOS = ["downside", "base", "upside"] as const;
+
+function reconcileNumber(actual: number | null, expected: number | null, path: string): void {
+	if (actual === null && expected === null) return;
+	if (actual === null || expected === null) throw new Error(`${path} does not reconcile: expected ${expected}, received ${actual}.`);
+	const tolerance = Math.max(0.000001, Math.abs(expected) * 0.000001);
+	if (Math.abs(actual - expected) > tolerance) {
+		throw new Error(`${path} does not reconcile: expected ${expected}, received ${actual}.`);
+	}
+}
+
+function derivedRatio(numerator: number | null, denominator: number | null): number | null {
+	if (numerator === null || denominator === null || denominator === 0) return null;
+	return numerator / denominator;
+}
+
+function reconcileRoas(metrics: Record<string, ScenarioMetric>, path: string): void {
+	const roas = metrics.roas;
+	if (!roas) return;
+	const revenue = metrics.revenue;
+	const spend = metrics.spend;
+	if (!revenue || !spend) throw new Error(`${path}.roas requires revenue and spend metrics.`);
+	for (const scenario of SCENARIOS) {
+		reconcileNumber(roas[scenario], derivedRatio(revenue[scenario], spend[scenario]), `${path}.roas.${scenario}`);
+	}
+}
+
+function validateFinancialMetricSemantics(
+	metrics: Record<string, ScenarioMetric>,
+	reportingCurrency: string,
+	expectedWindow: string,
+	path: string,
+): void {
+	for (const metricName of ["spend", "revenue"] as const) {
+		const metric = metrics[metricName];
+		if (!metric) throw new Error(`${path}.${metricName} is required.`);
+		if (metric.unit !== reportingCurrency) throw new Error(`${path}.${metricName}.unit must equal reporting_currency ${reportingCurrency}.`);
+		if (metric.window !== expectedWindow) throw new Error(`${path}.${metricName}.window must equal ${expectedWindow}.`);
+	}
+	if (metrics.roas) {
+		if (metrics.roas.unit !== "ratio") throw new Error(`${path}.roas.unit must be ratio.`);
+		if (metrics.roas.window !== expectedWindow) throw new Error(`${path}.roas.window must equal ${expectedWindow}.`);
+	}
+}
+
+function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycleForecastInput {
+	exactKeys(source, TOP_LEVEL_KEYS.approved_cycle_forecast, "artifact");
+	const targetPeriod = period(source.target_period, "artifact.target_period");
+	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);
+		return {
+			app_id: string(item.app_id, `${path}.app_id`),
+			store: string(item.store, `${path}.store`),
+			channel_group: string(item.channel_group, `${path}.channel_group`),
+			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`),
+		};
+	});
+	if (allocations.length === 0) throw new Error("artifact.approved_allocation must not be empty.");
+	if (allocations.length > 500) throw new Error("artifact.approved_allocation cannot exceed 500 slices.");
+
+	const forecastSlices = array(source.forecast_by_slice, "artifact.forecast_by_slice").map((value, index) => {
+		const path = `artifact.forecast_by_slice[${index}]`;
+		const item = record(value, path);
+		exactKeys(item, ["app_id", "store", "channel_group", "metrics"], path);
+		return {
+			app_id: string(item.app_id, `${path}.app_id`),
+			store: string(item.store, `${path}.store`),
+			channel_group: string(item.channel_group, `${path}.channel_group`),
+			metrics: scenarioMetrics(item.metrics, `${path}.metrics`),
+		};
+	});
+
+	const allocationKeys = new Set<string>();
+	for (const allocation of allocations) {
+		const key = sliceKey(allocation);
+		if (allocationKeys.has(key)) throw new Error(`artifact.approved_allocation contains duplicate slice ${key.replaceAll("\u0000", " / ")}.`);
+		allocationKeys.add(key);
+	}
+	const forecastKeys = new Set<string>();
+	for (const slice of forecastSlices) {
+		const key = sliceKey(slice);
+		if (forecastKeys.has(key)) throw new Error(`artifact.forecast_by_slice contains duplicate slice ${key.replaceAll("\u0000", " / ")}.`);
+		forecastKeys.add(key);
+		if (!allocationKeys.has(key)) throw new Error("Every forecast_by_slice row must map to approved_allocation.");
+	}
+	if (forecastKeys.size !== allocationKeys.size) throw new Error("Every approved_allocation row must have one forecast_by_slice row.");
+
+	const consolidated = scenarioMetrics(source.consolidated_forecast, "artifact.consolidated_forecast");
+	const reportingCurrency = currency(source.reporting_currency, "artifact.reporting_currency");
+	if (!consolidated.spend || !consolidated.revenue) throw new Error("artifact.consolidated_forecast requires spend and revenue metrics.");
+	const expectedWindow = canonicalForecastWindow(targetPeriod);
+	validateFinancialMetricSemantics(consolidated, reportingCurrency, expectedWindow, "artifact.consolidated_forecast");
+	for (const slice of forecastSlices) {
+		const path = `artifact.forecast_by_slice[${sliceKey(slice).replaceAll("\u0000", " / ")}]`;
+		validateFinancialMetricSemantics(slice.metrics, reportingCurrency, expectedWindow, `${path}.metrics`);
+		reconcileRoas(slice.metrics, `${path}.metrics`);
+	}
+	for (const metricName of ["spend", "revenue"] as const) {
+		const consolidatedMetric = consolidated[metricName];
+		if (!consolidatedMetric) throw new Error(`artifact.consolidated_forecast.${metricName} is required.`);
+		for (const scenario of SCENARIOS) {
+			const values = forecastSlices.map((slice) => slice.metrics[metricName]?.[scenario] ?? null);
+			const expected = values.every((value) => value !== null)
+				? values.reduce<number>((total, value) => total + (value as number), 0)
+				: null;
+			reconcileNumber(consolidatedMetric[scenario], expected, `artifact.consolidated_forecast.${metricName}.${scenario}`);
+		}
+	}
+	reconcileRoas(consolidated, "artifact.consolidated_forecast");
+	for (const allocation of allocations) {
+		const forecastSlice = forecastSlices.find((slice) => sliceKey(slice) === sliceKey(allocation)) as ForecastSlice;
+		reconcileNumber(forecastSlice.metrics.spend.base, allocation.approved_spend, `artifact.forecast_by_slice[${sliceKey(allocation).replaceAll("\u0000", " / ")}].metrics.spend.base`);
+	}
+	const allocationTotal = allocations.reduce((total, item) => total + item.approved_spend, 0);
+	const consolidatedSpend = consolidated.spend?.base;
+	if (consolidatedSpend === undefined || consolidatedSpend === null) {
+		throw new Error("artifact.consolidated_forecast.spend.base is required.");
+	}
+	if (Math.abs(allocationTotal - consolidatedSpend) > 0.01) {
+		throw new Error(`Approved allocation ${allocationTotal} does not reconcile to consolidated spend ${consolidatedSpend}.`);
+	}
+
+	const policySource = record(source.calibration_policy, "artifact.calibration_policy");
+	exactKeys(policySource, ["stop_loss_roas_lt", "deviation_warning_abs_gte", "deviation_trigger_abs_gt", "policy_version"], "artifact.calibration_policy");
+	const policy = {
+		stop_loss_roas_lt: nonNegative(policySource.stop_loss_roas_lt, "artifact.calibration_policy.stop_loss_roas_lt") as number,
+		deviation_warning_abs_gte: nonNegative(policySource.deviation_warning_abs_gte, "artifact.calibration_policy.deviation_warning_abs_gte") as number,
+		deviation_trigger_abs_gt: nonNegative(policySource.deviation_trigger_abs_gt, "artifact.calibration_policy.deviation_trigger_abs_gt") as number,
+		policy_version: string(policySource.policy_version, "artifact.calibration_policy.policy_version"),
+	};
+	if (policy.deviation_warning_abs_gte > policy.deviation_trigger_abs_gt) {
+		throw new Error("Calibration warning threshold cannot exceed the trigger threshold.");
+	}
+
+	const status = enumValue(source.status, ["complete", "complete_with_limits", "blocked"] as const, "artifact.status");
+	const approvalConditionsSatisfied = boolean(source.approval_conditions_satisfied, "artifact.approval_conditions_satisfied");
+	if (status !== "blocked" && !approvalConditionsSatisfied) {
+		throw new Error("A non-blocked approved forecast requires all approval conditions to be satisfied.");
+	}
+	return {
+		artifact_type: "approved_cycle_forecast",
+		status,
+		forecast_version: string(source.forecast_version, "artifact.forecast_version"),
+		strategy_version: string(source.strategy_version, "artifact.strategy_version"),
+		strategy_review_id: string(source.strategy_review_id, "artifact.strategy_review_id"),
+		human_approval_id: string(source.human_approval_id, "artifact.human_approval_id"),
+		approval_conditions_satisfied: approvalConditionsSatisfied,
+		target_period: targetPeriod,
+		data_as_of: isoTimestamp(source.data_as_of, "artifact.data_as_of"),
+		source_snapshot_ids: strings(source.source_snapshot_ids, "artifact.source_snapshot_ids"),
+		assumption_version: string(source.assumption_version, "artifact.assumption_version"),
+		model_version: string(source.model_version, "artifact.model_version"),
+		reporting_currency: reportingCurrency,
+		approved_allocation: allocations,
+		forecast_by_slice: forecastSlices,
+		consolidated_forecast: consolidated,
+		calibration_policy: policy,
+		unsupported_metrics: jsonArray(source.unsupported_metrics, "artifact.unsupported_metrics"),
+		reconciliation_checks: jsonArray(source.reconciliation_checks, "artifact.reconciliation_checks"),
+		frozen_at: isoTimestamp(source.frozen_at, "artifact.frozen_at"),
+	};
+}
+
+function validateExecutionReceipt(source: Record<string, unknown>): ExecutionReceiptInput {
+	exactKeys(source, TOP_LEVEL_KEYS.execution_receipt, "artifact");
+	const slices = array(source.slices, "artifact.slices").map((value, index) => {
+		const path = `artifact.slices[${index}]`;
+		const item = record(value, path);
+		exactKeys(item, ["app_id", "store", "channel_group", "action", "planned_spend", "applied_spend", "evidence_ids"], path);
+		return {
+			app_id: string(item.app_id, `${path}.app_id`),
+			store: string(item.store, `${path}.store`),
+			channel_group: string(item.channel_group, `${path}.channel_group`),
+			action: string(item.action, `${path}.action`),
+			planned_spend: nonNegative(item.planned_spend, `${path}.planned_spend`) as number,
+			applied_spend: nonNegative(item.applied_spend, `${path}.applied_spend`, true),
+			evidence_ids: strings(item.evidence_ids, `${path}.evidence_ids`),
+		};
+	});
+	const sliceKeys = new Set<string>();
+	for (const slice of slices) {
+		const key = sliceKey(slice);
+		if (sliceKeys.has(key)) throw new Error(`artifact.slices contains duplicate slice ${key.replaceAll("\u0000", " / ")}.`);
+		sliceKeys.add(key);
+	}
+
+	const preflightSource = record(source.preflight, "artifact.preflight");
+	exactKeys(preflightSource, ["result", "observed_state_fingerprint"], "artifact.preflight");
+	const preflight = {
+		result: enumValue(preflightSource.result, ["pass", "fail"] as const, "artifact.preflight.result"),
+		observed_state_fingerprint: string(preflightSource.observed_state_fingerprint, "artifact.preflight.observed_state_fingerprint"),
+	};
+	const dryRunSource = record(source.dry_run, "artifact.dry_run");
+	exactKeys(dryRunSource, ["supported", "result"], "artifact.dry_run");
+	const dryRun = {
+		supported: boolean(dryRunSource.supported, "artifact.dry_run.supported"),
+		result: enumValue(dryRunSource.result, ["pass", "fail", "not_supported"] as const, "artifact.dry_run.result"),
+	};
+	if (dryRun.supported && dryRun.result === "not_supported") {
+		throw new Error("artifact.dry_run.result cannot be not_supported when dry_run.supported is true.");
+	}
+	if (!dryRun.supported && dryRun.result !== "not_supported") {
+		throw new Error("artifact.dry_run.result must be not_supported when dry_run.supported is false.");
+	}
+
+	const reconciliationSource = record(source.reconciliation, "artifact.reconciliation");
+	exactKeys(reconciliationSource, ["result", "resulting_state_fingerprint"], "artifact.reconciliation");
+	const reconciliation = {
+		result: enumValue(reconciliationSource.result, ["pass", "partial", "fail"] as const, "artifact.reconciliation.result"),
+		resulting_state_fingerprint: reconciliationSource.resulting_state_fingerprint === null
+			? null
+			: string(reconciliationSource.resulting_state_fingerprint, "artifact.reconciliation.resulting_state_fingerprint"),
+	};
+	const requestedMutations = jsonArray(source.requested_mutations, "artifact.requested_mutations");
+	const appliedMutations = jsonArray(source.applied_mutations, "artifact.applied_mutations");
+	const failedMutations = jsonArray(source.failed_mutations, "artifact.failed_mutations");
+	const status = enumValue(source.status, ["complete", "complete_with_limits", "blocked"] as const, "artifact.status");
+	const verificationStatus = enumValue(source.verification_status, ["reported", "verified", "failed"] as const, "artifact.verification_status");
+	const externalReceiptIds = strings(source.external_receipt_ids, "artifact.external_receipt_ids");
+	const executedAt = source.executed_at === null ? null : isoTimestamp(source.executed_at, "artifact.executed_at");
+	if (status === "blocked" && (appliedMutations.length > 0 || slices.some((slice) => slice.applied_spend !== null))) {
+		throw new Error("A blocked execution receipt cannot contain applied mutations or applied spend.");
+	}
+	if (status === "blocked" && executedAt !== null) {
+		throw new Error("A blocked execution receipt cannot have executed_at.");
+	}
+	if (verificationStatus === "verified") {
+		if (executedAt === null) throw new Error("Verified execution requires executed_at evidence.");
+		if (reconciliation.result !== "pass" || reconciliation.resulting_state_fingerprint === null) {
+			throw new Error("Verified execution requires a passing reconciliation and resulting-state fingerprint evidence.");
+		}
+		if (slices.length === 0 || slices.some((slice) => slice.applied_spend === null || slice.evidence_ids.length === 0)) {
+			throw new Error("Verified execution requires applied spend and evidence for every receipt slice.");
+		}
+	}
+	if (status === "complete" && verificationStatus !== "verified") {
+		throw new Error("A complete execution receipt must be verified; reported or failed execution is complete_with_limits or blocked.");
+	}
+	return {
+		artifact_type: "execution_receipt",
+		status,
+		forecast_version: string(source.forecast_version, "artifact.forecast_version"),
+		strategy_version: string(source.strategy_version, "artifact.strategy_version"),
+		human_approval_id: string(source.human_approval_id, "artifact.human_approval_id"),
+		execution_request_id: string(source.execution_request_id, "artifact.execution_request_id"),
+		execution_mode: enumValue(source.execution_mode, ["manual", "adapter"] as const, "artifact.execution_mode"),
+		verification_status: verificationStatus,
+		adapter: string(source.adapter, "artifact.adapter"),
+		target_accounts: strings(source.target_accounts, "artifact.target_accounts"),
+		idempotency_key: string(source.idempotency_key, "artifact.idempotency_key"),
+		target_period: period(source.target_period, "artifact.target_period"),
+		reporting_currency: currency(source.reporting_currency, "artifact.reporting_currency"),
+		preflight,
+		dry_run: dryRun,
+		requested_mutations: requestedMutations,
+		applied_mutations: appliedMutations,
+		failed_mutations: failedMutations,
+		reconciliation,
+		executed_at: executedAt,
+		slices,
+		external_receipt_ids: externalReceiptIds,
+		blockers: jsonArray(source.blockers, "artifact.blockers"),
+	};
+}
+
+export function validateArtifact(value: unknown): CanonicalArtifactInput {
+	const source = record(value, "artifact");
+	const artifactType = enumValue(source.artifact_type, ARTIFACT_TYPES, "artifact.artifact_type");
+	return artifactType === "approved_cycle_forecast"
+		? validateApprovedForecast(source)
+		: validateExecutionReceipt(source);
+}
+
+export function isApprovedCycleForecast(value: CanonicalArtifact): value is ApprovedCycleForecast {
+	return value.artifact_type === "approved_cycle_forecast";
+}
+
+export function isExecutionReceiptForForecast(
+	execution: Pick<ExecutionReceiptInput, "forecast_version">,
+	forecast: Pick<ApprovedCycleForecastInput, "forecast_version">,
+): boolean {
+	return execution.forecast_version === forecast.forecast_version;
+}
+
+export function validateExecutionAgainstForecast(
+	execution: ExecutionReceiptInput,
+	forecast: ApprovedCycleForecastInput,
+): void {
+	if (execution.forecast_version !== forecast.forecast_version) throw new Error("Execution receipt forecast_version does not match the approved forecast.");
+	if (execution.strategy_version !== forecast.strategy_version) throw new Error("Execution receipt strategy_version does not match the approved forecast.");
+	if (execution.human_approval_id !== forecast.human_approval_id) throw new Error("Execution receipt human_approval_id does not match the approved forecast.");
+	const allocationByKey = new Map(forecast.approved_allocation.map((allocation) => [sliceKey(allocation), allocation]));
+	const executionKeys = new Set<string>();
+	for (const slice of execution.slices) {
+		const key = sliceKey(slice);
+		executionKeys.add(key);
+		const allocation = allocationByKey.get(key);
+		if (!allocation) throw new Error(`Execution receipt contains an unapproved slice ${key.replaceAll("\u0000", " / ")}.`);
+		if (slice.action !== allocation.action) throw new Error(`Execution receipt action does not match the approved allocation for ${key.replaceAll("\u0000", " / ")}.`);
+		reconcileNumber(slice.planned_spend, allocation.approved_spend, `execution_receipt.slices[${key.replaceAll("\u0000", " / ")}].planned_spend`);
+	}
+	if (execution.status === "complete" && executionKeys.size !== allocationByKey.size) {
+		throw new Error("A complete execution receipt must contain every approved allocation slice.");
+	}
+}