@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/runtime-jobs.js

@@ -0,0 +1,463 @@
+import { mkdirSync } from "node:fs";
+import { asProjectDataDir, projectBuildPlanPackagePath, } from "../contracts/lib/project-paths.js";
+import { createRunEventId, createRunEventTimestamp, } from "./execution/events.js";
+import { byCreatedAtDesc, listJsonFiles, localJobPath, localJobsRoot, readLocalJobRunAt, writeJsonFile, } from "./runtime-persistence.js";
+import { applyEventToLocalJob, } from "./runtime-event-applier.js";
+import { createRunId } from "./runtime-resource-builders.js";
+import { upsertProjectConfig, findProjectConfig, loadSourceFolderConfig, writeBenchmarkSpecsForProject, } from "../projects/source-config.js";
+import { BuildPlanAuthoringRuntimeRequestSchema, BuildPlanAuthoringResultSchema, LocalJobEventAppendRequestSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, BenchmarkQuestionDraftRuntimeRequestSchema, BenchmarkQuestionDraftResultSchema, } from "./schemas/index.js";
+import { artifactRequirementsForPlanAuthoring, requestedArtifactsForPlanAuthoring, } from "./plan-artifact-contract.js";
+import { isTerminalStatus } from "./runtime-status.js";
+const INTERRUPTED_JOB_RUN_MESSAGE = "Job interrupted because the local service stopped before the job reached a terminal state.";
+export function listJobs(projectDataDir) {
+    return byCreatedAtDesc(listJsonFiles(localJobsRoot(projectDataDir))
+        .map(readLocalJobRunAt)
+        .filter((run) => run !== null));
+}
+export function getJob(projectDataDir, runId) {
+    return listJobs(projectDataDir).find((run) => run.run_id === runId) ?? null;
+}
+export function getJobEvents(projectDataDir, runId) {
+    return getJob(projectDataDir, runId)?.events ?? null;
+}
+export function createJobRun(runtime, projectDataDir, requestValue) {
+    const request = LocalJobRunCreateRequestSchema.parse(requestValue);
+    const runId = createRunId("job");
+    const now = new Date().toISOString();
+    const run = LocalJobRunResourceSchema.parse({
+        kind: "interf-local-job-run",
+        version: 1,
+        run_id: runId,
+        job_type: request.job_type,
+        status: "running",
+        title: request.title,
+        ...(request.project !== undefined ? { project: request.project } : {}),
+        ...(request.build_plan !== undefined ? { build_plan: request.build_plan } : {}),
+        ...(request.source_path !== undefined ? { source_path: request.source_path } : {}),
+        ...(request.output_path !== undefined ? { output_path: request.output_path } : {}),
+        ...(request.agent !== undefined ? { agent: request.agent } : {}),
+        created_at: now,
+        started_at: now,
+        steps: request.steps.map((step) => ({
+            ...step,
+            status: "queued",
+        })),
+        events: [
+            {
+                type: "job.started",
+                event_id: createRunEventId("event"),
+                run_id: runId,
+                timestamp: now,
+                message: request.title,
+            },
+        ],
+    });
+    writeJobRun(runtime, projectDataDir, run);
+    return run;
+}
+export function appendJobRunEvent(runtime, projectDataDir, runId, requestValue) {
+    const request = LocalJobEventAppendRequestSchema.parse(requestValue);
+    const current = getJob(projectDataDir, runId);
+    if (!current)
+        return null;
+    if (isTerminalStatus(current.status))
+        return current;
+    const event = {
+        type: request.type,
+        event_id: createRunEventId("event"),
+        run_id: runId,
+        timestamp: new Date().toISOString(),
+        ...(request.step_id ? { step_id: request.step_id } : {}),
+        ...(request.message ? { message: request.message } : {}),
+        ...(request.artifact ? { artifact: request.artifact } : {}),
+        ...(request.input ? { input: request.input } : {}),
+        ...(request.output ? { output: request.output } : {}),
+    };
+    const next = LocalJobRunResourceSchema.parse(applyEventToLocalJob(current, event));
+    writeJobRun(runtime, projectDataDir, next);
+    return next;
+}
+export async function createBenchmarkQuestionDraftRun(runtime, projectDataDir, requestValue) {
+    const request = BenchmarkQuestionDraftRuntimeRequestSchema.parse(requestValue);
+    const job = createJobRun(runtime, projectDataDir, {
+        job_type: "benchmark-question-draft",
+        title: `Draft benchmark questions for ${request.project}`,
+        project: request.project,
+        source_path: request.source_folder_path,
+        steps: [
+            {
+                id: "read-source",
+                label: "Prepare Source locator",
+                input: {
+                    project: request.project,
+                    source_folder_path: request.source_folder_path,
+                },
+            },
+            {
+                id: "agent-draft",
+                label: "Draft benchmark questions",
+                input: {
+                    intent: request.intent ?? null,
+                    target_count: request.target_count,
+                },
+            },
+            {
+                id: "normalize-checks",
+                label: "Normalize saved benchmark checks",
+            },
+        ],
+    });
+    appendJobRunEvent(runtime, projectDataDir, job.run_id, {
+        type: "step.started",
+        step_id: "read-source",
+        message: "Preparing Source locator for benchmark drafting.",
+        input: {
+            project: request.project,
+            source_folder_path: request.source_folder_path,
+        },
+    });
+    appendJobRunEvent(runtime, projectDataDir, job.run_id, {
+        type: "step.completed",
+        step_id: "read-source",
+        message: "Source locator is ready for the drafting agent.",
+        output: {
+            project: request.project,
+            source_folder_path: request.source_folder_path,
+        },
+    });
+    appendJobRunEvent(runtime, projectDataDir, job.run_id, {
+        type: "step.started",
+        step_id: "agent-draft",
+        message: "Drafting saved benchmark questions from agent-visible Source.",
+        input: {
+            intent: request.intent ?? null,
+            target_count: request.target_count,
+        },
+    });
+    void runBenchmarkQuestionDraftInBackground(runtime, projectDataDir, request, job.run_id);
+    return getJob(projectDataDir, job.run_id) ?? job;
+}
+export async function createBuildPlanAuthoringRun(runtime, projectDataDir, requestValue, jobType = "build-plan-draft") {
+    const parsedRequest = BuildPlanAuthoringRuntimeRequestSchema.parse(requestValue);
+    const savedProject = parsedRequest.project
+        ? findProjectConfig(loadSourceFolderConfig(projectDataDir), parsedRequest.project)
+        : null;
+    const requestedArtifacts = requestedArtifactsForPlanAuthoring({
+        projectDataDir,
+        projectConfig: savedProject,
+        explicitRequestedArtifacts: parsedRequest.requested_artifacts,
+    });
+    const request = {
+        ...parsedRequest,
+        checks: parsedRequest.checks ?? parsedRequest.context_checks ?? [],
+        requested_artifacts: requestedArtifacts,
+        artifact_requirements: artifactRequirementsForPlanAuthoring({
+            projectDataDir,
+            projectConfig: savedProject,
+            requestedArtifacts,
+            explicitArtifactRequirements: parsedRequest.artifact_requirements,
+        }),
+        source_context: parsedRequest.source_context ?? null,
+    };
+    const isImprovement = jobType === "build-plan-improvement";
+    const job = createJobRun(runtime, projectDataDir, {
+        job_type: jobType,
+        title: isImprovement ? `Improve Build Plan ${request.build_plan_id}` : `Draft Build Plan ${request.build_plan_id}`,
+        project: request.project ?? null,
+        build_plan: request.build_plan_id,
+        source_path: request.source_folder_path,
+        output_path: projectBuildPlanPackagePath(asProjectDataDir(projectDataDir), request.build_plan_id),
+        steps: [
+            {
+                id: "inspect-source",
+                label: "Prepare Source locator",
+                input: {
+                    project: request.project ?? null,
+                    source_folder_path: request.source_folder_path,
+                    checks: request.checks.length,
+                    requested_artifacts: request.requested_artifacts.length,
+                    source_context: request.source_context ? "provided" : "none",
+                },
+            },
+            {
+                id: "draft-package",
+                label: isImprovement ? "Improve Build Plan definition" : "Draft Build Plan definition",
+                input: {
+                    build_plan_id: request.build_plan_id,
+                    label: request.label,
+                    intent: request.intent,
+                    requested_artifacts: request.requested_artifacts.length,
+                    artifact_requirements: request.artifact_requirements.length,
+                },
+            },
+            {
+                id: "validate-package",
+                label: "Validate Build Plan definition",
+                input: {
+                    build_plan_id: request.build_plan_id,
+                },
+            },
+        ],
+    });
+    appendJobRunEvent(runtime, projectDataDir, job.run_id, {
+        type: "step.started",
+        step_id: "inspect-source",
+        message: isImprovement ? "Preparing Source locator for Build Plan improvement." : "Preparing Source locator for Build Plan drafting.",
+        input: {
+            project: request.project ?? null,
+            source_folder_path: request.source_folder_path,
+            checks: request.checks.length,
+            requested_artifacts: request.requested_artifacts.length,
+            source_context: request.source_context ? "provided" : "none",
+        },
+    });
+    appendJobRunEvent(runtime, projectDataDir, job.run_id, {
+        type: "step.completed",
+        step_id: "inspect-source",
+        message: "Source context is ready.",
+        output: {
+            source_folder_path: request.source_folder_path,
+            checks: request.checks.length,
+            requested_artifacts: request.requested_artifacts.length,
+        },
+    });
+    appendJobRunEvent(runtime, projectDataDir, job.run_id, {
+        type: "step.started",
+        step_id: "draft-package",
+        message: isImprovement ? "Improving Build Plan definition." : "Drafting Build Plan definition.",
+        input: {
+            build_plan_id: request.build_plan_id,
+            label: request.label,
+            intent: request.intent,
+            requested_artifacts: request.requested_artifacts.length,
+            artifact_requirements: request.artifact_requirements.length,
+        },
+    });
+    void runBuildPlanAuthoringInBackground(runtime, projectDataDir, request, job.run_id);
+    return getJob(projectDataDir, job.run_id) ?? job;
+}
+async function runBenchmarkQuestionDraftInBackground(runtime, projectDataDir, request, runId) {
+    runtime.beginActiveJobRun(runId);
+    runtime.beginActiveRun();
+    return runBenchmarkQuestionDraftInBackgroundInner(runtime, projectDataDir, request, runId).finally(() => {
+        runtime.endActiveRun();
+        runtime.endActiveJobRun(runId);
+    });
+}
+async function runBenchmarkQuestionDraftInBackgroundInner(runtime, projectDataDir, request, runId) {
+    try {
+        if (!runtime.handlers.createBenchmarkQuestionDraft) {
+            throw new Error("No benchmark-question-draft handler is configured for this local service.");
+        }
+        const result = BenchmarkQuestionDraftResultSchema.parse(await runtime.handlers.createBenchmarkQuestionDraft(request, jobRunContext(runtime, projectDataDir, runId)));
+        const specPaths = writeBenchmarkSpecsForProject({
+            projectDataDir,
+            projectName: request.project,
+            checks: result.checks,
+            description: request.intent ?? `Saved benchmark checks for Project ${request.project}.`,
+        });
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "step.completed",
+            step_id: "agent-draft",
+            message: `Drafted ${result.checks.length} benchmark checks.`,
+            output: {
+                checks: result.checks,
+            },
+        });
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "step.started",
+            step_id: "normalize-checks",
+            message: "Normalizing drafted benchmark questions into saved check records.",
+            input: {
+                checks: result.checks.length,
+            },
+        });
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "step.completed",
+            step_id: "normalize-checks",
+            message: `${result.checks.length} benchmark checks ready for review.`,
+            output: {
+                checks: result.checks.length,
+                spec_paths: specPaths,
+            },
+        });
+        setJobRunResult(runtime, projectDataDir, runId, { ...result, spec_paths: specPaths });
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "job.completed",
+            message: `Drafted ${result.checks.length} benchmark checks.`,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "step.failed",
+            step_id: "agent-draft",
+            message,
+            output: {
+                error: message,
+            },
+        });
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "job.failed",
+            message,
+        });
+    }
+}
+async function runBuildPlanAuthoringInBackground(runtime, projectDataDir, request, runId) {
+    runtime.beginActiveJobRun(runId);
+    runtime.beginActiveRun();
+    return runBuildPlanAuthoringInBackgroundInner(runtime, projectDataDir, request, runId).finally(() => {
+        runtime.endActiveRun();
+        runtime.endActiveJobRun(runId);
+    });
+}
+async function runBuildPlanAuthoringInBackgroundInner(runtime, projectDataDir, request, runId) {
+    try {
+        if (!runtime.handlers.createBuildPlanAuthoringRun) {
+            throw new Error("No Build Plan-authoring handler is configured for this local service.");
+        }
+        const result = BuildPlanAuthoringResultSchema.parse(await runtime.handlers.createBuildPlanAuthoringRun(request, jobRunContext(runtime, projectDataDir, runId)));
+        setJobRunResult(runtime, projectDataDir, runId, result);
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: result.status === "executor-failed" ? "step.failed" : "step.completed",
+            step_id: "draft-package",
+            message: result.summary,
+            output: {
+                status: result.status,
+                changed: result.changed,
+                build_plan_path: result.build_plan_path,
+                shell_path: result.shell_path,
+            },
+        });
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "step.started",
+            step_id: "validate-package",
+            message: "Validating Build Plan package structure and stage contract.",
+            input: {
+                build_plan_path: result.build_plan_path,
+            },
+        });
+        if (result.status === "updated" || result.status === "no-change") {
+            let selectedProject = null;
+            if (request.project) {
+                const selected = runtime.resolveProjectConfig(projectDataDir, request.project, {
+                    build_plan: request.build_plan_id,
+                });
+                upsertProjectConfig(projectDataDir, selected);
+                runtime.readinessCache.invalidateProject(projectDataDir, selected.name);
+                runtime.buildRunCache.invalidateProject(projectDataDir, selected.name);
+                runtime.verifyRunCache.invalidateProject(projectDataDir, selected.name);
+                runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
+                runtime.buildPlanListingCache.invalidate(projectDataDir);
+                selectedProject = selected.name;
+            }
+            appendJobRunEvent(runtime, projectDataDir, runId, {
+                type: "step.completed",
+                step_id: "validate-package",
+                message: selectedProject
+                    ? `${result.summary} Selected Build Plan ${request.build_plan_id} for Project ${selectedProject}.`
+                    : result.summary,
+                output: {
+                    status: result.status,
+                    validation: result.validation ?? null,
+                    selected_project: selectedProject,
+                },
+            });
+            appendJobRunEvent(runtime, projectDataDir, runId, {
+                type: "job.completed",
+                message: selectedProject
+                    ? `${result.summary} Selected Build Plan ${request.build_plan_id} for Project ${selectedProject}.`
+                    : result.summary,
+            });
+        }
+        else {
+            appendJobRunEvent(runtime, projectDataDir, runId, {
+                type: "step.failed",
+                step_id: "validate-package",
+                message: result.summary,
+                output: {
+                    status: result.status,
+                    validation: result.validation ?? null,
+                },
+            });
+            appendJobRunEvent(runtime, projectDataDir, runId, {
+                type: "job.failed",
+                message: result.summary,
+            });
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "step.failed",
+            step_id: "draft-package",
+            message,
+            output: {
+                error: message,
+            },
+        });
+        appendJobRunEvent(runtime, projectDataDir, runId, {
+            type: "job.failed",
+            message,
+        });
+    }
+}
+export function jobRunContext(runtime, projectDataDir, runId) {
+    return {
+        runId,
+        sourcePath: projectDataDir,
+        emit: (event) => {
+            appendJobRunEvent(runtime, projectDataDir, runId, event);
+        },
+    };
+}
+export function writeJobRun(runtime, projectDataDir, run) {
+    mkdirSync(localJobsRoot(projectDataDir), { recursive: true });
+    writeJsonFile(localJobPath(projectDataDir, run.run_id), LocalJobRunResourceSchema.parse(run));
+    if (run.project) {
+        // Some job runs (benchmark-question drafts) flip readiness state.
+        runtime.readinessCache.invalidateProject(projectDataDir, run.project);
+        runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
+    }
+}
+export function setJobRunResult(runtime, projectDataDir, runId, result) {
+    const current = getJob(projectDataDir, runId);
+    if (!current)
+        return;
+    if (isTerminalStatus(current.status))
+        return;
+    const normalizedResult = result && typeof result === "object" && !Array.isArray(result)
+        ? result
+        : { value: result };
+    writeJobRun(runtime, projectDataDir, LocalJobRunResourceSchema.parse({
+        ...current,
+        result: normalizedResult,
+    }));
+}
+export function finalizeInterruptedJobRuns(runtime, projectDataDir) {
+    for (const run of listJobs(projectDataDir)) {
+        if (isTerminalStatus(run.status) || runtime.activeJobRuns.has(run.run_id))
+            continue;
+        const timestamp = createRunEventTimestamp();
+        const interruptedRun = LocalJobRunResourceSchema.parse({
+            ...run,
+            steps: run.steps.map((step) => {
+                if (step.status !== "running")
+                    return step;
+                return {
+                    ...step,
+                    status: "failed",
+                    finished_at: step.finished_at ?? timestamp,
+                    summary: step.summary ?? INTERRUPTED_JOB_RUN_MESSAGE,
+                };
+            }),
+        });
+        writeJobRun(runtime, projectDataDir, applyEventToLocalJob(interruptedRun, {
+            type: "job.failed",
+            event_id: createRunEventId("event"),
+            run_id: run.run_id,
+            timestamp,
+            message: INTERRUPTED_JOB_RUN_MESSAGE,
+        }));
+    }
+}

