@interf/compiler 0.9.5 → 0.16.0

package/dist/packages/engine/preparation-store.js

@@ -0,0 +1,194 @@
+/**
+ * 0.13 preparation store.
+ *
+ * Each preparation lives at `~/.interf/preparations/<id>/` and is also
+ * registered with the runtime as a synthetic workspace so the existing
+ * compile / test / readiness machinery (preparation-keyed under the hood)
+ * keeps working without a parallel implementation.
+ *
+ *   ~/.interf/preparations/<id>/
+ *     interf.json          ← preparation config, single preparation entry name=<id>
+ *     <id>/                ← portable context (matches preparation name)
+ *
+ * NOTE: We keep the synthetic `interf.json` shape (with a `preparations[]`
+ * array of length 1, name=id, path=id) so the existing compile/test
+ * machinery stays functional. The doc-shape `config.json` /
+ * `portable-context/` from `instance-paths.ts` is aspirational; transitioning
+ * the entire compile pipeline to read those names is out of scope for the
+ * 0.13 cutover.
+ *
+ * Public callers reach this through the preparation-keyed HTTP routes.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { PreparationNameSchema, MethodIdSchema, } from "../contracts/lib/schema.js";
+import { preparationDataDir, preparationsRoot, } from "./instance-paths.js";
+import { saveSourceFolderConfig, loadSourceFolderConfig, } from "../project/source-config.js";
+function ensurePreparationsRoot() {
+    mkdirSync(preparationsRoot(), { recursive: true });
+}
+function loadStoredPreparation(prepId) {
+    const prepDataDir = preparationDataDir(prepId);
+    if (!existsSync(prepDataDir) || !statSync(prepDataDir).isDirectory())
+        return null;
+    const config = loadSourceFolderConfig(prepDataDir);
+    if (!config)
+        return null;
+    const preparation = config.preparations?.find((p) => p.name === prepId);
+    if (!preparation)
+        return null;
+    const sourceFolderPath = config.source_folder?.path;
+    if (!sourceFolderPath)
+        return null;
+    return {
+        id: prepId,
+        prepDataDir,
+        source: { kind: "local-folder", locator: sourceFolderPath },
+        methodId: preparation.method ?? null,
+        about: preparation.about ?? null,
+        config: preparation,
+        portableContextPath: join(prepDataDir, prepId),
+        configPath: join(prepDataDir, "interf.json"),
+    };
+}
+/** List every preparation registered under `~/.interf/preparations/`. */
+export function listStoredPreparations() {
+    const root = preparationsRoot();
+    if (!existsSync(root))
+        return [];
+    const entries = readdirSync(root, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const stored = loadStoredPreparation(entry.name);
+        if (stored)
+            out.push(stored);
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Read one preparation by id. Returns null when missing. */
+export function getStoredPreparation(prepId) {
+    return loadStoredPreparation(prepId);
+}
+/**
+ * Create a preparation: scaffold its data dir, write the synthetic
+ * workspace config, and register it with the runtime so subsequent
+ * compile / test / readiness calls find it.
+ *
+ * Throws on validation errors (bad id, bad method id, source missing).
+ */
+export function createStoredPreparation(runtime, input) {
+    PreparationNameSchema.parse(input.id);
+    if (input.method_id != null) {
+        MethodIdSchema.parse(input.method_id);
+    }
+    const sourceLocator = resolve(input.source.locator);
+    if (!existsSync(sourceLocator)) {
+        throw new Error(`Source folder does not exist: ${sourceLocator}`);
+    }
+    if (!statSync(sourceLocator).isDirectory()) {
+        throw new Error(`Source folder is not a directory: ${sourceLocator}`);
+    }
+    ensurePreparationsRoot();
+    const prepDataDir = preparationDataDir(input.id);
+    if (existsSync(prepDataDir) && loadStoredPreparation(input.id)) {
+        throw new Error(`Preparation already exists: ${input.id}`);
+    }
+    mkdirSync(prepDataDir, { recursive: true });
+    const preparation = {
+        name: input.id,
+        path: input.id,
+        ...(input.method_id ? { method: input.method_id } : {}),
+        checks: (input.checks ?? []).map((check) => ({
+            question: check.question,
+            ...(check.answer ? { answer: check.answer } : {}),
+            ...(check.strictness ? { strictness: check.strictness } : {}),
+            ...(check.expect ? { expect: check.expect } : {}),
+        })),
+        ...(input.about ? { about: input.about } : {}),
+        ...(input.max_attempts ? { max_attempts: input.max_attempts } : {}),
+        ...(input.max_loops ? { max_loops: input.max_loops } : {}),
+    };
+    saveSourceFolderConfig(prepDataDir, {
+        source_folder: { path: sourceLocator },
+        preparations: [preparation],
+    });
+    // Hand the synthetic workspace to the runtime so the existing
+    // compile/test/readiness paths see it.
+    runtime.registerPreparation(prepDataDir);
+    const stored = loadStoredPreparation(input.id);
+    if (!stored)
+        throw new Error(`Failed to load freshly-created preparation ${input.id}`);
+    return stored;
+}
+/**
+ * Delete a preparation: deregister its synthetic workspace and remove
+ * `~/.interf/preparations/<id>/` from disk. Returns true when something
+ * was actually removed.
+ */
+export function deleteStoredPreparation(runtime, prepId) {
+    const prepDataDir = preparationDataDir(prepId);
+    if (!existsSync(prepDataDir))
+        return false;
+    runtime.deregisterPreparation(prepDataDir);
+    rmSync(prepDataDir, { recursive: true, force: true });
+    return true;
+}
+/**
+ * Update mutable fields on an existing preparation (method binding,
+ * about text). Returns the freshly-loaded record. Throws if the
+ * preparation does not exist.
+ */
+export function updateStoredPreparation(prepId, patch) {
+    const stored = loadStoredPreparation(prepId);
+    if (!stored)
+        throw new Error(`Preparation not found: ${prepId}`);
+    if (patch.method_id !== undefined && patch.method_id !== null) {
+        MethodIdSchema.parse(patch.method_id);
+    }
+    const nextPreparation = {
+        ...stored.config,
+        ...(patch.method_id === null
+            ? { method: undefined }
+            : patch.method_id !== undefined
+                ? { method: patch.method_id }
+                : {}),
+    };
+    const aboutPatch = patch.about === undefined ? stored.about : patch.about;
+    const preparationWithAbout = aboutPatch
+        ? { ...nextPreparation, about: aboutPatch }
+        : (() => {
+            const { about: _omitAbout, ...rest } = nextPreparation;
+            return rest;
+        })();
+    saveSourceFolderConfig(stored.prepDataDir, {
+        source_folder: { path: stored.source.locator },
+        preparations: [preparationWithAbout],
+    });
+    const next = loadStoredPreparation(prepId);
+    if (!next)
+        throw new Error(`Failed to reload updated preparation ${prepId}`);
+    return next;
+}
+/**
+ * Re-register every preparation directory with the runtime on startup so
+ * synthetic workspaces survive a `interf web` restart.
+ */
+export function rehydratePreparations(runtime) {
+    for (const stored of listStoredPreparations()) {
+        runtime.registerPreparation(stored.prepDataDir);
+    }
+}
+/** Build the wire shape for `GET /v1/preparations/<id>` given a stored preparation. */
+export function preparationWireShape(stored) {
+    return {
+        id: stored.id,
+        source: stored.source,
+        method_id: stored.methodId,
+        about: stored.about,
+        config_path: stored.configPath,
+        portable_context: { kind: "local-path", value: stored.portableContextPath },
+        checks: stored.config.checks ?? [],
+    };
+}

package/dist/packages/{local-service → engine}/readiness-check-draft.d.ts

@@ -1,5 +1,5 @@
-import type { MethodExecutor } from "../agents/lib/executors.js";
-import type { SourceReadinessCheck } from "../project-model/lib/schema.js";
+import type { MethodExecutor } from "./agents/lib/executors.js";
+import type { SourceReadinessCheck } from "../project/lib/schema.js";
 export declare function buildReadinessCheckDraftPrompt(options: {
     preparationName: string;
     sourceFolderPath: string;

package/dist/packages/engine/routes.d.ts

@@ -0,0 +1,78 @@
+export declare const LOCAL_SERVICE_DEFAULT_HOST = "127.0.0.1";
+export declare const LOCAL_SERVICE_DEFAULT_PORT = 4873;
+export declare const LOCAL_SERVICE_ROUTES: {
+    readonly root: "/";
+    readonly api: "/v1";
+    readonly health: "/health";
+    readonly instance: "/v1/instance";
+    readonly preparations: "/v1/preparations";
+    readonly methods: "/v1/methods";
+    readonly runs: "/v1/runs";
+    readonly actionProposals: "/v1/action-proposals";
+    /**
+     * 0.14 single-active-agent shortcut. Kept as a back-compat shim
+     * over the role-map's `general` row in 0.15+.
+     */
+    readonly executor: "/v1/executor";
+    /**
+     * 0.15 connected-agents primitive — registry, role-map, role list.
+     * `agents/{name}` and `agents/role-map` are sub-resources handled
+     * by string match in `server.ts`.
+     */
+    readonly agents: "/v1/agents";
+    readonly openPath: "/v1/open-path";
+};
+/** Preparation-scoped sub-resources (relative to /v1/preparations/<id>/). */
+export declare const PREPARATION_SUBRESOURCES: {
+    readonly compileRuns: "compile-runs";
+    readonly verifyRuns: "verify-runs";
+    readonly methodAuthoringRuns: "method-authoring-runs";
+    readonly methodImprovementRuns: "method-improvement-runs";
+    readonly readinessCheckDrafts: "readiness-check-drafts";
+    readonly changes: "changes";
+    readonly reset: "reset";
+    readonly runs: "runs";
+    readonly readiness: "readiness";
+    readonly sourceFiles: "source-files";
+    readonly portableContext: "portable-context";
+    /**
+     * 0.16 — read a portable-context file (read-only, path-guarded
+     * inside the prep's portable-context root). Used by the locator
+     * pattern's `api-served` kind:
+     *   GET /v1/preparations/<id>/files/<relpath>
+     */
+    readonly files: "files";
+};
+/** Method-scoped sub-resources (relative to /v1/methods/<id>/). */
+export declare const METHOD_SUBRESOURCES: {
+    readonly runs: "runs";
+    /**
+     * 0.16 — read a method package file (read-only, path-guarded inside
+     * the method root). Used by the locator pattern's `api-served` kind:
+     *   GET /v1/methods/<id>/files/<relpath>
+     */
+    readonly files: "files";
+};
+/** Run-scoped sub-resources (relative to /v1/runs/<run-id>/). */
+export declare const RUN_SUBRESOURCES: {
+    readonly events: "events";
+    readonly cancel: "cancel";
+    readonly proof: "proof";
+    readonly artifacts: "artifacts";
+};
+export declare function buildLocalServiceUrl(options?: {
+    host?: string;
+    port?: number;
+}): string;
+/** Path builder: /v1/preparations/<id>. */
+export declare function preparationResourcePath(prepId: string): string;
+/** Path builder: /v1/preparations/<id>/<subresource>. */
+export declare function preparationSubresourcePath(prepId: string, sub: keyof typeof PREPARATION_SUBRESOURCES): string;
+/** Path builder: /v1/runs/<run-id>. */
+export declare function runResourcePath(runId: string): string;
+/** Path builder: /v1/runs/<run-id>/<subresource>. */
+export declare function runSubresourcePath(runId: string, sub: keyof typeof RUN_SUBRESOURCES): string;
+/** Path builder: /v1/methods/<id>. */
+export declare function methodResourcePath(methodId: string): string;
+/** Path builder: /v1/methods/<id>/<subresource>. */
+export declare function methodSubresourcePath(methodId: string, sub: keyof typeof METHOD_SUBRESOURCES): string;

package/dist/packages/engine/routes.js

@@ -0,0 +1,92 @@
+export const LOCAL_SERVICE_DEFAULT_HOST = "127.0.0.1";
+export const LOCAL_SERVICE_DEFAULT_PORT = 4873;
+export const LOCAL_SERVICE_ROUTES = {
+    root: "/",
+    api: "/v1",
+    health: "/health",
+    // 0.13 surface — preparation-keyed.
+    instance: "/v1/instance",
+    preparations: "/v1/preparations",
+    methods: "/v1/methods",
+    runs: "/v1/runs",
+    actionProposals: "/v1/action-proposals",
+    /**
+     * 0.14 single-active-agent shortcut. Kept as a back-compat shim
+     * over the role-map's `general` row in 0.15+.
+     */
+    executor: "/v1/executor",
+    /**
+     * 0.15 connected-agents primitive — registry, role-map, role list.
+     * `agents/{name}` and `agents/role-map` are sub-resources handled
+     * by string match in `server.ts`.
+     */
+    agents: "/v1/agents",
+    openPath: "/v1/open-path",
+};
+/** Preparation-scoped sub-resources (relative to /v1/preparations/<id>/). */
+export const PREPARATION_SUBRESOURCES = {
+    compileRuns: "compile-runs",
+    verifyRuns: "verify-runs",
+    methodAuthoringRuns: "method-authoring-runs",
+    methodImprovementRuns: "method-improvement-runs",
+    readinessCheckDrafts: "readiness-check-drafts",
+    changes: "changes",
+    reset: "reset",
+    runs: "runs",
+    readiness: "readiness",
+    sourceFiles: "source-files",
+    portableContext: "portable-context",
+    /**
+     * 0.16 — read a portable-context file (read-only, path-guarded
+     * inside the prep's portable-context root). Used by the locator
+     * pattern's `api-served` kind:
+     *   GET /v1/preparations/<id>/files/<relpath>
+     */
+    files: "files",
+};
+/** Method-scoped sub-resources (relative to /v1/methods/<id>/). */
+export const METHOD_SUBRESOURCES = {
+    runs: "runs",
+    /**
+     * 0.16 — read a method package file (read-only, path-guarded inside
+     * the method root). Used by the locator pattern's `api-served` kind:
+     *   GET /v1/methods/<id>/files/<relpath>
+     */
+    files: "files",
+};
+/** Run-scoped sub-resources (relative to /v1/runs/<run-id>/). */
+export const RUN_SUBRESOURCES = {
+    events: "events",
+    cancel: "cancel",
+    proof: "proof",
+    artifacts: "artifacts",
+};
+export function buildLocalServiceUrl(options = {}) {
+    const host = options.host ?? LOCAL_SERVICE_DEFAULT_HOST;
+    const port = options.port ?? LOCAL_SERVICE_DEFAULT_PORT;
+    return `http://${host}:${port}`;
+}
+/** Path builder: /v1/preparations/<id>. */
+export function preparationResourcePath(prepId) {
+    return `${LOCAL_SERVICE_ROUTES.preparations}/${encodeURIComponent(prepId)}`;
+}
+/** Path builder: /v1/preparations/<id>/<subresource>. */
+export function preparationSubresourcePath(prepId, sub) {
+    return `${preparationResourcePath(prepId)}/${PREPARATION_SUBRESOURCES[sub]}`;
+}
+/** Path builder: /v1/runs/<run-id>. */
+export function runResourcePath(runId) {
+    return `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(runId)}`;
+}
+/** Path builder: /v1/runs/<run-id>/<subresource>. */
+export function runSubresourcePath(runId, sub) {
+    return `${runResourcePath(runId)}/${RUN_SUBRESOURCES[sub]}`;
+}
+/** Path builder: /v1/methods/<id>. */
+export function methodResourcePath(methodId) {
+    return `${LOCAL_SERVICE_ROUTES.methods}/${encodeURIComponent(methodId)}`;
+}
+/** Path builder: /v1/methods/<id>/<subresource>. */
+export function methodSubresourcePath(methodId, sub) {
+    return `${methodResourcePath(methodId)}/${METHOD_SUBRESOURCES[sub]}`;
+}

package/dist/packages/{local-service → engine}/run-observability.d.ts

@@ -1,6 +1,6 @@
-import { type ArtifactRef, type CompileRun } from "../execution/lib/schema.js";
-import { type LocalJobRunResource, type RunObservabilityResource, type TestRunResource } from "./lib/schema.js";
+import { type ArtifactRef, type CompileRun } from "./execution/lib/schema.js";
+import { type LocalJobRunResource, type RunObservabilityResource, type VerifyRunResource } from "./lib/schema.js";
 export declare function uniqueArtifacts(artifacts: ArtifactRef[]): ArtifactRef[];
 export declare function compileRunToObservability(run: CompileRun): RunObservabilityResource;
-export declare function testRunToObservability(run: TestRunResource): RunObservabilityResource;
+export declare function verifyRunToObservability(run: VerifyRunResource): RunObservabilityResource;
 export declare function jobRunToObservability(job: LocalJobRunResource): RunObservabilityResource;

package/dist/packages/{local-service → engine}/run-observability.js

@@ -1,4 +1,4 @@
-import { createRunEventTimestamp, } from "../execution/events.js";
+import { createRunEventTimestamp, } from "./execution/events.js";
 import { RunObservabilityResourceSchema, } from "./lib/schema.js";
 export function uniqueArtifacts(artifacts) {
     const seen = new Set();
@@ -268,23 +268,23 @@ export function compileRunToObservability(run) {
         },
     });
 }
-export function testRunToObservability(run) {
+export function verifyRunToObservability(run) {
     const traceStatus = methodTraceRunStatus(run.status);
     const title = `Check readiness ${run.preparation}`;
-    const methodName = interfTraceName("test", title);
+    const methodName = interfTraceName("verify", title);
     const completedAt = run.finished_at ?? (traceStatus === "completed" || traceStatus === "failed" || traceStatus === "cancelled"
         ? run.started_at ?? new Date().toISOString()
         : undefined);
     const readinessRun = run.readiness_run;
-    const raw = readinessRun?.raw ?? null;
+    const sourceFiles = readinessRun?.source_files ?? null;
     const compiled = readinessRun?.compiled ?? null;
     const proofCandidates = [
-        raw
+        sourceFiles
             ? {
                 id: `${run.run_id}-source-files`,
                 label: "source files baseline",
-                ok: raw.ok ?? raw.passed_cases === raw.total_cases,
-                detail: `${raw.passed_cases}/${raw.total_cases} checks`,
+                ok: sourceFiles.ok ?? sourceFiles.passed_cases === sourceFiles.total_cases,
+                detail: `${sourceFiles.passed_cases}/${sourceFiles.total_cases} checks`,
             }
             : null,
         compiled
@@ -298,7 +298,7 @@ export function testRunToObservability(run) {
     ];
     const proof = proofCandidates.filter((value) => value !== null);
     const artifacts = uniqueArtifacts([
-        ...(raw?.run_path ? [{ path: raw.run_path, role: "test", label: "source files readiness run" }] : []),
+        ...(sourceFiles?.run_path ? [{ path: sourceFiles.run_path, role: "test", label: "source files readiness run" }] : []),
         ...(compiled?.run_path ? [{ path: compiled.run_path, role: "test", label: "portable context readiness run" }] : []),
     ]);
     let eventIndex = 0;
@@ -307,9 +307,10 @@ export function testRunToObservability(run) {
             deploymentId: "local-interf",
             methodName,
             input: {
-                kind: "test",
+                kind: "verify",
                 preparation: run.preparation,
-                mode: run.mode,
+                // 0.15 — verify runs always judge against compiled output.
+                mode: "compiled",
             },
         }),
     ];
@@ -318,18 +319,18 @@ export function testRunToObservability(run) {
             methodName,
             input: {
                 preparation: run.preparation,
-                mode: run.mode,
+                mode: "compiled",
             },
         }));
     }
     const targetStepCandidates = [
-        raw
+        sourceFiles
             ? {
                 id: "source-files-baseline",
                 label: "Source files baseline",
-                status: raw.ok ?? raw.passed_cases === raw.total_cases ? "succeeded" : "failed",
-                input: raw.target ?? { type: "source-files", path: run.source_path ?? null },
-                output: raw,
+                status: sourceFiles.ok ?? sourceFiles.passed_cases === sourceFiles.total_cases ? "succeeded" : "failed",
+                input: sourceFiles.target ?? { type: "source-files", path: run.source_path ?? null },
+                output: sourceFiles,
             }
             : null,
         compiled
@@ -350,7 +351,7 @@ export function testRunToObservability(run) {
             status: run.status === "failed" ? "failed" : "succeeded",
             input: {
                 preparation: run.preparation,
-                mode: run.mode,
+                mode: "compiled",
             },
             output: readinessRun ?? null,
         });
