@viccydev/pi-fpa 0.8.1 → 0.9.1

package/README.md

@@ -80,7 +80,7 @@ Extension 内置的关键防护：
 
 ## Artifact 与看板 Extension
 
-`fpa-artifacts` 提供 `fpa_artifact_commit`，对 `approved_cycle_forecast` 和 `execution_receipt` 做严格字段校验、对账、稳定指纹和原子落盘。只有工具返回成功后的 JSON 才是冻结产物，Markdown 不是正式数据源。
+`fpa-artifacts` 提供 `fpa_forecast_finalize`，把紧凑 Forecast plan 一次性合成、校验、按目标周期推导生命周期角色并冻结；模型无需在 Graph handoff 与 ledger 枚举之间转译 `forecast_role`。通用的 `fpa_artifact_commit` 仍负责 `approved_cycle_forecast` 和 `execution_receipt` 的严格字段校验、对账、稳定指纹和原子落盘。只有工具返回成功后的 JSON 才是冻结产物，Markdown 不是正式数据源。
 
 `fpa-dashboard` 提供分模块发布工具和兼容的闭环刷新工具：
 
@@ -159,12 +159,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.8.1
+pi install git:github.com/linyqh/pi-fpa@v0.9.1
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.8.1` 对应 `v0.8.1`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.1` 对应 `v0.9.1`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/extensions/fpa-artifacts/compose.ts

@@ -6,10 +6,16 @@ import {
 	type AllocationAction,
 	type ApprovedCycleForecastInput,
 	type ForecastAllocation,
+	type ForecastConclusion,
 	type ForecastSlice,
 	type Period,
 	type ScenarioMetric,
 } from "./contracts.ts";
+import {
+	assessForecastQuality,
+	type ForecastDimensionSnapshot,
+	type ForecastQualityAssessment,
+} from "./forecast-quality.ts";
 
 // ============================================================================
 // Composing an approved forecast from a compact plan.
@@ -28,19 +34,14 @@ import {
 // 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.
+// Deliberately returns the artifact instead of writing it, so isolated callers
+// can inspect diagnostics without mutation. The forecast-freeze Graph uses the
+// finalizer as its one mutation seam; malformed plans fail once with the full
+// actionable limitation report instead of entering a repair loop.
 // ============================================================================
 
 /** 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 UaDimensionValues extends ForecastDimensionSnapshot {}
 
 export interface PlanSliceRoas {
 	downside: number | null;
@@ -172,7 +173,10 @@ function sumScenario(values: Array<number | null>): number | null {
 export interface ComposeDiagnostics {
 	slice_count: number;
 	stopped_slice_count: number;
+	limited_slice_count: number;
 	total_approved_spend: number;
+	calculable_approved_spend: number;
+	calculable_spend_pct: number;
 	validated_dimensions: boolean;
 	portfolio_placeholder_app_id: string | null;
 }
@@ -192,21 +196,78 @@ export interface ComposeResult {
  */
 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 },
+		{ dataset: "ua_spend", metrics: ["spend"], dimensions: ["app_code", "platform", "media_source"], limit: 1000 },
 		signal,
 	);
