@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/runtime-project-mutations.d.ts

@@ -0,0 +1,7 @@
+import { type ResetResult } from "./schemas/index.js";
+import type { ProjectConfig } from "../projects/lib/schema.js";
+import type { LocalServiceRuntime } from "./runtime.js";
+export declare function applyReset(runtime: LocalServiceRuntime, projectDataDir: string, requestValue: unknown): ResetResult;
+export declare function resolveProjectConfig(projectDataDir: string, projectName: string, overrides?: Partial<Pick<ProjectConfig, "build_plan">>): ProjectConfig;
+export declare function ensureContextGraphForRun(projectDataDir: string, projectConfig: ProjectConfig, runId: string): string;
+export declare function defaultProjectId(projectDataDir: string): string;

package/dist/packages/runtime/runtime-project-mutations.js

@@ -0,0 +1,65 @@
+import { existsSync } from "node:fs";
+import { asProjectDataDir, projectContextGraphPath, projectRunContextGraphPath, } from "../contracts/lib/project-paths.js";
+import { buildPlanIdForProjectConfig, findProjectConfig, listProjectConfigs, loadSourceFolderConfig, syncContextGraphInterfConfigFromProjectConfig, } from "../projects/source-config.js";
+import { ensureContextGraphScaffoldAt, } from "./context-graph-scaffold.js";
+import { resetBuildGeneratedState, } from "./build/reset.js";
+import { ResetRequestSchema, ResetResultSchema, } from "./schemas/index.js";
+import { requireSelectedBuildPlan } from "./runtime-proposal-helpers.js";
+export function applyReset(runtime, projectDataDir, requestValue) {
+    const request = ResetRequestSchema.parse(requestValue);
+    const project = findProjectConfig(loadSourceFolderConfig(projectDataDir), request.project);
+    if (!project) {
+        throw new Error(`Project "${request.project}" is not saved.`);
+    }
+    const projectData = asProjectDataDir(projectDataDir);
+    const contextGraphPath = project.latest_context_graph_run_id
+        ? projectRunContextGraphPath(projectData, project.latest_context_graph_run_id)
+        : projectContextGraphPath(projectData, request.project);
+    if (!existsSync(contextGraphPath)) {
+        throw new Error(`Context Graph for Project "${request.project}" does not exist.`);
+    }
+    resetBuildGeneratedState(contextGraphPath, request.scope);
+    // Reset wipes generated state, including saved Build/benchmark/readiness records.
+    runtime.buildRunCache.invalidateProject(projectDataDir, request.project);
+    runtime.verifyRunCache.invalidateProject(projectDataDir, request.project);
+    runtime.readinessCache.invalidateProject(projectDataDir, request.project);
+    runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
+    return ResetResultSchema.parse({
+        kind: "interf-reset-result",
+        version: 1,
+        project: request.project,
+        scope: request.scope,
+        context_graph_path: contextGraphPath,
+        changed: true,
+        message: `Reset ${request.scope} state for Project ${request.project}.`,
+    });
+}
+export function resolveProjectConfig(projectDataDir, projectName, overrides = {}) {
+    const project = findProjectConfig(loadSourceFolderConfig(projectDataDir), projectName);
+    if (!project) {
+        throw new Error(`Project "${projectName}" is not saved in this control plane folder.`);
+    }
+    const buildPlan = overrides.build_plan ?? buildPlanIdForProjectConfig(project) ?? undefined;
+    return {
+        ...project,
+        ...(buildPlan ? { build_plan: buildPlan } : {}),
+    };
+}
+export function ensureContextGraphForRun(projectDataDir, projectConfig, runId) {
+    const buildPlanId = requireSelectedBuildPlan(projectConfig);
+    const contextGraphPath = ensureContextGraphScaffoldAt({
+        projectDataDir,
+        contextGraphPath: projectRunContextGraphPath(asProjectDataDir(projectDataDir), runId),
+        projectName: projectConfig.name,
+        buildPlanId,
+    });
+    syncContextGraphInterfConfigFromProjectConfig(contextGraphPath, projectConfig);
+    return contextGraphPath;
+}
+export function defaultProjectId(projectDataDir) {
+    const project = listProjectConfigs(loadSourceFolderConfig(projectDataDir))[0];
+    if (!project) {
+        throw new Error("No Project is saved in this control plane folder.");
+    }
+    return project.name;
+}