package/dist/packages/runtime/runtime-observability.d.ts

@@ -0,0 +1,11 @@
+import type { RunObservabilityResource } from "./schemas/index.js";
+import type { LocalServiceRuntime } from "./runtime.js";
+export declare function listRunObservability(runtime: LocalServiceRuntime, projectDataDir: string): RunObservabilityResource[];
+export declare function getRunObservability(runtime: LocalServiceRuntime, projectDataDir: string, runId: string): RunObservabilityResource | null;
+/**
+ * Build Plan Activity runs: every Build Plan draft or improvement job whose
+ * Build Plan id matches `buildPlanId`. Surfaced through
+ * `GET /v1/build-plans/<id>/runs` so Build Plan detail can show the full
+ * audit trail of authoring + improvement work.
+ */
+export declare function listBuildPlanRuns(runtime: LocalServiceRuntime, projectDataDir: string, buildPlanId: string): RunObservabilityResource[];

package/dist/packages/runtime/runtime-observability.js

@@ -0,0 +1,39 @@
+import { buildRunToObservability, jobRunToObservability, verifyRunToObservability, } from "./run-observability.js";
+import { timestampKey } from "./runtime-persistence.js";
+import { listBuildRuns } from "./runtime-build-runs.js";
+import { listVerifyRuns } from "./runtime-verify-runs.js";
+import { listJobs } from "./runtime-jobs.js";
+import { getReadiness } from "./runtime-project-reads.js";
+export function listRunObservability(runtime, projectDataDir) {
+    return [
+        ...listBuildRuns(runtime, projectDataDir).map((resource) => buildRunToObservability({
+            ...resource.run,
+            readiness: getReadiness(runtime, projectDataDir, resource.run.project),
+        })),
+        ...listVerifyRuns(runtime, projectDataDir)
+            .filter((run) => !run.parent_run_id)
+            .map(verifyRunToObservability),
+        ...listJobs(projectDataDir).map(jobRunToObservability),
+    ].sort((left, right) => {
+        const leftTime = timestampKey(left.started_at ?? left.created_at ?? left.finished_at);
+        const rightTime = timestampKey(right.started_at ?? right.created_at ?? right.finished_at);
+        return rightTime - leftTime;
+    });
+}
+export function getRunObservability(runtime, projectDataDir, runId) {
+    return listRunObservability(runtime, projectDataDir).find((run) => run.run_id === runId) ?? null;
+}
+/**
+ * Build Plan Activity runs: every Build Plan draft or improvement job whose
+ * Build Plan id matches `buildPlanId`. Surfaced through
+ * `GET /v1/build-plans/<id>/runs` so Build Plan detail can show the full
+ * audit trail of authoring + improvement work.
+ */
+export function listBuildPlanRuns(runtime, projectDataDir, buildPlanId) {
+    return listRunObservability(runtime, projectDataDir).filter((run) => {
+        if (run.build_plan !== buildPlanId)
+            return false;
+        return (run.run_type === "build-plan-draft" ||
+            run.run_type === "build-plan-improvement");
+    });
+}

