@viccydev/pi-fpa 0.5.0 → 0.6.0

package/extensions/fpa-dashboard/status.ts

@@ -3,17 +3,27 @@ import { lstat, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 
 import { resolveDashboardDir } from "./publisher.ts";
+import {
+	validateProjectorProvenance,
+	validateProjectorRuntime,
+	type DashboardProjectorProvenance,
+	type DashboardProjectorRuntime,
+} from "./provenance.ts";
 import { stableJson } from "../fpa-artifacts/store.ts";
 import { DASHBOARD_WIDGET_TYPES, validateDatasetForWidget, type DashboardWidgetType } from "./schema.ts";
+import { validateActualsSnapshot } from "./source.ts";
 
-const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}\.json$/;
-const GENERATION_RECEIPT_RE = /^build-receipt\.([a-f0-9]{12})\.([a-f0-9]{12})\.json$/;
+const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,191}\.json$/;
+const GENERATION_RECEIPT_RE = /^build-receipt\.([a-f0-9]{64})\.([a-f0-9]{64})\.json$/;
 
 export interface DashboardStatus {
 	dashboard_exists: boolean;
 	dashboard_dir: string;
 	generation_id?: string;
 	updated_at?: string;
+	projector?: DashboardProjectorProvenance;
+	runtime?: DashboardProjectorRuntime;
+	provenance_status?: "verified" | "legacy_missing" | "invalid";
 	widget_count: number;
 	diagnostics: Array<{ target: string; message: string }>;
 }
@@ -50,6 +60,9 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		return { dashboard_exists: false, dashboard_dir: dashboardDir, widget_count: 0, diagnostics: [{ target: "manifest.json", message: "unsupported dashboard kind/schema or widgets shape" }] };
 	}
 	const receiptDatasets = new Map<string, string>();
+	let projector: DashboardProjectorProvenance | undefined;
+	let runtime: DashboardProjectorRuntime | undefined;
+	let provenanceStatus: DashboardStatus["provenance_status"];
 	const receiptFilename = typeof source.buildReceipt === "string" && DATASET_FILE_RE.test(source.buildReceipt)
 		? source.buildReceipt
 		: "build-receipt.json";
@@ -62,6 +75,23 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		if (receiptSource.kind !== "fpa.dashboard.build" || receiptSource.schema_version !== 1) {
 			throw new Error("has an unsupported build receipt kind or schema");
 		}
+		if (receiptSource.projector === undefined && receiptSource.runtime === undefined) {
+			provenanceStatus = "legacy_missing";
+		} else {
+			provenanceStatus = "verified";
+			try {
+				projector = validateProjectorProvenance(receiptSource.projector);
+			} catch (error) {
+				provenanceStatus = "invalid";
+				diagnostics.push({ target: `${receiptFilename} projector`, message: error instanceof Error ? error.message : String(error) });
+			}
+			try {
+				runtime = validateProjectorRuntime(receiptSource.runtime);
+			} catch (error) {
+				provenanceStatus = "invalid";
+				diagnostics.push({ target: `${receiptFilename} runtime`, message: error instanceof Error ? error.message : String(error) });
+			}
+		}
 		if (typeof source.generationId === "string" && receiptSource.generation_id !== source.generationId) {
 			diagnostics.push({ target: receiptFilename, message: "generation does not match manifest.json" });
 		}
