@viccydev/pi-fpa 0.6.2 → 0.7.0

package/README.md

@@ -60,7 +60,7 @@ Extension 内置的关键防护：
 | --- | --- |
 | `fpa_dashboard_status` | 只读检查当前 manifest、构建回执和各数据集是否可读 |
 | `fpa_dashboard_refresh` | 从冻结预测、可选执行回执和实时 Actuals 生成固定的闭环看板；先 preview，再携带相同指纹原子 publish |
-| `fpa_dashboard_refresh_queue` | 检查或处理持久刷新队列；Forecast/Execution commit 自动入队，Actuals watermark 按 SLA 轮询并幂等发布 |
+| `fpa_dashboard_refresh_queue` | 检查或处理持久刷新队列；主 Agent 用 `enqueue_artifact` 显式交接 Forecast/Execution，Actuals watermark 按 SLA 轮询并幂等发布 |
 
 持续刷新由 package 自带的独立 worker 驱动，Web 保持严格只读：
 
@@ -127,12 +127,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.6.2
+pi install git:github.com/linyqh/pi-fpa@v0.7.0
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.6.2` 对应 `v0.6.2`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.7.0` 对应 `v0.7.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/extensions/fpa-artifacts/index.ts

@@ -2,7 +2,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { composeApprovedForecast } from "./compose.ts";
-import { enqueueDashboardRefresh } from "../fpa-dashboard/coordinator.ts";
 import {
 	commitArtifact,
 	commitArtifactFromPath,
@@ -53,7 +52,7 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 				context: Type.Optional(Type.Object({
 					scope_id: Type.String({ minLength: 1, maxLength: 256 }),
 					cycle_id: Type.String({ minLength: 1, maxLength: 256 }),
-					forecast_role: Type.Optional(Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan")])),
+					forecast_role: Type.Optional(Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan"), Type.Literal("backtest")])),
 					upstream_refs: Type.Optional(Type.Array(artifactRefSchema, { maxItems: 16 })),
 					promote_legacy_pointer: Type.Optional(Type.Boolean()),
 				}, { additionalProperties: false })),
@@ -79,40 +78,21 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 			const committed = hasPath
 				? await commitArtifactFromPath(ctx.cwd, params.artifact_path as string, commitOptions)
 				: await commitArtifact(ctx.cwd, params.artifact, commitOptions);
-			let dashboardRefresh;
-			let dashboardRefreshError: string | undefined;
-			if (committed.artifactRef && params.context) {
-				try {
-					const forecastRef = committed.artifactType === "approved_cycle_forecast"
-						? committed.artifactRef
-						: params.context.upstream_refs?.find((ref) => ref.artifact_type === "approved_cycle_forecast") as ArtifactRefV2 | undefined;
-					if (!forecastRef) throw new Error("Assigned execution commit has no forecast ref for dashboard refresh.");
-					dashboardRefresh = await enqueueDashboardRefresh(ctx.cwd, {
-						preset: "forecast-closed-loop-v1",
-						locale: "zh-CN",
-						scope_id: params.context.scope_id,
-						cycle_id: params.context.cycle_id,
-						forecast_ref: forecastRef,
-						...(committed.artifactType === "approved_cycle_forecast" && params.context.forecast_role ? { forecast_role: params.context.forecast_role } : {}),
-						...(committed.artifactType === "execution_receipt" ? { execution_ref: committed.artifactRef } : {}),
-						reason: committed.artifactType === "approved_cycle_forecast" ? "forecast_committed" : "execution_committed",
-					});
-				} catch (error) {
-					// The immutable ledger commit is already durable. Report the
-					// secondary delivery failure explicitly instead of pretending the
-					// commit itself failed and encouraging an unsafe duplicate retry.
-					dashboardRefreshError = error instanceof Error ? error.message : String(error);
-				}
-			}
 			return toolResult({
-				status: dashboardRefreshError ? "committed_refresh_enqueue_failed" : "committed",
+				status: "committed",
 				artifact_type: committed.artifactType,
 				immutable_fingerprint: committed.fingerprint,
 				path: committed.path,
 				ledger_status: committed.ledgerStatus,
 				...(committed.artifactRef ? { artifact_ref: committed.artifactRef } : {}),
-				...(dashboardRefresh ? { dashboard_refresh: dashboardRefresh } : {}),
-				...(dashboardRefreshError ? { dashboard_refresh_error: dashboardRefreshError } : {}),
+				...(committed.artifactRef ? {
+					dashboard_handoff: {
+						status: "deferred",
+						tool: "fpa_dashboard_refresh_queue",
+						action: "enqueue_artifact",
+						artifact_ref: committed.artifactRef,
+					},
+				} : {}),
 			});
 		},
 	});

package/extensions/fpa-artifacts/store.ts

@@ -35,18 +35,25 @@ export interface ArtifactRefV2 {
 	body_fingerprint: string;
 }
 
+export const FORECAST_ROLES = ["original", "eac", "next_plan", "backtest"] as const;
+export type ForecastRole = typeof FORECAST_ROLES[number];
+
+export function isForecastRole(value: unknown): value is ForecastRole {
+	return typeof value === "string" && (FORECAST_ROLES as readonly string[]).includes(value);
+}
+
 export interface ArtifactCommitContext {
 	scope_id: string;
 	cycle_id: string;
 	upstream_refs?: ArtifactRefV2[];
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: ForecastRole;
 }
 
 export interface ArtifactLedgerContext {
 	scope_id: string;
 	cycle_id: string;
 	upstream_refs: ArtifactRefV2[];
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: ForecastRole;
 }
 
 export interface CommitArtifactOptions {
@@ -61,7 +68,7 @@ interface ArtifactLedgerEntry extends ArtifactRefV2 {
 	created_at: string;
 	available_at: string;
 	upstream_refs: ArtifactRefV2[];
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: ForecastRole;
 	assignment_status: "assigned";
 }
 
@@ -227,14 +234,14 @@ function validateCommitContext(value: ArtifactCommitContext): ArtifactLedgerCont
 	if (!Array.isArray(upstream) || upstream.length > 16) throw new Error("context.upstream_refs must be an array of at most 16 artifact refs.");
 	const upstreamRefs = upstream.map((ref, index) => validateArtifactRef(ref, `context.upstream_refs[${index}]`));
 	if (new Set(upstreamRefs.map((ref) => ref.entry_id)).size !== upstreamRefs.length) throw new Error("context.upstream_refs must not contain duplicates.");
-	if (source.forecast_role !== undefined && source.forecast_role !== "original" && source.forecast_role !== "eac" && source.forecast_role !== "next_plan") {
-		throw new Error("context.forecast_role must be original, eac, or next_plan.");
+	if (source.forecast_role !== undefined && !isForecastRole(source.forecast_role)) {
+		throw new Error("context.forecast_role must be original, eac, next_plan, or backtest.");
 	}
 	return {
 		scope_id: contextId(source.scope_id, "context.scope_id"),
 		cycle_id: contextId(source.cycle_id, "context.cycle_id"),
 		upstream_refs: upstreamRefs,
-		...(source.forecast_role ? { forecast_role: source.forecast_role as ArtifactLedgerContext["forecast_role"] } : {}),
+		...(isForecastRole(source.forecast_role) ? { forecast_role: source.forecast_role } : {}),
 	};
 }
 
@@ -326,7 +333,7 @@ function validateLedgerEntry(value: Record<string, unknown>, path: string): { re
 	}
 	if (!Array.isArray(value.upstream_refs) || value.upstream_refs.length > 16) throw new Error(`${path}.upstream_refs must be an array of at most 16 artifact refs.`);
 	const upstreamRefs = value.upstream_refs.map((item, index) => validateArtifactRef(item, `${path}.upstream_refs[${index}]`));
-	if (value.forecast_role !== undefined && value.forecast_role !== "original" && value.forecast_role !== "eac" && value.forecast_role !== "next_plan") {
+	if (value.forecast_role !== undefined && !isForecastRole(value.forecast_role)) {
 		throw new Error(`${path}.forecast_role is unsupported.`);
 	}
 	if (ref.artifact_type === "execution_receipt" && value.forecast_role !== undefined) throw new Error(`${path}.forecast_role is allowed only for forecasts.`);
@@ -334,7 +341,7 @@ function validateLedgerEntry(value: Record<string, unknown>, path: string): { re
 		scope_id: ref.scope_id,
 		cycle_id: ref.cycle_id,
 		upstream_refs: upstreamRefs,
-		...(value.forecast_role ? { forecast_role: value.forecast_role as ArtifactLedgerContext["forecast_role"] } : {}),
+		...(isForecastRole(value.forecast_role) ? { forecast_role: value.forecast_role } : {}),
 	};
 	const expectedEntryId = entryIdentity(context, ref.artifact_type, ref.body_fingerprint);
 	if (expectedEntryId !== ref.entry_id) throw new Error(`${path} identity does not match its upstream refs.`);
@@ -418,9 +425,22 @@ async function commitLedgerEntry(
 export async function commitArtifact(projectRoot: string, input: unknown, options: CommitArtifactOptions = {}): Promise<CommitArtifactResult> {
 	const artifact = validateArtifact(input);
 	const context = options.context ? validateCommitContext(options.context) : null;
-	if (artifact.artifact_type === "approved_cycle_forecast" && context?.forecast_role === "original"
-		&& Date.parse(artifact.frozen_at) > Date.parse(artifact.target_period.start_inclusive)) {
-		throw new Error("An original forecast must be frozen no later than the target period start; use forecast_role=eac for an in-period reforecast.");
+	if (artifact.artifact_type === "approved_cycle_forecast" && context?.forecast_role) {
+		const frozenAt = Date.parse(artifact.frozen_at);
+		const periodStart = Date.parse(artifact.target_period.start_inclusive);
+		const periodEnd = Date.parse(artifact.target_period.end_exclusive);
+		if (context.forecast_role === "original" && frozenAt > periodStart) {
+			throw new Error("An original forecast must be frozen no later than the target period start; use forecast_role=eac for an in-period reforecast.");
+		}
+		if (context.forecast_role === "eac" && (frozenAt < periodStart || frozenAt >= periodEnd)) {
+			throw new Error("An EAC forecast must be frozen during its target period.");
+		}
+		if (context.forecast_role === "next_plan" && frozenAt > periodStart) {
+			throw new Error("A next-plan forecast must be frozen no later than its target period start.");
+		}
+		if (context.forecast_role === "backtest" && frozenAt < periodEnd) {
+			throw new Error("A backtest forecast must be frozen after its target period has ended.");
+		}
 	}
 	if (artifact.artifact_type === "execution_receipt") {
 		if (context?.forecast_role !== undefined) throw new Error("context.forecast_role is allowed only for approved forecasts.");
@@ -442,9 +462,13 @@ export async function commitArtifact(projectRoot: string, input: unknown, option
 	}
 	const fingerprint = artifactFingerprint(artifact);
 	const committed = { ...artifact, immutable_fingerprint: fingerprint } as CanonicalArtifact;
+	const forwardOnlyRole = context?.forecast_role === "next_plan" || context?.forecast_role === "backtest";
+	const promoteLegacyPointer = options.promoteLegacyPointer ?? !forwardOnlyRole;
+	if (forwardOnlyRole && promoteLegacyPointer) {
+		throw new Error(`A ${context.forecast_role} forecast cannot replace the legacy operating pointer.`);
+	}
 	const ledgerCommit = context ? await commitLedgerEntry(projectRoot, committed, context) : undefined;
 	const artifactRef = ledgerCommit?.ref;
-	const promoteLegacyPointer = options.promoteLegacyPointer ?? true;
 	const destination = promoteLegacyPointer
 		? await writeLegacyPointer(projectRoot, committed)
 		: ledgerCommit?.bodyPath ?? join(await ensureArtifactDirectory(projectRoot), `${artifact.artifact_type}.json`);

package/extensions/fpa-dashboard/coordinator.ts

@@ -2,7 +2,13 @@ import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, open, readFile, readdir, realpath, rename, stat, unlink } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
-import { readArtifactByRef, stableJson, validateArtifactRef, type ArtifactRefV2 } from "../fpa-artifacts/store.ts";
+import {
+	readArtifactByRef,
+	stableJson,
+	validateArtifactRef,
+	type ArtifactRefV2,
+	type ForecastRole,
+} from "../fpa-artifacts/store.ts";
 import { dashboardBuildFingerprint, publishDashboard, resolveDashboardDir } from "./publisher.ts";
 import { buildDashboardProjection } from "./service.ts";
 
@@ -19,7 +25,7 @@ export interface DashboardRefreshRequest {
 	scope_id: string;
 	cycle_id: string;
 	forecast_ref: ArtifactRefV2;
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: OperatingForecastRole;
 	execution_ref?: ArtifactRefV2;
 	next_forecast_ref?: ArtifactRefV2;
 	forward_forecast_refs?: ArtifactRefV2[];
@@ -52,6 +58,80 @@ export interface EnqueueDashboardRefreshResult {
 	queue_dir: string;
 }
 
+export interface DashboardRefreshNotApplicableResult {
+	status: "not_applicable";
+	reason: "backtest_forecasts_do_not_update_the_operating_dashboard";
+	artifact_ref: ArtifactRefV2;
+}
+
+type OperatingForecastRole = Exclude<ForecastRole, "backtest">;
+
+function isOperatingForecastRole(value: unknown): value is OperatingForecastRole {
+	return value === "original" || value === "eac" || value === "next_plan";
+}
+
+function backtestNotApplicable(artifactRef: ArtifactRefV2): DashboardRefreshNotApplicableResult {
+	return {
+		status: "not_applicable",
+		reason: "backtest_forecasts_do_not_update_the_operating_dashboard",
+		artifact_ref: artifactRef,
+	};
+}
+
+/**
+ * Resolve one exact committed artifact into durable dashboard work.
+ *
+ * This is the package-owned handoff seam used by the main Agent after a Graph
+ * finishes. Callers provide only the immutable artifact ref; role and upstream
+ * lineage are read from the ledger rather than guessed or copied from prompts.
+ */
+export async function enqueueDashboardRefreshForArtifact(
+	cwd: string,
+	value: unknown,
+	locale: "zh-CN" | "en-US" = "zh-CN",
+): Promise<EnqueueDashboardRefreshResult | DashboardRefreshNotApplicableResult> {
+	const artifactRef = validateArtifactRef(value);
+	const committed = await readArtifactByRef(cwd, artifactRef);
+	const context = committed.ledgerContext;
+	if (!context) throw new Error("Dashboard handoff requires an assigned ledger artifact.");
+
+	if (committed.artifact.artifact_type === "approved_cycle_forecast") {
+		if (!context.forecast_role) throw new Error("Dashboard handoff requires the committed forecast_role from ledger context.");
+		if (context.forecast_role === "backtest") {
+			return backtestNotApplicable(artifactRef);
+		}
+		return enqueueDashboardRefresh(cwd, {
+			preset: "forecast-closed-loop-v1",
+			locale,
+			scope_id: artifactRef.scope_id,
+			cycle_id: artifactRef.cycle_id,
+			forecast_ref: artifactRef,
+			forecast_role: context.forecast_role,
+			reason: "forecast_committed",
+		});
+	}
+
+	if (context.upstream_refs.length !== 1 || context.upstream_refs[0].artifact_type !== "approved_cycle_forecast") {
+		throw new Error("Execution dashboard handoff requires exactly one approved forecast upstream ref.");
+	}
+	const forecastRef = context.upstream_refs[0];
+	const forecast = await readArtifactByRef(cwd, forecastRef);
+	if (!forecast.ledgerContext?.forecast_role) throw new Error("Execution dashboard handoff requires the upstream forecast_role from ledger context.");
+	if (forecast.ledgerContext.forecast_role === "backtest") {
+		return backtestNotApplicable(artifactRef);
+	}
+	return enqueueDashboardRefresh(cwd, {
+		preset: "forecast-closed-loop-v1",
+		locale,
+		scope_id: artifactRef.scope_id,
+		cycle_id: artifactRef.cycle_id,
+		forecast_ref: forecastRef,
+		forecast_role: forecast.ledgerContext.forecast_role,
+		execution_ref: artifactRef,
+		reason: "execution_committed",
+	});
+}
+
 export interface DashboardRefreshQueueStatus {
 	queue_dir: string;
 	pending: number;
@@ -122,7 +202,7 @@ interface DashboardRefreshSubscription {
 	scope_id: string;
 	cycle_id: string;
 	forecast_ref: ArtifactRefV2;
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: OperatingForecastRole;
 	execution_ref?: ArtifactRefV2;
 	next_forecast_ref?: ArtifactRefV2;
 	forward_forecast_refs?: ArtifactRefV2[];
@@ -160,7 +240,7 @@ function validateRequest(value: DashboardRefreshRequest): DashboardRefreshReques
 	const scopeId = boundedId(source.scope_id, "refresh request.scope_id");
 	const cycleId = boundedId(source.cycle_id, "refresh request.cycle_id");
 	const forecastRef = validateArtifactRef(source.forecast_ref, "refresh request.forecast_ref");
-	if (source.forecast_role !== undefined && source.forecast_role !== "original" && source.forecast_role !== "eac" && source.forecast_role !== "next_plan") {
+	if (source.forecast_role !== undefined && !isOperatingForecastRole(source.forecast_role)) {
 		throw new Error("refresh request.forecast_role is unsupported.");
 	}
 	if (forecastRef.artifact_type !== "approved_cycle_forecast" || forecastRef.scope_id !== scopeId || forecastRef.cycle_id !== cycleId) {
@@ -193,7 +273,7 @@ function validateRequest(value: DashboardRefreshRequest): DashboardRefreshReques
 		scope_id: scopeId,
 		cycle_id: cycleId,
 		forecast_ref: forecastRef,
-		...(source.forecast_role ? { forecast_role: source.forecast_role as DashboardRefreshRequest["forecast_role"] } : {}),
+		...(isOperatingForecastRole(source.forecast_role) ? { forecast_role: source.forecast_role } : {}),
 		...(executionRef ? { execution_ref: executionRef } : {}),
 		...(nextForecastRef ? { next_forecast_ref: nextForecastRef } : {}),
 		...(forwardForecastRefs.length > 0 ? { forward_forecast_refs: forwardForecastRefs } : {}),
@@ -494,13 +574,45 @@ async function enqueueEventOnly(
 
 async function sortForwardForecastRefs(projectRoot: string, refs: ArtifactRefV2[]): Promise<ArtifactRefV2[]> {
 	const dated = await Promise.all(refs.map(async (ref) => {
-		const read = await readArtifactByRef(projectRoot, ref);
+		let read;
+		try {
+			read = await readArtifactByRef(projectRoot, ref);
+		} catch (error) {
+			throw new Error(
+				`Forward forecast lineage is incomplete at ${ref.entry_id}: ${error instanceof Error ? error.message : String(error)}`,
+				{ cause: error },
+			);
+		}
 		if (read.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("A forward forecast ref resolved to the wrong artifact type.");
 		return { ref, start: Date.parse(read.artifact.target_period.start_inclusive) };
 	}));
 	return dated.sort((left, right) => left.start - right.start).map((item) => item.ref).slice(0, 6);
 }
 
+function canonicalTimezone(timezone: string): string {
+	return new Intl.DateTimeFormat("en-US", { timeZone: timezone }).resolvedOptions().timeZone;
+}
+
+async function assertExactNextPlanSuccessor(
+	projectRoot: string,
+	active: DashboardRefreshSubscription,
+	nextRef: ArtifactRefV2,
+): Promise<void> {
+	const [currentRead, nextRead] = await Promise.all([
+		readArtifactByRef(projectRoot, active.forecast_ref),
+		readArtifactByRef(projectRoot, nextRef),
+	]);
+	if (currentRead.artifact.artifact_type !== "approved_cycle_forecast" || nextRead.artifact.artifact_type !== "approved_cycle_forecast") {
+		throw new Error("Next-plan dashboard handoff must resolve two approved forecasts.");
+	}
+	const current = currentRead.artifact;
+	const next = nextRead.artifact;
+	if (Date.parse(next.target_period.start_inclusive) !== Date.parse(current.target_period.end_exclusive)
+		|| canonicalTimezone(next.target_period.timezone) !== canonicalTimezone(current.target_period.timezone)) {
+		throw new Error("Next-plan forecast must be the exact successor of the active cycle in the same timezone.");
+	}
+}
+
 export async function enqueueDashboardRefresh(cwd: string, value: DashboardRefreshRequest): Promise<EnqueueDashboardRefreshResult> {
 	const request = validateRequest(value);
 	const projectRoot = await realpath(cwd);
@@ -516,13 +628,16 @@ export async function enqueueDashboardRefresh(cwd: string, value: DashboardRefre
 	)) {
 		throw new Error("Next-plan dashboard refresh requires an active current-cycle subscription in the same project and scope.");
 	}
-	const subscription = await persistSubscription(directories, projectName, request, now);
+	if (request.forecast_role === "next_plan" && active) {
+		await assertExactNextPlanSuccessor(projectRoot, active, request.forecast_ref);
+	}
 	if (request.forecast_role === "next_plan") {
 		if (active) {
 			const unsortedForwardRefs = [...(active.forward_forecast_refs ?? (active.next_forecast_ref ? [active.next_forecast_ref] : [])), request.forecast_ref]
 				.filter((ref, index, refs) => refs.findIndex((candidate) => candidate.entry_id === ref.entry_id) === index)
 				.slice(0, 6);
 			const forwardRefs = await sortForwardForecastRefs(projectRoot, unsortedForwardRefs);
+			await persistSubscription(directories, projectName, request, now);
 			const linked = { ...active, next_forecast_ref: forwardRefs[0], forward_forecast_refs: forwardRefs, updated_at: now };
 			await atomicReplace(join(directories.subscriptions, `${active.subscription_id}.json`), `${JSON.stringify(linked, null, 2)}\n`);
 			return enqueueEventOnly(directories, projectName, validateRequest({
@@ -538,7 +653,9 @@ export async function enqueueDashboardRefresh(cwd: string, value: DashboardRefre
 				reason: "forecast_committed",
 			}), now);
 		}
-	} else if (request.reason === "forecast_committed" || request.reason === "execution_committed") {
+	}
+	const subscription = await persistSubscription(directories, projectName, request, now);
+	if (request.reason === "forecast_committed" || request.reason === "execution_committed") {
 		await atomicReplace(join(directories.root, "active-subscription.json"), `${JSON.stringify({
 			kind: "fpa.dashboard.active-subscription",
 			schema_version: 1,

package/extensions/fpa-dashboard/cycle-operating-projection.ts

@@ -5,6 +5,7 @@ import {
 	type ExecutionReceiptInput,
 	type ScenarioMetric,
 } from "../fpa-artifacts/contracts.ts";
+import type { ForecastRole } from "../fpa-artifacts/store.ts";
 import {
 	ACTUALS_DATA_AS_OF_UNAVAILABLE,
 	validateActualsSnapshot,
@@ -16,11 +17,11 @@ export interface CycleOperatingProjectionInput {
 	scope_id: string;
 	cycle_id: string;
 	current_forecast: unknown;
-	current_forecast_role?: "original" | "eac" | "next_plan";
+	current_forecast_role?: ForecastRole;
 	actuals: unknown;
 	execution?: unknown;
 	next_forecast?: unknown;
-	next_forecast_role?: "original" | "eac" | "next_plan";
+	next_forecast_role?: ForecastRole;
 }
 
 interface ScenarioValues {

package/extensions/fpa-dashboard/forward-outlook.ts

@@ -35,6 +35,10 @@ function values(metric: ScenarioMetric | undefined, path: string) {
 	return { downside: metric.downside, base: metric.base, upside: metric.upside };
 }
 
+function canonicalTimezone(timezone: string): string {
+	return new Intl.DateTimeFormat("en-US", { timeZone: timezone }).resolvedOptions().timeZone;
+}
+
 export function projectForwardOutlook(input: {
 	current_forecast: unknown;
 	forward_forecasts: ForwardForecastInput[];
@@ -47,7 +51,7 @@ export function projectForwardOutlook(input: {
 		const forecast = approvedForecast(item.forecast, `forward_forecasts[${index}].forecast`);
 		if (item.ref.artifact_type !== "approved_cycle_forecast" || item.ref.body_fingerprint === "" || item.ref.cycle_id === "") throw new Error(`forward_forecasts[${index}].ref is invalid.`);
 		if (forecast.reporting_currency !== current.reporting_currency) throw new Error(`forward_forecasts[${index}] reporting currency does not match the current forecast.`);
-		if (forecast.target_period.timezone !== current.target_period.timezone || Date.parse(forecast.target_period.start_inclusive) !== Date.parse(expectedStart)) {
+		if (canonicalTimezone(forecast.target_period.timezone) !== canonicalTimezone(current.target_period.timezone) || Date.parse(forecast.target_period.start_inclusive) !== Date.parse(expectedStart)) {
 			throw new Error(`forward_forecasts[${index}] must be the exact consecutive successor in the same timezone.`);
 		}
 		expectedStart = forecast.target_period.end_exclusive;

package/extensions/fpa-dashboard/index.ts

@@ -2,10 +2,11 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import type { ArtifactRefV2 } from "../fpa-artifacts/store.ts";
+import { readArtifactByRef, type ArtifactRefV2 } from "../fpa-artifacts/store.ts";
 import { dashboardBuildFingerprint, publishDashboard } from "./publisher.ts";
 import {
 	enqueueDashboardRefresh,
+	enqueueDashboardRefreshForArtifact,
 	inspectDashboardRefreshQueue,
 	processDashboardRefreshQueue,
 } from "./coordinator.ts";
@@ -34,7 +35,7 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		promptSnippet: "Inspect the current FP&A dashboard generation and diagnostics",
 		parameters: Type.Object({
 			expected_lineage: Type.Optional(Type.Object({
-				forecast_role: Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan")]),
+				forecast_role: Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan"), Type.Literal("backtest")]),
 				forecast_ref: Type.String({ pattern: "^[a-f0-9]{64}$" }),
 			}, { additionalProperties: false })),
 			require_lineage_match: Type.Optional(Type.Boolean()),
@@ -93,7 +94,16 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 				...(params.next_forecast_ref ? { nextForecastRef: params.next_forecast_ref as ArtifactRefV2 } : {}),
 				...(params.forward_forecast_refs ? { forwardForecastRefs: params.forward_forecast_refs as ArtifactRefV2[] } : {}),
 			} : undefined;
+			if (exact) {
+				const exactForecast = await readArtifactByRef(ctx.cwd, exact.forecastRef);
+				if (exactForecast.ledgerContext?.forecast_role === "backtest") {
+					throw new Error("A backtest forecast cannot be previewed or published as the operating dashboard.");
+				}
+			}
 			const { build, forecast, actuals, sliceKeyMismatch, projector, runtime } = await buildDashboardProjection(ctx.cwd, params.preset, params.locale ?? "zh-CN", exact, signal);
+			if (build.source.forecast_role === "backtest") {
+				throw new Error("A backtest forecast cannot be previewed or published as the operating dashboard.");
+			}
 			const previewFingerprint = dashboardBuildFingerprint(build, projector);
 			const summary = {
 				preset: params.preset,
@@ -144,11 +154,12 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "fpa_dashboard_refresh_queue",
 		label: "FP&A Dashboard Refresh Queue",
-		description: "Inspect or drain the durable dashboard refresh queue, or enqueue an Actuals-watermark refresh against exact immutable artifact refs.",
+		description: "Inspect or drain the durable dashboard refresh queue, enqueue an exact committed artifact after Graph handoff, or enqueue an Actuals-watermark refresh.",
 		promptSnippet: "Inspect or process durable FP&A dashboard refresh work",
 		parameters: Type.Object({
-			action: StringEnum(["status", "drain", "enqueue_actuals"] as const),
+			action: StringEnum(["status", "drain", "enqueue_artifact", "enqueue_actuals"] as const),
 			locale: Type.Optional(StringEnum(["zh-CN", "en-US"] as const)),
+			artifact_ref: Type.Optional(artifactRefSchema),
 			scope_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 			cycle_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 			forecast_ref: Type.Optional(artifactRefSchema),
@@ -162,6 +173,14 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			if (params.action === "status") return toolResult(await inspectDashboardRefreshQueue(ctx.cwd) as unknown as Record<string, unknown>);
 			if (params.action === "drain") return toolResult(await processDashboardRefreshQueue(ctx.cwd, { limit: params.limit, signal }) as unknown as Record<string, unknown>);
+			if (params.action === "enqueue_artifact") {
+				if (!params.artifact_ref) throw new Error("enqueue_artifact requires artifact_ref from fpa_artifact_commit.");
+				return toolResult(await enqueueDashboardRefreshForArtifact(
+					ctx.cwd,
+					params.artifact_ref,
+					params.locale ?? "zh-CN",
+				) as unknown as Record<string, unknown>);
+			}
 			if (!params.scope_id || !params.cycle_id || !params.forecast_ref || !params.actuals_watermark) {
 				throw new Error("enqueue_actuals requires scope_id, cycle_id, forecast_ref, and actuals_watermark.");
 			}

package/extensions/fpa-dashboard/projector.ts

@@ -7,6 +7,7 @@ import {
 	type ForecastAllocation,
 	type ForecastSlice,
 } from "../fpa-artifacts/contracts.ts";
+import type { ForecastRole } from "../fpa-artifacts/store.ts";
 import { validateActualsSnapshot, ACTUALS_DATA_AS_OF_UNAVAILABLE, type DashboardActualsSnapshot, type DashboardActualSlice } from "./source.ts";
 import type { CycleOperatingProjection } from "./cycle-operating-projection.ts";
 import type { ForwardOutlookProjection } from "./forward-outlook.ts";
@@ -67,7 +68,7 @@ export interface DashboardBuild {
 		forecast_ref?: string;
 		next_forecast_ref?: string;
 		execution_ref?: string;
-		forecast_role?: "original" | "eac" | "next_plan";
+		forecast_role?: ForecastRole;
 		forecast_version: string;
 		forecast_fingerprint?: string;
 		next_forecast_fingerprint?: string;

package/extensions/fpa-dashboard/publisher.ts

@@ -177,6 +177,9 @@ export function dashboardBuildFingerprint(build: DashboardBuild, projector: Dash
 
 export async function publishDashboard(options: PublishDashboardOptions): Promise<PublishDashboardResult> {
 	assertBuild(options.build);
+	if (options.build.source.forecast_role === "backtest") {
+		throw new Error("A backtest forecast cannot replace the operating dashboard.");
+	}
 	const projector = validateProjectorProvenance(options.projector);
 	const runtime = validateProjectorRuntime(options.runtime);
 	const dashboardDir = await resolveDashboardDir(options.cwd);

package/extensions/fpa-dashboard/status.ts

@@ -9,7 +9,7 @@ import {
 	type DashboardProjectorProvenance,
 	type DashboardProjectorRuntime,
 } from "./provenance.ts";
-import { stableJson } from "../fpa-artifacts/store.ts";
+import { isForecastRole, stableJson, type ForecastRole } from "../fpa-artifacts/store.ts";
 import { DASHBOARD_WIDGET_TYPES, validateDatasetForWidget, type DashboardWidgetType } from "./schema.ts";
 import { validateActualsSnapshot } from "./source.ts";
 
@@ -31,7 +31,7 @@ export interface DashboardStatus {
 }
 
 export interface DashboardLineageExpectation {
-	forecast_role: "original" | "eac" | "next_plan";
+	forecast_role: ForecastRole;
 	forecast_ref: string;
 }
 
@@ -47,7 +47,7 @@ export interface DashboardReceiptSummary {
 		cycle_id?: string;
 		forecast_version: string;
 		forecast_ref?: string;
-		forecast_role?: "original" | "eac" | "next_plan";
+		forecast_role?: ForecastRole;
 		next_forecast_ref?: string;
 		forward_forecast_refs: string[];
 		execution_ref?: string;
@@ -80,7 +80,7 @@ function buildReceiptSummary(receipt: Record<string, unknown>): DashboardReceipt
 	const dataAsOf = optionalBoundedString(source?.data_as_of, 256);
 	if (!source || !forecastVersion || !dataAsOf) return undefined;
 	const role = source.forecast_role;
-	const forecastRole = role === "original" || role === "eac" || role === "next_plan" ? role : undefined;
+	const forecastRole = isForecastRole(role) ? role : undefined;
 	const forwardForecastRefs = Array.isArray(source.forward_forecast_refs)
 		? source.forward_forecast_refs.filter((value): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value)).slice(0, 6)
 		: [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -30,9 +30,9 @@
 		"fpa-dashboard-worker": "./bin/fpa-dashboard-worker.mjs"
 	},
   "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/artifact-ledger.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs && node tests/pi-loader-smoke.mjs && node tests/worker-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/artifact-ledger.test.mjs tests/artifact-handoff.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs && node tests/pi-loader-smoke.mjs && node tests/worker-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/artifact-ledger.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs",
+		"test:unit": "node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/artifact-ledger.test.mjs tests/artifact-handoff.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs",
     "test:loader": "node tests/pi-loader-smoke.mjs && node tests/worker-loader-smoke.mjs",
     "test:live": "node tests/live-smoke.mjs",
     "pack:check": "npm pack --dry-run"

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

@@ -30,8 +30,14 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
    `fpa_artifact_commit` and an assigned context containing the explicit
    `scope_id`, `cycle_id`, and `forecast_role`. Use `original` only when the
    forecast is frozen no later than period start; use `eac` for an in-period
-   reforecast and `next_plan` when it is the approved direct successor of the
-   active cycle.
+   reforecast and `next_plan` only when it is frozen no later than its target
+   period start and is the approved direct successor of the active cycle. Use
+   `backtest` for a historical rerun frozen after its target
+   period; it is immutable evidence, not an operating plan, and it must not
+   replace the current pointer or enter the operating dashboard queue. A
+   `next_plan` is likewise stored as forward lineage and does not replace the
+   legacy current pointer; its explicit dashboard handoff links it to the
+   active cycle after successor validation.
 
 ## Write the decision, not the arithmetic
 
@@ -76,4 +82,4 @@ declaration upstream needs correcting.
 
 ## Completion
 
-The planning workflow ends only after `fpa_artifact_commit` returns `status: committed` and an `immutable_fingerprint`. A Markdown report is optional context, not the frozen source of truth. Never report a forecast as frozen on the strength of a written file alone — the file is a draft until the tool returns a fingerprint. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.
+The planning workflow ends only after `fpa_artifact_commit` returns `status: committed`, an `immutable_fingerprint`, and (for assigned artifacts) a `dashboard_handoff`. Commit freezes the business artifact but does not enqueue or publish dashboard work. The calling main Agent owns that explicit handoff. A Markdown report is optional context, not the frozen source of truth. Never report a forecast as frozen on the strength of a written file alone — the file is a draft until the tool returns a fingerprint. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.

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

@@ -17,6 +17,21 @@ only part of this tuple or fall back to a mutable current pointer.
 
 ## Procedure
 
+### Post-Graph handoff
+
+1. Take the exact `artifact_ref` from `fpa_artifact_commit.dashboard_handoff`.
+2. Call `fpa_dashboard_refresh_queue` with `action: enqueue_artifact` and that
+   ref. Do not restate scope, cycle, role, or upstream refs; the package resolves
+   them from the immutable ledger.
+3. If the result is `enqueued` or `already_pending` and the current task expects
+   the dashboard immediately, call one bounded `drain`, then verify with
+   `fpa_dashboard_status`.
+4. If the result is `not_applicable` for a `backtest`, report that the historical
+   forecast is frozen and the operating dashboard intentionally remains
+   unchanged. Never relabel the artifact to force it into the active lineage.
+
+### Human-requested rebuild
+
 1. Call `fpa_dashboard_status` to inspect the current generation and diagnostics.
 2. Call `fpa_dashboard_refresh` with `preset: forecast-closed-loop-v1` and `mode: preview`.
 3. Review the returned lineage, coverage, query receipts, warnings, widget list, and `preview_fingerprint`.
@@ -41,8 +56,9 @@ answer, and do not describe it as "the period has no data yet".
 - Never fabricate Actuals, replace missing values with zero, or average row-level ratios.
 - Do not edit the approved forecast during projection.
 - If inputs change between preview and publish, preview again rather than bypassing the fingerprint check.
-- This skill performs one bounded human-requested refresh. Assigned artifact
-  commits and Actuals watermark changes are monitored separately by the durable
-  package coordinator running in the package-owned `fpa-dashboard-worker`
-  process (never in the read-only Web host); inspect or drain that queue with
-  `fpa_dashboard_refresh_queue` rather than recreating its writes manually.
+- Artifact commit never performs dashboard I/O. The calling main Agent explicitly
+  enqueues its exact handoff. Actuals watermark changes remain monitored by the
+  durable package coordinator running in the package-owned
+  `fpa-dashboard-worker` process (never in the read-only Web host); inspect or
+  drain that queue with `fpa_dashboard_refresh_queue` rather than recreating its
+  writes manually.