@viccydev/pi-fpa 0.5.0 → 0.6.0

package/README.md

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

package/bin/fpa-dashboard-worker.mjs

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

package/extensions/fpa-artifacts/compose.ts

@@ -55,6 +55,7 @@ export interface PlanSlice {
 	baseline_spend: number | null;
 	approved_spend: number;
 	action: AllocationAction;
+	owner?: string;
 	roas: PlanSliceRoas;
 }
 
@@ -119,7 +120,7 @@ function text(value: unknown, path: string): string {
 function planSlice(value: unknown, index: number): PlanSlice {
 	const path = `plan.slices[${index}]`;
 	const source = record(value, path);
-	const allowed = new Set(["app_id", "store", "channel_group", "baseline_spend", "approved_spend", "action", "roas"]);
+	const allowed = new Set(["app_id", "store", "channel_group", "baseline_spend", "approved_spend", "action", "owner", "roas"]);
 	const unknown = Object.keys(source).filter((key) => !allowed.has(key));
 	if (unknown.length > 0) throw new Error(`${path} has unsupported keys: ${unknown.join(", ")}.`);
 	const action = source.action;
@@ -136,6 +137,7 @@ function planSlice(value: unknown, index: number): PlanSlice {
 		baseline_spend: nonNegative(source.baseline_spend, `${path}.baseline_spend`, true),
 		approved_spend: nonNegative(source.approved_spend, `${path}.approved_spend`) as number,
 		action: action as AllocationAction,
+		...(source.owner === undefined ? {} : { owner: text(source.owner, `${path}.owner`) }),
 		roas: {
 			downside: nonNegative(roasSource.downside, `${path}.roas.downside`, true),
 			base: nonNegative(roasSource.base, `${path}.roas.base`, true),
@@ -302,6 +304,7 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		baseline_spend: slice.baseline_spend,
 		approved_spend: slice.approved_spend,
 		action: slice.action,
+		...(slice.owner ? { owner: slice.owner } : {}),
 	}));
 
 	// Spend is the decision, not a prediction: an approved allocation is the same

package/extensions/fpa-artifacts/contracts.ts

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

package/extensions/fpa-artifacts/index.ts

@@ -2,7 +2,14 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { composeApprovedForecast } from "./compose.ts";
-import { commitArtifact, commitArtifactFromPath, readProjectJsonFile } from "./store.ts";
+import { enqueueDashboardRefresh } from "../fpa-dashboard/coordinator.ts";
+import {
+	commitArtifact,
+	commitArtifactFromPath,
+	readArtifactByRef,
+	readProjectJsonFile,
+	type ArtifactRefV2,
+} from "./store.ts";
 
 function toolResult(value: Record<string, unknown>) {
 	return {
@@ -11,6 +18,17 @@ function toolResult(value: Record<string, unknown>) {
 	};
 }
 
+const artifactRefSchema = Type.Object({
+	scope_id: Type.String({ minLength: 1, maxLength: 256 }),
+	cycle_id: Type.String({ minLength: 1, maxLength: 256 }),
+	artifact_type: Type.Union([
+		Type.Literal("approved_cycle_forecast"),
+		Type.Literal("execution_receipt"),
+	]),
+	entry_id: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+	body_fingerprint: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+}, { additionalProperties: false });
+
 export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "fpa_artifact_commit",
@@ -32,6 +50,13 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 					minLength: 1,
 					description: "Project-relative path to a JSON file holding the canonical artifact. Mutually exclusive with artifact.",
 				})),
+				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")])),
+					upstream_refs: Type.Optional(Type.Array(artifactRefSchema, { maxItems: 16 })),
+					promote_legacy_pointer: Type.Optional(Type.Boolean()),
+				}, { additionalProperties: false })),
 			},
 			{ additionalProperties: false },
 		),
@@ -42,14 +67,70 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 			if (hasInline === hasPath) {
 				throw new Error("Supply exactly one of artifact or artifact_path.");
 			}
+			const commitOptions = params.context ? {
+				context: {
+					scope_id: params.context.scope_id,
+					cycle_id: params.context.cycle_id,
+					forecast_role: params.context.forecast_role,
+					upstream_refs: params.context.upstream_refs as ArtifactRefV2[] | undefined,
+				},
+				promoteLegacyPointer: params.context.promote_legacy_pointer,
+			} : undefined;
 			const committed = hasPath
-				? await commitArtifactFromPath(ctx.cwd, params.artifact_path as string)
-				: await commitArtifact(ctx.cwd, params.artifact);
+				? 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: "committed",
+				status: dashboardRefreshError ? "committed_refresh_enqueue_failed" : "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 } : {}),
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_artifact_read",
+		label: "Read Exact FP&A Artifact",
+		description: "Resolve and verify one immutable FP&A artifact by its exact scope, cycle, entry, and body fingerprint. Never falls back to the current pointer.",
+		promptSnippet: "Read an exact immutable FP&A artifact reference",
+		parameters: Type.Object({ artifact_ref: artifactRefSchema }, { additionalProperties: false }),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const read = await readArtifactByRef(ctx.cwd, params.artifact_ref);
+			return toolResult({
+				status: "resolved",
+				artifact_ref: params.artifact_ref,
+				artifact: read.artifact as unknown as Record<string, unknown>,
+				path: read.path,
 			});
 		},
 	});