package/dist/packages/{engine → runtime}/runtime-persistence.d.ts

@@ -1,38 +1,29 @@
 import { type BuildRun } from "./execution/lib/schema.js";
-import { type RuntimeRun } from "./build/lib/schema.js";
-import { type ActionProposalResource, type LocalJobRunResource, type VerifyRunResource } from "./lib/schema.js";
-export declare function buildRunsRoot(verifiableContextPath: string): string;
-export declare function buildRunPath(verifiableContextPath: string, runId: string): string;
-export declare function verifyRunsRoot(verifiableContextPath: string): string;
-export declare function verifyRunPath(verifiableContextPath: string, runId: string): string;
+import { type ExecutionStageLedger } from "./build/lib/schema.js";
+import { type ActionProposalResource, type LocalJobRunResource, type VerifyRunResource } from "./schemas/index.js";
+export declare function projectBuildRunsRoot(projectDataDir: string): string;
+export declare function projectBuildRunPath(projectDataDir: string, runId: string): string;
+export declare function verifyRunsRoot(contextGraphPath: string): string;
+export declare function verifyRunPath(contextGraphPath: string, runId: string): string;
 export declare function localJobsRoot(rootPath: string): string;
 export declare function localJobPath(rootPath: string, runId: string): string;
 export declare function actionProposalsRoot(rootPath: string): string;
 export declare function actionProposalPath(rootPath: string, proposalId: string): string;
