@viccydev/pi-fpa 0.4.1 → 0.6.0

package/extensions/fpa-dashboard/coordinator.ts

@@ -0,0 +1,831 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, realpath, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+import { readArtifactByRef, stableJson, validateArtifactRef, type ArtifactRefV2 } from "../fpa-artifacts/store.ts";
+import { dashboardBuildFingerprint, publishDashboard, resolveDashboardDir } from "./publisher.ts";
+import { buildDashboardProjection } from "./service.ts";
+
+const EVENT_MAX_BYTES = 64 * 1024;
+const MAX_ATTEMPTS = 3;
+const LOCK_STALE_MS = 5 * 60 * 1000;
+const ACTUALS_POLL_INTERVAL_MS = 5 * 60 * 1000;
+const COORDINATOR_HEARTBEAT_TTL_MS = 90 * 1000;
+const REASON_VALUES = new Set(["forecast_committed", "execution_committed", "actuals_watermark", "generation_identity", "manual"]);
+
+export interface DashboardRefreshRequest {
+	preset: "forecast-closed-loop-v1";
+	locale?: "zh-CN" | "en-US";
+	scope_id: string;
+	cycle_id: string;
+	forecast_ref: ArtifactRefV2;
+	forecast_role?: "original" | "eac" | "next_plan";
+	execution_ref?: ArtifactRefV2;
+	next_forecast_ref?: ArtifactRefV2;
+	forward_forecast_refs?: ArtifactRefV2[];
+	reason: "forecast_committed" | "execution_committed" | "actuals_watermark" | "generation_identity" | "manual";
+	actuals_watermark?: string;
+	desired_generation_id?: string;
+}
+
+export interface DashboardRefreshEvent extends DashboardRefreshRequest {
+	kind: "fpa.dashboard.refresh-event";
+	schema_version: 1;
+	event_id: string;
+	project_name: string;
+	enqueued_at: string;
+	attempt: number;
+	not_before?: string;
+	last_error?: string;
+}
+
+export interface DashboardRefreshWorkResult {
+	generation_id: string;
+	data_as_of: string;
+	published: boolean;
+	actuals_watermark?: string;
+}
+
+export interface EnqueueDashboardRefreshResult {
+	event_id: string;
+	status: "enqueued" | "already_pending" | "already_processing" | "already_completed" | "already_dead";
+	queue_dir: string;
+}
+
+export interface DashboardRefreshQueueStatus {
+	queue_dir: string;
+	pending: number;
+	processing: number;
+	completed: number;
+	dead: number;
+	busy: boolean;
+}
+
+export interface ProcessDashboardRefreshQueueOptions {
+	limit?: number;
+	signal?: AbortSignal;
+	now?: () => Date;
+	worker?: (event: DashboardRefreshEvent, projectRoot: string, signal?: AbortSignal) => Promise<DashboardRefreshWorkResult>;
+}
+
+export interface ProcessDashboardRefreshQueueResult extends DashboardRefreshQueueStatus {
+	status: "processed" | "busy";
+	processed: number;
+	succeeded: number;
+	superseded: number;
+	retried: number;
+	failed: number;
+}
+
+export class ObsoleteDashboardRefreshError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ObsoleteDashboardRefreshError";
+	}
+}
+
+export interface DashboardCoordinatorStatus {
+	kind: "fpa.dashboard.coordinator-status";
+	schema_version: 1;
+	state: "idle" | "healthy" | "refreshing" | "degraded" | "failed";
+	heartbeat_at: string;
+	heartbeat_expires_at: string;
+	last_success_at: string | null;
+	last_actuals_watermark: string | null;
+	next_poll_at: string | null;
+	project_name: string | null;
+	scope_id: string | null;
+	cycle_id: string | null;
+	generation_id: string | null;
+	pending: number;
+	processing: number;
+	dead: number;
+	last_error: string | null;
+}
+
+interface QueueDirectories {
+	root: string;
+	pending: string;
+	processing: string;
+	completed: string;
+	dead: string;
+	subscriptions: string;
+}
+
+interface DashboardRefreshSubscription {
+	kind: "fpa.dashboard.refresh-subscription";
+	schema_version: 1;
+	subscription_id: string;
+	project_name: string;
+	preset: "forecast-closed-loop-v1";
+	locale: "zh-CN" | "en-US";
+	scope_id: string;
+	cycle_id: string;
+	forecast_ref: ArtifactRefV2;
+	forecast_role?: "original" | "eac" | "next_plan";
+	execution_ref?: ArtifactRefV2;
+	next_forecast_ref?: ArtifactRefV2;
+	forward_forecast_refs?: ArtifactRefV2[];
+	updated_at: string;
+	next_poll_at?: string;
+	last_generation_id?: string;
+	desired_generation_id?: string;
+	last_actuals_watermark?: string;
+}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function boundedId(value: unknown, path: string): string {
+	if (typeof value !== "string" || value.trim() === "" || value.length > 256 || /[\u0000-\u001f\u007f]/.test(value)) {
+		throw new Error(`${path} must be a non-empty string of at most 256 characters without control characters.`);
+	}
+	return value;
+}
+
+function boundedOptional(value: unknown, path: string): string | undefined {
+	if (value === undefined) return undefined;
+	return boundedId(value, path);
+}
+
+function validateRequest(value: DashboardRefreshRequest): DashboardRefreshRequest {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("refresh request must be an object.");
+	const source = value as unknown as Record<string, unknown>;
+	const allowed = new Set(["preset", "locale", "scope_id", "cycle_id", "forecast_ref", "forecast_role", "execution_ref", "next_forecast_ref", "forward_forecast_refs", "reason", "actuals_watermark", "desired_generation_id"]);
+	for (const key of Object.keys(source)) if (!allowed.has(key)) throw new Error(`refresh request.${key} is not allowed.`);
+	if (source.preset !== "forecast-closed-loop-v1") throw new Error("refresh request.preset is unsupported.");
+	if (source.locale !== undefined && source.locale !== "zh-CN" && source.locale !== "en-US") throw new Error("refresh request.locale is unsupported.");
+	if (typeof source.reason !== "string" || !REASON_VALUES.has(source.reason)) throw new Error("refresh request.reason is unsupported.");
+	const scopeId = boundedId(source.scope_id, "refresh request.scope_id");
+	const cycleId = boundedId(source.cycle_id, "refresh request.cycle_id");
+	const forecastRef = validateArtifactRef(source.forecast_ref, "refresh request.forecast_ref");
+	if (source.forecast_role !== undefined && source.forecast_role !== "original" && source.forecast_role !== "eac" && source.forecast_role !== "next_plan") {
+		throw new Error("refresh request.forecast_role is unsupported.");
+	}
+	if (forecastRef.artifact_type !== "approved_cycle_forecast" || forecastRef.scope_id !== scopeId || forecastRef.cycle_id !== cycleId) {
+		throw new Error("refresh request.forecast_ref must identify the requested scope and cycle forecast.");
+	}
+	const executionRef = source.execution_ref === undefined ? undefined : validateArtifactRef(source.execution_ref, "refresh request.execution_ref");
+	if (executionRef && (executionRef.artifact_type !== "execution_receipt" || executionRef.scope_id !== scopeId || executionRef.cycle_id !== cycleId)) {
+		throw new Error("refresh request.execution_ref must identify the requested scope and cycle execution receipt.");
+	}
+	const nextForecastRef = source.next_forecast_ref === undefined ? undefined : validateArtifactRef(source.next_forecast_ref, "refresh request.next_forecast_ref");
+	if (nextForecastRef && (nextForecastRef.artifact_type !== "approved_cycle_forecast" || nextForecastRef.scope_id !== scopeId || nextForecastRef.entry_id === forecastRef.entry_id)) {
+		throw new Error("refresh request.next_forecast_ref must identify a different forecast in the same scope.");
+	}
+	if (source.forward_forecast_refs !== undefined && (!Array.isArray(source.forward_forecast_refs) || source.forward_forecast_refs.length > 6)) {
+		throw new Error("refresh request.forward_forecast_refs must contain at most six refs.");
+	}
+	const forwardForecastRefs = (source.forward_forecast_refs as unknown[] | undefined)?.map((ref, index) => validateArtifactRef(ref, `refresh request.forward_forecast_refs[${index}]`)) ?? [];
+	if (new Set(forwardForecastRefs.map((ref) => ref.entry_id)).size !== forwardForecastRefs.length) throw new Error("refresh request.forward_forecast_refs must not contain duplicates.");
+	if (forwardForecastRefs.some((ref) => ref.artifact_type !== "approved_cycle_forecast" || ref.scope_id !== scopeId)) throw new Error("refresh request.forward_forecast_refs must contain forecasts in the requested scope.");
+	if (nextForecastRef && forwardForecastRefs.length > 0 && nextForecastRef.entry_id !== forwardForecastRefs[0].entry_id) throw new Error("refresh request.next_forecast_ref must be the first forward forecast ref.");
+	const desiredGenerationId = source.desired_generation_id === undefined
+		? undefined
+		: boundedId(source.desired_generation_id, "refresh request.desired_generation_id");
+	if (desiredGenerationId !== undefined && !/^[a-f0-9]{64}$/.test(desiredGenerationId)) {
+		throw new Error("refresh request.desired_generation_id must be a SHA-256 digest.");
+	}
+	return {
+		preset: "forecast-closed-loop-v1",
+		...(source.locale ? { locale: source.locale as "zh-CN" | "en-US" } : {}),
+		scope_id: scopeId,
+		cycle_id: cycleId,
+		forecast_ref: forecastRef,
+		...(source.forecast_role ? { forecast_role: source.forecast_role as DashboardRefreshRequest["forecast_role"] } : {}),
+		...(executionRef ? { execution_ref: executionRef } : {}),
+		...(nextForecastRef ? { next_forecast_ref: nextForecastRef } : {}),
+		...(forwardForecastRefs.length > 0 ? { forward_forecast_refs: forwardForecastRefs } : {}),
+		reason: source.reason as DashboardRefreshRequest["reason"],
+		...(boundedOptional(source.actuals_watermark, "refresh request.actuals_watermark") ? { actuals_watermark: source.actuals_watermark as string } : {}),
+		...(desiredGenerationId ? { desired_generation_id: desiredGenerationId } : {}),
+	};
+}
+
+async function pathKind(path: string): Promise<"missing" | "directory" | "symlink" | "other"> {
+	try {
+		const value = await lstat(path);
+		if (value.isSymbolicLink()) return "symlink";
+		if (value.isDirectory()) return "directory";
+		return "other";
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
+		throw error;
+	}
+}
+
+async function ensureDirectory(path: string, label: string): Promise<void> {
+	const kind = await pathKind(path);
+	if (kind === "symlink" || kind === "other") throw new Error(`${label} must be a regular directory, not a symlink.`);
+	if (kind === "missing") await mkdir(path, { recursive: true, mode: 0o700 });
+}
+
+async function queueDirectories(cwd: string): Promise<QueueDirectories> {
+	const dashboardDir = await resolveDashboardDir(cwd);
+	await ensureDirectory(dashboardDir, "Dashboard directory");
+	const root = join(dashboardDir, "refresh-queue");
+	await ensureDirectory(root, "Dashboard refresh queue");
+	const result = {
+		root,
+		pending: join(root, "pending"),
+		processing: join(root, "processing"),
+		completed: join(root, "completed"),
+		dead: join(root, "dead"),
+		subscriptions: join(root, "subscriptions"),
+	};
+	for (const [path, label] of [[result.pending, "pending"], [result.processing, "processing"], [result.completed, "completed"], [result.dead, "dead"], [result.subscriptions, "subscriptions"]] as const) {
+		await ensureDirectory(path, `Dashboard refresh ${label} queue`);
+	}
+	return result;
+}
+
+async function writeExclusive(path: string, contents: string): Promise<boolean> {
+	try {
+		const handle = await open(path, "wx", 0o600);
+		try {
+			await handle.writeFile(contents, "utf8");
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+		throw error;
+	}
+}
+
+async function atomicReplace(path: string, contents: string): Promise<void> {
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	try {
+		await rename(temporary, path);
+	} catch (error) {
+		await unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+}
+
+async function readCoordinatorStatus(cwd: string): Promise<DashboardCoordinatorStatus | null> {
+	const path = join(await resolveDashboardDir(cwd), "coordinator-status.json");
+	try {
+		const metadata = await lstat(path);
+		if (metadata.isSymbolicLink() || !metadata.isFile() || metadata.size > EVENT_MAX_BYTES) return null;
+		const value = JSON.parse(await readFile(path, "utf8")) as DashboardCoordinatorStatus;
+		return value.kind === "fpa.dashboard.coordinator-status" && value.schema_version === 1 ? value : null;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+async function writeCoordinatorStatus(
+	cwd: string,
+	options: {
+		now: Date;
+		queue?: DashboardRefreshQueueStatus;
+		state?: DashboardCoordinatorStatus["state"];
+		lastSuccess?: boolean;
+		lastActualsWatermark?: string | null;
+		nextPollAt?: string | null;
+		subscription?: DashboardRefreshSubscription | null;
+		lastError?: string | null;
+	},
+): Promise<DashboardCoordinatorStatus> {
+	const dashboardDir = await resolveDashboardDir(cwd);
+	await ensureDirectory(dashboardDir, "Dashboard directory");
+	const previous = await readCoordinatorStatus(cwd);
+	const queue = options.queue ?? await inspectDashboardRefreshQueue(cwd);
+	const status: DashboardCoordinatorStatus = {
+		kind: "fpa.dashboard.coordinator-status",
+		schema_version: 1,
+		state: options.state ?? (queue.dead > 0 ? "degraded" : queue.pending + queue.processing > 0 ? "refreshing" : "healthy"),
+		heartbeat_at: options.now.toISOString(),
+		heartbeat_expires_at: new Date(options.now.getTime() + COORDINATOR_HEARTBEAT_TTL_MS).toISOString(),
+		last_success_at: options.lastSuccess ? options.now.toISOString() : previous?.last_success_at ?? null,
+		last_actuals_watermark: options.lastActualsWatermark === undefined ? previous?.last_actuals_watermark ?? null : options.lastActualsWatermark,
+		next_poll_at: options.nextPollAt === undefined ? previous?.next_poll_at ?? null : options.nextPollAt,
+		project_name: options.subscription?.project_name ?? null,
+		scope_id: options.subscription?.scope_id ?? null,
+		cycle_id: options.subscription?.cycle_id ?? null,
+		generation_id: options.subscription?.last_generation_id ?? null,
+		pending: queue.pending,
+		processing: queue.processing,
+		dead: queue.dead,
+		last_error: options.lastError === undefined ? previous?.last_error ?? null : options.lastError,
+	};
+	await atomicReplace(join(dashboardDir, "coordinator-status.json"), `${JSON.stringify(status, null, 2)}\n`);
+	return status;
+}
+
+async function readEvent(path: string): Promise<DashboardRefreshEvent> {
+	const file = await lstat(path);
+	if (file.isSymbolicLink() || !file.isFile() || file.size > EVENT_MAX_BYTES) throw new Error("Refresh event must be a bounded regular file.");
+	const source = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;
+	if (source.kind !== "fpa.dashboard.refresh-event" || source.schema_version !== 1) throw new Error("Refresh event has an unsupported contract.");
+	const request = validateRequest({
+		preset: source.preset,
+		locale: source.locale,
+		scope_id: source.scope_id,
+		cycle_id: source.cycle_id,
+		forecast_ref: source.forecast_ref,
+		forecast_role: source.forecast_role,
+		execution_ref: source.execution_ref,
+		next_forecast_ref: source.next_forecast_ref,
+		forward_forecast_refs: source.forward_forecast_refs,
+		reason: source.reason,
+		actuals_watermark: source.actuals_watermark,
+		desired_generation_id: source.desired_generation_id,
+	} as DashboardRefreshRequest);
+	if (typeof source.event_id !== "string" || !/^[a-f0-9]{64}$/.test(source.event_id)) throw new Error("Refresh event has an invalid event_id.");
+	if (typeof source.project_name !== "string" || basename(source.project_name) !== source.project_name || source.project_name === "." || source.project_name === "..") throw new Error("Refresh event has an invalid project_name.");
+	if (typeof source.enqueued_at !== "string" || Number.isNaN(Date.parse(source.enqueued_at))) throw new Error("Refresh event has an invalid enqueued_at.");
+	if (!Number.isInteger(source.attempt) || (source.attempt as number) < 0 || (source.attempt as number) > MAX_ATTEMPTS) throw new Error("Refresh event has an invalid attempt.");
+	if (source.not_before !== undefined && (typeof source.not_before !== "string" || Number.isNaN(Date.parse(source.not_before)))) throw new Error("Refresh event has an invalid not_before.");
+	if (source.last_error !== undefined && (typeof source.last_error !== "string" || source.last_error.length > 2048)) throw new Error("Refresh event has an invalid last_error.");
+	const expectedId = eventIdentity(source.project_name, request);
+	if (expectedId !== source.event_id) throw new Error("Refresh event identity does not match its immutable request.");
+	return {
+		kind: "fpa.dashboard.refresh-event",
+		schema_version: 1,
+		event_id: source.event_id,
+		project_name: source.project_name,
+		enqueued_at: source.enqueued_at,
+		attempt: source.attempt as number,
+		...(source.not_before ? { not_before: source.not_before as string } : {}),
+		...(source.last_error ? { last_error: source.last_error as string } : {}),
+		...request,
+	};
+}
+
+function eventIdentity(projectName: string, request: DashboardRefreshRequest): string {
+	return sha256(stableJson({ project_name: projectName, request }));
+}
+
+async function eventState(directories: QueueDirectories, filename: string): Promise<EnqueueDashboardRefreshResult["status"] | null> {
+	for (const [directory, status] of [
+		[directories.pending, "already_pending"],
+		[directories.processing, "already_processing"],
+		[directories.completed, "already_completed"],
+		[directories.dead, "already_dead"],
+	] as const) {
+		if (await pathKind(join(directory, filename)) !== "missing") return status;
+	}
+	return null;
+}
+
+function subscriptionIdentity(projectName: string, scopeId: string, cycleId: string): string {
+	return sha256(stableJson({ project_name: projectName, scope_id: scopeId, cycle_id: cycleId }));
+}
+
+async function readSubscription(path: string): Promise<DashboardRefreshSubscription> {
+	const file = await lstat(path);
+	if (file.isSymbolicLink() || !file.isFile() || file.size > EVENT_MAX_BYTES) throw new Error("Dashboard refresh subscription must be a bounded regular file.");
+	const source = JSON.parse(await readFile(path, "utf8")) as DashboardRefreshSubscription;
+	if (source.kind !== "fpa.dashboard.refresh-subscription" || source.schema_version !== 1) throw new Error("Dashboard refresh subscription has an unsupported contract.");
+	const request = validateRequest({
+		preset: source.preset,
+		locale: source.locale,
+		scope_id: source.scope_id,
+		cycle_id: source.cycle_id,
+		forecast_ref: source.forecast_ref,
+		forecast_role: source.forecast_role,
+		execution_ref: source.execution_ref,
+		next_forecast_ref: source.next_forecast_ref,
+		forward_forecast_refs: source.forward_forecast_refs,
+		desired_generation_id: source.desired_generation_id,
+		reason: "manual",
+	});
+	const expected = subscriptionIdentity(source.project_name, request.scope_id, request.cycle_id);
+	if (source.subscription_id !== expected || basename(source.project_name) !== source.project_name) throw new Error("Dashboard refresh subscription identity is invalid.");
+	return source;
+}
+
+async function readOptionalSubscription(path: string): Promise<DashboardRefreshSubscription | null> {
+	try {
+		return await readSubscription(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+async function activeSubscription(directories: QueueDirectories): Promise<DashboardRefreshSubscription | null> {
+	try {
+		const pointerPath = join(directories.root, "active-subscription.json");
+		const file = await lstat(pointerPath);
+		if (file.isSymbolicLink() || !file.isFile() || file.size > EVENT_MAX_BYTES) throw new Error("Active dashboard subscription pointer is invalid.");
+		const pointer = JSON.parse(await readFile(pointerPath, "utf8")) as { subscription_id?: unknown };
+		if (typeof pointer.subscription_id !== "string" || !/^[a-f0-9]{64}$/.test(pointer.subscription_id)) throw new Error("Active dashboard subscription pointer has no valid id.");
+		return await readSubscription(join(directories.subscriptions, `${pointer.subscription_id}.json`));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+async function persistSubscription(
+	directories: QueueDirectories,
+	projectName: string,
+	request: DashboardRefreshRequest,
+	now: string,
+): Promise<DashboardRefreshSubscription> {
+	const subscriptionId = subscriptionIdentity(projectName, request.scope_id, request.cycle_id);
+	const path = join(directories.subscriptions, `${subscriptionId}.json`);
+	const existing = await readOptionalSubscription(path);
+	const sameForecast = existing?.forecast_ref.entry_id === request.forecast_ref.entry_id;
+	const subscription: DashboardRefreshSubscription = {
+		kind: "fpa.dashboard.refresh-subscription",
+		schema_version: 1,
+		subscription_id: subscriptionId,
+		project_name: projectName,
+		preset: request.preset,
+		locale: request.locale ?? existing?.locale ?? "zh-CN",
+		scope_id: request.scope_id,
+		cycle_id: request.cycle_id,
+		forecast_ref: request.forecast_ref,
+		...(request.forecast_role ? { forecast_role: request.forecast_role } : existing?.forecast_role ? { forecast_role: existing.forecast_role } : {}),
+		...(request.execution_ref ? { execution_ref: request.execution_ref } : sameForecast && existing?.execution_ref ? { execution_ref: existing.execution_ref } : {}),
+		...(request.next_forecast_ref ? { next_forecast_ref: request.next_forecast_ref } : sameForecast && existing?.next_forecast_ref ? { next_forecast_ref: existing.next_forecast_ref } : {}),
+		...(request.forward_forecast_refs ? { forward_forecast_refs: request.forward_forecast_refs } : sameForecast && existing?.forward_forecast_refs ? { forward_forecast_refs: existing.forward_forecast_refs } : {}),
+		updated_at: now,
+		...(sameForecast && existing?.next_poll_at ? { next_poll_at: existing.next_poll_at } : {}),
+		...(sameForecast && existing?.last_generation_id ? { last_generation_id: existing.last_generation_id } : {}),
+		...(request.desired_generation_id
+			? { desired_generation_id: request.desired_generation_id }
+			: sameForecast && existing?.desired_generation_id
+				? { desired_generation_id: existing.desired_generation_id }
+				: {}),
+		...(sameForecast && existing?.last_actuals_watermark ? { last_actuals_watermark: existing.last_actuals_watermark } : {}),
+	};
+	await atomicReplace(path, `${JSON.stringify(subscription, null, 2)}\n`);
+	return subscription;
+}
+
+async function enqueueEventOnly(
+	directories: QueueDirectories,
+	projectName: string,
+	request: DashboardRefreshRequest,
+	now: string,
+): Promise<EnqueueDashboardRefreshResult> {
+	const eventId = eventIdentity(projectName, request);
+	const filename = `${eventId}.json`;
+	const existing = await eventState(directories, filename);
+	if (existing) return { event_id: eventId, status: existing, queue_dir: directories.root };
+	const event: DashboardRefreshEvent = {
+		kind: "fpa.dashboard.refresh-event",
+		schema_version: 1,
+		event_id: eventId,
+		project_name: projectName,
+		enqueued_at: now,
+		attempt: 0,
+		...request,
+	};
+	const created = await writeExclusive(join(directories.pending, filename), `${JSON.stringify(event, null, 2)}\n`);
+	return { event_id: eventId, status: created ? "enqueued" : "already_pending", queue_dir: directories.root };
+}
+
+async function sortForwardForecastRefs(projectRoot: string, refs: ArtifactRefV2[]): Promise<ArtifactRefV2[]> {
+	const dated = await Promise.all(refs.map(async (ref) => {
+		const read = await readArtifactByRef(projectRoot, ref);
+		if (read.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("A forward forecast ref resolved to the wrong artifact type.");
+		return { ref, start: Date.parse(read.artifact.target_period.start_inclusive) };
+	}));
+	return dated.sort((left, right) => left.start - right.start).map((item) => item.ref).slice(0, 6);
+}
+
+export async function enqueueDashboardRefresh(cwd: string, value: DashboardRefreshRequest): Promise<EnqueueDashboardRefreshResult> {
+	const request = validateRequest(value);
+	const projectRoot = await realpath(cwd);
+	const projectName = basename(projectRoot);
+	const directories = await queueDirectories(projectRoot);
+	const now = new Date().toISOString();
+	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) {
+			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);
+			const forwardRefs = await sortForwardForecastRefs(projectRoot, unsortedForwardRefs);
+			const linked = { ...active, next_forecast_ref: forwardRefs[0], forward_forecast_refs: forwardRefs, updated_at: now };
+			await atomicReplace(join(directories.subscriptions, `${active.subscription_id}.json`), `${JSON.stringify(linked, null, 2)}\n`);
+			return enqueueEventOnly(directories, projectName, validateRequest({
+				preset: active.preset,
+				locale: active.locale,
+				scope_id: active.scope_id,
+				cycle_id: active.cycle_id,
+				forecast_ref: active.forecast_ref,
+				forecast_role: active.forecast_role,
+				execution_ref: active.execution_ref,
+				next_forecast_ref: request.forecast_ref,
+				forward_forecast_refs: forwardRefs,
+				reason: "forecast_committed",
+			}), now);
+		}
+	} else if (request.reason === "forecast_committed" || request.reason === "execution_committed") {
+		await atomicReplace(join(directories.root, "active-subscription.json"), `${JSON.stringify({
+			kind: "fpa.dashboard.active-subscription",
+			schema_version: 1,
+			subscription_id: subscription.subscription_id,
+			updated_at: now,
+		}, null, 2)}\n`);
+	}
+	return enqueueEventOnly(directories, projectName, request, now);
+}
+
+async function countJsonFiles(path: string): Promise<number> {
+	return (await readdir(path, { withFileTypes: true })).filter((entry) => entry.isFile() && /^[a-f0-9]{64}\.json$/.test(entry.name)).length;
+}
+
+export async function inspectDashboardRefreshQueue(cwd: string): Promise<DashboardRefreshQueueStatus> {
+	const directories = await queueDirectories(cwd);
+	const [pending, processing, completed, dead, lockKind] = await Promise.all([
+		countJsonFiles(directories.pending),
+		countJsonFiles(directories.processing),
+		countJsonFiles(directories.completed),
+		countJsonFiles(directories.dead),
+		pathKind(join(directories.root, "coordinator.lock")),
+	]);
+	return { queue_dir: directories.root, pending, processing, completed, dead, busy: lockKind !== "missing" };
+}
+
+async function acquireLock(directories: QueueDirectories, now: Date): Promise<(() => Promise<void>) | null> {
+	const lockPath = join(directories.root, "coordinator.lock");
+	if (!await writeExclusive(lockPath, `${JSON.stringify({ acquired_at: now.toISOString(), pid: process.pid })}\n`)) {
+		try {
+			const lockStat = await stat(lockPath);
+			if (now.getTime() - lockStat.mtimeMs <= LOCK_STALE_MS) return null;
+			await unlink(lockPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+		if (!await writeExclusive(lockPath, `${JSON.stringify({ acquired_at: now.toISOString(), pid: process.pid })}\n`)) return null;
+	}
+	return async () => { await unlink(lockPath).catch(() => undefined); };
+}
+
+async function resolveEventProject(workspaceRoot: string, projectName: string): Promise<string> {
+	const candidate = resolve(workspaceRoot, projectName);
+	const relation = relative(workspaceRoot, candidate);
+	if (relation === "" || relation.startsWith("..") || isAbsolute(relation)) throw new Error("Refresh event project escapes the workspace.");
+	const projectRoot = await realpath(candidate);
+	if (dirname(projectRoot) !== workspaceRoot) throw new Error("Refresh event project must be a direct workspace child.");
+	return projectRoot;
+}
+
+async function defaultWorker(event: DashboardRefreshEvent, projectRoot: string, signal?: AbortSignal): Promise<DashboardRefreshWorkResult> {
+	const result = await buildDashboardProjection(projectRoot, event.preset, event.locale ?? "zh-CN", {
+		scopeId: event.scope_id,
+		cycleId: event.cycle_id,
+		forecastRef: event.forecast_ref,
+		...(event.execution_ref ? { executionRef: event.execution_ref } : {}),
+		...(event.next_forecast_ref ? { nextForecastRef: event.next_forecast_ref } : {}),
+		...(event.forward_forecast_refs ? { forwardForecastRefs: event.forward_forecast_refs } : {}),
+	}, signal);
+	if (result.sliceKeyMismatch) throw new Error(`Dashboard publish refused. ${result.sliceKeyMismatch}`);
+	if (result.forecast.status !== "complete" || !result.forecast.approval_conditions_satisfied) {
+		throw new Error("Dashboard publish requires a complete approved forecast with all approval conditions satisfied.");
+	}
+	const generationId = dashboardBuildFingerprint(result.build, result.projector);
+	if (event.desired_generation_id && generationId !== event.desired_generation_id) {
+		throw new ObsoleteDashboardRefreshError("Dashboard inputs changed after polling; the stale desired generation must be replanned.");
+	}
+	await publishDashboard({ cwd: projectRoot, build: result.build, projector: result.projector, runtime: result.runtime, actualsSnapshot: result.actuals });
+	return {
+		generation_id: generationId,
+		data_as_of: result.build.source.data_as_of,
+		published: true,
+		actuals_watermark: result.build.source.actuals_watermark,
+	};
+}
+
+async function recordSubscriptionSuccess(
+	directories: QueueDirectories,
+	event: DashboardRefreshEvent,
+	result: DashboardRefreshWorkResult,
+	now: Date,
+): Promise<void> {
+	const subscriptionId = subscriptionIdentity(event.project_name, event.scope_id, event.cycle_id);
+	const path = join(directories.subscriptions, `${subscriptionId}.json`);
+	const subscription = await readOptionalSubscription(path);
+	if (!subscription || subscription.forecast_ref.entry_id !== event.forecast_ref.entry_id) return;
+	if (event.desired_generation_id && result.generation_id !== event.desired_generation_id) {
+		throw new Error("Dashboard refresh result does not match the event's desired generation identity.");
+	}
+	await atomicReplace(path, `${JSON.stringify({
+		...subscription,
+		last_generation_id: result.generation_id,
+		desired_generation_id: event.desired_generation_id ?? result.generation_id,
+		last_actuals_watermark: result.actuals_watermark ?? result.generation_id,
+		next_poll_at: new Date(now.getTime() + ACTUALS_POLL_INTERVAL_MS).toISOString(),
+		updated_at: now.toISOString(),
+	}, null, 2)}\n`);
+}
+
+export async function processDashboardRefreshQueue(cwd: string, options: ProcessDashboardRefreshQueueOptions = {}): Promise<ProcessDashboardRefreshQueueResult> {
+	const projectRoot = await realpath(cwd);
+	const workspaceRoot = dirname(projectRoot);
+	const directories = await queueDirectories(projectRoot);
+	const now = options.now?.() ?? new Date();
+	const release = await acquireLock(directories, now);
+	if (!release) return { status: "busy", processed: 0, succeeded: 0, superseded: 0, retried: 0, failed: 0, ...await inspectDashboardRefreshQueue(projectRoot), busy: true };
+	let processed = 0;
+	let succeeded = 0;
+	let superseded = 0;
+	let retried = 0;
+	let failed = 0;
+	try {
+		const completedNames = new Set(await readdir(directories.completed));
+		for (const name of await readdir(directories.processing)) {
+			if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+			const path = join(directories.processing, name);
+			if (completedNames.has(name)) {
+				await unlink(path).catch(() => undefined);
+				continue;
+			}
+			const value = await stat(path);
+			if (now.getTime() - value.mtimeMs > LOCK_STALE_MS) await rename(path, join(directories.pending, name)).catch(() => undefined);
+		}
+
+		const names = (await readdir(directories.pending)).filter((name) => /^[a-f0-9]{64}\.json$/.test(name)).sort();
+		const limit = Math.max(1, Math.min(options.limit ?? 32, 100));
+		for (const name of names) {
+			if (processed >= limit || options.signal?.aborted) break;
+			const pendingPath = join(directories.pending, name);
+			let event: DashboardRefreshEvent;
+			try {
+				event = await readEvent(pendingPath);
+			} catch (error) {
+				await rename(pendingPath, join(directories.dead, name));
+				failed += 1;
+				processed += 1;
+				continue;
+			}
+			if (event.not_before && Date.parse(event.not_before) > now.getTime()) continue;
+			const processingPath = join(directories.processing, name);
+			try {
+				await rename(pendingPath, processingPath);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+				throw error;
+			}
+			processed += 1;
+			try {
+				const result = await (options.worker ?? defaultWorker)(event, await resolveEventProject(workspaceRoot, event.project_name), options.signal);
+				await atomicReplace(join(directories.completed, name), `${JSON.stringify({
+					kind: "fpa.dashboard.refresh-result",
+					schema_version: 1,
+					event_id: event.event_id,
+					completed_at: now.toISOString(),
+					...result,
+				}, null, 2)}\n`);
+				await recordSubscriptionSuccess(directories, event, result, now);
+				await unlink(processingPath);
+				succeeded += 1;
+			} catch (error) {
+				const message = (error instanceof Error ? error.message : String(error)).slice(0, 2048);
+				if (error instanceof ObsoleteDashboardRefreshError) {
+					await atomicReplace(join(directories.completed, name), `${JSON.stringify({
+						kind: "fpa.dashboard.refresh-result",
+						schema_version: 1,
+						event_id: event.event_id,
+						status: "superseded",
+						completed_at: now.toISOString(),
+						message,
+					}, null, 2)}\n`);
+					await unlink(processingPath);
+					superseded += 1;
+					continue;
+				}
+				const attempt = event.attempt + 1;
+				if (attempt >= MAX_ATTEMPTS) {
+					await atomicReplace(join(directories.dead, name), `${JSON.stringify({ ...event, attempt, last_error: message, failed_at: now.toISOString() }, null, 2)}\n`);
+					await unlink(processingPath);
+					failed += 1;
+				} else {
+					const notBefore = new Date(now.getTime() + (2 ** (attempt - 1)) * 30_000).toISOString();
+					await atomicReplace(join(directories.pending, name), `${JSON.stringify({ ...event, attempt, last_error: message, not_before: notBefore }, null, 2)}\n`);
+					await unlink(processingPath);
+					retried += 1;
+				}
+			}
+		}
+	} finally {
+		await release();
+	}
+	return { status: "processed", processed, succeeded, superseded, retried, failed, ...await inspectDashboardRefreshQueue(projectRoot), busy: false };
+}
+
+export interface PollDashboardActualsResult {
+	status: "idle" | "not_due" | "pending_exists" | "unchanged" | "enqueued";
+	event_id?: string;
+	generation_id?: string;
+}
+
+export function dashboardProjectionIsCurrent(
+	last: { actuals_watermark?: string; generation_id?: string },
+	desired: { actuals_watermark?: string; generation_id: string },
+): boolean {
+	return Boolean(desired.actuals_watermark)
+		&& desired.actuals_watermark === last.actuals_watermark
+		&& desired.generation_id === last.generation_id;
+}
+
+export async function pollDashboardActualsWatermark(
+	cwd: string,
+	options: { signal?: AbortSignal; now?: () => Date } = {},
+): Promise<PollDashboardActualsResult> {
+	const projectRoot = await realpath(cwd);
+	const workspaceRoot = dirname(projectRoot);
+	const directories = await queueDirectories(projectRoot);
+	if (await countJsonFiles(directories.pending) > 0 || await countJsonFiles(directories.processing) > 0) return { status: "pending_exists" };
+	const subscription = await activeSubscription(directories);
+	if (!subscription) return { status: "idle" };
+	const now = options.now?.() ?? new Date();
+	if (subscription.next_poll_at && Date.parse(subscription.next_poll_at) > now.getTime()) return { status: "not_due" };
+	const targetProject = await resolveEventProject(workspaceRoot, subscription.project_name);
+	const projection = await buildDashboardProjection(targetProject, subscription.preset, subscription.locale, {
+		scopeId: subscription.scope_id,
+		cycleId: subscription.cycle_id,
+		forecastRef: subscription.forecast_ref,
+		...(subscription.execution_ref ? { executionRef: subscription.execution_ref } : {}),
+		...(subscription.next_forecast_ref ? { nextForecastRef: subscription.next_forecast_ref } : {}),
+		...(subscription.forward_forecast_refs ? { forwardForecastRefs: subscription.forward_forecast_refs } : {}),
+	}, options.signal);
+	const generationId = dashboardBuildFingerprint(projection.build, projection.projector);
+	const actualsWatermark = projection.build.source.actuals_watermark;
+	const path = join(directories.subscriptions, `${subscription.subscription_id}.json`);
+	if (dashboardProjectionIsCurrent(
+		{ actuals_watermark: subscription.last_actuals_watermark, generation_id: subscription.last_generation_id },
+		{ actuals_watermark: actualsWatermark, generation_id: generationId },
+	)) {
+		await atomicReplace(path, `${JSON.stringify({
+			...subscription,
+			desired_generation_id: generationId,
+			next_poll_at: new Date(now.getTime() + ACTUALS_POLL_INTERVAL_MS).toISOString(),
+			updated_at: now.toISOString(),
+		}, null, 2)}\n`);
+		return { status: "unchanged", generation_id: generationId };
+	}
+	await atomicReplace(path, `${JSON.stringify({
+		...subscription,
+		desired_generation_id: generationId,
+		updated_at: now.toISOString(),
+	}, null, 2)}\n`);
+	const enqueued = await enqueueDashboardRefresh(targetProject, {
+		preset: subscription.preset,
+		locale: subscription.locale,
+		scope_id: subscription.scope_id,
+		cycle_id: subscription.cycle_id,
+		forecast_ref: subscription.forecast_ref,
+		...(subscription.forecast_role ? { forecast_role: subscription.forecast_role } : {}),
+		...(subscription.execution_ref ? { execution_ref: subscription.execution_ref } : {}),
+		...(subscription.next_forecast_ref ? { next_forecast_ref: subscription.next_forecast_ref } : {}),
+		...(subscription.forward_forecast_refs ? { forward_forecast_refs: subscription.forward_forecast_refs } : {}),
+		reason: actualsWatermark === subscription.last_actuals_watermark ? "generation_identity" : "actuals_watermark",
+		actuals_watermark: actualsWatermark ?? generationId,
+		desired_generation_id: generationId,
+	});
+	return { status: "enqueued", event_id: enqueued.event_id, generation_id: generationId };
+}
+
+export async function runDashboardRefreshCoordinator(
+	cwd: string,
+	options: ProcessDashboardRefreshQueueOptions = {},
+): Promise<{ poll: PollDashboardActualsResult; queue: ProcessDashboardRefreshQueueResult }> {
+	const operationNow = options.now?.() ?? new Date();
+	try {
+		const poll = await pollDashboardActualsWatermark(cwd, { signal: options.signal, now: () => operationNow });
+		const queue = await processDashboardRefreshQueue(cwd, { ...options, now: () => operationNow });
+		const directories = await queueDirectories(cwd);
+		const subscription = await activeSubscription(directories);
+		const completedNow = options.now?.() ?? new Date();
+		await writeCoordinatorStatus(cwd, {
+			now: completedNow,
+			queue,
+			state: queue.dead > 0 || queue.failed > 0 ? "degraded" : queue.pending + queue.processing > 0 ? "refreshing" : subscription ? "healthy" : "idle",
+			lastSuccess: queue.succeeded > 0,
+			lastActualsWatermark: subscription?.last_actuals_watermark ?? null,
+			nextPollAt: subscription?.next_poll_at ?? null,
+			subscription,
+			lastError: queue.failed > 0 ? `${queue.failed} refresh event(s) moved to dead letter.` : null,
+		});
+		return { poll, queue };
+	} catch (error) {
+		const failedNow = options.now?.() ?? new Date();
+		await writeCoordinatorStatus(cwd, {
+			now: failedNow,
+			state: "failed",
+			lastError: (error instanceof Error ? error.message : String(error)).slice(0, 2048),
+		}).catch(() => undefined);
+		throw error;
+	}
+}