@interf/compiler 0.21.0 → 0.22.0

package/dist/packages/engine/run-observability.js

@@ -23,7 +23,7 @@ function observableRunStatus(status) {
         return "cancelled";
     return "succeeded";
 }
-function methodTraceRunStatus(status) {
+function runTraceStatus(status) {
     if (status === "queued" || status === "pending")
         return "pending";
     if (status === "running")
@@ -34,7 +34,7 @@ function methodTraceRunStatus(status) {
         return "cancelled";
     return "completed";
 }
-function safeMethodNamePart(value) {
+function safeTraceNamePart(value) {
     return value
         .replace(/[^a-zA-Z0-9._/-]+/g, "-")
         .replace(/\/+/g, "/")
@@ -42,12 +42,12 @@ function safeMethodNamePart(value) {
         || "run";
 }
 function interfTraceName(runType, name) {
-    return `interf//./runs/${runType}//${safeMethodNamePart(name)}`;
+    return `interf//./runs/${runType}//${safeTraceNamePart(name)}`;
 }
-function methodStepName(runType, label) {
-    return `step//./interf/${runType}//${safeMethodNamePart(label)}`;
+function runTraceStepName(runType, label) {
+    return `step//./interf/${runType}//${safeTraceNamePart(label)}`;
 }
-function structuredMethodError(message) {
+function structuredRunTraceError(message) {
     return {
         message: message || "Run failed.",
         code: "INTERF_RUN_ERROR",
@@ -82,7 +82,7 @@ function buildTraceStreamChunks(runId, events) {
         message: event.message ?? event.summary ?? event.error ?? event.reason ?? event.type,
     }), event));
 }
-function proofChecksForCompileRun(run) {
+function proofChecksForBuildRun(run) {
     return run.stages.flatMap((stage) => (stage.latest_proof?.checks ?? []).map((check) => ({
         ...check,
         detail: check.detail ?? `${stage.stage_label ?? stage.stage_id} / ${stage.status}`,
@@ -94,10 +94,10 @@ function agentLabelForJob(job) {
 function jobTypeLabelForMetric(type) {
     if (type === "readiness-check-draft")
         return "Draft readiness checks";
-    if (type === "method-authoring")
-        return "Method draft";
-    if (type === "method-improvement")
-        return "Method improvement";
+    if (type === "build-plan-draft")
+        return "Build Plan draft";
+    if (type === "build-plan-improvement")
+        return "Build Plan improvement";
     return "Local job";
 }
 function stageTracePayload(stage) {
@@ -109,12 +109,20 @@ function stageTracePayload(stage) {
         ...(stage.latest_proof ? { proof: stage.latest_proof } : {}),
     };
 }
-export function compileRunToObservability(run) {
+function buildPlanForRun(run) {
+    return run.build_plan;
+}
+function verifiableContextPathForRun(run) {
+    return run.verifiable_context_path;
+}
+export function buildRunToObservability(run) {
     const artifacts = uniqueArtifacts(run.stages.flatMap((stage) => stage.artifacts));
-    const proof = proofChecksForCompileRun(run);
+    const proof = proofChecksForBuildRun(run);
     const executor = run.stages.find((stage) => stage.executor)?.executor ?? null;
-    const traceStatus = methodTraceRunStatus(run.status);
-    const methodName = interfTraceName("compile", `Prepare ${run.preparation}`);
+    const traceStatus = runTraceStatus(run.status);
+    const buildPlan = buildPlanForRun(run);
+    const verifiableContextPath = verifiableContextPathForRun(run);
+    const traceName = interfTraceName("build", `Build ${run.preparation}`);
     const completedAt = run.finished_at ?? (traceStatus === "completed" || traceStatus === "failed" || traceStatus === "cancelled"
         ? run.started_at ?? run.created_at
         : undefined);
@@ -122,11 +130,11 @@ export function compileRunToObservability(run) {
     const events = [
         traceEvent(run.run_id, "run_created", run.created_at, eventIndex++, {
             deploymentId: "local-interf",
-            methodName,
+            traceName,
             input: {
-                kind: "compile",
+                kind: "build",
                 preparation: run.preparation,
-                method: run.method,
+                build_plan: buildPlan,
                 source_path: run.source_path,
             },
             executionContext: {
@@ -137,10 +145,10 @@ export function compileRunToObservability(run) {
     ];
     if (run.started_at) {
         events.push(traceEvent(run.run_id, "run_started", run.started_at, eventIndex++, {
-            methodName,
+            traceName,
             input: {
                 preparation: run.preparation,
-                method: run.method,
+                build_plan: buildPlan,
             },
             executionContext: {
                 backend: run.backend,
@@ -151,7 +159,7 @@ export function compileRunToObservability(run) {
     for (const stage of run.stages) {
         if (stage.status === "queued")
             continue;
-        const stepName = methodStepName("compile", stage.stage_label ?? stage.stage_id);
+        const stepName = runTraceStepName("build", stage.stage_label ?? stage.stage_id);
         const stepCreatedAt = stage.started_at ?? run.started_at ?? run.created_at;
         const stepStartedAt = stage.started_at ?? stepCreatedAt;
         const stepCompletedAt = stage.finished_at ?? run.finished_at ?? completedAt ?? stepCreatedAt;
@@ -172,7 +180,7 @@ export function compileRunToObservability(run) {
         }, stage.stage_id));
         if (stage.status === "failed") {
             events.push(traceEvent(run.run_id, "step_failed", stepCompletedAt, eventIndex++, {
-                error: structuredMethodError(stage.failure ?? stage.summary),
+                error: structuredRunTraceError(stage.failure ?? stage.summary),
                 output: stageTracePayload(stage),
             }, stage.stage_id));
         }
@@ -185,7 +193,7 @@ export function compileRunToObservability(run) {
     if (traceStatus === "completed") {
         events.push(traceEvent(run.run_id, "run_completed", completedAt, eventIndex++, {
             output: {
-                portable_context_path: run.portable_context_path,
+                verifiable_context_path: verifiableContextPath,
                 artifacts,
                 proof,
                 latest_proof: run.latest_proof ?? null,
@@ -194,7 +202,7 @@ export function compileRunToObservability(run) {
     }
     else if (traceStatus === "failed") {
         events.push(traceEvent(run.run_id, "run_failed", completedAt, eventIndex++, {
-            error: structuredMethodError(run.stages.find((stage) => stage.failure)?.failure ?? run.latest_proof?.summary),
+            error: structuredRunTraceError(run.stages.find((stage) => stage.failure)?.failure ?? run.latest_proof?.summary),
         }));
     }
     else if (traceStatus === "cancelled") {
@@ -204,13 +212,13 @@ export function compileRunToObservability(run) {
         kind: "interf-run-observability",
         version: 1,
         run_id: run.run_id,
-        run_type: "compile",
-        title: `Prepare ${run.preparation}`,
+        run_type: "build",
+        title: `Build ${run.preparation}`,
         status: observableRunStatus(run.status),
         preparation: run.preparation,
-        method: run.method,
+        build_plan: buildPlan,
         source_path: run.source_path,
-        output_path: run.portable_context_path,
+        output_path: verifiableContextPath,
         executor,
         agent_label: executor?.display_name ?? run.backend,
         created_at: run.created_at,
@@ -219,7 +227,7 @@ export function compileRunToObservability(run) {
         readiness: run.readiness ?? null,
         metrics: [
             { label: "Preparation", value: run.preparation },
-            { label: "Method", value: run.method },
+            { label: "Build Plan", value: buildPlan },
             { label: "Executor", value: executor?.display_name ?? run.backend },
             { label: "Stages", value: `${run.stages.filter((stage) => stage.status === "succeeded").length}/${run.stages.length}` },
             { label: "Stage proof", value: `${proof.filter((check) => check.ok).length}/${proof.length}` },
@@ -232,31 +240,31 @@ export function compileRunToObservability(run) {
                 runId: run.run_id,
                 status: traceStatus,
                 deploymentId: "local-interf",
-                methodName,
+                traceName,
                 specVersion: 1,
                 executionContext: {
                     product: "Interf",
-                    run_type: "compile",
+                    run_type: "build",
                     preparation: run.preparation,
-                    method: run.method,
+                    build_plan: buildPlan,
                     backend: run.backend,
                     executor,
                 },
                 input: {
                     preparation: run.preparation,
-                    method: run.method,
+                    build_plan: buildPlan,
                     source_path: run.source_path,
                 },
                 ...(traceStatus === "completed"
                     ? {
                         output: {
-                            portable_context_path: run.portable_context_path,
+                            verifiable_context_path: verifiableContextPath,
                             artifacts,
                             proof,
                         },
                     }
                     : {}),
-                ...(traceStatus === "failed" ? { error: structuredMethodError(run.stages.find((stage) => stage.failure)?.failure) } : {}),
+                ...(traceStatus === "failed" ? { error: structuredRunTraceError(run.stages.find((stage) => stage.failure)?.failure) } : {}),
                 ...(run.started_at ? { startedAt: run.started_at } : {}),
                 ...(completedAt ? { completedAt } : {}),
                 createdAt: run.created_at,
@@ -268,15 +276,15 @@ export function compileRunToObservability(run) {
     });
 }
 export function verifyRunToObservability(run) {
-    const traceStatus = methodTraceRunStatus(run.status);
+    const traceStatus = runTraceStatus(run.status);
     const title = `Check readiness ${run.preparation}`;
-    const methodName = interfTraceName("verify", title);
+    const traceName = 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 sourceFiles = readinessRun?.source_files ?? null;
-    const compiled = readinessRun?.compiled ?? null;
+    const verifiableContext = readinessRun?.verifiable_context ?? null;
     const proofCandidates = [
         sourceFiles
             ? {
@@ -286,39 +294,39 @@ export function verifyRunToObservability(run) {
                 detail: `${sourceFiles.passed_cases}/${sourceFiles.total_cases} checks`,
             }
             : null,
-        compiled
+        verifiableContext
             ? {
-                id: `${run.run_id}-portable-context`,
-                label: "portable context",
-                ok: compiled.ok ?? compiled.passed_cases === compiled.total_cases,
-                detail: `${compiled.passed_cases}/${compiled.total_cases} checks`,
+                id: `${run.run_id}-verifiable-context`,
+                label: "verifiable context",
+                ok: verifiableContext.ok ?? verifiableContext.passed_cases === verifiableContext.total_cases,
+                detail: `${verifiableContext.passed_cases}/${verifiableContext.total_cases} checks`,
             }
             : null,
     ];
     const proof = proofCandidates.filter((value) => value !== null);
     const artifacts = uniqueArtifacts([
         ...(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" }] : []),
+        ...(verifiableContext?.run_path ? [{ path: verifiableContext.run_path, role: "test", label: "verifiable context readiness run" }] : []),
     ]);
     let eventIndex = 0;
     const events = [
         traceEvent(run.run_id, "run_created", run.started_at, eventIndex++, {
             deploymentId: "local-interf",
-            methodName,
+            traceName,
             input: {
                 kind: "verify",
                 preparation: run.preparation,
-                // 0.15 — verify runs always judge against compiled output.
-                mode: "compiled",
+                // 0.15 - verify runs always judge against verifiable context.
+                mode: "built",
             },
         }),
     ];
     if (run.started_at) {
         events.push(traceEvent(run.run_id, "run_started", run.started_at, eventIndex++, {
-            methodName,
+            traceName,
             input: {
                 preparation: run.preparation,
-                mode: "compiled",
+                mode: "built",
             },
         }));
     }
@@ -332,13 +340,13 @@ export function verifyRunToObservability(run) {
                 output: sourceFiles,
             }
             : null,
-        compiled
+        verifiableContext
             ? {
-                id: "portable-context-check",
-                label: "Portable context",
-                status: compiled.ok ?? compiled.passed_cases === compiled.total_cases ? "succeeded" : "failed",
-                input: compiled.target ?? { type: "portable-context", path: run.portable_context_path ?? null },
-                output: compiled,
+                id: "verifiable-context-check",
+                label: "Verifiable context",
+                status: verifiableContext.ok ?? verifiableContext.passed_cases === verifiableContext.total_cases ? "succeeded" : "failed",
+                input: verifiableContext.target ?? { type: "verifiable-context", path: run.verifiable_context_path ?? null },
+                output: verifiableContext,
             }
             : null,
     ];
@@ -350,7 +358,7 @@ export function verifyRunToObservability(run) {
             status: run.status === "failed" ? "failed" : "succeeded",
             input: {
                 preparation: run.preparation,
-                mode: "compiled",
+                mode: "built",
             },
             output: readinessRun ?? null,
         });
@@ -358,14 +366,14 @@ export function verifyRunToObservability(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("verify", step.label),
+            stepName: runTraceStepName("verify", step.label),
             input: step.input,
         }, step.id));
         events.push(traceEvent(run.run_id, "step_started", timestamp, eventIndex++, {
             attempt: 1,
         }, step.id));
         events.push(traceEvent(run.run_id, step.status === "failed" ? "step_failed" : "step_completed", run.finished_at ?? timestamp, eventIndex++, step.status === "failed"
-            ? { error: structuredMethodError(run.error ?? `${step.label} did not pass.`), output: step.output }
+            ? { error: structuredRunTraceError(run.error ?? `${step.label} did not pass.`), output: step.output }
             : { result: step.output }, step.id));
     }
     if (traceStatus === "completed") {
@@ -378,7 +386,7 @@ export function verifyRunToObservability(run) {
     }
     else if (traceStatus === "failed") {
         events.push(traceEvent(run.run_id, "run_failed", completedAt, eventIndex++, {
-            error: structuredMethodError(run.error),
+            error: structuredRunTraceError(run.error),
         }));
     }
     else if (traceStatus === "cancelled") {
@@ -392,19 +400,19 @@ export function verifyRunToObservability(run) {
         title,
         status: observableRunStatus(run.status),
         preparation: run.preparation,
-        method: compiled?.target?.method ?? null,
+        build_plan: verifiableContext?.target?.build_plan ?? null,
         source_path: run.source_path ?? null,
-        output_path: run.portable_context_path ?? null,
+        output_path: run.verifiable_context_path ?? null,
         created_at: run.started_at ?? completedAt ?? new Date().toISOString(),
         started_at: run.started_at ?? null,
         finished_at: run.finished_at ?? null,
         readiness: run.readiness ?? null,
         metrics: [
             { label: "Preparation", value: run.preparation },
-            { 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: "Mode", value: "verifiable context" },
+            { label: "Readiness checks", value: verifiableContext ? `${verifiableContext.passed_cases}/${verifiableContext.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}` : "-" },
+            { label: "Verifiable context", value: verifiableContext ? `${verifiableContext.passed_cases}/${verifiableContext.total_cases}` : "-" },
         ],
         artifacts,
         proof,
@@ -413,22 +421,22 @@ export function verifyRunToObservability(run) {
                 runId: run.run_id,
                 status: traceStatus,
                 deploymentId: "local-interf",
-                methodName,
+                traceName,
                 specVersion: 1,
                 executionContext: {
                     product: "Interf",
                     run_type: "verify",
                     preparation: run.preparation,
-                    mode: "compiled",
+                    mode: "built",
                 },
                 input: {
                     preparation: run.preparation,
-                    mode: "compiled",
+                    mode: "built",
                     source_path: run.source_path ?? null,
-                    portable_context_path: run.portable_context_path ?? null,
+                    verifiable_context_path: run.verifiable_context_path ?? null,
                 },
                 ...(traceStatus === "completed" ? { output: { readiness_run: readinessRun, proof } } : {}),
-                ...(traceStatus === "failed" ? { error: structuredMethodError(run.error) } : {}),
+                ...(traceStatus === "failed" ? { error: structuredRunTraceError(run.error) } : {}),
                 ...(run.started_at ? { startedAt: run.started_at } : {}),
                 ...(completedAt ? { completedAt } : {}),
                 createdAt: run.started_at ?? completedAt ?? new Date().toISOString(),
@@ -440,11 +448,14 @@ export function verifyRunToObservability(run) {
     });
 }
 export function jobRunToObservability(job) {
-    const runType = (job.job_type === "readiness-check-draft" ||
-        job.job_type === "method-authoring" ||
-        job.job_type === "method-improvement"
-        ? job.job_type
-        : "job");
+    const runType = (job.job_type === "readiness-check-draft"
+        ? "readiness-check-draft"
+        : job.job_type === "build-plan-draft"
+            ? "build-plan-draft"
+            : job.job_type === "build-plan-improvement"
+                ? "build-plan-improvement"
+                : "job");
+    const buildPlanId = job.build_plan ?? null;
     const executor = job.agent
         ? {
             kind: "local-agent",
@@ -453,8 +464,8 @@ export function jobRunToObservability(job) {
             command: job.agent.command ?? null,
         }
         : null;
-    const traceStatus = methodTraceRunStatus(job.status);
-    const methodName = interfTraceName(runType, job.title);
+    const traceStatus = runTraceStatus(job.status);
+    const traceName = interfTraceName(runType, job.title);
     const completedAt = job.finished_at ?? (traceStatus === "completed" || traceStatus === "failed" || traceStatus === "cancelled"
         ? job.started_at ?? job.created_at
         : undefined);
@@ -462,11 +473,11 @@ export function jobRunToObservability(job) {
     const events = [
         traceEvent(job.run_id, "run_created", job.created_at, eventIndex++, {
             deploymentId: "local-interf",
-            methodName,
+            traceName,
             input: {
                 job_type: job.job_type,
                 preparation: job.preparation ?? null,
-                method: job.method ?? null,
+                build_plan: buildPlanId,
             },
             executionContext: {
                 executor,
@@ -475,7 +486,7 @@ export function jobRunToObservability(job) {
     ];
     if (job.started_at) {
         events.push(traceEvent(job.run_id, "run_started", job.started_at, eventIndex++, {
-            methodName,
+            traceName,
             input: {
                 job_type: job.job_type,
                 preparation: job.preparation ?? null,
@@ -488,7 +499,7 @@ export function jobRunToObservability(job) {
     for (const step of job.steps) {
         const timestamp = step.started_at ?? job.started_at ?? job.created_at;
         events.push(traceEvent(job.run_id, "step_created", timestamp, eventIndex++, {
-            stepName: methodStepName(runType, step.label),
+            stepName: runTraceStepName(runType, step.label),
             input: step.input ?? {
                 step_id: step.id,
                 label: step.label,
@@ -501,7 +512,7 @@ export function jobRunToObservability(job) {
         }
         if (step.status === "failed") {
             events.push(traceEvent(job.run_id, "step_failed", step.finished_at ?? completedAt ?? timestamp, eventIndex++, {
-                error: structuredMethodError(step.summary ?? job.error),
+                error: structuredRunTraceError(step.summary ?? job.error),
                 output: step.output ?? null,
             }, step.id));
         }
@@ -522,14 +533,15 @@ export function jobRunToObservability(job) {
     }
     else if (traceStatus === "failed") {
         events.push(traceEvent(job.run_id, "run_failed", completedAt, eventIndex++, {
-            error: structuredMethodError(job.error),
+            error: structuredRunTraceError(job.error),
         }));
     }
     else if (traceStatus === "cancelled") {
         events.push(traceEvent(job.run_id, "run_cancelled", completedAt, eventIndex++));
     }
     const outputPath = job.output_path ?? (typeof job.result?.path === "string" ? job.result.path : null);
-    const outputIsArtifact = job.job_type !== "method-authoring" && job.job_type !== "method-improvement";
+    const outputIsArtifact = job.job_type !== "build-plan-draft"
+        && job.job_type !== "build-plan-improvement";
     const artifacts = uniqueArtifacts(outputIsArtifact && outputPath ? [{ path: outputPath, role: "output" }] : []);
     return RunObservabilityResourceSchema.parse({
         kind: "interf-run-observability",
@@ -539,7 +551,7 @@ export function jobRunToObservability(job) {
         title: job.title,
         status: observableRunStatus(job.status),
         preparation: job.preparation ?? null,
-        method: job.method ?? null,
+        build_plan: buildPlanId,
         source_path: job.source_path ?? null,
         output_path: outputPath,
         executor,
@@ -552,7 +564,7 @@ export function jobRunToObservability(job) {
             { label: "Executor", value: agentLabelForJob(job) ?? "local executor" },
             { label: "Phases", value: `${job.steps.filter((step) => step.status === "succeeded").length}/${job.steps.length}` },
             { label: "Preparation", value: job.preparation ?? "-" },
-            { label: "Method", value: job.method ?? "-" },
+            { label: "Build Plan", value: buildPlanId ?? "-" },
         ],
         artifacts,
         proof: [],
@@ -561,24 +573,24 @@ export function jobRunToObservability(job) {
                 runId: job.run_id,
                 status: traceStatus,
                 deploymentId: "local-interf",
-                methodName,
+                traceName,
                 specVersion: 1,
                 executionContext: {
                     product: "Interf",
                     run_type: runType,
                     job_type: job.job_type,
                     preparation: job.preparation ?? null,
-                    method: job.method ?? null,
+                    build_plan: buildPlanId,
                     executor,
                 },
                 input: {
                     job_type: job.job_type,
                     preparation: job.preparation ?? null,
-                    method: job.method ?? null,
+                    build_plan: buildPlanId,
                     source_path: job.source_path ?? null,
                 },
                 ...(traceStatus === "completed" ? { output: job.result ?? { output_path: outputPath } } : {}),
-                ...(traceStatus === "failed" ? { error: structuredMethodError(job.error) } : {}),
+                ...(traceStatus === "failed" ? { error: structuredRunTraceError(job.error) } : {}),
                 ...(job.started_at ? { startedAt: job.started_at } : {}),
                 ...(completedAt ? { completedAt } : {}),
                 createdAt: job.created_at,

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

@@ -4,13 +4,13 @@
  * 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
+ * (Interf UI, CLI status loops) hit those endpoints multiple times
+ * per second; on instances with hundreds of build / 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
+ * is keyed by Preparation data directory so independent Preparations 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
@@ -19,13 +19,13 @@
  * lowering recompute cost.
  */
 /**
- * Per-(workspace, preparation) cache for compile run records, plus a
- * runId -> preparation index so `getCompileRun(runId)` can resolve to
+ * Per-(Preparation data directory, preparation) cache for Build run records, plus a
+ * runId -> preparation index so `getBuildRun(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;
+    private byPreparationRoot;
     /** prepDataDir -> runId -> preparation. */
     private runIndex;
     get(prepDataDir: string, preparation: string, fill: () => TRecord[], runIdOf: (record: TRecord) => string): TRecord[];
@@ -33,20 +33,20 @@ export declare class RunListingCache<TRecord> {
     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;
+    /** Drop everything for a Preparation data directory (e.g. after a reset). */
+    invalidatePreparationRoot(prepDataDir: string): void;
 }
 /**
- * Per-(workspace, preparation) readiness cache. Readiness joins compile
+ * Per-(Preparation data directory, preparation) readiness cache. Readiness joins build
  * 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;
+    private byPreparationRoot;
     get(prepDataDir: string, preparation: string, compute: () => TReadiness): TReadiness;
     invalidatePreparation(prepDataDir: string, preparation: string): void;
-    invalidateWorkspace(prepDataDir: string): void;
+    invalidatePreparationRoot(prepDataDir: string): void;
 }
 /**
  * Source-folder listing cache keyed by `(cacheKey, folderRootMtime)`.
@@ -63,12 +63,12 @@ export declare class MtimeListingCache<TList> {
     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
+ * Build Plan listing cache keyed by the joined mtimes of the
+ * bundled / user-library / Preparation-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 MethodListingCache<TList> {
+export declare class BuildPlanListingCache<TList> {
     private cache;
     get(cacheKey: string, rootPaths: string[], fill: () => TList): TList;
     invalidate(cacheKey: string): void;