@viccydev/pi-fpa 0.9.2 → 0.9.4

package/README.md

@@ -159,12 +159,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.9.2
+pi install git:github.com/linyqh/pi-fpa@v0.9.4
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.2` 对应 `v0.9.2`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.4` 对应 `v0.9.4`。工作流会检出该标签，执行 `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

@@ -76,12 +76,34 @@ if (args.includes("--once")) {
     if (!abortController.signal.aborted) throw error;
   }
 } else {
+  // A failure that persists — a missing ledger, an artifact a subscription
+  // still references — repeats on every tick. Reprinting its stack every
+  // interval buries everything else in the log without adding information, so
+  // an unchanged failure is reported once in full and then only counted.
+  let lastFailure = null;
+  let repeatCount = 0;
   while (!stopping) {
     try {
 	  await runOnce();
+	  if (lastFailure) {
+		process.stderr.write(`${new Date().toISOString()} recovered after ${repeatCount + 1} consecutive failure(s)\n`);
+		lastFailure = null;
+		repeatCount = 0;
+	  }
     } catch (error) {
 	  if (abortController.signal.aborted) break;
-	  process.stderr.write(`${new Date().toISOString()} ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+	  const message = error instanceof Error ? error.message : String(error);
+	  if (message === lastFailure) {
+		repeatCount += 1;
+		// Back off the log, not the work: still retried every interval.
+		if (repeatCount === 1 || repeatCount % 20 === 0) {
+		  process.stderr.write(`${new Date().toISOString()} still failing (${repeatCount + 1}x): ${message}\n`);
+		}
+	  } else {
+		lastFailure = message;
+		repeatCount = 0;
+		process.stderr.write(`${new Date().toISOString()} ${error instanceof Error ? error.stack ?? message : message}\n`);
+	  }
     }
     if (!stopping) await new Promise((resolveWait) => {
 	  const timer = setTimeout(() => {

package/extensions/fpa-artifacts/store.ts

@@ -144,7 +144,21 @@ async function existingLedgerDirectories(projectRoot: string): Promise<{ root: s
 	const objects = join(root, "objects");
 	const entries = join(root, "entries");
 	for (const [path, label] of [[root, ".ledger"], [objects, ".ledger/objects"], [entries, ".ledger/entries"]] as const) {
-		const stat = await lstat(path);
+		let stat;
+		try {
+			stat = await lstat(path);
+		} catch (error) {
+			// A project with no ledger is a state a caller can act on — the
+			// artifacts were never committed through it, or the directory was
+			// removed out from under a subscription that still holds refs.
+			// Letting a raw ENOENT escape turns that into an unreadable stack
+			// trace in the coordinator's last_error, which the operator then
+			// has to reverse-engineer.
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				throw new Error(`This project has no artifact ledger (${label} is missing), so artifacts cannot be resolved by ref. Commit an artifact through the ledger before referencing one.`);
+			}
+			throw error;
+		}
 		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${label} must be a regular directory, not a symlink.`);
 	}
 	return { root, objects, entries };

package/extensions/fpa-dashboard/coordinator.ts

@@ -11,6 +11,7 @@ import {
 } from "../fpa-artifacts/store.ts";
 import { dashboardBuildFingerprint, resolveDashboardDir } from "./publisher.ts";
 import { publishDashboardProjection } from "./compat-publisher.ts";
+import { readDashboardModuleManifest } from "./module-publisher.ts";
 import { buildDashboardProjection } from "./service.ts";
 
 const EVENT_MAX_BYTES = 64 * 1024;
@@ -178,6 +179,13 @@ export interface DashboardCoordinatorStatus {
 	scope_id: string | null;
 	cycle_id: string | null;
 	generation_id: string | null;
+	/**
+	 * The modular manifest's current `dashboardRevision`, read from disk rather
+	 * than from the subscription. `generation_id` only ever identifies a legacy
+	 * whole-dashboard generation, so a consumer on a v2 manifest has nothing in
+	 * the same hash space to compare against without this.
+	 */
+	dashboard_revision: string | null;
 	pending: number;
 	processing: number;
 	dead: number;
@@ -384,6 +392,13 @@ async function writeCoordinatorStatus(
 	await ensureDirectory(dashboardDir, "Dashboard directory");
 	const previous = await readCoordinatorStatus(cwd);
 	const queue = options.queue ?? await inspectDashboardRefreshQueue(cwd);
+	// Read the revision off the manifest instead of tracking it in the
+	// subscription: every publish path (legacy refresh, module publish,
+	// strategy transition) rewrites the manifest, so this is the one value that
+	// is correct no matter who wrote last.
+	const dashboardRevision = await readDashboardModuleManifest(cwd)
+		.then((manifest) => manifest?.dashboardRevision ?? null)
+		.catch(() => previous?.dashboard_revision ?? null);
 	const status: DashboardCoordinatorStatus = {
 		kind: "fpa.dashboard.coordinator-status",
 		schema_version: 1,
@@ -397,6 +412,7 @@ async function writeCoordinatorStatus(
 		scope_id: options.subscription?.scope_id ?? null,
 		cycle_id: options.subscription?.cycle_id ?? null,
 		generation_id: options.subscription?.last_generation_id ?? null,
+		dashboard_revision: dashboardRevision,
 		pending: queue.pending,
 		processing: queue.processing,
 		dead: queue.dead,

package/extensions/fpa-dashboard/module-publisher.ts

@@ -6,7 +6,14 @@ import { stableJson } from "../fpa-artifacts/store.ts";
 import type { DashboardWidget } from "./projector.ts";
 import { validateDatasetForWidget } from "./schema.ts";
 
-export type DashboardModuleId = "period-review" | "next-strategy" | "next-forecast" | "execution-evidence";
+export type DashboardModuleId =
+	| "portfolio-overview"
+	| "period-review"
+	| "next-strategy"
+	| "next-forecast"
+	| "forecast-accuracy"
+	| "decision-ledger"
+	| "execution-evidence";
 export type DashboardModuleStatus = "published" | "awaiting_decision" | "approved" | "changes_requested" | "generating" | "superseded";
 
 export interface DashboardModuleInteraction {
@@ -20,6 +27,14 @@ export interface DashboardModuleBuild {
 	status: DashboardModuleStatus;
 	source: Record<string, unknown>;
 	widgets: DashboardWidget[];
+	/**
+	 * Decision limits the projector found while building this module — an
+	 * unverified execution receipt, approved slices with no Actuals, an
+	 * incomplete close. They belong to the module they were computed for, so
+	 * the consumer can show them next to the numbers they qualify instead of
+	 * pooling every module's caveats into one banner nobody reads.
+	 */
+	warnings?: string[];
 	interaction?: DashboardModuleInteraction;
 }
 
@@ -64,7 +79,15 @@ export interface DashboardManifestV2 {
 	modules: Partial<Record<DashboardModuleId, DashboardModuleManifestEntry>>;
 }
 
-const MODULE_IDS: DashboardModuleId[] = ["period-review", "next-strategy", "next-forecast", "execution-evidence"];
+const MODULE_IDS: DashboardModuleId[] = [
+	"portfolio-overview",
+	"period-review",
+	"next-strategy",
+	"next-forecast",
+	"forecast-accuracy",
+	"decision-ledger",
+	"execution-evidence",
+];
 const MODULE_ID_SET = new Set<string>(MODULE_IDS);
 const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,191}\.json$/;
 
@@ -136,6 +159,12 @@ function assertModule(module: DashboardModuleBuild): void {
 	if (!MODULE_ID_SET.has(module.id)) throw new Error(`Unsupported dashboard module id "${module.id}".`);
 	if (!module.title?.trim()) throw new Error("Dashboard module title is required.");
 	if (!Array.isArray(module.widgets) || module.widgets.length === 0 || module.widgets.length > 64) throw new Error("Dashboard module must contain between 1 and 64 widgets.");
+	if (module.warnings !== undefined) {
+		if (!Array.isArray(module.warnings) || module.warnings.length > 128) throw new Error("Dashboard module warnings must be an array of at most 128 entries.");
+		for (const warning of module.warnings) {
+			if (typeof warning !== "string" || warning.length > 4_096) throw new Error("Each dashboard module warning must be a string of at most 4096 characters.");
+		}
+	}
 	if (module.interaction && (module.id !== "next-strategy" || module.status !== "awaiting_decision")) {
 		throw new Error("Strategy decisions are available only on an awaiting next-strategy module.");
 	}
@@ -209,6 +238,9 @@ async function normalizeLegacyModuleReceipt(
 	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Legacy dashboard build receipt must be a regular file.");
 	const old = JSON.parse(await readFile(sourcePath, "utf8")) as { source?: unknown; warnings?: unknown; datasets?: unknown };
 	if (!Array.isArray(old.datasets)) throw new Error("Legacy dashboard build receipt datasets are invalid.");
+	// The legacy generation receipt carried warnings at the top level too, so
+	// they migrate straight across rather than being buried inside `source`.
+	const legacyWarnings = Array.isArray(old.warnings) ? old.warnings.filter((entry): entry is string => typeof entry === "string") : [];
 	const receipt = {
 		kind: "fpa.dashboard.module.build",
 		schema_version: 1,
@@ -216,7 +248,8 @@ async function normalizeLegacyModuleReceipt(
 		module_revision: legacy.revision,
 		published_at: legacy.updatedAt,
 		status: legacy.status,
-		source: { ...(old.source && typeof old.source === "object" ? old.source : {}), warnings: old.warnings ?? [], legacy_generation_id: legacy.revision },
+		source: { ...(old.source && typeof old.source === "object" ? old.source : {}), legacy_generation_id: legacy.revision },
+		warnings: legacyWarnings,
 		datasets: old.datasets,
 	};
 	const contents = `${JSON.stringify(receipt, null, 2)}\n`;
@@ -290,6 +323,7 @@ export async function publishDashboardModule(options: PublishDashboardModuleOpti
 			published_at: publishedAt,
 			status: options.module.status,
 			source: options.module.source,
+			warnings: options.module.warnings ?? [],
 			datasets: datasets.map(({ widget, filename, digest }) => ({ logical: widget.dataset, filename, sha256: digest })),
 		};
 		const receiptContents = `${JSON.stringify(receipt, null, 2)}\n`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -19,17 +19,20 @@
   "engines": {
     "node": ">=22.19"
   },
+  "fpaDashboard": {
+    "contractVersion": 1
+  },
   "files": [
     "README.md",
-	"bin",
-	"graphs",
+    "bin",
+    "graphs",
     "prompts",
     "skills",
     "extensions"
   ],
-	"bin": {
-		"fpa-dashboard-worker": "./bin/fpa-dashboard-worker.mjs"
-	},
+  "bin": {
+    "fpa-dashboard-worker": "./bin/fpa-dashboard-worker.mjs"
+  },
   "scripts": {
     "test": "node tests/package-structure.test.mjs && node tests/workflow-routing.test.mjs && node --test tests/workflow-routing-guard.test.mjs tests/graph-contract.test.mjs tests/graph-installer.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/forecast-finalize.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-module-publisher.test.mjs tests/dashboard-stage-projector.test.mjs tests/strategy-decision.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",
@@ -59,7 +62,7 @@
       "./skills"
     ],
     "extensions": [
-		"./extensions/fpa-routing-guard/index.ts",
+      "./extensions/fpa-routing-guard/index.ts",
       "./extensions/fpa-data/index.ts",
       "./extensions/fpa-artifacts/index.ts",
       "./extensions/fpa-dashboard/index.ts"