@@ -70,15 +100,33 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		}
 		const receiptNameMatch = receiptFilename.match(GENERATION_RECEIPT_RE);
 		if (receiptNameMatch) {
-			if (typeof source.generationId !== "string" || receiptNameMatch[1] !== source.generationId.slice(0, 12)) {
-				diagnostics.push({ target: receiptFilename, message: "filename generation prefix does not match manifest.json" });
+			if (typeof source.generationId !== "string" || receiptNameMatch[1] !== source.generationId) {
+				diagnostics.push({ target: receiptFilename, message: "filename generation digest does not match manifest.json" });
 			}
 			const receiptDigest = createHash("sha256").update(stableJson(receipt)).digest("hex");
-			if (receiptNameMatch[2] !== receiptDigest.slice(0, 12)) {
+			if (receiptNameMatch[2] !== receiptDigest) {
 				diagnostics.push({ target: receiptFilename, message: "receipt content digest does not match its filename" });
 			}
 		}
 		if (!Array.isArray(receiptSource.datasets)) throw new Error("datasets must be an array");
+		if (receiptSource.source && typeof receiptSource.source === "object" && !Array.isArray(receiptSource.source)) {
+			const actualsRef = (receiptSource.source as Record<string, unknown>).actuals_snapshot_ref;
+			if (actualsRef !== undefined) {
+				if (typeof actualsRef !== "string" || !/^[a-f0-9]{64}$/.test(actualsRef)) {
+					diagnostics.push({ target: `${receiptFilename} source.actuals_snapshot_ref`, message: "must be a sha256 digest" });
+				} else {
+					try {
+						const snapshot = await readJson(join(dashboardDir, "actuals", `${actualsRef}.json`), 2 * 1024 * 1024);
+						const validated = validateActualsSnapshot(snapshot);
+						if (createHash("sha256").update(stableJson(validated)).digest("hex") !== actualsRef) {
+							diagnostics.push({ target: `actuals/${actualsRef}.json`, message: "Actuals snapshot content digest does not match its immutable ref" });
+						}
+					} catch (error) {
+						diagnostics.push({ target: `actuals/${actualsRef}.json`, message: error instanceof Error ? error.message : String(error) });
+					}
+				}
+			}
+		}
 		for (const [index, raw] of receiptSource.datasets.entries()) {
 			if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
 				diagnostics.push({ target: `${receiptFilename} datasets[${index}]`, message: "must be an object" });
@@ -148,6 +196,9 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		dashboard_dir: dashboardDir,
 		...(typeof source.generationId === "string" ? { generation_id: source.generationId } : {}),
 		...(typeof source.updatedAt === "string" ? { updated_at: source.updatedAt } : {}),
+		...(projector ? { projector } : {}),
+		...(runtime ? { runtime } : {}),
+		...(provenanceStatus ? { provenance_status: provenanceStatus } : {}),
 		widget_count: source.widgets.length,
 		diagnostics,
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -16,20 +16,30 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": ">=22.19"
+  },
   "files": [
     "README.md",
+	"bin",
     "prompts",
     "skills",
     "extensions"
   ],
+	"bin": {
+		"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/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs && node tests/pi-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/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/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs",
-    "test:loader": "node tests/pi-loader-smoke.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: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"
   },
+  "dependencies": {
+    "jiti": "2.7.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",

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

@@ -29,7 +29,7 @@ If any requirement is missing, return `blocked` and make no external call. Never
 4. Present or record the dry-run result when the adapter supports it.
 5. Execute only the approved mutation set.
 6. Read back the resulting state and reconcile it with the requested state.
-7. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/execution_receipt.input.json`, then commit it with `fpa_artifact_commit` using `artifact_path`.
+7. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/execution_receipt.input.json`, then commit it with `fpa_artifact_commit` using `artifact_path` and the exact `scope_id`, `cycle_id`, and approved Forecast `upstream_refs` entry returned by planning. Never validate against a mutable current pointer.
 
 ## Stop conditions
 

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

@@ -21,12 +21,17 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 ## Procedure
 
 1. Verify approval and artifact lineage.
-2. Lock the approved allocation and all approval conditions.
+2. Lock the approved allocation, accountable owner for each slice when known, and all approval conditions.
 3. Recalculate future-period operating outcomes from that allocation using the declared model.
 4. Provide downside, base, and upside values for each supported KPI.
 5. Reconcile allocation totals, formulas, and cross-metric identities.
 6. Write the forecast plan to `artifacts/forecast_plan.json` using [artifact-contract.md](references/artifact-contract.md).
-7. Derive the artifact with `fpa_forecast_compose`, then freeze it with `fpa_artifact_commit`.
+7. Derive the artifact with `fpa_forecast_compose`, then freeze it with
+   `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.
 
 ## Write the decision, not the arithmetic
 

package/skills/fpa-forecast-approved-strategy/references/artifact-contract.md

@@ -21,6 +21,7 @@ approved_allocation:
     baseline_spend: number | null
     approved_spend: number
     action: stop | decrease | hold | increase | explore
+	owner: string  # optional accountable operator
 forecast_by_slice:
   - app_id: string
     store: string
@@ -78,6 +79,7 @@ slices:
     baseline_spend: number | null
     approved_spend: number
     action: stop | decrease | hold | increase | explore
+	owner: string  # optional; shown as the accountable operator on the CEO dashboard
     roas: {downside: number|null, base: number|null, upside: number|null}
 consolidated_extra_metrics:   # optional; measured portfolio series only
   metric_name: {downside, base, upside, unit}

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

@@ -11,6 +11,10 @@ Load `$fpa-apply-core-rules` first. Follow [dashboard-policy.md](references/dash
 
 Require a committed `approved_cycle_forecast` for the target project. Treat a committed `execution_receipt` as optional execution evidence; never describe manual reported execution as independently verified.
 
+For an assigned ledger cycle, pass `scope_id`, `cycle_id`, and the exact
+`forecast_ref`; pass exact execution/forward refs when available. Never provide
+only part of this tuple or fall back to a mutable current pointer.
+
 ## Procedure
 
 1. Call `fpa_dashboard_status` to inspect the current generation and diagnostics.
@@ -37,4 +41,8 @@ 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 refresh; it does not continuously monitor the dashboard.
+- 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.