@viccydev/pi-fpa 0.9.4 → 0.9.6

package/extensions/fpa-dashboard/decision-package.ts

@@ -0,0 +1,437 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, readdir, realpath, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import { stableJson } from "../fpa-artifacts/store.ts";
+
+// ============================================================================
+// Decision packages.
+//
+// A confirmed strategy used to leave no trace a person could follow: the
+// dashboard posted an action, the agent re-ran a Graph, and the decision
+// itself stopped existing. A decision package is that decision made into an
+// object with a lifecycle — what was approved, by whom, against which budget,
+// and what happened afterwards.
+//
+// Two stores, because the data has two different natures:
+//
+//   * The package is written once and never edited. It carries the parameter
+//     snapshot as it stood at approval. If this were mutable, "what was
+//     approved" would drift into "what we ended up doing", and the ledger
+//     would lose the only thing it exists to prove.
+//
+//   * Events append. Execution progress, threshold breaches, and task
+//     transitions arrive over time and must never overwrite each other.
+//
+// Deliberately NOT an entry in the artifact ledger: that ledger holds the
+// immutable forecast/execution chain, addressed by content fingerprint. A
+// package accumulates history, so it would have to be re-committed on every
+// event, and each re-commit would mint a new identity for the same decision.
+// ============================================================================
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const DECISION_ID_RE = /^DEC-\d{4}-\d{4}-[a-f0-9]{8}$/;
+const PACKAGES_DIR = "decision-packages";
+
+export const DECISION_STATUSES = ["in_progress", "completed", "variance", "cancelled"] as const;
+export type DecisionStatus = (typeof DECISION_STATUSES)[number];
+
+export const DECISION_EVENT_TYPES = [
+	"approved",
+	"parameters_locked",
+	"task_accepted",
+	"task_completed",
+	"parameter_adjusted",
+	"threshold_breached",
+	"closed",
+] as const;
+export type DecisionEventType = (typeof DECISION_EVENT_TYPES)[number];
+
+export const DECISION_TASK_STATUSES = ["not_started", "in_progress", "completed", "adjusted", "synced", "configured", "not_completed"] as const;
+export type DecisionTaskStatus = (typeof DECISION_TASK_STATUSES)[number];
+
+export interface DecisionApproval {
+	step_order: number;
+	role: string;
+	approver: string;
+	action: "approved" | "acknowledged" | "rejected";
+	decided_at: string;
+	comment?: string;
+}
+
+export interface DecisionTask {
+	task_id: string;
+	task_name: string;
+	owner: string;
+	due_date: string;
+	status: DecisionTaskStatus;
+	completed_at?: string;
+}
+
+export interface DecisionPackage {
+	kind: "fpa.decision.package";
+	schema_version: 1;
+	decision_id: string;
+	version: string;
+	title: string;
+	scope_id: string;
+	cycle_id: string;
+	strategy_version: string;
+	handoff_fingerprint: string;
+	action_id: string;
+	owner: string | null;
+	approver_role: string;
+	/** Null when the approved strategy carries no budget the ledger can track. */
+	approved_budget_usd: number | null;
+	/** Fraction over budget that trips an alert, e.g. 0.10 for +10%. */
+	budget_threshold_pct: number;
+	reporting_currency: string;
+	approved_at: string;
+	locked_at: string;
+	/** The parameters as approved. Never edited — see the note above. */
+	parameters: Record<string, unknown>;
+	approvals: DecisionApproval[];
+	tasks: DecisionTask[];
+	memo_ref: string | null;
+	/** Integrity over everything above. */
+	package_fingerprint: string;
+}
+
+export interface DecisionEvent {
+	kind: "fpa.decision.event";
+	schema_version: 1;
+	decision_id: string;
+	event_at: string;
+	actor: string;
+	actor_type: "human" | "system";
+	event_type: DecisionEventType;
+	summary: string;
+	reason?: string;
+	change_detail?: string;
+	estimated_impact_usd?: number;
+}
+
+/** Identifiers and titles: no control characters at all, DEL included. */
+const CONTROL_CHARS = new RegExp("[\\u0000-\\u001f\\u007f]");
+
+/**
+ * Free text a person wrote — an approval comment, a reason for a change.
+ * Newlines and tabs are content there, so only the remaining control
+ * characters are rejected.
+ */
+const CONTROL_CHARS_ALLOWING_NEWLINES = new RegExp("[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f]");
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function boundedString(value: unknown, label: string, max = 512): string {
+	if (typeof value !== "string" || value.trim() === "" || value.length > max || CONTROL_CHARS.test(value)) {
+		throw new Error(`${label} must be a non-empty bounded string without control characters.`);
+	}
+	return value;
+}
+
+function optionalBoundedString(value: unknown, label: string, max = 4_096): string | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "string" || value.length > max || CONTROL_CHARS_ALLOWING_NEWLINES.test(value)) {
+		throw new Error(`${label} must be a bounded string without control characters.`);
+	}
+	return value;
+}
+
+function isoTimestamp(value: unknown, label: string): string {
+	const text = boundedString(value, label, 64);
+	if (Number.isNaN(Date.parse(text))) throw new Error(`${label} must be an ISO timestamp.`);
+	return text;
+}
+
+function finiteNumber(value: unknown, label: string): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${label} must be a finite number.`);
+	return value;
+}
+
+function enumValue<T extends readonly string[]>(value: unknown, allowed: T, label: string): T[number] {
+	if (typeof value !== "string" || !allowed.includes(value)) {
+		throw new Error(`${label} must be one of ${allowed.join(", ")}.`);
+	}
+	return value as T[number];
+}
+
+async function ensureDirectory(parent: string, name: string): Promise<string> {
+	const path = join(parent, name);
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${name} must be a regular directory, not a symlink.`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(path, { recursive: true, mode: 0o700 });
+	}
+	return path;
+}
+
+async function appendOnlyWrite(directory: string, destination: string, contents: string): Promise<"created" | "exists"> {
+	const temporary = join(directory, `.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		try {
+			await link(temporary, destination);
+			return "created";
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") return "exists";
+			throw error;
+		}
+	} finally {
+		await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+	}
+}
+
+/**
+ * A human-readable id with a content-addressed tail.
+ *
+ * The ledger is read by people discussing a specific decision, so `DEC-2026-
+ * 0718-3f9a1c02` beats a bare digest in a meeting. The tail still binds the id
+ * to the approval it came from, so two decisions cannot collide on the same day.
+ */
+export function decisionIdFor(input: { actionId: string; strategyVersion: string; approvedAt: string }): string {
+	const date = new Date(input.approvedAt);
+	if (Number.isNaN(date.getTime())) throw new Error("approvedAt must be an ISO timestamp.");
+	const year = date.getUTCFullYear();
+	const monthDay = `${String(date.getUTCMonth() + 1).padStart(2, "0")}${String(date.getUTCDate()).padStart(2, "0")}`;
+	const tail = sha256(stableJson({ action_id: input.actionId, strategy_version: input.strategyVersion })).slice(0, 8);
+	return `DEC-${year}-${monthDay}-${tail}`;
+}
+
+export interface CreateDecisionPackageInput {
+	actionId: string;
+	strategyVersion: string;
+	handoffFingerprint: string;
+	title: string;
+	scopeId: string;
+	cycleId: string;
+	approverRole: string;
+	owner?: string | null;
+	approvedBudgetUsd?: number | null;
+	budgetThresholdPct?: number;
+	reportingCurrency?: string;
+	parameters?: Record<string, unknown>;
+	approvals?: DecisionApproval[];
+	tasks?: DecisionTask[];
+	memoRef?: string | null;
+	version?: string;
+	approvedAt?: string;
+}
+
+function validateApprovals(value: unknown): DecisionApproval[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.length > 16) throw new Error("approvals must be an array of at most 16 entries.");
+	return value.map((raw, index) => {
+		if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`approvals[${index}] must be an object.`);
+		const source = raw as Record<string, unknown>;
+		return {
+			step_order: finiteNumber(source.step_order, `approvals[${index}].step_order`),
+			role: boundedString(source.role, `approvals[${index}].role`, 128),
+			approver: boundedString(source.approver, `approvals[${index}].approver`, 128),
+			action: enumValue(source.action, ["approved", "acknowledged", "rejected"] as const, `approvals[${index}].action`),
+			decided_at: isoTimestamp(source.decided_at, `approvals[${index}].decided_at`),
+			...(optionalBoundedString(source.comment, `approvals[${index}].comment`) !== undefined
+				? { comment: optionalBoundedString(source.comment, `approvals[${index}].comment`) as string }
+				: {}),
+		};
+	});
+}
+
+function validateTasks(value: unknown): DecisionTask[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.length > 64) throw new Error("tasks must be an array of at most 64 entries.");
+	return value.map((raw, index) => {
+		if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`tasks[${index}] must be an object.`);
+		const source = raw as Record<string, unknown>;
+		return {
+			task_id: boundedString(source.task_id, `tasks[${index}].task_id`, 64),
+			task_name: boundedString(source.task_name, `tasks[${index}].task_name`, 256),
+			owner: boundedString(source.owner, `tasks[${index}].owner`, 128),
+			due_date: boundedString(source.due_date, `tasks[${index}].due_date`, 32),
+			status: enumValue(source.status, DECISION_TASK_STATUSES, `tasks[${index}].status`),
+			...(source.completed_at ? { completed_at: isoTimestamp(source.completed_at, `tasks[${index}].completed_at`) } : {}),
+		};
+	});
+}
+
+/**
+ * Write the package for a confirmed strategy. Idempotent: committing the same
+ * decision twice returns the existing package rather than minting a second one.
+ */
+export async function createDecisionPackage(cwd: string, input: CreateDecisionPackageInput): Promise<DecisionPackage> {
+	if (!SHA256_RE.test(input.actionId)) throw new Error("actionId must be a SHA-256 digest.");
+	if (!SHA256_RE.test(input.handoffFingerprint)) throw new Error("handoffFingerprint must be a SHA-256 digest.");
+	const approvedAt = input.approvedAt ?? new Date().toISOString();
+	const budgetThreshold = input.budgetThresholdPct ?? 0.1;
+	if (budgetThreshold < 0 || budgetThreshold > 1) throw new Error("budgetThresholdPct must be between 0 and 1.");
+	const approvedBudget = input.approvedBudgetUsd ?? null;
+	if (approvedBudget !== null) finiteNumber(approvedBudget, "approvedBudgetUsd");
+
+	const decisionId = decisionIdFor({ actionId: input.actionId, strategyVersion: input.strategyVersion, approvedAt });
+	const core = {
+		kind: "fpa.decision.package" as const,
+		schema_version: 1 as const,
+		decision_id: decisionId,
+		version: input.version ?? "v1",
+		title: boundedString(input.title, "title", 256),
+		scope_id: boundedString(input.scopeId, "scopeId", 256),
+		cycle_id: boundedString(input.cycleId, "cycleId", 256),
+		strategy_version: boundedString(input.strategyVersion, "strategyVersion"),
+		handoff_fingerprint: input.handoffFingerprint,
+		action_id: input.actionId,
+		owner: input.owner ? boundedString(input.owner, "owner", 128) : null,
+		approver_role: boundedString(input.approverRole, "approverRole", 128),
+		approved_budget_usd: approvedBudget,
+		budget_threshold_pct: budgetThreshold,
+		reporting_currency: input.reportingCurrency ?? "USD",
+		approved_at: approvedAt,
+		// The snapshot is sealed at the same instant it is approved: a gap
+		// between the two is a window in which the parameters could change.
+		locked_at: approvedAt,
+		parameters: input.parameters ?? {},
+		approvals: validateApprovals(input.approvals),
+		tasks: validateTasks(input.tasks),
+		memo_ref: input.memoRef ?? null,
+	};
+	const pkg: DecisionPackage = { ...core, package_fingerprint: sha256(stableJson(core)) };
+
+	const projectRoot = await realpath(cwd);
+	const artifactsDir = await ensureDirectory(projectRoot, "artifacts");
+	const packagesDir = await ensureDirectory(artifactsDir, PACKAGES_DIR);
+	const path = join(packagesDir, `${decisionId}.json`);
+	const write = await appendOnlyWrite(packagesDir, path, `${JSON.stringify(pkg, null, 2)}\n`);
+	if (write === "exists") {
+		const existing = await readDecisionPackage(cwd, decisionId);
+		if (existing.package_fingerprint !== pkg.package_fingerprint) {
+			throw new Error(`Decision package ${decisionId} already exists with different content.`);
+		}
+		return existing;
+	}
+	await appendDecisionEvent(cwd, {
+		decision_id: decisionId,
+		event_at: approvedAt,
+		actor: input.approverRole,
+		actor_type: "human",
+		event_type: "approved",
+		summary: `${input.approverRole} approved ${core.title}`,
+	});
+	await appendDecisionEvent(cwd, {
+		decision_id: decisionId,
+		event_at: approvedAt,
+		actor: "system",
+		actor_type: "system",
+		event_type: "parameters_locked",
+		summary: "Parameter snapshot locked; the approved parameters are now immutable.",
+	});
+	return pkg;
+}
+
+export function validateDecisionPackage(value: unknown, label = "decision package"): DecisionPackage {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+	const source = value as Record<string, unknown>;
+	if (source.kind !== "fpa.decision.package" || source.schema_version !== 1) throw new Error(`${label} kind or schema version is unsupported.`);
+	const decisionId = boundedString(source.decision_id, `${label}.decision_id`, 64);
+	if (!DECISION_ID_RE.test(decisionId)) throw new Error(`${label}.decision_id is malformed.`);
+	if (typeof source.package_fingerprint !== "string" || !SHA256_RE.test(source.package_fingerprint)) {
+		throw new Error(`${label}.package_fingerprint must be a SHA-256 digest.`);
+	}
+	const { package_fingerprint: fingerprint, ...core } = source;
+	if (sha256(stableJson(core)) !== fingerprint) throw new Error(`${label} fingerprint does not match its content.`);
+	return source as unknown as DecisionPackage;
+}
+
+export async function readDecisionPackage(cwd: string, decisionId: string): Promise<DecisionPackage> {
+	if (!DECISION_ID_RE.test(decisionId)) throw new Error("decisionId is malformed.");
+	const projectRoot = await realpath(cwd);
+	const path = join(projectRoot, "artifacts", PACKAGES_DIR, `${decisionId}.json`);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Decision package must be a regular file, not a symlink.");
+	if (stat.size > 512 * 1024) throw new Error("Decision package exceeds its 512KB limit.");
+	return validateDecisionPackage(JSON.parse(await readFile(path, "utf8")), `decision package ${decisionId}`);
+}
+
+export async function listDecisionPackages(cwd: string): Promise<DecisionPackage[]> {
+	const projectRoot = await realpath(cwd);
+	const packagesDir = join(projectRoot, "artifacts", PACKAGES_DIR);
+	let names: string[];
+	try {
+		names = await readdir(packagesDir);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const packages: DecisionPackage[] = [];
+	for (const name of names.filter((entry) => entry.endsWith(".json")).slice(0, 500)) {
+		const decisionId = name.slice(0, -".json".length);
+		if (!DECISION_ID_RE.test(decisionId)) continue;
+		packages.push(await readDecisionPackage(cwd, decisionId));
+	}
+	// Newest first: the decision someone is asking about is usually the last one.
+	return packages.sort((left, right) => right.approved_at.localeCompare(left.approved_at));
+}
+
+export async function appendDecisionEvent(cwd: string, event: Omit<DecisionEvent, "kind" | "schema_version">): Promise<DecisionEvent> {
+	if (!DECISION_ID_RE.test(event.decision_id)) throw new Error("decision_id is malformed.");
+	const record: DecisionEvent = {
+		kind: "fpa.decision.event",
+		schema_version: 1,
+		decision_id: event.decision_id,
+		event_at: isoTimestamp(event.event_at, "event_at"),
+		actor: boundedString(event.actor, "actor", 128),
+		actor_type: enumValue(event.actor_type, ["human", "system"] as const, "actor_type"),
+		event_type: enumValue(event.event_type, DECISION_EVENT_TYPES, "event_type"),
+		summary: boundedString(event.summary, "summary", 1_024),
+		...(optionalBoundedString(event.reason, "reason") !== undefined ? { reason: event.reason as string } : {}),
+		...(optionalBoundedString(event.change_detail, "change_detail") !== undefined ? { change_detail: event.change_detail as string } : {}),
+		...(event.estimated_impact_usd !== undefined ? { estimated_impact_usd: finiteNumber(event.estimated_impact_usd, "estimated_impact_usd") } : {}),
+	};
+
+	const projectRoot = await realpath(cwd);
+	const artifactsDir = await ensureDirectory(projectRoot, "artifacts");
+	const packagesDir = await ensureDirectory(artifactsDir, PACKAGES_DIR);
+	const path = join(packagesDir, `${event.decision_id}.events.jsonl`);
+	// Append with O_APPEND so concurrent writers interleave whole lines rather
+	// than overwriting each other's offsets.
+	const handle = await open(path, "a", 0o600);
+	try {
+		await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	return record;
+}
+
+export async function readDecisionEvents(cwd: string, decisionId: string): Promise<DecisionEvent[]> {
+	if (!DECISION_ID_RE.test(decisionId)) throw new Error("decisionId is malformed.");
+	const projectRoot = await realpath(cwd);
+	const path = join(projectRoot, "artifacts", PACKAGES_DIR, `${decisionId}.events.jsonl`);
+	let raw: string;
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Decision event log must be a regular file, not a symlink.");
+		if (stat.size > 4 * 1024 * 1024) throw new Error("Decision event log exceeds its 4MB limit.");
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const events: DecisionEvent[] = [];
+	for (const [index, line] of raw.split("\n").entries()) {
+		if (line.trim() === "") continue;
+		const parsed = JSON.parse(line) as DecisionEvent;
+		if (parsed.kind !== "fpa.decision.event" || parsed.schema_version !== 1 || parsed.decision_id !== decisionId) {
+			throw new Error(`Decision event log line ${index + 1} does not belong to ${decisionId}.`);
+		}
+		events.push(parsed);
+	}
+	return events.sort((left, right) => left.event_at.localeCompare(right.event_at));
+}