package/dist/packages/runtime/runtime-project-reads.d.ts

@@ -0,0 +1,18 @@
+import { type Readiness } from "../contracts/lib/schema.js";
+import { type ContextGraphHandoff } from "../contracts/lib/project-schema.js";
+import { type ProjectResource, type SourceFileResource, type ContextGraphResource, type StageExecutionSession } from "./schemas/index.js";
+import type { ProjectConfig } from "../projects/lib/schema.js";
+import type { LocalServiceRuntime } from "./runtime.js";
+export declare function listProjects(runtime: LocalServiceRuntime, projectDataDir: string): ProjectResource[];
+export declare function getProject(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): ProjectResource | null;
+export declare function listProjectReadiness(runtime: LocalServiceRuntime, projectDataDir: string): Readiness[];
+export declare function getProjectReadiness(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): Readiness | null;
+export declare function listReadiness(runtime: LocalServiceRuntime, projectDataDir: string): Readiness[];
+export declare function getReadiness(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): Readiness | null;
+export declare function computeProjectReadiness(runtime: LocalServiceRuntime, projectDataDir: string, project: ProjectConfig): Readiness;
+export declare function listSourceFiles(runtime: LocalServiceRuntime, projectDataDir: string, projectName?: string | null): SourceFileResource[];
+export declare function listContextGraphs(runtime: LocalServiceRuntime, projectDataDir: string, projectName?: string | null): ContextGraphResource[];
+export declare function getContextGraph(runtime: LocalServiceRuntime, projectDataDir: string, graphId: string): ContextGraphResource | null;
+export declare function getLatestContextGraph(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): ContextGraphResource | null;
+export declare function listLatestContextGraphStageSessions(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): StageExecutionSession[];
+export declare function getContextGraphHandoff(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): ContextGraphHandoff | null;

package/dist/packages/runtime/runtime-project-reads.js