-export declare function readJsonFile(filePath: string): unknown | null;
 export declare function writeJsonFile(filePath: string, value: unknown): void;
-export declare function readJsonOrNull<T>(filePath: string, schema: {
-    safeParse(value: unknown): {
-        success: true;
-        data: T;
-    } | {
-        success: false;
-    };
-}): T | null;
 export declare function listJsonFiles(dirPath: string): string[];
 export declare function readBuildRunAt(filePath: string): BuildRun | null;
 export declare function readVerifyRunAt(filePath: string): VerifyRunResource | null;
 export declare function readLocalJobRunAt(filePath: string): LocalJobRunResource | null;
 export declare function readActionProposalAt(filePath: string): ActionProposalResource | null;
 /**
- * Read the per-stage runtime-run history NDJSON. Each line is a `RuntimeRun`
+ * Read the per-stage runtime-run history NDJSON. Each line is a `ExecutionStageLedger`
  * record; lines that fail to parse are silently skipped so the runtime can
  * tolerate a partially-written tail without crashing.
  */
-export declare function readRuntimeRunHistory(verifiableContextPath: string): RuntimeRun[];
+export declare function readExecutionStageLedgerHistory(contextGraphPath: string): ExecutionStageLedger[];
 /**
  * Sort items newest-first using `started_at` (with a `finished_at` fallback).
- * Used for build/test run lists where the canonical order is by activity
+ * Used for Build/benchmark run lists where the canonical order is by activity
  * window, not by record-creation time.
  */
 export declare function newestFirst<T extends {

package/dist/packages/{engine → runtime}/runtime-persistence.js

@@ -5,40 +5,41 @@
  * no shared state. Every other runtime module composes on top of this layer
  * so the runtime coordinator stays small.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync, } from "node:fs";
