@viccydev/pi-fpa 0.5.0 → 0.6.1

package/extensions/fpa-dashboard/status.ts

@@ -3,21 +3,152 @@ 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";
+	receipt_summary?: DashboardReceiptSummary;
+	lineage_verification?: DashboardLineageVerification;
 	widget_count: number;
 	diagnostics: Array<{ target: string; message: string }>;
 }
 
+export interface DashboardLineageExpectation {
+	forecast_role: "original" | "eac" | "next_plan";
+	forecast_ref: string;
+}
+
+export interface DashboardLineageVerification {
+	matches: boolean;
+	reason: string | null;
+}
+
+export interface DashboardReceiptSummary {
+	source: {
+		project_name?: string;
+		scope_id?: string;
+		cycle_id?: string;
+		forecast_version: string;
+		forecast_ref?: string;
+		forecast_role?: "original" | "eac" | "next_plan";
+		next_forecast_ref?: string;
+		forward_forecast_refs: string[];
+		execution_ref?: string;
+		data_as_of: string;
+	};
+	actuals: {
+		period_complete: boolean | null;
+		reconciled: boolean | null;
+	};
+	operating: {
+		current_forecast_version: string | null;
+		execution_status: string | null;
+		next_cycle_status: string | null;
+		next_forecast_version: string | null;
+	};
+	warnings: string[];
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function optionalBoundedString(value: unknown, maxLength = 4096): string | undefined {
+	return typeof value === "string" && value.length > 0 && value.length <= maxLength ? value : undefined;
+}
+
+function buildReceiptSummary(receipt: Record<string, unknown>): DashboardReceiptSummary | undefined {
+	const source = record(receipt.source);
+	const forecastVersion = optionalBoundedString(source?.forecast_version, 256);
+	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 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)
+		: [];
+	const evidence = record(source.actuals_snapshot_evidence);
+	const projection = record(receipt.operating_projection);
+	const currentCycle = record(projection?.current_cycle);
+	const execution = record(currentCycle?.execution);
+	const nextCycle = record(projection?.next_cycle);
+	const warnings = Array.isArray(receipt.warnings)
+		? receipt.warnings.filter((value): value is string => typeof value === "string" && value.length <= 4096).slice(0, 128)
+		: [];
+	return {
+		source: {
+			...(optionalBoundedString(source.project_name, 256) ? { project_name: source.project_name as string } : {}),
+			...(optionalBoundedString(source.scope_id, 256) ? { scope_id: source.scope_id as string } : {}),
+			...(optionalBoundedString(source.cycle_id, 256) ? { cycle_id: source.cycle_id as string } : {}),
+			forecast_version: forecastVersion,
+			...(optionalBoundedString(source.forecast_ref, 64) && /^[a-f0-9]{64}$/.test(source.forecast_ref as string) ? { forecast_ref: source.forecast_ref as string } : {}),
+			...(forecastRole ? { forecast_role: forecastRole } : {}),
+			...(optionalBoundedString(source.next_forecast_ref, 64) && /^[a-f0-9]{64}$/.test(source.next_forecast_ref as string) ? { next_forecast_ref: source.next_forecast_ref as string } : {}),
+			forward_forecast_refs: forwardForecastRefs,
+			...(optionalBoundedString(source.execution_ref, 64) && /^[a-f0-9]{64}$/.test(source.execution_ref as string) ? { execution_ref: source.execution_ref as string } : {}),
+			data_as_of: dataAsOf,
+		},
+		actuals: {
+			period_complete: typeof evidence?.period_complete === "boolean" ? evidence.period_complete : null,
+			reconciled: typeof evidence?.reconciled === "boolean" ? evidence.reconciled : null,
+		},
+		operating: {
+			current_forecast_version: optionalBoundedString(currentCycle?.forecast_version, 256) ?? null,
+			execution_status: optionalBoundedString(execution?.status, 256) ?? null,
+			next_cycle_status: optionalBoundedString(nextCycle?.status, 256) ?? null,
+			next_forecast_version: optionalBoundedString(nextCycle?.forecast_version, 256) ?? null,
+		},
+		warnings,
+	};
+}
+
+function verifyLineage(
+	summary: DashboardReceiptSummary | undefined,
+	expectation: DashboardLineageExpectation,
+): DashboardLineageVerification {
+	if (!/^[a-f0-9]{64}$/.test(expectation.forecast_ref)) throw new Error("expected forecast_ref must be a SHA-256 entry id.");
+	if (!summary) return { matches: false, reason: "Dashboard receipt has no verifiable business lineage." };
+	if (expectation.forecast_role === "next_plan") {
+		if (summary.source.forecast_ref === expectation.forecast_ref) {
+			return { matches: false, reason: "Expected next-plan forecast is published as the current forecast." };
+		}
+		if (summary.source.next_forecast_ref !== expectation.forecast_ref) {
+			return { matches: false, reason: "Expected next-plan forecast is not linked as next_forecast_ref." };
+		}
+		if (!summary.source.forward_forecast_refs.includes(expectation.forecast_ref)) {
+			return { matches: false, reason: "Expected next-plan forecast is not present in forward_forecast_refs." };
+		}
+		if (summary.operating.next_cycle_status !== "ready" && summary.operating.next_cycle_status !== "ready_with_limits") {
+			return { matches: false, reason: "Expected next-plan forecast is linked but the next cycle is not ready." };
+		}
+		return { matches: true, reason: null };
+	}
+	if (summary.source.forecast_ref !== expectation.forecast_ref) {
+		return { matches: false, reason: "Expected forecast is not published as the current forecast." };
+	}
+	if (summary.source.forecast_role !== expectation.forecast_role) {
+		return { matches: false, reason: "Published current forecast role does not match the expected role." };
+	}
+	return { matches: true, reason: null };
+}
+
 async function readJson(path: string, maxBytes: number): Promise<unknown> {
 	const stat = await lstat(path);
 	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("must be a regular file, not a symlink");
@@ -25,7 +156,7 @@ async function readJson(path: string, maxBytes: number): Promise<unknown> {
 	return JSON.parse(await readFile(path, "utf8"));
 }
 
-export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
+export async function inspectDashboard(cwd: string, expectation?: DashboardLineageExpectation): Promise<DashboardStatus> {
 	const dashboardDir = await resolveDashboardDir(cwd);
 	const diagnostics: DashboardStatus["diagnostics"] = [];
 	let manifest: unknown;
@@ -50,6 +181,10 @@ 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"];
+	let receiptSummary: DashboardReceiptSummary | undefined;
 	const receiptFilename = typeof source.buildReceipt === "string" && DATASET_FILE_RE.test(source.buildReceipt)
 		? source.buildReceipt
 		: "build-receipt.json";
@@ -62,6 +197,24 @@ 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");
 		}
+		receiptSummary = buildReceiptSummary(receiptSource);
+		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 +223,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 +319,11 @@ 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 } : {}),
+		...(receiptSummary ? { receipt_summary: receiptSummary } : {}),
+		...(expectation ? { lineage_verification: verifyLineage(receiptSummary, expectation) } : {}),
 		widget_count: source.widgets.length,
 		diagnostics,
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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.