@@ -0,0 +1,574 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { asProjectDataDir, projectConfigPath, projectRunContextGraphPath, } from "../contracts/lib/project-paths.js";
+import { layerForPath } from "../contracts/lib/context-graph-layer.js";
+import { buildPlanIdForProjectConfig, buildTestSpecFromSourceFolderConfig, fingerprintSavedBenchmarkSpec, findProjectConfig, listProjectConfigs, loadSourceFolderConfig, resolveProjectSourceBindingPath, } from "../projects/source-config.js";
+import { isInterfRelativePath, ReadinessSchema, } from "../contracts/lib/schema.js";
+import { ContextGraphHandoffSchema, } from "../contracts/lib/project-schema.js";
+import { readInterfConfig, } from "../projects/interf.js";
+import { loadContextGraphSourceManifest, } from "./build/source-manifest.js";
+import { loadGraphManifest, } from "./build/stage-manifest.js";
+import { contextGraphRuntimeGraphManifestPath, } from "./build/context-graph-paths.js";
+import { listStageExecutionSessions, } from "./build/stage-session.js";
+import { buildProjectResource, readinessSummaryForStatus, readinessTargetResult, } from "./runtime-resource-builders.js";
+import { aggregateArtifactVerdict, } from "./build/artifact-status.js";
+import { buildBuildEvidence, } from "./build/build-evidence.js";
+import { buildContextGraphSemanticGraph, } from "./context-graph-semantic-graph.js";
+import { validateContextGraph } from "./build/validate.js";
+import { SourceFileResourceSchema, ContextGraphResourceSchema, StageExecutionSessionSchema, } from "./schemas/index.js";
+import { uniqueArtifacts } from "./run-observability.js";
+import { listBuildRunsForProject, } from "./runtime-build-runs.js";
+import { readExecutionStageLedgerHistory } from "./runtime-persistence.js";
+import { getBuildPlan } from "../build-plans/package/build-plan-definitions.js";
+import { listContextInterfaceArtifacts } from "../build-plans/package/context-interface.js";
+import { latestTopLevelVerifyRun, listVerifyRunsForProject, readLatestBenchmarkRun, } from "./runtime-verify-runs.js";
+export function listProjects(runtime, projectDataDir) {
+    const config = loadSourceFolderConfig(projectDataDir);
+    // Per-project config file mtime is a migration-free "last touched" signal —
+    // each Project owns its `~/.interf/projects/<id>/interf.json`. Clients sort
+    // the Projects list newest-first by this so a just-created Project lands on
+    // top instead of buried alphabetically.
+    const configPath = projectConfigPath(asProjectDataDir(projectDataDir));
+    let updatedAt = null;
+    try {
+        updatedAt = statSync(configPath).mtime.toISOString();
+    }
+    catch {
+        updatedAt = null;
+    }
+    return listProjectConfigs(config).map((project) => {
+        const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
+        const verifyRuns = listVerifyRunsForProject(runtime, projectDataDir, project.name);
+        const latestVerifyRun = latestTopLevelVerifyRun(verifyRuns);
+        const contextGraphRun = latestContextGraphBuildRun(project, buildRuns);
+        const readiness = computeProjectReadiness(runtime, projectDataDir, project);
+        return buildProjectResource(project, readiness, {
+            latestBuildRunId: buildRuns[0]?.run_id ?? null,
+            latestContextGraphBuildRunId: contextGraphRun?.run_id ?? null,
+            latestTestRunId: latestVerifyRun?.run_id ?? null,
+        }, resolveProjectSourceBindingPath(projectDataDir, project, config), configPath, 
+        // Surface per-Artifact status from the latest Build run so the UI can
+        // render Artifact rows on the Project page without a separate fetch.
+        contextGraphRun?.artifacts ?? [], updatedAt);
+    });
+}
+export function getProject(runtime, projectDataDir, projectName) {
+    return listProjects(runtime, projectDataDir).find((project) => project.name === projectName) ?? null;
+}
+export function listProjectReadiness(runtime, projectDataDir) {
+    return listReadiness(runtime, projectDataDir);
+}
+export function getProjectReadiness(runtime, projectDataDir, projectName) {
+    return getReadiness(runtime, projectDataDir, projectName);
+}
+export function listReadiness(runtime, projectDataDir) {
+    const config = loadSourceFolderConfig(projectDataDir);
+    return listProjectConfigs(config).map((project) => computeProjectReadiness(runtime, projectDataDir, project));
+}
+export function getReadiness(runtime, projectDataDir, projectName) {
+    const project = findProjectConfig(loadSourceFolderConfig(projectDataDir), projectName);
+    return project ? computeProjectReadiness(runtime, projectDataDir, project) : null;
+}
+export function computeProjectReadiness(runtime, projectDataDir, project) {
+    return runtime.readinessCache.get(projectDataDir, project.name, () => computeProjectReadinessUncached(runtime, projectDataDir, project));
+}
+function latestContextGraphBuildRun(project, buildRuns) {
+    const selected = project.latest_context_graph_run_id
+        ? buildRuns.find((run) => run.run_id === project.latest_context_graph_run_id && run.status === "succeeded") ?? null
+        : null;
+    return selected ?? buildRuns.find((run) => run.status === "succeeded") ?? null;
+}
+function contextGraphPathForBuildRun(projectDataDir, buildRun) {
+    if (!buildRun)
+        return null;
+    if (existsSync(buildRun.context_graph_path))
+        return buildRun.context_graph_path;
+    const projectOwnedPath = projectRunContextGraphPath(asProjectDataDir(projectDataDir), buildRun.run_id);
+    if (existsSync(projectOwnedPath))
+        return projectOwnedPath;
+    return buildRun.context_graph_path;
+}
+function computeProjectReadinessUncached(runtime, projectDataDir, project) {
+    const generatedAt = new Date().toISOString();
+    const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
+    const buildRun = buildRuns[0] ?? null;
+    const contextGraphRun = latestContextGraphBuildRun(project, buildRuns);
+    const contextGraphPath = contextGraphPathForBuildRun(projectDataDir, contextGraphRun);
+    const contextExists = Boolean(contextGraphPath && existsSync(contextGraphPath));
+    const contextGraphValidation = contextGraphPath && contextExists
+        ? validateContextGraph(contextGraphPath)
+        : null;
+    const graphManifest = contextGraphPath && contextExists ? loadGraphManifest(contextGraphPath) : null;
+    const contextReady = Boolean(contextGraphRun && contextGraphValidation?.ok);
+    const verifyRun = latestTopLevelVerifyRun(listVerifyRunsForProject(runtime, projectDataDir, project.name));
+    const benchmarkRun = readLatestBenchmarkRun(projectDataDir, project.name);
+    const artifactStatuses = contextGraphRun?.artifacts ?? [];
+    const hasArtifactContract = artifactStatuses.length > 0;
+    const artifactVerdict = aggregateArtifactVerdict(artifactStatuses);
+    const artifactFailures = artifactStatuses.filter((artifact) => artifact.status !== "ready");
+    const artifactCheckResults = artifactStatuses.flatMap((artifact) => artifact.check_results ?? []);
+    const requiredArtifactCheckResults = artifactCheckResults.filter((result) => result.required !== false);
+    const passedArtifactCheckResults = requiredArtifactCheckResults.filter((result) => result.passed);
+    const requiredContextChecks = (contextGraphRun?.context_checks ?? []).filter((check) => check.required !== false);
+    const failedContextChecks = requiredContextChecks.filter((check) => check.status !== "passed");
+    const contextChecksPassed = requiredContextChecks.length === 0 || failedContextChecks.length === 0;
+    const savedBenchmarkSpec = buildTestSpecFromSourceFolderConfig({
+        projectDataDir,
+        targetName: project.name,
+        targetType: "context-graph",
+    });
+    const configuredChecks = savedBenchmarkSpec?.cases.length ?? 0;
+    const currentFingerprint = savedBenchmarkSpec
+        ? fingerprintSavedBenchmarkSpec({
+            projectDataDir,
+            projectName: project.name,
+            targetType: "context-graph",
+        })
+        : null;
+    const benchmarkRunFingerprint = benchmarkRun?.checks_fingerprint ?? null;
+    const sourceResult = readinessTargetResult(benchmarkRun?.source_files, currentFingerprint, benchmarkRunFingerprint);
+    const contextResult = readinessTargetResult(benchmarkRun?.context_graph, currentFingerprint, benchmarkRunFingerprint);
+    const checksStale = Boolean(currentFingerprint && benchmarkRunFingerprint && currentFingerprint !== benchmarkRunFingerprint);
+    const buildCheck = (() => {
+        if (!buildRun) {
+            return {
+                gate: "build-run",
+                ok: false,
+                status: "not-built",
+                summary: "Context Graph has not been built yet.",
+                artifact_path: contextReady ? contextGraphPath : null,
+            };
+        }
+        if (buildRun.status === "succeeded") {
+            return {
+                gate: "build-run",
+                ok: contextReady,
+                status: contextReady ? "built" : "failed",
+                summary: contextReady
+                    ? "Latest Build produced the Context Graph."
+                    : "Latest Build finished but did not produce a Context Graph.",
+                run_id: buildRun.run_id,
+                artifact_path: contextReady ? contextGraphPath : null,
+            };
+        }
+        if (buildRun.status === "queued" || buildRun.status === "running") {
+            return {
+                gate: "build-run",
+                ok: false,
+                status: "building",
+                summary: "Build is in progress.",
+                run_id: buildRun.run_id,
+                artifact_path: contextExists ? contextGraphPath : null,
+            };
+        }
+        return {
+            gate: "build-run",
+            ok: false,
+            status: "failed",
+            summary: buildRun.status === "cancelled"
+                ? "Latest Build was cancelled."
+                : "Latest Build failed.",
+            run_id: buildRun.run_id,
+            artifact_path: contextReady ? contextGraphPath : null,
+        };
+    })();
+    if (graphManifest && buildRun?.status === "succeeded" && contextReady) {
+        const status = graphManifest.readiness.ready ? "ready" : "not-ready";
+        return ReadinessSchema.parse({
+            kind: "interf-readiness-state",
+            version: 1,
+            generated_at: generatedAt,
+            project: project.name,
+            status,
+            ready: graphManifest.readiness.ready,
+            summary: graphManifest.readiness.summary,
+            context_graph_path: contextGraphPath,
+            latest_build_run_id: buildRun.run_id,
+            latest_benchmark_run_id: verifyRun?.run_id ?? null,
+            build: buildCheck,
+            check_results: {
+                configured: configuredChecks,
+                fingerprint: currentFingerprint,
+                source_files: sourceResult,
+                context_graph: contextResult,
+            },
+            checks: [
+                {
+                    gate: "context-graph",
+                    ok: graphManifest.readiness.ready,
+                    status,
+                    summary: graphManifest.readiness.summary,
+                    artifact_path: contextGraphPath,
+                },
+                buildCheck,
+            ],
+        });
+    }
+    // COMPAT fallback — reached only when no GraphManifest exists yet
+    // (pre-refactor build or build still running). The primary readiness path
+    // is the early return above that reads graphManifest.readiness directly.
+    // Keep these legacy gates so old UIs that consume readiness.checks don't
+    // crash; do not add new gates here. Removal path: once every active Build
+    // produces a GraphManifest, the early return covers all cases and this
+    // fallback can be replaced with a single "not yet built" check.
+    const checks = [
+        {
+            gate: "context-graph",
+            ok: contextReady,
+            status: contextReady ? "built" : "not-built",
+            summary: contextReady
+                ? "Context Graph is built."
+                : "Context Graph has not been built yet.",
+            artifact_path: contextReady ? contextGraphPath : null,
+        },
+        buildCheck,
+        {
+            gate: "artifact-diagnostics",
+            ok: !hasArtifactContract || artifactVerdict === "ready",
+            status: !hasArtifactContract
+                ? "not-configured"
+                : artifactVerdict === "ready" ? "ready" : "not-ready",
+            summary: !hasArtifactContract
+                ? "No outputs declared by the selected Build Plan."
+                : artifactVerdict === "ready"
+                    ? `${artifactStatuses.length} Artifact${artifactStatuses.length === 1 ? "" : "s"} ready; ${passedArtifactCheckResults.length}/${requiredArtifactCheckResults.length} required diagnostic${requiredArtifactCheckResults.length === 1 ? "" : "s"} passed.`
+                    : `${artifactFailures.length} Artifact${artifactFailures.length === 1 ? "" : "s"} not ready.`,
+        },
+        {
+            gate: "context-checks",
+            ok: contextChecksPassed,
+            status: requiredContextChecks.length === 0
+                ? "not-configured"
+                : contextChecksPassed ? "ready" : "not-ready",
+            summary: requiredContextChecks.length === 0
+                ? "No GraphManifest coverage rollup exists for this Build."
+                : contextChecksPassed
+                    ? `${requiredContextChecks.length} legacy readiness check${requiredContextChecks.length === 1 ? "" : "s"} passed.`
+                    : `${failedContextChecks.length} legacy readiness check${failedContextChecks.length === 1 ? "" : "s"} not passed.`,
+        },
+        {
+            gate: "benchmarks",
+            ok: true,
+            status: configuredChecks > 0 ? "built" : "not-configured",
+            summary: configuredChecks > 0
+                ? `${configuredChecks} benchmark check${configuredChecks === 1 ? "" : "s"} configured.`
+                : "No benchmark checks configured yet.",
+        },
+        {
+            gate: "benchmarks-current",
+            ok: !checksStale,
+            status: checksStale ? "stale" : "built",
+            summary: checksStale
+                ? "Latest benchmark result is stale — your checks have changed since."
+                : "Latest benchmark result matches the saved checks.",
+        },
+    ];
+    const status = (() => {
+        if (buildRun?.status === "queued" || buildRun?.status === "running")
+            return "building";
+        if (verifyRun?.status === "queued" || verifyRun?.status === "running")
+            return "checking";
+        if (buildRun?.status === "failed" || buildRun?.status === "cancelled")
+            return "failed";
+        if (!buildRun || !contextReady)
+            return "not-built";
+        if (hasArtifactContract && artifactVerdict !== "ready")
+            return "not-ready";
+        if (!contextChecksPassed)
+            return "not-ready";
+        if (checksStale)
+            return "stale";
+        if (configuredChecks === 0)
+            return hasArtifactContract ? "ready" : "built";
+        if (!contextResult)
+            return "built";
+        return contextResult.total > 0 && contextResult.passed === contextResult.total ? "ready" : "not-ready";
+    })();
+    const ready = status === "ready";
+    return ReadinessSchema.parse({
+        kind: "interf-readiness-state",
+        version: 1,
+        generated_at: generatedAt,
+        project: project.name,
+        status,
+        ready,
+        summary: readinessSummaryForStatus(status),
+        context_graph_path: contextReady ? contextGraphPath : null,
+        latest_build_run_id: buildRun?.run_id ?? null,
+        latest_benchmark_run_id: verifyRun?.run_id ?? null,
+        build: buildCheck,
+        check_results: {
+            configured: configuredChecks,
+            fingerprint: currentFingerprint,
+            source_files: sourceResult,
+            context_graph: contextResult,
+        },
+        checks,
+    });
+}
+/**
+ * Real on-disk size + mtime for a source file, read live from the source
+ * folder. The build manifest only sometimes carries `size_bytes` (older
+ * builds omit it) and never carries an mtime, so reads that trusted the
+ * manifest showed "0 B / -" for files that are really tens of KB to MBs.
+ * Returns null when the file moved or the locator isn't a local path.
+ */
+function statSourceFile(sourceLocator, relativePath) {
+    try {
+        const absolute = join(sourceLocator, relativePath);
+        if (!existsSync(absolute))
+            return null;
+        const info = statSync(absolute);
+        return info.isFile() ? { size: info.size, mtime: info.mtime } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function listSourceFiles(runtime, projectDataDir, projectName) {
+    const config = loadSourceFolderConfig(projectDataDir);
+    const projects = listProjectConfigs(config)
+        .filter((project) => !projectName || project.name === projectName);
+    return projects.flatMap((project) => {
+        const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
+        const latestRun = latestContextGraphBuildRun(project, buildRuns);
+        const contextGraphPath = contextGraphPathForBuildRun(projectDataDir, latestRun);
+        const manifest = contextGraphPath ? loadContextGraphSourceManifest(contextGraphPath) : null;
+        if (!manifest)
+            return [];
+        return manifest.files.map((file) => {
+            const stat = statSourceFile(manifest.source.locator, file.path);
+            return SourceFileResourceSchema.parse({
+                project: project.name,
+                source_manifest_id: manifest.manifest_id,
+                source_file_id: file.id,
+                path: file.path,
+                locator: file.locator,
+                kind: file.kind,
+                absolute_path: file.locator,
+                size_bytes: stat?.size ?? file.size_bytes ?? 0,
+                modified_at: stat ? stat.mtime.toISOString() : null,
+                source_folder_path: manifest.source.locator,
+            });
+        });
+    });
+}
+export function listContextGraphs(runtime, projectDataDir, projectName) {
+    return listProjectConfigs(loadSourceFolderConfig(projectDataDir))
+        .filter((project) => !projectName || project.name === projectName)
+        .flatMap((project) => listProjectContextGraphs(runtime, projectDataDir, project))
+        .filter((graph) => graph !== null);
+}
+export function getContextGraph(runtime, projectDataDir, graphId) {
+    return listContextGraphs(runtime, projectDataDir)
+        .find((graph) => graph.graph_id === graphId || graph.build_run_id === graphId) ?? null;
+}
+export function getLatestContextGraph(runtime, projectDataDir, projectName) {
+    const project = findProjectConfig(loadSourceFolderConfig(projectDataDir), projectName);
+    if (!project)
+        return null;
+    const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
+    const contextGraphRun = latestContextGraphBuildRun(project, buildRuns);
+    const context = getProjectContextGraph(runtime, projectDataDir, project, contextGraphRun);
+    if (!context?.exists || !context.path)
+        return null;
+    const buildRunId = contextGraphRun?.run_id ?? null;
+    const rows = context.build_evidence?.rows ?? [];
+    const passing = rows.filter((row) => !row.issue_state || row.issue_state === "pass").length;
+    const primaryMetricCount = context.primary_metrics.length;
+    return ContextGraphResourceSchema.parse({
+        ...context,
+        kind: "interf-context-graph",
+        version: 1,
+        graph_id: buildRunId ?? `${projectName}-latest`,
+        project_id: projectName,
+        build_run_id: buildRunId,
+        created_at: contextGraphRun?.finished_at ?? contextGraphRun?.started_at ?? contextGraphRun?.created_at ?? context.readiness.generated_at,
+        is_latest: true,
+        build_evidence: context.build_evidence
+            ? {
+                ...context.build_evidence,
+                summary: primaryMetricCount > 0
+                    ? `${context.build_evidence.summary} · ${primaryMetricCount} primary metric${primaryMetricCount === 1 ? "" : "s"}`
+                    : `${context.build_evidence.summary} · ${passing}/${rows.length} diagnostic rows`,
+            }
+            : context.build_evidence,
+    });
+}
+export function listLatestContextGraphStageSessions(runtime, projectDataDir, projectName) {
+    const project = findProjectConfig(loadSourceFolderConfig(projectDataDir), projectName);
+    if (!project)
+        return [];
+    const latestRun = listBuildRunsForProject(runtime, projectDataDir, project.name)[0] ?? null;
+    const contextGraphPath = contextGraphPathForBuildRun(projectDataDir, latestRun);
+    if (!contextGraphPath || !existsSync(contextGraphPath))
+        return [];
+    return listStageExecutionSessions(contextGraphPath)
+        .map((session) => StageExecutionSessionSchema.parse(session));
+}
+export function getContextGraphHandoff(runtime, projectDataDir, projectName) {
+    const context = getLatestContextGraph(runtime, projectDataDir, projectName);
+    if (!context)
+        return null;
+    return ContextGraphHandoffSchema.parse({
+        kind: "interf-context-graph-handoff",
+        version: 1,
+        entrypoint: context.entrypoint_artifact ?? contextGraphEntrypointHandoff(context.path),
+        artifacts: context.artifact_handoffs,
+        ...(context.portable_handoff ? { portable: context.portable_handoff } : {}),
+    });
+}
+function listProjectContextGraphs(runtime, projectDataDir, project) {
+    const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
+    const latest = latestContextGraphBuildRun(project, buildRuns);
+    const graphs = buildRuns
+        .filter((run) => run.status === "succeeded")
+        .map((run) => getProjectContextGraph(runtime, projectDataDir, project, run, run.run_id === latest?.run_id))
+        .filter((graph) => graph !== null);
+    return graphs;
+}
+function getProjectContextGraph(runtime, projectDataDir, project, buildRun, isLatest = true) {
+    if (!buildRun)
+        return null;
+    const path = contextGraphPathForBuildRun(projectDataDir, buildRun);
+    if (!path)
+        return null;
+    // A succeeded Build's Context Graph is immutable: cache the fully-built
+    // resource keyed by run id + graph-manifest mtime. Non-succeeded runs (and
+    // graphs without a readable manifest) fall through to a fresh compute every
+    // time. `isLatest` flips the `is_latest` flag but is otherwise stable per
+    // run within a request, so fold it into the cache key suffix.
+    if (buildRun.status === "succeeded") {
+        return runtime.contextGraphResourceCache.get(projectDataDir, `${buildRun.run_id}:${isLatest ? "latest" : "historical"}`, contextGraphRuntimeGraphManifestPath(path), () => buildProjectContextGraphResource(runtime, projectDataDir, project, buildRun, path, isLatest));
+    }
+    return buildProjectContextGraphResource(runtime, projectDataDir, project, buildRun, path, isLatest);
+}
+function buildProjectContextGraphResource(runtime, projectDataDir, project, buildRun, path, isLatest) {
+    const config = readInterfConfig(path);
+    const sourceManifest = loadContextGraphSourceManifest(path);
+    const graphManifest = loadGraphManifest(path);
+    const verifyRuns = listVerifyRunsForProject(runtime, projectDataDir, project.name);
+    const latestVerifyRun = latestTopLevelVerifyRun(verifyRuns);
+    const readiness = computeProjectReadiness(runtime, projectDataDir, project);
+    const buildPlan = config?.build_plan ?? buildRun.build_plan ?? buildPlanIdForProjectConfig(project);
+    const sourceFileCount = listSourceFiles(runtime, projectDataDir, project.name).length;
+    let expectedStageCount;
+    let expectedOutputCount;
+    if (buildPlan) {
+        try {
+            const activeBuildPlan = getBuildPlan(buildPlan, { projectDataDir });
+            expectedStageCount = activeBuildPlan.stages.length;
+            const contextInterface = activeBuildPlan.contextInterface;
+            expectedOutputCount = contextInterface ? listContextInterfaceArtifacts(contextInterface).length : undefined;
+        }
+        catch {
+            expectedStageCount = undefined;
+            expectedOutputCount = undefined;
+        }
+    }
+    const artifacts = uniqueArtifacts(buildRun.stages.flatMap((stage) => stage.artifacts));
+    const artifactHandoffs = contextGraphArtifactHandoffs(path, artifacts);
+    const createdAt = buildRun.finished_at ?? buildRun.started_at ?? buildRun.created_at ?? readiness.generated_at;
+    const semanticEntrypointPath = artifactHandoffs.find((handoff) => handoff.path?.endsWith(".md"))?.path
+        ?? artifactHandoffs[0]?.path
+        ?? null;
+    return ContextGraphResourceSchema.parse({
+        kind: "interf-context-graph",
+        version: 1,
+        graph_id: buildRun.run_id,
+        project_id: project.name,
+        intent: project.intent ?? "",
+        build_run_id: buildRun.run_id,
+        source_manifest_id: sourceManifest?.manifest_id ?? null,
+        created_at: createdAt,
+        is_latest: isLatest,
+        project: project.name,
+        path,
+        exists: existsSync(path),
+        readiness,
+        build_plan: buildPlan,
+        latest_build_run_id: buildRun.run_id,
+        latest_benchmark_run_id: latestVerifyRun?.run_id ?? null,
+        entrypoint_artifact: artifactHandoffs[0] ?? null,
+        artifact_handoffs: artifactHandoffs,
+        portable_handoff: {
+            locator: { kind: "local-path", value: path },
+            instructions: "Start from home.md, then follow links into knowledge/, summaries/, and source refs.",
+        },
+        artifacts,
+        semantic_graph: buildContextGraphSemanticGraph({
+            contextGraphPath: path,
+            projectId: project.name,
+            generatedAt: createdAt,
+            sourceManifest,
+            entrypointPath: semanticEntrypointPath,
+        }),
+        graph_manifest: graphManifest,
+        primary_metrics: graphManifest?.primary_metrics ?? [],
+        stage_summaries: graphManifest?.stages ?? [],
+        entrypoints: graphManifest?.entrypoints ?? [],
+        resources: graphManifest?.resources ?? [],
+        readiness_rollup: graphManifest?.readiness ?? null,
+        stage_sessions: listStageExecutionSessions(path),
+        build_evidence: buildBuildEvidence({
+            projectId: project.name,
+            buildRun,
+            readiness,
+            sourceFileCount,
+            expectedStageCount,
+            expectedOutputCount,
+            stageEvidence: latestStageEvidenceForContext(path),
+            primaryMetrics: graphManifest?.primary_metrics ?? [],
+        }),
+    });
+}
+function contextGraphArtifactHandoffs(contextGraphPath, artifacts) {
+    const entrypoint = contextGraphEntrypointHandoff(contextGraphPath);
+    const outputs = artifacts.filter((artifact) => artifact.role === "output" && isInterfRelativePath(artifact.path));
+    const artifactEntrypoints = outputs.filter((artifact) => layerForPath(artifact.path) === "artifacts");
+    const ordered = [
+        ...artifactEntrypoints,
+        ...outputs.filter((artifact) => !artifactEntrypoints.includes(artifact)),
+    ];
+    const seen = new Set([entrypoint.path]);
+    const handoffs = ordered
+        .filter((artifact) => {
+        if (seen.has(artifact.path))
+            return false;
+        seen.add(artifact.path);
+        return true;
+    })
+        .map((artifact) => ({
+        label: artifact.label ?? artifact.path,
+        locator: { kind: "local-path", value: join(contextGraphPath, artifact.path) },
+        path: artifact.path,
+        role: "artifact",
+        ...(artifact.stage_id ? { summary: `Produced by stage ${artifact.stage_id}.` } : {}),
+    }));
+    return [entrypoint, ...handoffs];
+}
+function contextGraphEntrypointHandoff(contextGraphPath) {
+    return {
+        artifact_id: "home",
+        label: "Context Graph home",
+        locator: { kind: "local-path", value: join(contextGraphPath, "home.md") },
+        path: "home.md",
+        artifact_kind: "file",
+        role: "entrypoint",
+        summary: "Primary downstream agent entrypoint. Start here before following links into knowledge/ and summaries/.",
+    };
+}
+function latestStageEvidenceForContext(contextGraphPath) {
+    const latestByStage = new Map();
+    for (const entry of readExecutionStageLedgerHistory(contextGraphPath)) {
+        if (!entry.evidence)
+            continue;
+        const existing = latestByStage.get(entry.stage);
+        if (!existing || entry.updated_at >= existing.updated_at) {
+            latestByStage.set(entry.stage, entry);
+        }
+    }
+    return [...latestByStage.values()]
+        .map((entry) => entry.evidence)
+        .filter((entry) => entry !== undefined);
+}