+import { join } from "node:path";
 import { BuildRunSchema, } from "./execution/lib/schema.js";
-import { verifiableContextRuntimeRunHistoryPath, verifiableContextRuntimeRoot, testRootForVerifiableContext, } from "./build/verifiable-context-paths.js";
-import { RuntimeRunSchema, } from "./build/lib/schema.js";
-import { asPreparationDataDir, preparationServiceActionProposalsRoot, preparationServiceJobsRoot, } from "../contracts/lib/preparation-paths.js";
-import { ActionProposalResourceSchema, LocalJobRunResourceSchema, VerifyRunResourceSchema, } from "./lib/schema.js";
+import { contextGraphExecutionStageLedgerHistoryPath, testRootForContextGraph, } from "./build/context-graph-paths.js";
+import { ExecutionStageLedgerSchema, } from "./build/lib/schema.js";
+import { asProjectDataDir, projectServiceBuildRunsRoot, projectServiceActionProposalsRoot, projectServiceJobsRoot, } from "../contracts/lib/project-paths.js";
+import { ActionProposalResourceSchema, LocalJobRunResourceSchema, VerifyRunResourceSchema, } from "./schemas/index.js";
+import { writeJsonAtomic } from "./build/atomic-fs.js";
 // ---- Path helpers --------------------------------------------------------
