@viccydev/pi-fpa 0.6.0 → 0.6.2

package/README.md

@@ -127,12 +127,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.6.0
+pi install git:github.com/linyqh/pi-fpa@v0.6.2
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.6.0` 对应 `v0.6.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.6.2` 对应 `v0.6.2`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/extensions/fpa-dashboard/coordinator.ts

@@ -507,10 +507,18 @@ export async function enqueueDashboardRefresh(cwd: string, value: DashboardRefre
 	const projectName = basename(projectRoot);
 	const directories = await queueDirectories(projectRoot);
 	const now = new Date().toISOString();
+	const active = request.forecast_role === "next_plan" ? await activeSubscription(directories) : undefined;
+	if (request.forecast_role === "next_plan" && (
+		!active
+		|| active.project_name !== projectName
+		|| active.scope_id !== request.scope_id
+		|| active.subscription_id === subscriptionIdentity(projectName, request.scope_id, request.cycle_id)
+	)) {
+		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") {
-		const active = await activeSubscription(directories);
-		if (active && active.project_name === projectName && active.scope_id === request.scope_id && active.subscription_id !== subscription.subscription_id) {
+		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);

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

@@ -153,6 +153,10 @@ function addDay(date: string): string {
 	return value.toISOString().slice(0, 10);
 }
 
+function canonicalTimezone(timezone: string): string {
+	return new Intl.DateTimeFormat("en-US", { timeZone: timezone }).resolvedOptions().timeZone;
+}
+
 function approximatelyEqual(left: number, right: number): boolean {
 	return Math.abs(left - right) <= Math.max(0.000001, Math.max(Math.abs(left), Math.abs(right)) * 0.000001);
 }
@@ -209,7 +213,7 @@ export function projectCycleOperatingProjection(input: CycleOperatingProjectionI
 	const receipt = input.execution === undefined ? undefined : execution(input.execution, current);
 	const next = input.next_forecast === undefined ? undefined : forecast(input.next_forecast, "next_forecast");
 	if (next && (Date.parse(next.target_period.start_inclusive) !== Date.parse(current.target_period.end_exclusive)
-		|| next.target_period.timezone !== current.target_period.timezone)) {
+		|| canonicalTimezone(next.target_period.timezone) !== canonicalTimezone(current.target_period.timezone))) {
 		throw new Error("next_forecast target period must be the exact successor of the current cycle in the same timezone.");
 	}
 	if (next && next.reporting_currency !== current.reporting_currency) throw new Error("next_forecast reporting_currency must match current_forecast.");

package/extensions/fpa-dashboard/index.ts

@@ -32,10 +32,23 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		label: "FP&A Dashboard Status",
 		description: "Inspect the current tenant dashboard generation, datasets, build receipt, and diagnostics without changing files.",
 		promptSnippet: "Inspect the current FP&A dashboard generation and diagnostics",
-		parameters: Type.Object({}, { additionalProperties: false }),
+		parameters: Type.Object({
+			expected_lineage: Type.Optional(Type.Object({
+				forecast_role: Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan")]),
+				forecast_ref: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+			}, { additionalProperties: false })),
+			require_lineage_match: Type.Optional(Type.Boolean()),
+		}, { additionalProperties: false }),
 		executionMode: "parallel",
-		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-			return toolResult(await inspectDashboard(ctx.cwd) as unknown as Record<string, unknown>);
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (params.require_lineage_match && !params.expected_lineage) {
+				throw new Error("require_lineage_match requires expected_lineage.");
+			}
+			const status = await inspectDashboard(ctx.cwd, params.expected_lineage);
+			if (params.require_lineage_match && !status.lineage_verification?.matches) {
+				throw new Error(`Dashboard lineage verification failed: ${status.lineage_verification?.reason ?? "no verifiable lineage"}`);
+			}
+			return toolResult(status as unknown as Record<string, unknown>);
 		},
 	});
 

package/extensions/fpa-dashboard/status.ts

@@ -24,10 +24,131 @@ export interface DashboardStatus {
 	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");
@@ -35,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;
@@ -63,6 +184,7 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 	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";
@@ -75,6 +197,7 @@ 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 {
@@ -199,6 +322,8 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		...(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.6.0",
+  "version": "0.6.2",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",