@viccydev/pi-fpa 0.5.0 → 0.6.0

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,6 +104,140 @@ 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.
  *
@@ -106,45 +284,192 @@ export async function readProjectJsonFile(projectRoot: string, artifactPath: str
  * 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> {
-	return commitArtifact(projectRoot, await readProjectJsonFile(projectRoot, artifactPath));
+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.`);
+	}
+	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 };
+}
+
+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>;
+}
 
-export async function commitArtifact(projectRoot: string, input: unknown): Promise<CommitArtifactResult> {
+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> {
@@ -159,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> {