@@ -358,7 +359,7 @@ export function testRunToObservability(run) {
     for (const step of targetSteps) {
         const timestamp = run.started_at ?? run.finished_at ?? new Date().toISOString();
         events.push(traceEvent(run.run_id, "step_created", timestamp, eventIndex++, {
-            stepName: methodStepName("test", step.label),
+            stepName: methodStepName("verify", step.label),
             input: step.input,
         }, step.id));
         events.push(traceEvent(run.run_id, "step_started", timestamp, eventIndex++, {
@@ -388,7 +389,7 @@ export function testRunToObservability(run) {
         kind: "interf-run-observability",
         version: 1,
         run_id: run.run_id,
-        run_type: "test",
+        run_type: "verify",
         title,
         status: observableRunStatus(run.status),
         preparation: run.preparation,
@@ -401,9 +402,9 @@ export function testRunToObservability(run) {
         readiness: run.readiness ?? null,
         metrics: [
             { label: "Preparation", value: run.preparation },
-            { label: "Mode", value: run.mode },
-            { label: "Readiness checks", value: compiled ? `${compiled.passed_cases}/${compiled.total_cases}` : raw ? `${raw.passed_cases}/${raw.total_cases}` : "0/0" },
-            { label: "Source files", value: raw ? `${raw.passed_cases}/${raw.total_cases}` : "-" },
+            { label: "Mode", value: "compiled" },
+            { label: "Readiness checks", value: compiled ? `${compiled.passed_cases}/${compiled.total_cases}` : sourceFiles ? `${sourceFiles.passed_cases}/${sourceFiles.total_cases}` : "0/0" },
+            { label: "Source files", value: sourceFiles ? `${sourceFiles.passed_cases}/${sourceFiles.total_cases}` : "-" },
             { label: "Portable context", value: compiled ? `${compiled.passed_cases}/${compiled.total_cases}` : "-" },
         ],
         artifacts,
@@ -417,13 +418,13 @@ export function testRunToObservability(run) {
                 specVersion: 1,
                 executionContext: {
                     product: "Interf",
-                    run_type: "test",
+                    run_type: "verify",
                     preparation: run.preparation,
-                    mode: run.mode,
+                    mode: "compiled",
                 },
                 input: {
                     preparation: run.preparation,
-                    mode: run.mode,
+                    mode: "compiled",
                     source_path: run.source_path ?? null,
                     portable_context_path: run.portable_context_path ?? null,
                 },

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

@@ -0,0 +1,76 @@
+/**
+ * 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
+ * (Compiler UI, CLI status loops) hit those endpoints multiple times
+ * per second; on workspaces with hundreds of compile / test runs this
+ * shows up as the dominant CPU cost.
+ *
+ * The caches here memoize the parsed-and-validated results. Each cache
+ * is per-workspace so multi-workspace runtimes 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-preparation, not
+ * per-record) — staleness is the only correctness bug worth avoiding,
+ * and per-record invalidation introduces fan-out without measurably
+ * lowering recompute cost.
+ */
+/**
+ * Per-(workspace, preparation) cache for compile run records, plus a
+ * runId -> preparation index so `getCompileRun(runId)` can resolve to
+ * the owning preparation without scanning every preparation's runs.
+ */
+export declare class RunListingCache<TRecord> {
+    /** prepDataDir -> preparation -> records (newest-first sorted). */
+    private byWorkspace;
+    /** prepDataDir -> runId -> preparation. */
+    private runIndex;
+    get(prepDataDir: string, preparation: string, fill: () => TRecord[], runIdOf: (record: TRecord) => string): TRecord[];
+    /** Look up which preparation owns this runId, if known. */
+    preparationFor(prepDataDir: string, runId: string): string | null;
+    /** Invalidate a single preparation's cached records and id index. */
+    invalidatePreparation(prepDataDir: string, preparation: string): void;
+    /** Drop everything for a workspace (e.g. after a reset). */
+    invalidateWorkspace(prepDataDir: string): void;
+}
+/**
+ * Per-(workspace, preparation) readiness cache. Readiness joins compile
+ * runs, test runs, readiness-check runs, and the preparation config; it
+ * is computed on every poll. The cache invalidates when the runtime
+ * writes any of those underlying objects for a given preparation.
+ */
+export declare class ReadinessCache<TReadiness> {
+    private byWorkspace;
+    get(prepDataDir: string, preparation: string, compute: () => TReadiness): TReadiness;
+    invalidatePreparation(prepDataDir: string, preparation: string): void;
+    invalidateWorkspace(prepDataDir: 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;
+}
+/**
+ * Method-package listing cache keyed by the joined mtimes of the
+ * builtin / user / workspace method roots. If any of those ticks (a
+ * new local Method, an edit to the user library, etc.) the cache
+ * misses and we re-resolve.
+ */
+export declare class MethodListingCache<TList> {
+    private cache;
+    get(cacheKey: string, rootPaths: string[], fill: () => TList): TList;
+    invalidate(cacheKey: string): void;
+    invalidateAll(): void;
+}