@viccydev/pi-fpa 0.4.1 → 0.6.0

package/extensions/fpa-artifacts/index.ts

@@ -1,7 +1,15 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { commitArtifact, commitArtifactFromPath } from "./store.ts";
+import { composeApprovedForecast } from "./compose.ts";
+import { enqueueDashboardRefresh } from "../fpa-dashboard/coordinator.ts";
+import {
+	commitArtifact,
+	commitArtifactFromPath,
+	readArtifactByRef,
+	readProjectJsonFile,
+	type ArtifactRefV2,
+} from "./store.ts";
 
 function toolResult(value: Record<string, unknown>) {
 	return {
@@ -10,6 +18,17 @@ function toolResult(value: Record<string, unknown>) {
 	};
 }
 
+const artifactRefSchema = Type.Object({
+	scope_id: Type.String({ minLength: 1, maxLength: 256 }),
+	cycle_id: Type.String({ minLength: 1, maxLength: 256 }),
+	artifact_type: Type.Union([
+		Type.Literal("approved_cycle_forecast"),
+		Type.Literal("execution_receipt"),
+	]),
+	entry_id: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+	body_fingerprint: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+}, { additionalProperties: false });
+
 export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "fpa_artifact_commit",
@@ -31,6 +50,13 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 					minLength: 1,
 					description: "Project-relative path to a JSON file holding the canonical artifact. Mutually exclusive with artifact.",
 				})),
+				context: Type.Optional(Type.Object({
+					scope_id: Type.String({ minLength: 1, maxLength: 256 }),
+					cycle_id: Type.String({ minLength: 1, maxLength: 256 }),
+					forecast_role: Type.Optional(Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan")])),
+					upstream_refs: Type.Optional(Type.Array(artifactRefSchema, { maxItems: 16 })),
+					promote_legacy_pointer: Type.Optional(Type.Boolean()),
+				}, { additionalProperties: false })),
 			},
 			{ additionalProperties: false },
 		),
@@ -41,14 +67,103 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 			if (hasInline === hasPath) {
 				throw new Error("Supply exactly one of artifact or artifact_path.");
 			}
+			const commitOptions = params.context ? {
+				context: {
+					scope_id: params.context.scope_id,
+					cycle_id: params.context.cycle_id,
+					forecast_role: params.context.forecast_role,
+					upstream_refs: params.context.upstream_refs as ArtifactRefV2[] | undefined,
+				},
+				promoteLegacyPointer: params.context.promote_legacy_pointer,
+			} : undefined;
 			const committed = hasPath
