@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/runtime-build-runs.js

@@ -0,0 +1,555 @@
+import { mkdirSync, } from "node:fs";
+import { resolve } from "node:path";
+import { listProjectConfigs, loadSourceFolderConfig, markProjectLatestContextGraphRun, resolveProjectSourceBindingPath, } from "../projects/source-config.js";
+import { BuildRunSchema, } from "./execution/lib/schema.js";
+import { createRunEventId, createRunEventTimestamp, } from "./execution/events.js";
+import { loadState, } from "./build/state.js";
+import { loadContextGraphSourceManifest, } from "./build/source-manifest.js";
+import { byCreatedAtDesc, listJsonFiles, projectBuildRunPath, projectBuildRunsRoot, readBuildRunAt, readExecutionStageLedgerHistory, timestampKey, writeJsonFile, } from "./runtime-persistence.js";
+import { applyEventToBuildRun, INTERRUPTED_BUILD_RUN_REASON, reconcileBuildRunTerminalStatus, } from "./runtime-event-applier.js";
+import { createRunId, logsForExecutionStageLedger, logsForStageRun, evidenceForStage, stageArtifactRefs, } from "./runtime-resource-builders.js";
+import { computeArtifactStatuses } from "./build/artifact-status.js";
+import { buildPlanContextChecks, projectContextChecksForRun, } from "./context-checks.js";
+import { JsonlBillingEventSink, buildBillingEventsForRun, defaultBillingEventLogPath, } from "./build/billing-events.js";
+import { getBuildPlan } from "../build-plans/package/build-plan-definitions.js";
+import { BuildRunCreateRequestSchema, BuildRunResourceSchema, LocalRunHandlerResultSchema, } from "./schemas/index.js";
+import { uniqueArtifacts } from "./run-observability.js";
+import { requireSelectedBuildPlan } from "./runtime-proposal-helpers.js";
+import { readinessUpdatedEvent } from "./runtime-verify-runs.js";
+import { isTerminalStatus } from "./runtime-status.js";
+/** TTL for `POST .../build-runs` idempotency-key dedupe entries. */
+const IDEMPOTENCY_TTL_MS = 60 * 60 * 1000;
+/** Idempotency cache size at which to schedule an opportunistic prune. */
+const IDEMPOTENCY_PRUNE_THRESHOLD = 64;
+function countsFromContextGraphState(state, contextGraphPath) {
+    const counts = {};
+    const sourceManifest = loadContextGraphSourceManifest(contextGraphPath);
+    if (sourceManifest)
+        counts.source_total = sourceManifest.source_total;
+    for (const stage of Object.values(state.stages ?? {})) {
+        for (const [key, value] of Object.entries(stage.counts ?? {})) {
+            if (Number.isFinite(value))
+                counts[key] = Math.max(counts[key] ?? 0, value);
+        }
+        for (const [key, value] of Object.entries(stage.artifact_counts ?? {})) {
+            if (Number.isFinite(value))
+                counts[key] = Math.max(counts[key] ?? 0, value);
+        }
+    }
+    return counts;
+}
+function buildRunRecordFilesForProject(projectDataDir, projectName) {
+    void projectName;
+    return listJsonFiles(projectBuildRunsRoot(projectDataDir));
+}
+function readBuildRunRecordsForProject(projectDataDir, projectName) {
+    const byRunId = new Map();
+    for (const filePath of buildRunRecordFilesForProject(projectDataDir, projectName)) {
+        const run = readBuildRunAt(filePath);
+        if (!run || run.project !== projectName)
+            continue;
+        if (!byRunId.has(run.run_id))
+            byRunId.set(run.run_id, run);
+    }
+    return [...byRunId.values()];
+}
+export function listBuildRuns(runtime, projectDataDir) {
+    return byCreatedAtDesc(listProjectConfigs(loadSourceFolderConfig(projectDataDir))
+        .flatMap((project) => listBuildRunsForProject(runtime, projectDataDir, project.name))).map((run) => BuildRunResourceSchema.parse({ run }));
+}
+export function listBuildRunsForProject(runtime, projectDataDir, projectName) {
+    return runtime.buildRunCache.get(projectDataDir, projectName, () => byCreatedAtDesc(readBuildRunRecordsForProject(projectDataDir, projectName)), (run) => run.run_id);
+}
+export function getBuildRun(runtime, projectDataDir, runId) {
+    // Fast path: if the runId was seen during a recent listing, look up
+    // its owning Project directly and return that Project's
+    // cached entry instead of scanning every project on disk.
+    const known = runtime.buildRunCache.projectFor(projectDataDir, runId);
+    if (known) {
+        const found = listBuildRunsForProject(runtime, projectDataDir, known).find((entry) => entry.run_id === runId);
+        if (found)
+            return BuildRunResourceSchema.parse({ run: found });
+    }
+    // Slow path: scan all projects. Falls through after a cache
+    // miss for an in-flight run created before this process restarted.
+    for (const resource of listBuildRuns(runtime, projectDataDir)) {
+        if (resource.run.run_id === runId)
+            return resource;
+    }
+    return null;
+}
+export function getBuildRunEvents(runtime, projectDataDir, runId) {
+    return getBuildRun(runtime, projectDataDir, runId)?.run.events ?? null;
+}
+export function getBuildRunEvidence(runtime, projectDataDir, runId) {
+    const run = getBuildRun(runtime, projectDataDir, runId)?.run;
+    if (!run)
+        return null;
+    return run.stages
+        .map((stage) => stage.latest_evidence ?? null)
+        .filter((evidence) => evidence !== null);
+}
+export function getBuildRunArtifacts(runtime, projectDataDir, runId) {
+    const run = getBuildRun(runtime, projectDataDir, runId)?.run;
+    if (!run)
+        return null;
+    return uniqueArtifacts(run.stages.flatMap((stage) => stage.artifacts));
+}
+export async function createBuildRun(runtime, projectDataDir, requestValue) {
+    const request = BuildRunCreateRequestSchema.parse(requestValue);
+    const projectConfig = runtime.resolveProjectConfig(projectDataDir, request.project);
+    const runId = createRunId("build");
+    const contextGraphPath = runtime.ensureContextGraphForRun(projectDataDir, projectConfig, runId);
+    const now = new Date().toISOString();
+    const buildPlan = getBuildPlan(requireSelectedBuildPlan(projectConfig), {
+        projectDataDir,
+    });
+    const stageTotal = buildPlan.stages.length;
+    const run = BuildRunSchema.parse({
+        kind: "interf-build-run",
+        version: 1,
+        run_id: runId,
+        status: "running",
+        project: projectConfig.name,
+        build_plan: buildPlan.id,
+        backend: "native",
+        source_path: resolveProjectSourceBindingPath(projectDataDir, projectConfig),
+        context_graph_path: contextGraphPath,
+        created_at: now,
+        started_at: now,
+        stages: buildPlan.stages
+            .map((stage, index) => {
+            return {
+                run_id: runId,
+                stage_id: stage.id,
+                stage_label: stage.label,
+                stage_index: index,
+                stage_total: stageTotal,
+                status: "queued",
+                contract: {
+                    stage_label: stage.label,
+                    stage_index: index,
+                    stage_total: stageTotal,
+                    reads: stage.reads,
+                    writes: stage.writes,
+                },
+                artifacts: [],
+            };
+        }),
+        events: [],
+        context_checks: buildPlanContextChecks({
+            brief: buildPlan.brief ?? null,
+            artifacts: buildPlan.contextInterface?.artifacts ?? [],
+        }),
+    });
+    writeBuildRun(runtime, projectDataDir, run);
+    runtime.activeBuildRuns.set(runId, {
+        projectDataDir,
+        contextGraphPath,
+        project: projectConfig.name,
+        cancelled: false,
+    });
+    await recordBuildRunEvent(runtime, projectDataDir, contextGraphPath, runId, {
+        type: "run.started",
+        event_id: createRunEventId("event"),
+        run_id: runId,
+        timestamp: now,
+        project: projectConfig.name,
+        build_plan: buildPlan.id,
+        context_graph_path: contextGraphPath,
+        backend: "native",
+    });
+    const sink = {
+        emit: (event) => recordBuildRunEvent(runtime, projectDataDir, contextGraphPath, runId, event),
+    };
+    void runBuildInBackground(runtime, projectDataDir, request, {
+        runId,
+        sourcePath: projectDataDir,
+        contextGraphPath,
+        projectConfig,
+        events: sink,
+    });
+    const saved = readBuildRun(projectDataDir, runId) ?? run;
+    return BuildRunResourceSchema.parse({ run: saved });
+}
+/**
+ * Cancel an in-flight Build run. Marks the persisted record as
+ * `cancelled`, emits a `run.cancelled` event to capture the cancellation in
+ * the run timeline, and clears the active handle so retries may start a
+ * fresh run. If the run already finished, returns
+ * `{ cancelled: false, reason: "already finished" }` and persists nothing.
+ */
+export function cancelBuildRun(runtime, runId) {
+    const handle = runtime.activeBuildRuns.get(runId);
+    if (!handle) {
+        // Either unknown or already terminal. The server route already 404s
+        // unknown ids before calling this, so anything reaching here is a run
+        // we already finalized.
+        return { cancelled: false, reason: "already finished" };
+    }
+    if (handle.cancelled) {
+        return { cancelled: false, reason: "already cancelled" };
+    }
+    const cancelledAt = new Date().toISOString();
+    handle.cancelled = true;
+    handle.cancelledAt = cancelledAt;
+    const current = readBuildRun(handle.projectDataDir, runId);
+    if (current && !isTerminalStatus(current.status)) {
+        writeBuildRun(runtime, handle.projectDataDir, applyEventToBuildRun(current, {
+            type: "run.cancelled",
+            event_id: createRunEventId("event"),
+            run_id: runId,
+            timestamp: cancelledAt,
+            reason: "Build cancelled by request.",
+        }));
+    }
+    return { cancelled: true };
+}
+/**
+ * Look up the run id previously associated with this idempotency key in
+ * `projectDataDir`. Returns null when the key is unknown or its TTL has
+ * elapsed. The project argument is required so that the same key in
+ * two different projects always returns two different runs.
+ */
+export function findIdempotentBuildRun(runtime, projectDataDir, key) {
+    const resolvedRoot = resolve(projectDataDir);
+    const bucket = runtime.idempotencyKeyCache.get(resolvedRoot);
+    if (!bucket)
+        return null;
+    const entry = bucket.get(key);
+    if (!entry)
+        return null;
+    if (entry.expiresAt <= Date.now()) {
+        // Opportunistic single-key prune. The bulk prune runs on writes
+        // when the cache crosses the size threshold (see
+        // {@link recordIdempotentBuildRun}).
+        bucket.delete(key);
+        if (bucket.size === 0)
+            runtime.idempotencyKeyCache.delete(resolvedRoot);
+        return null;
+    }
+    return entry.runId;
+}
+/**
+ * Cache the run id created (or returned) for this idempotency key in
+ * `projectDataDir`. Entries expire after `IDEMPOTENCY_TTL_MS`. Pruning
+ * is opportunistic: the previous implementation walked every entry on
+ * every read AND write, which was O(N) per request. Now we only sweep
+ * when the cache grows past {@link IDEMPOTENCY_PRUNE_THRESHOLD}.
+ */
+export function recordIdempotentBuildRun(runtime, projectDataDir, key, runId) {
+    const resolvedRoot = resolve(projectDataDir);
+    let bucket = runtime.idempotencyKeyCache.get(resolvedRoot);
+    if (!bucket) {
+        bucket = new Map();
+        runtime.idempotencyKeyCache.set(resolvedRoot, bucket);
+    }
+    bucket.set(key, {
+        runId,
+        expiresAt: Date.now() + IDEMPOTENCY_TTL_MS,
+    });
+    if (totalIdempotencyEntries(runtime) > IDEMPOTENCY_PRUNE_THRESHOLD) {
+        pruneIdempotencyKeyCache(runtime);
+    }
+}
+/** Total cached idempotency entries across all projects. */
+function totalIdempotencyEntries(runtime) {
+    let total = 0;
+    for (const bucket of runtime.idempotencyKeyCache.values())
+        total += bucket.size;
+    return total;
+}
+function pruneIdempotencyKeyCache(runtime) {
+    const now = Date.now();
+    for (const [projectDataDir, bucket] of runtime.idempotencyKeyCache) {
+        for (const [key, entry] of bucket) {
+            if (entry.expiresAt <= now)
+                bucket.delete(key);
+        }
+        if (bucket.size === 0)
+            runtime.idempotencyKeyCache.delete(projectDataDir);
+    }
+}
+/**
+ * Test seam: force the cached entry for `key` in `projectDataDir` to be
+ * expired so the next lookup returns null. Returns true when an entry was
+ * found and expired. Tests use this in place of fake timers because the
+ * idempotency TTL is one hour and faking `Date.now()` would destabilize
+ * unrelated runtime state.
+ */
+export function expireIdempotencyKeyForTesting(runtime, projectDataDir, key) {
+    const bucket = runtime.idempotencyKeyCache.get(resolve(projectDataDir));
+    if (!bucket)
+        return false;
+    const entry = bucket.get(key);
+    if (!entry)
+        return false;
+    entry.expiresAt = Date.now() - 1;
+    return true;
+}
+async function runBuildInBackground(runtime, projectDataDir, request, context) {
+    runtime.beginActiveRun();
+    try {
+        if (!runtime.handlers.createBuildRun) {
+            throw new Error("No build-run handler is configured for this local service.");
+        }
+        const result = LocalRunHandlerResultSchema.parse(await runtime.handlers.createBuildRun(request, context));
+        const wasCancelled = runtime.activeBuildRuns.get(context.runId)?.cancelled === true;
+        if (wasCancelled) {
+            // The run was cancelled while the handler was still running. The
+            // cancellation path already wrote a `cancelled` record; just refresh
+            // observability and skip emitting a second terminal event.
+            refreshBuildRunFromRuntime(runtime, projectDataDir, context.contextGraphPath, context.runId);
+            await emitRuntimeDerivedEvents(runtime, projectDataDir, context.contextGraphPath, context.runId);
+            await recordBuildRunEvent(runtime, projectDataDir, context.contextGraphPath, context.runId, readinessUpdatedEvent(context.runId, context.projectConfig.name, runtime.computeProjectReadiness(projectDataDir, context.projectConfig)));
+            return;
+        }
+        refreshBuildRunFromRuntime(runtime, projectDataDir, context.contextGraphPath, context.runId);
+        await emitRuntimeDerivedEvents(runtime, projectDataDir, context.contextGraphPath, context.runId);
+        let readinessProjectConfig = context.projectConfig;
+        if (!result.ok) {
+            await recordBuildRunEvent(runtime, projectDataDir, context.contextGraphPath, context.runId, {
+                type: "run.failed",
+                event_id: createRunEventId("event"),
+                run_id: context.runId,
+                timestamp: createRunEventTimestamp(),
+                error: result.error ?? "Build failed.",
+            });
+        }
+        else {
+            await recordBuildRunEvent(runtime, projectDataDir, context.contextGraphPath, context.runId, {
+                type: "run.completed",
+                event_id: createRunEventId("event"),
+                run_id: context.runId,
+                timestamp: createRunEventTimestamp(),
+                summary: "Context Graph ready.",
+            });
+            readinessProjectConfig = markProjectLatestContextGraphRun(projectDataDir, context.projectConfig.name, context.runId);
+            runtime.readinessCache.invalidateProject(projectDataDir, context.projectConfig.name);
+        }
+        await recordBuildRunEvent(runtime, projectDataDir, context.contextGraphPath, context.runId, readinessUpdatedEvent(context.runId, context.projectConfig.name, runtime.computeProjectReadiness(projectDataDir, readinessProjectConfig)));
+        emitBillingEventsForRun(projectDataDir, context, runtime);
+    }
+    catch (error) {
+        await recordBuildRunEvent(runtime, projectDataDir, context.contextGraphPath, context.runId, {
+            type: "run.failed",
+            event_id: createRunEventId("event"),
+            run_id: context.runId,
+            timestamp: createRunEventTimestamp(),
+            error: error instanceof Error ? error.message : String(error),
+        });
+        await recordBuildRunEvent(runtime, projectDataDir, context.contextGraphPath, context.runId, readinessUpdatedEvent(context.runId, context.projectConfig.name, runtime.computeProjectReadiness(projectDataDir, context.projectConfig)));
+    }
+    finally {
+        runtime.activeBuildRuns.delete(context.runId);
+        runtime.endActiveRun();
+    }
+}
+export function readBuildRun(projectDataDir, runId) {
+    return readBuildRunAt(projectBuildRunPath(projectDataDir, runId));
+}
+export function finalizeInterruptedBuildRuns(runtime, projectDataDir) {
+    let projects;
+    try {
+        projects = listProjectConfigs(loadSourceFolderConfig(projectDataDir));
+    }
+    catch {
+        return;
+    }
+    for (const project of projects) {
+        for (const run of readBuildRunRecordsForProject(projectDataDir, project.name)) {
+            if (isTerminalStatus(run.status) || runtime.activeBuildRuns.has(run.run_id))
+                continue;
+            const timestamp = createRunEventTimestamp();
+            const interruptedRun = {
+                ...run,
+                stages: run.stages.map((stage) => {
+                    if (stage.status !== "running")
+                        return stage;
+                    return {
+                        ...stage,
+                        status: "failed",
+                        finished_at: stage.finished_at ?? timestamp,
+                        summary: stage.summary ?? INTERRUPTED_BUILD_RUN_REASON,
+                        failure: stage.failure ?? INTERRUPTED_BUILD_RUN_REASON,
+                    };
+                }),
+            };
+            writeBuildRun(runtime, projectDataDir, applyEventToBuildRun(interruptedRun, {
+                type: "run.cancelled",
+                event_id: createRunEventId("event"),
+                run_id: run.run_id,
+                timestamp,
+                reason: INTERRUPTED_BUILD_RUN_REASON,
+            }));
+        }
+    }
+}
+/**
+ * Emit per-Artifact billing events when a Build run reaches a terminal
+ * state. Writes a JSONL file under hidden context-graph runtime
+ * metadata. The JSONL output is an observability/dev fixture, NOT
+ * production billing data.
+ */
+function emitBillingEventsForRun(projectDataDir, context, runtime) {
+    try {
+        const run = readBuildRun(projectDataDir, context.runId);
+        if (!run || run.artifacts.length === 0)
+            return;
+        const sink = new JsonlBillingEventSink(defaultBillingEventLogPath({
+            projectDataDir: projectDataDir,
+            projectName: run.project,
+            runId: context.runId,
+        }));
+        const events = buildBillingEventsForRun({
+            runId: context.runId,
+            project: run.project,
+            buildPlanId: run.build_plan,
+            accountId: runtime?.currentAccount?.user_id ?? null,
+            artifacts: run.artifacts,
+            startedAt: run.started_at ?? null,
+            finishedAt: run.finished_at ?? null,
+        });
+        for (const event of events) {
+            sink.emit(event);
+        }
+    }
+    catch {
+        // Billing is observability-only locally; never let sink failures
+        // block a successful build.
+    }
+}
+export function writeBuildRun(runtime, projectDataDir, run) {
+    mkdirSync(projectBuildRunsRoot(projectDataDir), { recursive: true });
+    writeJsonFile(projectBuildRunPath(projectDataDir, run.run_id), BuildRunSchema.parse(run));
+    // Bust per-Project list + readiness caches so the next read
+    // reflects the write. We invalidate broadly (per-Project, not
+    // per-record) because list recompute cost is bounded by run count
+    // and the simpler model avoids fan-out bugs.
+    runtime.buildRunCache.invalidateProject(projectDataDir, run.project);
+    runtime.readinessCache.invalidateProject(projectDataDir, run.project);
+    // The Context Graph resource embeds the joined readiness verdict, so bust it
+    // whenever a Build run is written (build completion, refresh, cancel).
+    runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
+}
+async function recordBuildRunEvent(runtime, projectDataDir, contextGraphPath, runId, event) {
+    const current = readBuildRun(projectDataDir, runId);
+    if (!current)
+        return;
+    writeBuildRun(runtime, projectDataDir, applyEventToBuildRun(current, event));
+    if (event.type === "stage.passed" || event.type === "stage.failed") {
+        refreshBuildRunFromRuntime(runtime, projectDataDir, contextGraphPath, runId);
+    }
+}
+function refreshBuildRunFromRuntime(runtime, projectDataDir, contextGraphPath, runId) {
+    const current = readBuildRun(projectDataDir, runId);
+    if (!current)
+        return;
+    const state = loadState(contextGraphPath);
+    if (!state?.stages)
+        return;
+    const historyByStage = new Map();
+    for (const run of readExecutionStageLedgerHistory(contextGraphPath)) {
+        if (run.target_name !== current.project)
+            continue;
+        const existing = historyByStage.get(run.stage);
+        if (!existing || timestampKey(run.updated_at) >= timestampKey(existing.updated_at)) {
+            historyByStage.set(run.stage, run);
+        }
+    }
+    const next = {
+        ...current,
+        stages: current.stages.map((stage) => {
+            const stageState = state.stages?.[stage.stage_id];
+            if (!stageState)
+                return stage;
+            const runtimeRun = historyByStage.get(stage.stage_id);
+            const artifacts = uniqueArtifacts([
+                ...(stage.artifacts ?? []),
+                ...stageArtifactRefs(stage.stage_id, stageState.artifacts),
+            ]);
+            const evidence = stage.latest_evidence ?? (stageState.status === "succeeded"
+                ? evidenceForStage({
+                    runId,
+                    stageId: stage.stage_id,
+                    summary: stageState.summary,
+                    stageState,
+                    artifacts,
+                })
+                : null);
+            return {
+                ...stage,
+                started_at: stage.started_at ?? stageState.started_at,
+                finished_at: stage.finished_at ?? stageState.finished_at,
+                summary: stage.summary ?? stageState.summary ?? null,
+                executor: stage.executor ?? runtimeRun?.executor ?? null,
+                artifacts,
+                logs: stage.logs ?? logsForExecutionStageLedger(runtimeRun) ?? logsForStageRun(stageState),
+                latest_evidence: evidence,
+            };
+        }),
+    };
+    next.latest_evidence = [...next.stages].reverse().find((stage) => Boolean(stage.latest_evidence))?.latest_evidence ?? next.latest_evidence;
+    // Recompute per-Artifact status whenever the Build run is
+    // refreshed from runtime state.
+    try {
+        const buildPlan = getBuildPlan(current.build_plan, { projectDataDir });
+        next.artifacts = computeArtifactStatuses({
+            buildPlan,
+            contextGraphPath,
+            stageRuns: next.stages,
+            counts: countsFromContextGraphState(state, contextGraphPath),
+        });
+        next.context_checks = projectContextChecksForRun({
+            contextChecks: buildPlanContextChecks({
+                brief: buildPlan.brief ?? null,
+                artifacts: buildPlan.contextInterface?.artifacts ?? [],
+            }),
+            artifactStatuses: next.artifacts,
+        });
+    }
+    catch {
+        next.artifacts = current.artifacts ?? [];
+        next.context_checks = current.context_checks ?? [];
+    }
+    writeBuildRun(runtime, projectDataDir, reconcileBuildRunTerminalStatus(next));
+}
+async function emitRuntimeDerivedEvents(runtime, projectDataDir, contextGraphPath, runId) {
+    const state = loadState(contextGraphPath);
+    const run = readBuildRun(projectDataDir, runId);
+    if (!state?.stages || !run)
+        return;
+    for (const stage of run.stages) {
+        const stageState = state.stages[stage.stage_id];
+        if (!stageState)
+            continue;
+        const artifacts = stageArtifactRefs(stage.stage_id, stageState.artifacts);
+        const eventTimestamp = stage.finished_at ?? stageState.finished_at ?? createRunEventTimestamp();
+        for (const artifact of artifacts) {
+            await recordBuildRunEvent(runtime, projectDataDir, contextGraphPath, runId, {
+                type: "artifact.written",
+                event_id: createRunEventId("event"),
+                run_id: runId,
+                timestamp: eventTimestamp,
+                stage_id: stage.stage_id,
+                artifact,
+            });
+        }
+        if (stageState.status === "succeeded") {
+            await recordBuildRunEvent(runtime, projectDataDir, contextGraphPath, runId, {
+                type: "evidence.updated",
+                event_id: createRunEventId("event"),
+                run_id: runId,
+                timestamp: eventTimestamp,
+                stage_id: stage.stage_id,
+                evidence: evidenceForStage({
+                    runId,
+                    stageId: stage.stage_id,
+                    summary: stageState.summary,
+                    stageState,
+                    artifacts,
+                }),
+            });
+        }
+    }
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Runtime read-side caches.
+ *
+ * The local service runtime fronts a filesystem-backed model: every
+ * "list" or "get" call walks `.interf/runtime/...`, parses each JSON
+ * record through Zod, and returns the typed shape. Polling clients
+ * (Interf Desktop renderer, CLI status loops) hit those endpoints multiple times
+ * per second; on instances with hundreds of Build / benchmark runs this
+ * shows up as the dominant CPU cost.
+ *
+ * The caches here memoize the parsed-and-validated results. Each cache
+ * is keyed by Project data directory so independent Projects do
+ * not cross-pollinate, and each cache exposes both a read path (`get(...)`) and an explicit
+ * invalidation hook (`invalidate(...)`). The runtime calls
+ * `invalidate*` whenever it writes, so the next read repopulates from
+ * disk. Invalidation is intentionally broad (per-Project, not
+ * per-record) — staleness is the only correctness bug worth avoiding,
+ * and per-record invalidation introduces fan-out without measurably
+ * lowering recompute cost.
+ */
+/**
+ * Per-(Project data directory, project) cache for Build records, plus a
+ * runId -> project index so `getBuildRun(runId)` can resolve to
+ * the owning Project without scanning every Project's runs.
+ */
+export declare class RunListingCache<TRecord> {
+    /** projectDataDir -> project id -> records (newest-first sorted). */
+    private byProjectRoot;
+    /** projectDataDir -> runId -> project. */
+    private runIndex;
+    get(projectDataDir: string, project: string, fill: () => TRecord[], runIdOf: (record: TRecord) => string): TRecord[];
+    /** Look up which project owns this runId, if known. */
+    projectFor(projectDataDir: string, runId: string): string | null;
+    /** Invalidate a single project's cached records and id index. */
+    invalidateProject(projectDataDir: string, project: string): void;
+    /** Drop everything for a Project data directory (e.g. after a reset). */
+    invalidateProjectRoot(projectDataDir: string): void;
+}
+/**
+ * Per-(Project data directory, project) readiness cache. Readiness joins build
+ * runs, benchmark runs, and the Project config; it
+ * is computed on every poll. The cache invalidates when the runtime
+ * writes any of those underlying objects for a given project.
+ */
+export declare class ReadinessCache<TReadiness> {
+    private byProjectRoot;
+    get(projectDataDir: string, project: string, compute: () => TReadiness): TReadiness;
+    invalidateProject(projectDataDir: string, project: string): void;
+    invalidateProjectRoot(projectDataDir: string): void;
+}
+/**
+ * Source-folder listing cache keyed by `(cacheKey, folderRootMtime)`.
+ * `cacheKey` is the slot identifier; `folderPath` is the directory the
+ * cache stats for an mtime probe. UI polling is the hot path; CLI
+ * commands rarely hit the same path twice in <2s, hence the short TTL
+ * fallback.
+ */
+export declare class MtimeListingCache<TList> {
+    private static readonly TTL_MS;
+    private cache;
+    get(cacheKey: string, folderPath: string, fill: () => TList): TList;
+    invalidate(cacheKey: string): void;
+    invalidateAll(): void;
+}
+/**
+ * Build Plan listing cache keyed by the joined mtimes of the
+ * bundled / user-library / Project-local Build Plan package roots. If
+ * any of those ticks (a new local Build Plan package, an edit to the user library, etc.) the cache
+ * misses and we re-resolve.
+ */
+export declare class BuildPlanListingCache<TList> {
+    private cache;
+    get(cacheKey: string, rootPaths: string[], fill: () => TList): TList;
+    invalidate(cacheKey: string): void;
+    invalidateAll(): void;
+}
+/**
+ * Per-Project source-state cache.
+ *
+ * Computing the file index hash requires reading every source file's first
+ * 64KB; on Projects with thousands of files this is the dominant cost of a
+ * drift check. The cache keys by Project id and invalidates on Build
+ * completion (which produces a new Context Graph the drift verdict compares to).
+ */
+export declare class ProjectSourceStateCache<TState> {
+    private byProjectId;
+    get(projectId: string, compute: () => TState): TState;
+    set(projectId: string, value: TState): void;
+    invalidateProject(projectId: string): void;
+    invalidateAll(): void;
+}
+/**
+ * Per-Build-run Context Graph resource cache.
+ *
+ * A succeeded Build's Context Graph is immutable: its on-disk folder
+ * (`graph-manifest.json`, source manifest, stage sessions, semantic graph) is
+ * frozen once the run reaches `succeeded`. Rebuilding the full
+ * `ContextGraphResource` — readiness join, semantic graph, build evidence,
+ * validation — on every read is the dominant cost of opening a built Project.
+ *
+ * The cache keys by `(projectDataDir, runId, manifestMtimeMs)`:
+ *  - `runId` scopes a single Build's output.
+ *  - `manifestMtimeMs` is the mtime of the Build's
+ *    `.interf/runtime/graph-manifest.json`. It busts the entry if the graph is
+ *    rebuilt or edited in place; a fresh Build produces a fresh `runId`, so
+ *    those never collide either.
+ *
+ * Entries without a readable manifest mtime (mtime 0) are not cached — that
+ * only happens for an in-flight or malformed Build, where the resource is
+ * still changing and must be recomputed.
+ */
+export declare class ContextGraphResourceCache<TResource> {
+    private byKey;
+    get(projectDataDir: string, runId: string, manifestPath: string, compute: () => TResource): TResource;
+    invalidateProject(projectDataDir: string): void;
+    invalidateAll(): void;
+}