@interf/compiler 0.22.2 → 0.33.0

package/dist/packages/runtime/build/stage-evidence.js

@@ -0,0 +1,317 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { StageEvidenceSchema, } from "../../contracts/lib/schema.js";
+import { buildPlanPackagePathForContextGraph, contextGraphRuntimeLogsRoot, } from "./context-graph-paths.js";
+import { findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./context-graph-schema.js";
+import { StageEvidenceReconciliationSchema, } from "./lib/schema.js";
+import { loadBuildStageInputs } from "./source-manifest.js";
+import { loadExecutionStageLedger, updateExecutionStageLedger, } from "./runtime-runs.js";
+function normalizeRelativePath(path) {
+    return path.replaceAll("\\", "/").replace(/^\.?\//, "").replace(/\/+$/g, "");
+}
+function relativePathEqualsOrWithin(basePath, candidatePath) {
+    const base = normalizeRelativePath(basePath);
+    const candidate = normalizeRelativePath(candidatePath);
+    if (base.length === 0 || candidate.length === 0)
+        return false;
+    return candidate === base || candidate.startsWith(`${base}/`);
+}
+export function supportsStageEvidenceHarness(stage) {
+    return stage.contractType === "build-file-evidence";
+}
+export function shellStageEvidencePath(executionPath) {
+    return join(executionPath, "runtime", "stage-evidence.json");
+}
+export function shellStageHarnessPath(executionPath) {
+    return join(executionPath, "runtime", "stage.md");
+}
+export function writeStageHarnessProjection(options) {
+    if (!supportsStageEvidenceHarness({ contractType: options.contract.contract_type }))
+        return;
+    const runtimeRoot = join(options.executionPath, "runtime");
+    mkdirSync(runtimeRoot, { recursive: true });
+    const evidencePath = shellStageEvidencePath(options.executionPath);
+    if (!existsSync(evidencePath)) {
+        const starterEvidence = {
+            kind: "interf-stage-evidence",
+            version: 1,
+            run_id: options.contract.run_id,
+            stage: options.contract.stage,
+            counts: [],
+            items: [],
+            edges: [],
+        };
+        writeFileSync(evidencePath, `${JSON.stringify(starterEvidence, null, 2)}\n`);
+    }
+    writeFileSync(shellStageHarnessPath(options.executionPath), renderStageHarnessMarkdown(options.contract));
+}
+function renderStageHarnessMarkdown(contract) {
+    return [
+        "---",
+        "kind: interf-stage-harness",
+        "version: 1",
+        `run_id: ${contract.run_id}`,
+        `project_id: ${contract.target_name}`,
+        `build_plan: ${contract.build_plan.id}`,
+        `stage: ${contract.stage}`,
+        "contract_path: runtime/stage-contract.json",
+        "paths_path: runtime/paths.json",
+        "source_manifest_path: runtime/source-manifest.json",
+        "stage_inputs_path: runtime/stage-inputs.json",
+        "evidence_output_path: runtime/stage-evidence.json",
+        "---",
+        "",
+        "# Stage Harness",
+        "",
+        "Read the JSON contract first. This markdown file is a generated projection for the current stage only.",
+        "",
+        "## Evidence",
+        "",
+        "Write `runtime/stage-evidence.json` before you emit DONE.",
+        "Each evidence item must reference real assigned Source paths or declared output paths.",
+        "Agent status lines and self-reported completion do not count as accepted evidence.",
+        "",
+        "Minimum shape:",
+        "",
+        "```json",
+        JSON.stringify({
+            kind: "interf-stage-evidence",
+            version: 1,
+            run_id: contract.run_id,
+            stage: contract.stage,
+            counts: [
+                {
+                    key: "files_processed",
+                    label: "Files processed",
+                    value: 0,
+                    total: contract.counts.source_total ?? 0,
+                    unit: "files",
+                    source: "stage",
+                    stage_id: contract.stage,
+                    primary: true,
+                },
+            ],
+            items: [],
+            edges: [],
+        }, null, 2),
+        "```",
+        "",
+    ].join("\n");
+}
+export function reconcileStageEvidence(options) {
+    if (!supportsStageEvidenceHarness(options.stage))
+        return null;
+    const run = loadExecutionStageLedger(options.contextGraphPath);
+    if (!run)
+        return null;
+    const evidenceFilePath = shellStageEvidencePath(options.shellRoot);
+    const persistedEvidencePath = persistRawStageEvidence({
+        contextGraphPath: options.contextGraphPath,
+        evidenceFilePath,
+        run,
+    });
+    let parsed;
+    try {
+        parsed = StageEvidenceSchema.parse(JSON.parse(readFileSync(evidenceFilePath, "utf8")));
+    }
+    catch (error) {
+        const reconciliation = makeReconciliation({
+            evidencePath: persistedEvidencePath,
+            rejected: [{
+                    kind: "file",
+                    id: "stage-evidence-json",
+                    reason: `Invalid stage evidence JSON: ${error instanceof Error ? error.message : String(error)}`,
+                }],
+        });
+        updateExecutionStageLedger(options.contextGraphPath, {
+            evidence_path: persistedEvidencePath ?? undefined,
+            evidence: reconciliation,
+        });
+        return reconciliation;
+    }
+    const reconciliation = reconcileParsedStageEvidence({
+        contextGraphPath: options.contextGraphPath,
+        evidence: parsed,
+        evidencePath: persistedEvidencePath,
+        run,
+        stage: options.stage,
+    });
+    updateExecutionStageLedger(options.contextGraphPath, {
+        evidence_path: persistedEvidencePath ?? undefined,
+        evidence: reconciliation,
+    });
+    return reconciliation;
+}
+export function stageEvidenceAcceptanceFailure(reconciliation) {
+    if (!reconciliation) {
+        return "Stage evidence was not reconciled.";
+    }
+    if (reconciliation.rejected.length > 0) {
+        const first = reconciliation.rejected[0];
+        return `Stage evidence was rejected: ${first.id}: ${first.reason}`;
+    }
+    const acceptedItems = reconciliation.accepted.items;
+    if (acceptedItems.length === 0) {
+        return "Stage evidence needs at least one accepted source/output evidence item.";
+    }
+    const hasAcceptedRef = acceptedItems.some((item) => item.source_refs.length > 0 || item.output_refs.length > 0);
+    if (!hasAcceptedRef) {
+        return "Stage evidence items need accepted source or output refs.";
+    }
+    return null;
+}
+function persistRawStageEvidence(options) {
+    if (!existsSync(options.evidenceFilePath))
+        return null;
+    const targetPath = join(contextGraphRuntimeLogsRoot(options.contextGraphPath), `${options.run.run_id}.stage-evidence.json`);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    copyFileSync(options.evidenceFilePath, targetPath);
+    return relative(options.contextGraphPath, targetPath).replaceAll("\\", "/");
+}
+function reconcileParsedStageEvidence(options) {
+    const rejected = [];
+    if (options.evidence.run_id !== options.run.run_id) {
+        rejected.push({
+            kind: "file",
+            id: "run-id",
+            reason: `Evidence run_id "${options.evidence.run_id}" does not match active run "${options.run.run_id}".`,
+        });
+    }
+    if (options.evidence.stage !== options.stage.id || options.evidence.stage !== options.run.stage) {
+        rejected.push({
+            kind: "file",
+            id: "stage",
+            reason: `Evidence stage "${options.evidence.stage}" does not match active stage "${options.run.stage}".`,
+        });
+    }
+    if (rejected.length > 0) {
+        return makeReconciliation({ evidencePath: options.evidencePath, rejected });
+    }
+    const stageInputs = loadBuildStageInputs(options.contextGraphPath, options.stage.id);
+    const allowedSourcePaths = new Set((stageInputs?.inputs ?? []).map((input) => input.path));
+    const allowedSourceIds = new Set((stageInputs?.inputs ?? []).map((input) => input.source_file_id));
+    const acceptedItems = [];
+    for (const item of options.evidence.items) {
+        const reason = invalidItemReason({
+            contextGraphPath: options.contextGraphPath,
+            item,
+            allowedSourceIds,
+            allowedSourcePaths,
+            stage: options.stage,
+        });
+        if (reason) {
+            rejected.push({ kind: "item", id: item.id, reason });
+        }
+        else {
+            acceptedItems.push(item);
+        }
+    }
+    const acceptedSourceRefCount = new Set(acceptedItems.flatMap((item) => item.source_refs.map((ref) => ref.path))).size;
+    const acceptedCounts = [];
+    for (const count of options.evidence.counts) {
+        const reason = invalidCountReason({
+            count,
+            acceptedItems,
+            acceptedSourceRefCount,
+            stage: options.stage,
+        });
+        if (reason) {
+            rejected.push({ kind: "count", id: count.key, reason });
+        }
+        else {
+            acceptedCounts.push(count);
+        }
+    }
+    const acceptedItemIds = new Set(acceptedItems.map((item) => item.id));
+    const acceptedEdges = [];
+    for (const edge of options.evidence.edges) {
+        if (edge.stage_id !== options.stage.id) {
+            rejected.push({ kind: "edge", id: `${edge.from}:${edge.to}`, reason: "Edge stage does not match the active stage." });
+        }
+        else if (!acceptedItemIds.has(edge.from) || !acceptedItemIds.has(edge.to)) {
+            rejected.push({ kind: "edge", id: `${edge.from}:${edge.to}`, reason: "Edge endpoints must both be accepted evidence items." });
+        }
+        else {
+            acceptedEdges.push(edge);
+        }
+    }
+    return makeReconciliation({
+        evidencePath: options.evidencePath,
+        accepted: {
+            counts: acceptedCounts,
+            items: acceptedItems,
+            edges: acceptedEdges,
+        },
+        rejected,
+        warnings: options.evidence.warnings ?? [],
+    });
+}
+function invalidItemReason(options) {
+    if (options.item.stage_id !== options.stage.id)
+        return "Item stage does not match the active stage.";
+    if (options.item.source_refs.length === 0 && options.item.output_refs.length === 0) {
+        return "Evidence items need at least one source or output ref.";
+    }
+    for (const sourceRef of options.item.source_refs) {
+        if (!options.allowedSourcePaths.has(sourceRef.path)) {
+            return `Source ref "${sourceRef.path}" is not assigned to this stage.`;
+        }
+        if (sourceRef.source_file_id && !options.allowedSourceIds.has(sourceRef.source_file_id)) {
+            return `Source file id "${sourceRef.source_file_id}" is not assigned to this stage.`;
+        }
+    }
+    for (const outputRef of options.item.output_refs) {
+        const reason = invalidOutputRefReason(options.contextGraphPath, outputRef, options.stage);
+        if (reason)
+            return reason;
+    }
+    return null;
+}
+function invalidOutputRefReason(contextGraphPath, outputRef, stage) {
+    if (!stage.writes.includes(outputRef.artifact_id)) {
+        return `Output ref artifact "${outputRef.artifact_id}" is not declared as a stage write.`;
+    }
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
+    const artifact = schema ? findBuildPlanContextArtifact(schema, outputRef.artifact_id) : null;
+    if (!artifact)
+        return `Output ref artifact "${outputRef.artifact_id}" is not in the Build Plan schema.`;
+    if (!relativePathEqualsOrWithin(artifact.path, outputRef.path)) {
+        return `Output ref path "${outputRef.path}" is outside artifact "${artifact.id}".`;
+    }
+    if (!existsSync(join(contextGraphPath, outputRef.path))) {
+        return `Output ref path "${outputRef.path}" does not exist in the Context Graph.`;
+    }
+    return null;
+}
+function invalidCountReason(options) {
+    if (options.count.source === "engine")
+        return "Stage evidence cannot claim engine-owned counts.";
+    if (options.count.stage_id && options.count.stage_id !== options.stage.id) {
+        return "Count stage does not match the active stage.";
+    }
+    if (options.count.artifact_id && !options.stage.writes.includes(options.count.artifact_id)) {
+        return `Count artifact "${options.count.artifact_id}" is not declared as a stage write.`;
+    }
+    if (options.count.key === "files_processed" && options.count.value > options.acceptedSourceRefCount) {
+        return "files_processed cannot exceed accepted source refs.";
+    }
+    if (options.count.value > 0 && options.acceptedItems.length === 0) {
+        return "Positive stage counts need at least one accepted evidence item.";
+    }
+    return null;
+}
+function makeReconciliation(options) {
+    return StageEvidenceReconciliationSchema.parse({
+        kind: "interf-stage-evidence-reconciliation",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        evidence_path: options.evidencePath,
+        accepted: options.accepted ?? {
+            counts: [],
+            items: [],
+            edges: [],
+        },
+        rejected: options.rejected ?? [],
+        warnings: options.warnings ?? [],
+    });
+}

package/dist/packages/runtime/build/stage-reuse.d.ts

@@ -0,0 +1,11 @@
+import type { BuildStageExecutionDefinition } from "./build-target.js";
+export declare function computeStageFingerprint(contextGraphPath: string, stageDefinition: BuildStageExecutionDefinition): string | null;
+export interface StageReuseDecision {
+    reuse: boolean;
+    fingerprint: string | null;
+    summary: string;
+}
+export declare function stageReuseDecision(options: {
+    contextGraphPath: string;
+    stageDefinition: BuildStageExecutionDefinition;
+}): StageReuseDecision;

package/dist/packages/runtime/build/stage-reuse.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { buildPlanPackagePathForContextGraph, } from "./context-graph-paths.js";
+import { buildBuildStageExecutionPlan } from "./build-stage-plan.js";
+import { loadState } from "./state.js";
+import { loadBuildStageInputs, loadContextGraphSourceManifest } from "./source-manifest.js";
+import { validateBuildStage } from "./validate.js";
+import { StageFingerprintSchema } from "./lib/schema.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { readExecutionStageLedgerHistory } from "../runtime-persistence.js";
+import { stageEvidenceAcceptanceFailure, supportsStageEvidenceHarness, } from "./stage-evidence.js";
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableValue(entry)]));
+}
+function stableJson(value) {
+    return JSON.stringify(stableValue(value));
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function fileHash(path) {
+    if (!existsSync(path))
+        return null;
+    return sha256(readFileSync(path));
+}
+function latestStageRun(runs, runId, stageId) {
+    if (!runId)
+        return null;
+    return runs
+        .filter((run) => run.run_id === runId && run.stage === stageId)
+        .sort((left, right) => left.updated_at.localeCompare(right.updated_at))
+        .at(-1) ?? null;
+}
+function buildPlanPackageHash(contextGraphPath) {
+    const root = buildPlanPackagePathForContextGraph(contextGraphPath);
+    const files = listFilesRecursive(root)
+        .map((path) => ({
+        path,
+        relativePath: relative(root, path).replaceAll("\\", "/"),
+    }))
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    return sha256(stableJson(files.map((file) => ({
+        path: file.relativePath,
+        hash: fileHash(file.path),
+    }))));
+}
+export function computeStageFingerprint(contextGraphPath, stageDefinition) {
+    const stageInputs = loadBuildStageInputs(contextGraphPath, stageDefinition.id);
+    if (!stageInputs)
+        return null;
+    if (stageInputs.version !== 3 || !stageInputs.source_manifest_id)
+        return null;
+    const sourceManifest = loadContextGraphSourceManifest(contextGraphPath);
+    if (!sourceManifest || sourceManifest.manifest_id !== stageInputs.source_manifest_id)
+        return null;
+    const plan = buildBuildStageExecutionPlan(contextGraphPath, stageDefinition);
+    const stageSkillPath = join(buildPlanPackagePathForContextGraph(contextGraphPath), "build", "stages", stageDefinition.skillDir, "SKILL.md");
+    const payload = {
+        build_plan: {
+            id: plan.context.buildPlanId,
+            package_hash: buildPlanPackageHash(contextGraphPath),
+        },
+        source_manifest: {
+            manifest_id: sourceManifest.manifest_id,
+            generated_at: sourceManifest.generated_at,
+            source_total: sourceManifest.source_total,
+        },
+        source_slice: stageInputs.inputs
+            .map((input) => ({
+            source_file_id: input.source_file_id,
+            path: input.path,
+            locator: input.locator,
+            kind: input.kind,
+            size_bytes: input.size_bytes,
+            page_count: input.page_count,
+            inspectable_units: input.inspectable_units,
+            content_hash: input.content_hash,
+        }))
+            .sort((left, right) => `${left.source_file_id}:${left.path}`.localeCompare(`${right.source_file_id}:${right.path}`)),
+        stage: {
+            id: stageDefinition.id,
+            skill_dir: stageDefinition.skillDir,
+            skill_hash: fileHash(stageSkillPath),
+        },
+        contract: {
+            stage: stageDefinition.id,
+            contract_type: stageDefinition.contractType,
+            counts: plan.contract.counts,
+            artifacts: {
+                reads: [...plan.contract.artifacts.reads].sort((left, right) => left.localeCompare(right)),
+                writes: [...plan.contract.artifacts.writes].sort((left, right) => left.localeCompare(right)),
+                write_contracts: [...plan.contract.artifacts.write_contracts]
+                    .map((contract) => ({
+                    artifact_id: contract.artifact_id,
+                    path: contract.path,
+                    checks: contract.checks,
+                }))
+                    .sort((left, right) => `${left.artifact_id}:${left.path}`.localeCompare(`${right.artifact_id}:${right.path}`)),
+            },
+        },
+    };
+    return StageFingerprintSchema.parse(sha256(stableJson(payload)));
+}
+export function stageReuseDecision(options) {
+    const fingerprint = computeStageFingerprint(options.contextGraphPath, options.stageDefinition);
+    if (!fingerprint) {
+        return { reuse: false, fingerprint, summary: "missing stage fingerprint input" };
+    }
+    const state = loadState(options.contextGraphPath);
+    const record = state?.stages?.[options.stageDefinition.id];
+    if (!record || record.status !== "succeeded") {
+        return { reuse: false, fingerprint, summary: "stage has not succeeded yet" };
+    }
+    if (record.fingerprint !== fingerprint) {
+        return { reuse: false, fingerprint, summary: "stage fingerprint changed" };
+    }
+    if (supportsStageEvidenceHarness(options.stageDefinition)) {
+        const acceptedEvidenceRun = latestStageRun(readExecutionStageLedgerHistory(options.contextGraphPath), record.run_id, options.stageDefinition.id);
+        if (acceptedEvidenceRun?.status !== "succeeded") {
+            return { reuse: false, fingerprint, summary: "stage evidence run has not succeeded" };
+        }
+        const evidenceFailure = stageEvidenceAcceptanceFailure(acceptedEvidenceRun?.evidence ?? null);
+        if (evidenceFailure) {
+            return { reuse: false, fingerprint, summary: evidenceFailure };
+        }
+    }
+    const validation = validateBuildStage(options.contextGraphPath, options.stageDefinition.id);
+    if (!validation.required) {
+        return { reuse: false, fingerprint, summary: "stage is not required yet" };
+    }
+    if (!validation.ok) {
+        return { reuse: false, fingerprint, summary: validation.summary };
+    }
+    return { reuse: true, fingerprint, summary: "reused (verified, unchanged)" };
+}

package/dist/packages/runtime/build/state-artifacts.d.ts

@@ -0,0 +1,9 @@
+import { type ContextGraphHealth, type ContextGraphViewSpec, type SourceFiles, type SourceState } from "./lib/schema.js";
+export declare function refreshContextGraphArtifacts(dirPath: string, options?: {
+    ensureViewSpec?: boolean;
+}): {
+    health: ContextGraphHealth;
+    viewSpec?: ContextGraphViewSpec;
+    sourceFiles: SourceFiles;
+    sourceState: SourceState;
+};

package/dist/packages/runtime/build/state-artifacts.js

@@ -0,0 +1,14 @@
+import { saveContextGraphHealth, } from "./state-io.js";
+import { computeContextGraphHealth, } from "./state-health.js";
+import { ensureContextGraphSourceFiles, ensureContextGraphSourceState, ensureContextGraphViewSpec, } from "./state-view.js";
+export function refreshContextGraphArtifacts(dirPath, options) {
+    const health = computeContextGraphHealth(dirPath);
+    saveContextGraphHealth(dirPath, health);
+    const sourceFiles = ensureContextGraphSourceFiles(dirPath);
+    const sourceState = ensureContextGraphSourceState(dirPath, sourceFiles);
+    let viewSpec;
+    if (options?.ensureViewSpec) {
+        viewSpec = ensureContextGraphViewSpec(dirPath);
+    }
+    return { health, viewSpec, sourceFiles, sourceState };
+}

package/dist/packages/runtime/build/state-health.d.ts

@@ -0,0 +1,4 @@
+import { type ContextGraphHealth, type BuildStage, type RuntimeStatus } from "./lib/schema.js";
+export declare function computeContextGraphHealth(dirPath: string): ContextGraphHealth;
+export declare function resolveContextGraphStatus(..._args: unknown[]): RuntimeStatus;
+export declare function resolveBuildStage(...args: unknown[]): BuildStage;

package/dist/packages/{engine → runtime}/build/state-health.js

@@ -1,22 +1,21 @@
 import { basename } from "node:path";
-import { readInterfConfig, resolveSourceFolderPath, } from "../../project/interf-detect.js";
-import { discoverSourceFiles } from "./discovery.js";
-import { loadRuntimeRun } from "./runtime.js";
+import { readInterfConfig, } from "../../projects/interf-detect.js";
+import { loadExecutionStageLedger } from "./runtime.js";
 import { loadState } from "./state-io.js";
-import { validateVerifiableContextSetup, validateBuildStage, validateVerifiableContext, } from "./validate.js";
-import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./verifiable-context-schema.js";
-import { buildPlanPackagePathForVerifiableContext } from "./verifiable-context-paths.js";
+import { loadContextGraphSourceManifest } from "./source-manifest.js";
+import { validateContextGraph, } from "./validate.js";
+import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./context-graph-schema.js";
+import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
 import { getActiveBuildPlan, resolveRequiredBuildPlanFromConfig } from "../../build-plans/package/build-plan-definitions.js";
 import { countBuildArtifactsAtPath } from "./artifact-counts.js";
-export function computeVerifiableContextHealth(dirPath) {
+export function computeContextGraphHealth(dirPath) {
     const now = new Date().toISOString();
     const config = readInterfConfig(dirPath);
     const targetName = config?.name ?? basename(dirPath);
-    const sourcePath = config ? resolveSourceFolderPath(dirPath, config) : dirPath;
-    const sourceTotal = config ? discoverSourceFiles(sourcePath, dirPath).totalCount : 0;
+    const sourceTotal = loadContextGraphSourceManifest(dirPath)?.source_total ?? 0;
     const state = loadState(dirPath);
-    const validation = validateVerifiableContextSetup(dirPath);
-    const activeRun = loadRuntimeRun(dirPath);
+    const buildPlanValidation = validateContextGraph(dirPath);
+    const activeRun = loadExecutionStageLedger(dirPath);
     const buildPlanId = config
         ? resolveRequiredBuildPlanFromConfig(config, `.interf/interf.json for ${dirPath}`)
         : null;
@@ -29,14 +28,10 @@ export function computeVerifiableContextHealth(dirPath) {
             buildPlan = null;
         }
     }
-    const stageResults = buildPlan?.stages.map((stage) => ({
-        stage,
-        validation: validateBuildStage(dirPath, stage.id),
-    })) ?? [];
-    const completedStages = stageResults.filter((entry) => entry.validation.ok).length;
-    const firstFailed = stageResults.find((entry) => !entry.validation.ok) ?? null;
-    const buildPlanValidation = validateVerifiableContext(dirPath);
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(dirPath));
+    const completedStages = buildPlanValidation.counts.completed_stages ?? 0;
+    const firstFailedStage = Object.entries(buildPlanValidation.stage_results)
+        .find(([, ok]) => !ok)?.[0] ?? null;
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(dirPath));
     const artifactMetrics = Object.fromEntries((schema ? listBuildPlanContextArtifacts(schema) : []).map((artifact) => [
         `artifact_${artifact.id}`,
         countBuildArtifactsAtPath(dirPath, artifact.path, artifact.kind),
@@ -45,7 +40,7 @@ export function computeVerifiableContextHealth(dirPath) {
     let stage = "idle";
     let summary = "Idle — no source files have been built yet.";
     const errors = buildPlanValidation.errors.length;
-    if (!validation.config_present || !validation.config_valid || !validation.config_type_match || !validation.build_plan_valid || !validation.schema_valid) {
+    if (!buildPlanValidation.checks.config_present || !buildPlanValidation.checks.config_valid || !buildPlanValidation.checks.config_type_match || !buildPlanValidation.checks.build_plan_valid || !buildPlanValidation.checks.schema_valid) {
         status = "failed";
         stage = "failed";
         summary = buildPlanValidation.summary;
@@ -72,20 +67,20 @@ export function computeVerifiableContextHealth(dirPath) {
     }
     else {
         status = "stale";
-        stage = firstFailed?.stage.id ?? "built";
-        summary = firstFailed?.validation.summary ?? buildPlanValidation.summary;
+        stage = firstFailedStage ?? buildPlanValidation.stage;
+        summary = buildPlanValidation.summary;
     }
     const checks = {
-        ...validation,
+        ...buildPlanValidation.checks,
         ...(buildPlan
             ? Object.fromEntries(buildPlan.stages.map((buildPlanStage) => [
                 `stage_${buildPlanStage.id}_ok`,
-                stageResults.find((entry) => entry.stage.id === buildPlanStage.id)?.validation.ok ?? false,
+                buildPlanValidation.stage_results[buildPlanStage.id] ?? false,
             ]))
             : {}),
     };
     return {
-        kind: "verifiable-context-health",
+        kind: "context-graph-health",
         version: 2,
         generated_at: now,
         target_name: targetName,
@@ -103,7 +98,7 @@ export function computeVerifiableContextHealth(dirPath) {
         checks,
     };
 }
-export function resolveVerifiableContextStatus(..._args) {
+export function resolveContextGraphStatus(..._args) {
     const state = _args[_args.length - 1];
     if (state?.error_count && state.error_count > 0)
         return "failed";

package/dist/packages/runtime/build/state-io.d.ts

@@ -0,0 +1,12 @@
+import { type ContextGraphHealth, type ContextGraphState, type ContextGraphViewSpec, type SourceFiles, type SourceManifest, type SourceState } from "./lib/schema.js";
+export declare function loadState<T>(dirPath: string): T | null;
+export declare function saveState<T>(dirPath: string, state: T): void;
+export declare function loadContextGraphHealth(dirPath: string): ContextGraphHealth | null;
+export declare function saveContextGraphHealth(dirPath: string, health: ContextGraphHealth): void;
+export declare function loadContextGraphViewSpec(dirPath: string): ContextGraphViewSpec | null;
+export declare function saveContextGraphViewSpec(dirPath: string, viewSpec: ContextGraphViewSpec): void;
+export declare function loadContextGraphSourceManifest(dirPath: string): SourceManifest | null;
+export declare function loadContextGraphSourceFiles(dirPath: string): SourceFiles | null;
+export declare function loadContextGraphSourceState(dirPath: string): SourceState | null;
+export declare function saveEmptyExecutionInventory(dirPath: string): void;
+export declare function initContextGraphState(): ContextGraphState;