-				? await commitArtifactFromPath(ctx.cwd, params.artifact_path as string)
-				: await commitArtifact(ctx.cwd, params.artifact);
+				? await commitArtifactFromPath(ctx.cwd, params.artifact_path as string, commitOptions)
+				: await commitArtifact(ctx.cwd, params.artifact, commitOptions);
+			let dashboardRefresh;
+			let dashboardRefreshError: string | undefined;
+			if (committed.artifactRef && params.context) {
+				try {
+					const forecastRef = committed.artifactType === "approved_cycle_forecast"
+						? committed.artifactRef
+						: params.context.upstream_refs?.find((ref) => ref.artifact_type === "approved_cycle_forecast") as ArtifactRefV2 | undefined;
+					if (!forecastRef) throw new Error("Assigned execution commit has no forecast ref for dashboard refresh.");
+					dashboardRefresh = await enqueueDashboardRefresh(ctx.cwd, {
+						preset: "forecast-closed-loop-v1",
+						locale: "zh-CN",
+						scope_id: params.context.scope_id,
+						cycle_id: params.context.cycle_id,
+						forecast_ref: forecastRef,
+						...(committed.artifactType === "approved_cycle_forecast" && params.context.forecast_role ? { forecast_role: params.context.forecast_role } : {}),
+						...(committed.artifactType === "execution_receipt" ? { execution_ref: committed.artifactRef } : {}),
+						reason: committed.artifactType === "approved_cycle_forecast" ? "forecast_committed" : "execution_committed",
+					});
+				} catch (error) {
+					// The immutable ledger commit is already durable. Report the
+					// secondary delivery failure explicitly instead of pretending the
+					// commit itself failed and encouraging an unsafe duplicate retry.
+					dashboardRefreshError = error instanceof Error ? error.message : String(error);
+				}
+			}
 			return toolResult({
-				status: "committed",
+				status: dashboardRefreshError ? "committed_refresh_enqueue_failed" : "committed",
 				artifact_type: committed.artifactType,
 				immutable_fingerprint: committed.fingerprint,
 				path: committed.path,
+				ledger_status: committed.ledgerStatus,
+				...(committed.artifactRef ? { artifact_ref: committed.artifactRef } : {}),
+				...(dashboardRefresh ? { dashboard_refresh: dashboardRefresh } : {}),
+				...(dashboardRefreshError ? { dashboard_refresh_error: dashboardRefreshError } : {}),
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_artifact_read",
+		label: "Read Exact FP&A Artifact",
+		description: "Resolve and verify one immutable FP&A artifact by its exact scope, cycle, entry, and body fingerprint. Never falls back to the current pointer.",
+		promptSnippet: "Read an exact immutable FP&A artifact reference",
+		parameters: Type.Object({ artifact_ref: artifactRefSchema }, { additionalProperties: false }),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const read = await readArtifactByRef(ctx.cwd, params.artifact_ref);
+			return toolResult({
+				status: "resolved",
+				artifact_ref: params.artifact_ref,
+				artifact: read.artifact as unknown as Record<string, unknown>,
+				path: read.path,
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_forecast_compose",
+		label: "Compose Approved Forecast",
+		description:
+			"Derive a complete, self-consistent approved_cycle_forecast from a compact plan file holding only the approved allocation and its per-slice ROAS assumptions. " +
+			"Computes every scenario metric, the consolidated roll-up, units, windows, and frozen_at, and checks the plan's slice keys against the dimension values ua_spend actually uses. " +
+			"Returns the artifact for fpa_artifact_commit to freeze; writes nothing.",
+		promptSnippet: "Derive a complete approved forecast from a compact plan",
+		promptGuidelines: [
+			"Author the compact plan, not the full artifact: supply the allocation and each slice's ROAS assumption and let this tool derive the rest.",
+			"Do not compute revenue, ROAS, or consolidated totals by hand; hand-rounded values fail the commit reconciliation.",
+		],
+		parameters: Type.Object(
+			{
+				plan_path: Type.String({
+					minLength: 1,
+					description: "Project-relative path to the compact forecast plan JSON file.",
+				}),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const plan = await readProjectJsonFile(ctx.cwd, params.plan_path, "plan_path");
+			const composed = await composeApprovedForecast(plan, { signal });
+			return toolResult({
+				status: "composed",
+				artifact: composed.artifact as unknown as Record<string, unknown>,
+				diagnostics: composed.diagnostics as unknown as Record<string, unknown>,
 			});
 		},
 	});

package/extensions/fpa-artifacts/store.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { lstat, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
+import { link, lstat, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
 import {
@@ -16,14 +16,58 @@ export interface CommitArtifactResult {
 	artifactType: ArtifactType;
 	fingerprint: string;
 	path: string;
+	ledgerStatus: "assigned" | "legacy_unassigned";
+	artifactRef?: ArtifactRefV2;
 }
 
 export interface ReadArtifactResult {
 	artifact: CanonicalArtifact;
 	fingerprint: string;
 	path: string;
+	ledgerContext?: ArtifactLedgerContext;
 }
 
+export interface ArtifactRefV2 {
+	scope_id: string;
+	cycle_id: string;
+	artifact_type: ArtifactType;
+	entry_id: string;
+	body_fingerprint: string;
+}
+
+export interface ArtifactCommitContext {
+	scope_id: string;
+	cycle_id: string;
+	upstream_refs?: ArtifactRefV2[];
+	forecast_role?: "original" | "eac" | "next_plan";
+}
+
+export interface ArtifactLedgerContext {
+	scope_id: string;
+	cycle_id: string;
+	upstream_refs: ArtifactRefV2[];
+	forecast_role?: "original" | "eac" | "next_plan";
+}
+
+export interface CommitArtifactOptions {
+	context?: ArtifactCommitContext;
+	promoteLegacyPointer?: boolean;
+}
+
+interface ArtifactLedgerEntry extends ArtifactRefV2 {
+	kind: "fpa.artifact.entry";
+	schema_version: 2;
+	body_ref: string;
+	created_at: string;
+	available_at: string;
+	upstream_refs: ArtifactRefV2[];
+	forecast_role?: "original" | "eac" | "next_plan";
+	assignment_status: "assigned";
+}
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const CONTEXT_ID_MAX_LENGTH = 256;
+
 export function stableJson(value: unknown): string {
 	if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
 	if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
@@ -60,26 +104,176 @@ async function existingArtifactDirectory(projectRoot: string): Promise<string> {
 	return artifactsDir;
 }
 
+async function ensureOwnedDirectory(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, { mode: 0o700 }).catch((mkdirError: NodeJS.ErrnoException) => {
+			if (mkdirError.code !== "EEXIST") throw mkdirError;
+		});
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${name} must be a regular directory, not a symlink.`);
+	}
+	return path;
+}
+
+async function ledgerDirectories(projectRoot: string): Promise<{ root: string; objects: string; entries: string; heads: string }> {
+	const artifacts = await ensureArtifactDirectory(projectRoot);
+	const root = await ensureOwnedDirectory(artifacts, ".ledger");
+	return {
+		root,
+		objects: await ensureOwnedDirectory(root, "objects"),
+		entries: await ensureOwnedDirectory(root, "entries"),
+		heads: await ensureOwnedDirectory(root, "heads"),
+	};
+}
+
+async function existingLedgerDirectories(projectRoot: string): Promise<{ root: string; objects: string; entries: string }> {
+	const artifacts = await existingArtifactDirectory(projectRoot);
+	const root = join(artifacts, ".ledger");
+	const objects = join(root, "objects");
+	const entries = join(root, "entries");
+	for (const [path, label] of [[root, ".ledger"], [objects, ".ledger/objects"], [entries, ".ledger/entries"]] as const) {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${label} must be a regular directory, not a symlink.`);
+	}
+	return { root, objects, entries };
+}
+
+async function syncDirectory(path: string): Promise<void> {
+	const handle = await open(path, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+async function atomicReplace(directory: string, destination: string, contents: string): Promise<void> {
+	const temporary = join(directory, `.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	let closed = false;
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		closed = true;
+		await rename(temporary, destination);
+		await syncDirectory(directory);
+	} catch (error) {
+		if (!closed) await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+}
+
+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);
+	let closed = false;
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		closed = true;
+		try {
+			await link(temporary, destination);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") return "exists";
+			throw error;
+		}
+		await syncDirectory(directory);
+		return "created";
+	} finally {
+		if (!closed) await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+	}
+}
+
+function contextId(value: unknown, path: string): string {
+	if (typeof value !== "string" || value.trim() === "" || value.length > CONTEXT_ID_MAX_LENGTH || /[\u0000-\u001f\u007f]/.test(value)) {
+		throw new Error(`${path} must be a non-empty string of at most ${CONTEXT_ID_MAX_LENGTH} characters without control characters.`);
+	}
+	return value;
+}
+
+export function validateArtifactRef(value: unknown, path = "artifact_ref", allowEnvelopeFields = false): ArtifactRefV2 {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object.`);
+	const source = value as Record<string, unknown>;
+	const allowed = new Set(["scope_id", "cycle_id", "artifact_type", "entry_id", "body_fingerprint"]);
+	if (!allowEnvelopeFields) for (const key of Object.keys(source)) if (!allowed.has(key)) throw new Error(`${path}.${key} is not allowed.`);
+	const artifactType = source.artifact_type;
+	if (artifactType !== "approved_cycle_forecast" && artifactType !== "execution_receipt") throw new Error(`${path}.artifact_type is unsupported.`);
+	if (typeof source.entry_id !== "string" || !SHA256_RE.test(source.entry_id)) throw new Error(`${path}.entry_id must be a SHA-256 digest.`);
+	if (typeof source.body_fingerprint !== "string" || !SHA256_RE.test(source.body_fingerprint)) throw new Error(`${path}.body_fingerprint must be a SHA-256 digest.`);
+	return {
+		scope_id: contextId(source.scope_id, `${path}.scope_id`),
+		cycle_id: contextId(source.cycle_id, `${path}.cycle_id`),
+		artifact_type: artifactType,
+		entry_id: source.entry_id,
+		body_fingerprint: source.body_fingerprint,
+	};
+}
+
+function validateCommitContext(value: ArtifactCommitContext): ArtifactLedgerContext {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("context must be an object.");
+	const source = value as unknown as Record<string, unknown>;
+	const allowed = new Set(["scope_id", "cycle_id", "upstream_refs", "forecast_role"]);
+	for (const key of Object.keys(source)) if (!allowed.has(key)) throw new Error(`context.${key} is not allowed.`);
+	const upstream = source.upstream_refs === undefined ? [] : source.upstream_refs;
+	if (!Array.isArray(upstream) || upstream.length > 16) throw new Error("context.upstream_refs must be an array of at most 16 artifact refs.");
+	const upstreamRefs = upstream.map((ref, index) => validateArtifactRef(ref, `context.upstream_refs[${index}]`));
+	if (new Set(upstreamRefs.map((ref) => ref.entry_id)).size !== upstreamRefs.length) throw new Error("context.upstream_refs must not contain duplicates.");
+	if (source.forecast_role !== undefined && source.forecast_role !== "original" && source.forecast_role !== "eac" && source.forecast_role !== "next_plan") {
+		throw new Error("context.forecast_role must be original, eac, or next_plan.");
+	}
+	return {
+		scope_id: contextId(source.scope_id, "context.scope_id"),
+		cycle_id: contextId(source.cycle_id, "context.cycle_id"),
+		upstream_refs: upstreamRefs,
+		...(source.forecast_role ? { forecast_role: source.forecast_role as ArtifactLedgerContext["forecast_role"] } : {}),
+	};
+}
+
 /**
  * Resolve a caller-supplied draft path inside the project.
  *
  * Same fail-closed posture as the committed artifacts themselves: no escaping
  * the project root, no symlinks, no unbounded reads.
  */
-async function resolveDraftPath(projectRoot: string, artifactPath: string): Promise<string> {
-	if (!artifactPath.trim()) throw new Error("artifact_path must be a non-empty path.");
+async function resolveDraftPath(projectRoot: string, artifactPath: string, label = "artifact_path"): Promise<string> {
+	if (!artifactPath.trim()) throw new Error(`${label} must be a non-empty path.`);
 	const root = await realpath(projectRoot);
 	const resolved = resolve(root, artifactPath);
 	const relation = relative(root, resolved);
 	if (relation === "" || relation.startsWith("..") || isAbsolute(relation)) {
-		throw new Error("artifact_path must stay inside the project directory.");
+		throw new Error(`${label} must stay inside the project directory.`);
 	}
 	const stat = await lstat(resolved);
-	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("artifact_path must point at a regular file, not a symlink.");
-	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`artifact_path exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${label} must point at a regular file, not a symlink.`);
+	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`${label} exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
 	return resolved;
 }
 
+/**
+ * Read and parse a JSON file the agent wrote somewhere inside the project.
+ *
+ * Shared by every by-path entry point so they all get the same fail-closed
+ * posture, and so a malformed file is reported as a parse error against the
+ * caller's own path rather than as something deeper and less obvious.
+ */
+export async function readProjectJsonFile(projectRoot: string, artifactPath: string, label = "artifact_path"): Promise<unknown> {
+	const path = await resolveDraftPath(projectRoot, artifactPath, label);
+	try {
+		return JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		throw new Error(`${label} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
 /**
  * Commit a canonical artifact an agent wrote to disk instead of passing inline.
  *
@@ -90,51 +284,192 @@ async function resolveDraftPath(projectRoot: string, artifactPath: string): Prom
  * many turns as it takes, and this entry point keeps the validation,
  * reconciliation, fingerprinting, and atomic write identical to the inline path.
  */
-export async function commitArtifactFromPath(projectRoot: string, artifactPath: string): Promise<CommitArtifactResult> {
-	const path = await resolveDraftPath(projectRoot, artifactPath);
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(await readFile(path, "utf8"));
-	} catch (error) {
-		throw new Error(`artifact_path is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+export async function commitArtifactFromPath(projectRoot: string, artifactPath: string, options: CommitArtifactOptions = {}): Promise<CommitArtifactResult> {
+	return commitArtifact(projectRoot, await readProjectJsonFile(projectRoot, artifactPath), options);
+}
+
+async function writeLegacyPointer(projectRoot: string, committed: CanonicalArtifact): Promise<string> {
+	const artifactsDir = await ensureArtifactDirectory(projectRoot);
+	const destination = join(artifactsDir, `${committed.artifact_type}.json`);
+	await atomicReplace(artifactsDir, destination, `${JSON.stringify(committed, null, 2)}\n`);
+	return destination;
+}
+
+function entryIdentity(
+	context: ArtifactLedgerContext,
+	artifactType: ArtifactType,
+	bodyFingerprint: string,
+): string {
+	return createHash("sha256").update(stableJson({
+		scope_id: context.scope_id,
+		cycle_id: context.cycle_id,
+		artifact_type: artifactType,
+		body_fingerprint: bodyFingerprint,
+		upstream_refs: context.upstream_refs,
+		...(context.forecast_role ? { forecast_role: context.forecast_role } : {}),
+	})).digest("hex");
+}
+
+function validateLedgerEntry(value: Record<string, unknown>, path: string): { ref: ArtifactRefV2; context: ArtifactLedgerContext } {
+	const allowed = new Set([
+		"kind", "schema_version", "scope_id", "cycle_id", "artifact_type", "entry_id", "body_fingerprint",
+		"body_ref", "created_at", "available_at", "upstream_refs", "forecast_role", "assignment_status",
+	]);
+	for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`${path}.${key} is not allowed.`);
+	if (value.kind !== "fpa.artifact.entry" || value.schema_version !== 2 || value.assignment_status !== "assigned") {
+		throw new Error(`${path} has an unsupported kind, schema, or assignment status.`);
+	}
+	const ref = validateArtifactRef(value, path, true);
+	if (value.body_ref !== `objects/${ref.body_fingerprint}.json`) throw new Error(`${path} has an invalid body_ref.`);
+	for (const field of ["created_at", "available_at"] as const) {
+		if (typeof value[field] !== "string" || Number.isNaN(Date.parse(value[field]))) throw new Error(`${path}.${field} must be an ISO timestamp.`);
+	}
+	if (!Array.isArray(value.upstream_refs) || value.upstream_refs.length > 16) throw new Error(`${path}.upstream_refs must be an array of at most 16 artifact refs.`);
+	const upstreamRefs = value.upstream_refs.map((item, index) => validateArtifactRef(item, `${path}.upstream_refs[${index}]`));
+	if (value.forecast_role !== undefined && value.forecast_role !== "original" && value.forecast_role !== "eac" && value.forecast_role !== "next_plan") {
+		throw new Error(`${path}.forecast_role is unsupported.`);
 	}
-	return commitArtifact(projectRoot, parsed);
+	if (ref.artifact_type === "execution_receipt" && value.forecast_role !== undefined) throw new Error(`${path}.forecast_role is allowed only for forecasts.`);
+	const context: ArtifactLedgerContext = {
+		scope_id: ref.scope_id,
+		cycle_id: ref.cycle_id,
+		upstream_refs: upstreamRefs,
+		...(value.forecast_role ? { forecast_role: value.forecast_role as ArtifactLedgerContext["forecast_role"] } : {}),
+	};
+	const expectedEntryId = entryIdentity(context, ref.artifact_type, ref.body_fingerprint);
+	if (expectedEntryId !== ref.entry_id) throw new Error(`${path} identity does not match its upstream refs.`);
+	return { ref, context };
 }
 
-export async function commitArtifact(projectRoot: string, input: unknown): Promise<CommitArtifactResult> {
+async function readBoundedJson(path: string, label: string): Promise<Record<string, unknown>> {
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${label} must be a regular file, not a symlink.`);
+	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`${label} exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
+	const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label} must contain a JSON object.`);
+	return parsed as Record<string, unknown>;
+}
+
+function canonicalFromStored(source: Record<string, unknown>, artifactType: ArtifactType, label: string): CanonicalArtifact {
+	const body = { ...source };
+	const fingerprint = body.immutable_fingerprint;
+	delete body.immutable_fingerprint;
+	if (typeof fingerprint !== "string" || !SHA256_RE.test(fingerprint)) throw new Error(`${label} has no valid immutable_fingerprint.`);
+	const artifact = validateArtifact(body);
+	if (artifact.artifact_type !== artifactType) throw new Error(`${label} contains ${artifact.artifact_type}, expected ${artifactType}.`);
+	if (artifactFingerprint(artifact) !== fingerprint) throw new Error(`${label} fingerprint mismatch: the committed artifact was modified after freezing.`);
+	return { ...artifact, immutable_fingerprint: fingerprint } as CanonicalArtifact;
+}
+
+async function commitLedgerEntry(
+	projectRoot: string,
+	committed: CanonicalArtifact,
+	context: ArtifactLedgerContext,
+): Promise<{ ref: ArtifactRefV2; bodyPath: string }> {
+	const directories = await ledgerDirectories(projectRoot);
+	const fingerprint = committed.immutable_fingerprint;
+	const objectPath = join(directories.objects, `${fingerprint}.json`);
+	const objectContents = `${JSON.stringify(committed, null, 2)}\n`;
+	if (await appendOnlyWrite(directories.objects, objectPath, objectContents) === "exists") {
+		const existing = canonicalFromStored(await readBoundedJson(objectPath, `ledger object ${fingerprint}`), committed.artifact_type, `ledger object ${fingerprint}`);
+		if (existing.immutable_fingerprint !== fingerprint) throw new Error(`Ledger object ${fingerprint} conflicts with its content address.`);
+	}
+
+	const entryId = entryIdentity(context, committed.artifact_type, fingerprint);
+	const ref: ArtifactRefV2 = {
+		scope_id: context.scope_id,
+		cycle_id: context.cycle_id,
+		artifact_type: committed.artifact_type,
+		entry_id: entryId,
+		body_fingerprint: fingerprint,
+	};
+	const entryPath = join(directories.entries, `${entryId}.json`);
+	const now = new Date().toISOString();
+	const entry: ArtifactLedgerEntry = {
+		kind: "fpa.artifact.entry",
+		schema_version: 2,
+		...ref,
+		body_ref: `objects/${fingerprint}.json`,
+		created_at: now,
+		available_at: now,
+		upstream_refs: context.upstream_refs,
+		...(context.forecast_role ? { forecast_role: context.forecast_role } : {}),
+		assignment_status: "assigned",
+	};
+	if (await appendOnlyWrite(directories.entries, entryPath, `${JSON.stringify(entry, null, 2)}\n`) === "exists") {
+		const existing = await readBoundedJson(entryPath, `ledger entry ${entryId}`);
+		const existingRef = validateLedgerEntry(existing, `ledger entry ${entryId}`).ref;
+		if (stableJson(existingRef) !== stableJson(ref)) throw new Error(`Ledger entry ${entryId} conflicts with the requested artifact ref.`);
+	}
+	const headId = createHash("sha256").update(stableJson({
+		scope_id: context.scope_id,
+		cycle_id: context.cycle_id,
+		artifact_type: committed.artifact_type,
+	})).digest("hex");
+	await atomicReplace(directories.heads, join(directories.heads, `${headId}.json`), `${JSON.stringify({
+		kind: "fpa.artifact.head",
+		schema_version: 2,
+		...ref,
+		updated_at: now,
+	}, null, 2)}\n`);
+	return { ref, bodyPath: objectPath };
+}
+
+export async function commitArtifact(projectRoot: string, input: unknown, options: CommitArtifactOptions = {}): Promise<CommitArtifactResult> {
 	const artifact = validateArtifact(input);
+	const context = options.context ? validateCommitContext(options.context) : null;
+	if (artifact.artifact_type === "approved_cycle_forecast" && context?.forecast_role === "original"
+		&& Date.parse(artifact.frozen_at) > Date.parse(artifact.target_period.start_inclusive)) {
+		throw new Error("An original forecast must be frozen no later than the target period start; use forecast_role=eac for an in-period reforecast.");
+	}
 	if (artifact.artifact_type === "execution_receipt") {
-		const forecastRead = await readCommittedArtifact(projectRoot, "approved_cycle_forecast");
+		if (context?.forecast_role !== undefined) throw new Error("context.forecast_role is allowed only for approved forecasts.");
+		let forecastRead: ReadArtifactResult;
+		if (context) {
+			if (context.upstream_refs.length !== 1 || context.upstream_refs[0].artifact_type !== "approved_cycle_forecast") {
+				throw new Error("An assigned execution receipt requires exactly one approved_cycle_forecast upstream ref.");
+			}
+			const forecastRef = context.upstream_refs[0];
+			if (forecastRef.scope_id !== context.scope_id || forecastRef.cycle_id !== context.cycle_id) {
+				throw new Error("Execution context scope_id and cycle_id must match its forecast upstream ref.");
+			}
+			forecastRead = await readArtifactByRef(projectRoot, forecastRef);
+		} else {
+			forecastRead = await readCommittedArtifact(projectRoot, "approved_cycle_forecast");
+		}
 		if (forecastRead.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("Committed approved forecast has the wrong artifact type.");
 		validateExecutionAgainstForecast(artifact, forecastRead.artifact);
 	}
 	const fingerprint = artifactFingerprint(artifact);
 	const committed = { ...artifact, immutable_fingerprint: fingerprint } as CanonicalArtifact;
-	const artifactsDir = await ensureArtifactDirectory(projectRoot);
-	const destination = join(artifactsDir, `${artifact.artifact_type}.json`);
-	const temporary = join(artifactsDir, `.${artifact.artifact_type}.${randomUUID()}.tmp`);
+	const ledgerCommit = context ? await commitLedgerEntry(projectRoot, committed, context) : undefined;
+	const artifactRef = ledgerCommit?.ref;
+	const promoteLegacyPointer = options.promoteLegacyPointer ?? true;
+	const destination = promoteLegacyPointer
+		? await writeLegacyPointer(projectRoot, committed)
+		: ledgerCommit?.bodyPath ?? join(await ensureArtifactDirectory(projectRoot), `${artifact.artifact_type}.json`);
 
-	const handle = await open(temporary, "wx", 0o600);
-	let closed = false;
-	try {
-		await handle.writeFile(`${JSON.stringify(committed, null, 2)}\n`, "utf8");
-		await handle.sync();
-		await handle.close();
-		closed = true;
-		await rename(temporary, destination);
-		const directoryHandle = await open(artifactsDir, "r");
-		try {
-			await directoryHandle.sync();
-		} finally {
-			await directoryHandle.close();
-		}
-	} catch (error) {
-		if (!closed) await handle.close().catch(() => undefined);
-		await unlink(temporary).catch(() => undefined);
-		throw error;
-	}
+	return {
+		artifactType: artifact.artifact_type,
+		fingerprint,
+		path: destination,
+		ledgerStatus: artifactRef ? "assigned" : "legacy_unassigned",
+		...(artifactRef ? { artifactRef } : {}),
+	};
+}
 
-	return { artifactType: artifact.artifact_type, fingerprint, path: destination };
+export async function readArtifactByRef(projectRoot: string, value: unknown): Promise<ReadArtifactResult> {
+	const ref = validateArtifactRef(value);
+	const directories = await existingLedgerDirectories(projectRoot);
+	const entryPath = join(directories.entries, `${ref.entry_id}.json`);
+	const entry = await readBoundedJson(entryPath, `ledger entry ${ref.entry_id}`);
+	const validatedEntry = validateLedgerEntry(entry, `ledger entry ${ref.entry_id}`);
+	const storedRef = validatedEntry.ref;
+	if (stableJson(storedRef) !== stableJson(ref)) throw new Error(`Ledger entry ${ref.entry_id} does not match the requested artifact ref.`);
+	const bodyPath = join(directories.objects, `${ref.body_fingerprint}.json`);
+	const artifact = canonicalFromStored(await readBoundedJson(bodyPath, `ledger object ${ref.body_fingerprint}`), ref.artifact_type, `ledger object ${ref.body_fingerprint}`);
+	if (artifact.immutable_fingerprint !== ref.body_fingerprint) throw new Error(`Ledger object ${ref.body_fingerprint} does not match the artifact ref.`);
+	return { artifact, fingerprint: ref.body_fingerprint, path: bodyPath, ledgerContext: validatedEntry.context };
 }
 
 export async function readCommittedArtifact(projectRoot: string, artifactType: ArtifactType): Promise<ReadArtifactResult> {
@@ -149,17 +484,8 @@ export async function readCommittedArtifact(projectRoot: string, artifactType: A
 		throw new Error(`${artifactType} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
 	}
 	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${artifactType} must contain a JSON object.`);
-	const source = { ...(parsed as Record<string, unknown>) };
-	const fingerprint = source.immutable_fingerprint;
-	delete source.immutable_fingerprint;
-	if (typeof fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(fingerprint)) {
-		throw new Error(`${artifactType} has no valid immutable_fingerprint.`);
-	}
-	const artifact = validateArtifact(source);
-	if (artifact.artifact_type !== artifactType) throw new Error(`${path} contains ${artifact.artifact_type}, expected ${artifactType}.`);
-	const expected = artifactFingerprint(artifact);
-	if (expected !== fingerprint) throw new Error(`${artifactType} fingerprint mismatch: the committed artifact was modified after freezing.`);
-	return { artifact: { ...artifact, immutable_fingerprint: fingerprint } as CanonicalArtifact, fingerprint, path };
+	const artifact = canonicalFromStored(parsed as Record<string, unknown>, artifactType, artifactType);
+	return { artifact, fingerprint: artifact.immutable_fingerprint, path };
 }
 
 export async function readOptionalCommittedArtifact(projectRoot: string, artifactType: ArtifactType): Promise<ReadArtifactResult | null> {