-export function buildRunsRoot(verifiableContextPath) {
-    return join(verifiableContextRuntimeRoot(verifiableContextPath), "build-runs");
+export function projectBuildRunsRoot(projectDataDir) {
+    return projectServiceBuildRunsRoot(asProjectDataDir(projectDataDir));
 }
-export function buildRunPath(verifiableContextPath, runId) {
-    return join(buildRunsRoot(verifiableContextPath), `${runId}.json`);
+export function projectBuildRunPath(projectDataDir, runId) {
+    return join(projectBuildRunsRoot(projectDataDir), `${runId}.json`);
 }
-export function verifyRunsRoot(verifiableContextPath) {
-    return join(testRootForVerifiableContext(verifiableContextPath), "service-runs");
+export function verifyRunsRoot(contextGraphPath) {
+    return join(testRootForContextGraph(contextGraphPath), "service-runs");
 }
-export function verifyRunPath(verifiableContextPath, runId) {
-    return join(verifyRunsRoot(verifiableContextPath), `${runId}.json`);
+export function verifyRunPath(contextGraphPath, runId) {
+    return join(verifyRunsRoot(contextGraphPath), `${runId}.json`);
 }
 export function localJobsRoot(rootPath) {
-    return preparationServiceJobsRoot(asPreparationDataDir(rootPath));
+    return projectServiceJobsRoot(asProjectDataDir(rootPath));
 }
 export function localJobPath(rootPath, runId) {
     return join(localJobsRoot(rootPath), `${runId}.json`);
 }
 export function actionProposalsRoot(rootPath) {
-    return preparationServiceActionProposalsRoot(asPreparationDataDir(rootPath));
+    return projectServiceActionProposalsRoot(asProjectDataDir(rootPath));
 }
 export function actionProposalPath(rootPath, proposalId) {
     return join(actionProposalsRoot(rootPath), `${proposalId}.json`);
 }
 // ---- JSON IO -------------------------------------------------------------
-export function readJsonFile(filePath) {
+function readJsonFile(filePath) {
     try {
         return JSON.parse(readFileSync(filePath, "utf8"));
     }
@@ -47,10 +48,9 @@ export function readJsonFile(filePath) {
     }
 }
 export function writeJsonFile(filePath, value) {
-    mkdirSync(dirname(filePath), { recursive: true });
-    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+    writeJsonAtomic(filePath, value);
 }
-export function readJsonOrNull(filePath, schema) {
+function readJsonOrNull(filePath, schema) {
     const raw = readJsonFile(filePath);
     if (raw === null)
         return null;
@@ -85,12 +85,12 @@ export function readActionProposalAt(filePath) {
     return readJsonOrNull(filePath, ActionProposalResourceSchema);
 }
 /**
- * Read the per-stage runtime-run history NDJSON. Each line is a `RuntimeRun`
+ * Read the per-stage runtime-run history NDJSON. Each line is a `ExecutionStageLedger`
  * record; lines that fail to parse are silently skipped so the runtime can
  * tolerate a partially-written tail without crashing.
  */
-export function readRuntimeRunHistory(verifiableContextPath) {
-    const historyPath = verifiableContextRuntimeRunHistoryPath(verifiableContextPath);
+export function readExecutionStageLedgerHistory(contextGraphPath) {
+    const historyPath = contextGraphExecutionStageLedgerHistoryPath(contextGraphPath);
     if (!existsSync(historyPath))
         return [];
     try {
@@ -100,7 +100,7 @@ export function readRuntimeRunHistory(verifiableContextPath) {
             .filter((line) => line.length > 0)
             .map((line) => {
             try {
-                return RuntimeRunSchema.safeParse(JSON.parse(line));
+                return ExecutionStageLedgerSchema.safeParse(JSON.parse(line));
             }
             catch {
                 return { success: false };
@@ -116,7 +116,7 @@ export function readRuntimeRunHistory(verifiableContextPath) {
 // ---- Sort helpers --------------------------------------------------------
 /**
  * Sort items newest-first using `started_at` (with a `finished_at` fallback).
- * Used for build/test run lists where the canonical order is by activity
+ * Used for Build/benchmark run lists where the canonical order is by activity
  * window, not by record-creation time.
  */
 export function newestFirst(items) {