-	const values: UaDimensionValues = { app_code: new Set(), platform: new Set(), media_source: new Set() };
+	const values: UaDimensionValues = { app_code: new Set(), platform: new Set(), media_source: new Set(), tuples: 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));
+		if (row.app_code != null && row.platform != null && row.media_source != null) {
+			values.tuples?.add(sliceKey({
+				app_id: String(row.app_code),
+				store: String(row.platform),
+				channel_group: 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)`;
+/**
+ * Read only the candidate tuples named by the plan. This avoids treating the
+ * structured query's 1000-row safety cap as a complete dimension catalog.
+ */
+async function loadUaDimensionValuesForSlices(slices: PlanSlice[], signal?: AbortSignal): Promise<UaDimensionValues> {
+	const appIds = new Set(slices.map((slice) => slice.app_id));
+	const collapsedAppId = appIds.size === 1 ? [...appIds][0] : null;
+	let portfolioMode = false;
+	if (collapsedAppId !== null) {
+		const appProbe = await runStructuredQuery({
+			dataset: "ua_spend",
+			metrics: ["spend"],
+			dimensions: ["app_code"],
+			filters: { app_code: collapsedAppId },
+			limit: 1,
+		}, signal);
+		portfolioMode = appProbe.rows.length === 0;
+	}
+
+	const uniqueSlices = [...new Map(slices.map((slice) => [sliceKey(slice), slice])).values()];
+	const result = portfolioMode
+		? await runStructuredQuery({
+			dataset: "ua_spend",
+			metrics: ["spend"],
+			dimensions: ["platform", "media_source"],
+			exactUaChannelScope: uniqueSlices.map((slice) => ({ platform: slice.store, media_source: slice.channel_group })),
+			limit: uniqueSlices.length,
+		}, signal)
+		: await runStructuredQuery({
+			dataset: "ua_spend",
+			metrics: ["spend"],
+			dimensions: ["app_code", "platform", "media_source"],
+			exactUaScope: uniqueSlices.map((slice) => ({
+				app_code: slice.app_id,
+				platform: slice.store,
+				media_source: slice.channel_group,
+			})),
+			limit: uniqueSlices.length,
+		}, signal);
+	const values: UaDimensionValues = { app_code: new Set(), platform: new Set(), media_source: new Set(), tuples: 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));
+		if (row.platform != null && row.media_source != null) {
+			values.tuples?.add(sliceKey({
+				app_id: row.app_code == null ? "" : String(row.app_code),
+				store: String(row.platform),
+				channel_group: String(row.media_source),
+			}));
+		}
+	}
+	return values;
 }
 
 /**
@@ -218,33 +279,8 @@ function sample(values: Set<string>, limit = 8): string {
  * 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 function validateSliceKeys(slices: PlanSlice[], values: UaDimensionValues): ForecastQualityAssessment {
+	return assessForecastQuality(slices, values);
 }
 
 export interface ComposeOptions {
@@ -263,6 +299,7 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 	}
 	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));
+	if (slices.length > 500) throw new Error("plan.slices cannot exceed 500 slices.");
 
 	const seen = new Set<string>();
 	for (const slice of slices) {
@@ -289,9 +326,54 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 				+ "Scope deliberately excluded upstream is not a limit — if nothing in scope is missing, the status is complete.",
 		);
 	}
+	if (status === "complete_with_limits") {
+		const limitationErrors: string[] = [];
+		const capture = (check: () => void): void => {
+			try {
+				check();
+			} catch (error) {
+				limitationErrors.push(error instanceof Error ? error.message : String(error));
+			}
+		};
+		for (const [index, value] of unsupported.entries()) {
+			const path = `plan.unsupported_metrics[${index}]`;
+			let item: Record<string, unknown>;
+			try {
+				item = record(value, path);
+			} catch (error) {
+				limitationErrors.push(error instanceof Error ? error.message : String(error));
+				continue;
+			}
+			capture(() => { text(item.metric, `${path}.metric`); });
+			capture(() => { text(item.reason, `${path}.reason`); });
+			if (!Array.isArray(item.affected_scope) || item.affected_scope.length === 0) {
+				limitationErrors.push(`${path}.affected_scope must be a non-empty array.`);
+			} else {
+				for (const [scopeIndex, scope] of item.affected_scope.entries()) {
+					capture(() => { text(scope, `${path}.affected_scope[${scopeIndex}]`); });
+				}
+			}
+			const evidence = item.evidence === undefined ? [] : Array.isArray(item.evidence) ? item.evidence : [item.evidence];
+			if (evidence.length === 0) {
+				limitationErrors.push(`${path}.evidence must not be empty.`);
+			} else {
+				for (const [evidenceIndex, entry] of evidence.entries()) {
+					capture(() => { text(entry, `${path}.evidence[${evidenceIndex}]`); });
+				}
+			}
+			capture(() => { text(item.remediation, `${path}.remediation`); });
+			capture(() => { text(item.owner_role, `${path}.owner_role`); });
+		}
+		if (limitationErrors.length > 0) {
+			throw new Error(`Forecast plan limitations are invalid:\n- ${limitationErrors.join("\n- ")}`);
+		}
+	}
 
-	const loadValues = options.loadDimensionValues ?? loadUaDimensionValues;
-	const { portfolioAppId } = validateSliceKeys(slices, await loadValues(options.signal));
+	const dimensionValues = options.loadDimensionValues
+		? await options.loadDimensionValues(options.signal)
+		: await loadUaDimensionValuesForSlices(slices, options.signal);
+	const quality = validateSliceKeys(slices, dimensionValues);
+	const { portfolioAppId } = quality;
 
 	const period = record(source.target_period, "plan.target_period") as unknown as Period;
 	const currency = text(source.reporting_currency, "plan.reporting_currency").toUpperCase();
@@ -310,8 +392,11 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 	// 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 eligible = quality.eligibleSliceKeys.has(sliceKey(slice));
 		const derived = Object.fromEntries(
-			SCENARIOS.map((scenario) => [scenario, sliceScenario(slice.approved_spend, slice.roas[scenario])]),
+			SCENARIOS.map((scenario) => [scenario, eligible
+				? sliceScenario(slice.approved_spend, slice.roas[scenario])
+				: { revenue: null, roas: null }]),
 		) as Record<Scenario, { revenue: number | null; roas: number | null }>;
 		return {
 			app_id: slice.app_id,
@@ -357,6 +442,45 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		roas: scenarioMetric(consolidatedRoas, "ratio", window),
 	};
 
+	const eligibleForecastSlices = forecastBySlice.filter((slice) => quality.eligibleSliceKeys.has(sliceKey(slice)));
+	const conclusionStatus: ForecastConclusion["status"] = quality.dataQuality.status === "complete"
+		? "available"
+		: quality.dataQuality.status === "partial"
+			? "available_with_limits"
+			: "unavailable";
+	const conclusionScope: ForecastConclusion["scope"] = quality.dataQuality.status === "complete"
+		? "portfolio"
+		: quality.dataQuality.status === "partial"
+			? "calculable_slices"
+			: "none";
+	const conclusionScenario = (metric: "spend" | "revenue"): Record<Scenario, number | null> => Object.fromEntries(
+		SCENARIOS.map((scenario) => {
+			if (conclusionStatus === "unavailable") return [scenario, null];
+			return [scenario, sumScenario(eligibleForecastSlices.map((slice) => slice.metrics[metric][scenario]))];
+		}),
+	) as Record<Scenario, number | null>;
+	const conclusionSpend = conclusionScenario("spend");
+	const conclusionRevenue = conclusionScenario("revenue");
+	const conclusionRoas = Object.fromEntries(SCENARIOS.map((scenario) => {
+		const spend = conclusionSpend[scenario];
+		const revenue = conclusionRevenue[scenario];
+		return [scenario, spend === null || revenue === null || spend === 0 ? null : revenue / spend];
+	})) as Record<Scenario, number | null>;
+	const conclusion: ForecastConclusion = {
+		status: conclusionStatus,
+		scope: conclusionScope,
+		metrics: {
+			spend: scenarioMetric(conclusionSpend, currency, window),
+			revenue: scenarioMetric(conclusionRevenue, currency, window),
+			roas: scenarioMetric(conclusionRoas, "ratio", window),
+		},
+		warning: quality.dataQuality.status === "complete"
+			? null
+			: quality.dataQuality.status === "partial"
+				? `结论仅覆盖可计算切片，占计划支出的 ${(quality.dataQuality.calculable_spend_pct * 100).toFixed(2)}%；未覆盖切片未参与收入和 ROAS 计算。`
+				: "没有可计算切片；已保留全部批准预算，但不提供收入或 ROAS 数值结论。",
+	};
+
 	// 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.
@@ -379,9 +503,19 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		}
 	}
 
+	const artifactStatus = status === "blocked"
+		? "blocked"
+		: quality.dataQuality.status === "complete"
+			? status
+			: "complete_with_limits";
+	const qualityUnsupported = quality.dataQuality.issues.length === 0 ? [] : [{
+		metric: "revenue_roas_by_affected_slice",
+		reason: "slice_key_not_in_actuals",
+		affected_slice_count: quality.dataQuality.issue_count,
+	}];
 	const artifact = {
 		artifact_type: "approved_cycle_forecast",
-		status,
+		status: artifactStatus,
 		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"),
@@ -397,8 +531,10 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		forecast_by_slice: forecastBySlice,
 		consolidated_forecast: consolidated,
 		calibration_policy: source.calibration_policy,
-		unsupported_metrics: unsupported,
+		unsupported_metrics: [...unsupported, ...qualityUnsupported],
 		reconciliation_checks: source.reconciliation_checks,
+		data_quality: quality.dataQuality,
+		conclusion,
 		frozen_at: typeof source.frozen_at === "string" && source.frozen_at.trim()
 			? source.frozen_at
 			: (options.now?.() ?? new Date()).toISOString().replace(/\.\d{3}Z$/, "Z"),
@@ -409,7 +545,10 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		diagnostics: {
 			slice_count: slices.length,
 			stopped_slice_count: slices.filter((slice) => slice.approved_spend === 0).length,
+			limited_slice_count: quality.limitedSliceKeys.size,
 			total_approved_spend: slices.reduce((total, slice) => total + slice.approved_spend, 0),
+			calculable_approved_spend: quality.dataQuality.calculable_spend,
+			calculable_spend_pct: quality.dataQuality.calculable_spend_pct,
 			validated_dimensions: true,
 			portfolio_placeholder_app_id: portfolioAppId,
 		},

package/extensions/fpa-artifacts/contracts.ts

@@ -35,6 +35,35 @@ export interface ForecastSlice {
 	metrics: Record<string, ScenarioMetric>;
 }
 
+export interface ForecastDataQualityIssue {
+	issue_id: string;
+	code: "slice_key_not_in_actuals";
+	severity: "warning";
+	slice: Pick<ForecastSlice, "app_id" | "store" | "channel_group">;
+	affected_metrics: string[];
+	disposition: "excluded_from_calculation";
+	evidence: string[];
+	remediation: string;
+	owner_role: "data_steward";
+}
+
+export interface ForecastDataQuality {
+	status: "complete" | "partial" | "unavailable";
+	planned_spend: number;
+	calculable_spend: number;
+	calculable_spend_pct: number;
+	excluded_spend: number;
+	issue_count: number;
+	issues: ForecastDataQualityIssue[];
+}
+
+export interface ForecastConclusion {
+	status: "available" | "available_with_limits" | "unavailable";
+	scope: "portfolio" | "calculable_slices" | "none";
+	metrics: Record<string, ScenarioMetric>;
+	warning: string | null;
+}
+
 export interface CalibrationPolicy {
 	stop_loss_roas_lt: number;
 	deviation_warning_abs_gte: number;
@@ -62,6 +91,8 @@ export interface ApprovedCycleForecastInput {
 	calibration_policy: CalibrationPolicy;
 	unsupported_metrics: unknown[];
 	reconciliation_checks: unknown[];
+	data_quality?: ForecastDataQuality;
+	conclusion?: ForecastConclusion;
 	frozen_at: string;
 }
 
@@ -235,6 +266,26 @@ function jsonArray(value: unknown, path: string): unknown[] {
 	return array(value, path).map((item, index) => jsonValue(item, `${path}[${index}]`));
 }
 
+function actionableUnsupportedMetrics(value: unknown, path: string): unknown[] {
+	const items = jsonArray(value, path);
+	for (const [index, raw] of items.entries()) {
+		const itemPath = `${path}[${index}]`;
+		const item = record(raw, itemPath);
+		string(item.metric, `${itemPath}.metric`);
+		const reason = string(item.reason, `${itemPath}.reason`);
+		if (reason === "slice_key_not_in_actuals") continue;
+		const scopes = strings(item.affected_scope, `${itemPath}.affected_scope`);
+		if (scopes.length === 0) throw new Error(`${itemPath}.affected_scope must not be empty.`);
+		const evidence = Array.isArray(item.evidence)
+			? strings(item.evidence, `${itemPath}.evidence`)
+			: [string(item.evidence, `${itemPath}.evidence`)];
+		if (evidence.length === 0) throw new Error(`${itemPath}.evidence must not be empty.`);
+		string(item.remediation, `${itemPath}.remediation`);
+		string(item.owner_role, `${itemPath}.owner_role`);
+	}
+	return items;
+}
+
 function strings(value: unknown, path: string): string[] {
 	return array(value, path).map((item, index) => string(item, `${path}[${index}]`));
 }
@@ -316,6 +367,70 @@ function scenarioMetrics(value: unknown, path: string): Record<string, ScenarioM
 	return Object.fromEntries(entries.map(([name, metric]) => [string(name, `${path} key`), scenarioMetric(metric, `${path}.${name}`)]));
 }
 
+function forecastDataQuality(value: unknown, path: string): ForecastDataQuality {
+	const source = record(value, path);
+	exactKeys(source, ["status", "planned_spend", "calculable_spend", "calculable_spend_pct", "excluded_spend", "issue_count", "issues"], path);
+	const issues = array(source.issues, `${path}.issues`).map((raw, index) => {
+		const issuePath = `${path}.issues[${index}]`;
+		const issue = record(raw, issuePath);
+		exactKeys(issue, ["issue_id", "code", "severity", "slice", "affected_metrics", "disposition", "evidence", "remediation", "owner_role"], issuePath);
+		const slice = record(issue.slice, `${issuePath}.slice`);
+		exactKeys(slice, ["app_id", "store", "channel_group"], `${issuePath}.slice`);
+		return {
+			issue_id: string(issue.issue_id, `${issuePath}.issue_id`),
+			code: enumValue(issue.code, ["slice_key_not_in_actuals"] as const, `${issuePath}.code`),
+			severity: enumValue(issue.severity, ["warning"] as const, `${issuePath}.severity`),
+			slice: {
+				app_id: string(slice.app_id, `${issuePath}.slice.app_id`),
+				store: string(slice.store, `${issuePath}.slice.store`),
+				channel_group: string(slice.channel_group, `${issuePath}.slice.channel_group`),
+			},
+			affected_metrics: strings(issue.affected_metrics, `${issuePath}.affected_metrics`),
+			disposition: enumValue(issue.disposition, ["excluded_from_calculation"] as const, `${issuePath}.disposition`),
+			evidence: strings(issue.evidence, `${issuePath}.evidence`),
+			remediation: string(issue.remediation, `${issuePath}.remediation`),
+			owner_role: enumValue(issue.owner_role, ["data_steward"] as const, `${issuePath}.owner_role`),
+		};
+	});
+	for (const [index, issue] of issues.entries()) {
+		const allowedAffectedMetrics = new Set(["actuals_comparison", "revenue", "roas", "execution"]);
+		const actualAffectedMetrics = new Set(issue.affected_metrics);
+		if (actualAffectedMetrics.size !== issue.affected_metrics.length
+			|| actualAffectedMetrics.size !== allowedAffectedMetrics.size
+			|| [...allowedAffectedMetrics].some((metric) => !actualAffectedMetrics.has(metric))) {
+			throw new Error(`${path}.issues[${index}].affected_metrics must contain actuals_comparison, revenue, roas, and execution exactly once.`);
+		}
+	}
+	const plannedSpend = nonNegative(source.planned_spend, `${path}.planned_spend`) as number;
+	const calculableSpend = nonNegative(source.calculable_spend, `${path}.calculable_spend`) as number;
+	const excludedSpend = nonNegative(source.excluded_spend, `${path}.excluded_spend`) as number;
+	const calculableSpendPct = nonNegative(source.calculable_spend_pct, `${path}.calculable_spend_pct`) as number;
+	const issueCount = nonNegative(source.issue_count, `${path}.issue_count`) as number;
+	if (!Number.isInteger(issueCount) || issueCount !== issues.length) throw new Error(`${path}.issue_count must equal issues.length.`);
+	if (calculableSpendPct > 1) throw new Error(`${path}.calculable_spend_pct cannot exceed 1.`);
+	if (Math.abs(plannedSpend - calculableSpend - excludedSpend) > 0.01) throw new Error(`${path} spend coverage does not reconcile.`);
+	return {
+		status: enumValue(source.status, ["complete", "partial", "unavailable"] as const, `${path}.status`),
+		planned_spend: plannedSpend,
+		calculable_spend: calculableSpend,
+		calculable_spend_pct: calculableSpendPct,
+		excluded_spend: excludedSpend,
+		issue_count: issueCount,
+		issues,
+	};
+}
+
+function forecastConclusion(value: unknown, path: string): ForecastConclusion {
+	const source = record(value, path);
+	exactKeys(source, ["status", "scope", "metrics", "warning"], path);
+	return {
+		status: enumValue(source.status, ["available", "available_with_limits", "unavailable"] as const, `${path}.status`),
+		scope: enumValue(source.scope, ["portfolio", "calculable_slices", "none"] as const, `${path}.scope`),
+		metrics: scenarioMetrics(source.metrics, `${path}.metrics`),
+		warning: source.warning === null ? null : string(source.warning, `${path}.warning`),
+	};
+}
+
 export function sliceKey(value: { app_id: string; store: string; channel_group: string }): string {
 	return `${value.app_id}\u0000${value.store}\u0000${value.channel_group}`;
 }
@@ -366,7 +481,7 @@ function validateFinancialMetricSemantics(
 }
 
 function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycleForecastInput {
-	exactKeys(source, TOP_LEVEL_KEYS.approved_cycle_forecast, "artifact");
+	requiredAndOptionalKeys(source, TOP_LEVEL_KEYS.approved_cycle_forecast, ["data_quality", "conclusion"], "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}]`;
@@ -460,6 +575,85 @@ function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycl
 	}
 
 	const status = enumValue(source.status, ["complete", "complete_with_limits", "blocked"] as const, "artifact.status");
+	const unsupportedMetrics = actionableUnsupportedMetrics(source.unsupported_metrics, "artifact.unsupported_metrics");
+	if (status === "complete" && unsupportedMetrics.length > 0) {
+		throw new Error("A complete forecast cannot carry unsupported_metrics; use complete_with_limits.");
+	}
+	if (status === "complete_with_limits" && unsupportedMetrics.length === 0) {
+		throw new Error("A complete_with_limits forecast must describe at least one unsupported metric or data limit.");
+	}
+	const dataQuality = source.data_quality === undefined ? undefined : forecastDataQuality(source.data_quality, "artifact.data_quality");
+	const conclusion = source.conclusion === undefined ? undefined : forecastConclusion(source.conclusion, "artifact.conclusion");
+	if ((dataQuality === undefined) !== (conclusion === undefined)) {
+		throw new Error("artifact.data_quality and artifact.conclusion must be supplied together.");
+	}
+	const declaresSliceKeyLimit = unsupportedMetrics.some((item) => item !== null
+		&& typeof item === "object"
+		&& !Array.isArray(item)
+		&& (item as Record<string, unknown>).reason === "slice_key_not_in_actuals");
+	if (declaresSliceKeyLimit && (!dataQuality || dataQuality.issues.length === 0)) {
+		throw new Error("A slice_key_not_in_actuals limit requires data_quality issues and a partial conclusion.");
+	}
+	if (status === "complete" && dataQuality && dataQuality.status !== "complete") {
+		throw new Error("A complete forecast cannot carry partial or unavailable data quality.");
+	}
+	if (dataQuality && conclusion) {
+		const issueKeys = new Set<string>();
+		for (const issue of dataQuality.issues) {
+			const key = sliceKey(issue.slice);
+			if (!allocationKeys.has(key)) throw new Error(`artifact.data_quality issue slice is not in approved_allocation: ${key.replaceAll("\u0000", " / ")}.`);
+			if (issueKeys.has(key)) throw new Error(`artifact.data_quality contains duplicate issue slice ${key.replaceAll("\u0000", " / ")}.`);
+			issueKeys.add(key);
+			const affectedForecast = forecastSlices.find((slice) => sliceKey(slice) === key) as ForecastSlice;
+			for (const scenario of SCENARIOS) {
+				if (affectedForecast.metrics.revenue[scenario] !== null || affectedForecast.metrics.roas?.[scenario] !== null) {
+					throw new Error(`artifact.data_quality affected slice ${key.replaceAll("\u0000", " / ")} must keep revenue and ROAS null.`);
+				}
+			}
+		}
+		const expectedExcludedSpend = allocations
+			.filter((allocation) => issueKeys.has(sliceKey(allocation)))
+			.reduce((total, allocation) => total + allocation.approved_spend, 0);
+		const expectedCalculableSpend = allocationTotal - expectedExcludedSpend;
+		reconcileNumber(dataQuality.planned_spend, allocationTotal, "artifact.data_quality.planned_spend vs approved allocation");
+		reconcileNumber(dataQuality.excluded_spend, expectedExcludedSpend, "artifact.data_quality.excluded_spend vs affected allocation");
+		reconcileNumber(dataQuality.calculable_spend, expectedCalculableSpend, "artifact.data_quality.calculable_spend vs eligible allocation");
+		const expectedPct = allocationTotal === 0 ? (issueKeys.size === 0 ? 1 : 0) : expectedCalculableSpend / allocationTotal;
+		reconcileNumber(dataQuality.calculable_spend_pct, expectedPct, "artifact.data_quality.calculable_spend_pct coverage");
+		const expectedQualityStatus: ForecastDataQuality["status"] = issueKeys.size === 0
+			? "complete"
+			: expectedCalculableSpend === 0
+				? "unavailable"
+				: "partial";
+		if (dataQuality.status !== expectedQualityStatus) throw new Error(`artifact.data_quality.status must be ${expectedQualityStatus}.`);
+		const expectedConclusionStatus: ForecastConclusion["status"] = expectedQualityStatus === "complete"
+			? "available"
+			: expectedQualityStatus === "partial"
+				? "available_with_limits"
+				: "unavailable";
+		const expectedConclusionScope: ForecastConclusion["scope"] = expectedQualityStatus === "complete"
+			? "portfolio"
+			: expectedQualityStatus === "partial"
+				? "calculable_slices"
+				: "none";
+		if (conclusion.status !== expectedConclusionStatus || conclusion.scope !== expectedConclusionScope) {
+			throw new Error(`artifact.conclusion must use ${expectedConclusionStatus} / ${expectedConclusionScope} for its data coverage.`);
+		}
+		validateFinancialMetricSemantics(conclusion.metrics, reportingCurrency, expectedWindow, "artifact.conclusion.metrics");
+		reconcileRoas(conclusion.metrics, "artifact.conclusion.metrics");
+		const eligibleForecastSlices = forecastSlices.filter((slice) => !issueKeys.has(sliceKey(slice)));
+		for (const metricName of ["spend", "revenue"] as const) {
+			for (const scenario of SCENARIOS) {
+				const values = eligibleForecastSlices.map((slice) => slice.metrics[metricName][scenario]);
+				const expected = expectedQualityStatus === "unavailable"
+					? null
+					: values.every((value) => value !== null)
+						? values.reduce<number>((total, value) => total + (value as number), 0)
+						: null;
+				reconcileNumber(conclusion.metrics[metricName][scenario], expected, `artifact.conclusion.metrics.${metricName}.${scenario}`);
+			}
+		}
+	}
 	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.");
@@ -482,8 +676,10 @@ function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycl
 		forecast_by_slice: forecastSlices,
 		consolidated_forecast: consolidated,
 		calibration_policy: policy,
-		unsupported_metrics: jsonArray(source.unsupported_metrics, "artifact.unsupported_metrics"),
+		unsupported_metrics: unsupportedMetrics,
 		reconciliation_checks: jsonArray(source.reconciliation_checks, "artifact.reconciliation_checks"),
+		...(dataQuality ? { data_quality: dataQuality } : {}),
+		...(conclusion ? { conclusion } : {}),
 		frozen_at: isoTimestamp(source.frozen_at, "artifact.frozen_at"),
 	};
 }
@@ -617,9 +813,13 @@ export function validateExecutionAgainstForecast(
 	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 isolatedExecutionKeys = new Set((forecast.data_quality?.issues ?? []).map((issue) => sliceKey(issue.slice)));
 	const executionKeys = new Set<string>();
 	for (const slice of execution.slices) {
 		const key = sliceKey(slice);
+		if (isolatedExecutionKeys.has(key)) {
+			throw new Error(`Execution receipt contains a slice isolated by forecast data quality: ${key.replaceAll("\u0000", " / ")}.`);
+		}
 		executionKeys.add(key);
 		const allocation = allocationByKey.get(key);
 		if (!allocation) throw new Error(`Execution receipt contains an unapproved slice ${key.replaceAll("\u0000", " / ")}.`);