@interf/compiler 0.18.0 → 0.22.0

package/dist/packages/engine/server.js

@@ -4,16 +4,16 @@ import { randomBytes } from "node:crypto";
 import { existsSync, statSync, readFileSync } from "node:fs";
 import { dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { LOCAL_SERVICE_LOOPBACK_HOSTS, LocalServiceConfigSchema, LocalServiceDiscoverySchema, LocalServiceErrorSchema, OpenPathRequestSchema, ServiceRegistryEntrySchema, } from "./lib/schema.js";
+import { LOCAL_SERVICE_LOOPBACK_HOSTS, LocalServiceConfigSchema, LocalServiceDiscoverySchema, LocalServiceErrorSchema, OpenPathRequestSchema, PreparationCreateRequestSchema, PreparationUpdateRequestSchema, ServiceRegistryEntrySchema, BuildPlanSaveRequestSchema, } from "./lib/schema.js";
 import { assertPathWithinRoot, } from "../contracts/utils/path-guards.js";
 import { createLocalServiceRuntime, } from "./runtime.js";
 import { buildLocalServiceUrl, LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, LOCAL_SERVICE_ROUTES, PREPARATION_SUBRESOURCES, } from "./routes.js";
 import { registerServiceLocally, unregisterService, } from "./service-registry.js";
 import { createStoredPreparation, deleteStoredPreparation, getStoredPreparation, listStoredPreparations, preparationWireShape, rehydratePreparations, updateStoredPreparation, } from "./preparation-store.js";
 import { clearConnection, readActiveConnection, writeConnection, } from "./connection-config.js";
-import { userMethodsRoot } from "./instance-paths.js";
-import { builtinMethodPackagePath, methodDefinitionPath, } from "../methods/package/local-methods.js";
-import { userMethodPath, userMethodExists } from "../methods/package/user-methods.js";
+import { userBuildPlansRoot } from "./instance-paths.js";
+import { builtinBuildPlanPackagePath, buildPlanDefinitionPath, } from "../build-plans/package/local-build-plans.js";
+import { installUserBuildPlan, userBuildPlanPath, userBuildPlanExists } from "../build-plans/package/user-build-plans.js";
 /** HTTP methods that require an authenticated bearer token + Origin guard. */
 const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 /** Generate a fresh per-instance bearer token. */
@@ -122,20 +122,20 @@ function isAuthorizedMutation(req, runtime) {
 function packageRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 }
-export function resolveCompilerUiStaticRoot(rootPath = packageRoot()) {
-    const distRoot = join(rootPath, "dist", "compiler-ui");
-    const sourceExportRoot = join(rootPath, "apps", "compiler-ui", "out");
+export function resolveInterfUiStaticRoot(rootPath = packageRoot()) {
+    const distRoot = join(rootPath, "dist", "interf-ui");
+    const sourceExportRoot = join(rootPath, "src", "apps", "interf-ui", "out");
     if (existsSync(join(distRoot, "index.html")))
         return distRoot;
     if (existsSync(join(sourceExportRoot, "index.html")))
         return sourceExportRoot;
     return distRoot;
 }
-function compilerUiStaticRoot() {
-    const explicit = process.env.INTERF_COMPILER_UI_STATIC_ROOT?.trim();
+function interfUiStaticRoot() {
+    const explicit = process.env.INTERF_UI_STATIC_ROOT?.trim();
     if (explicit)
         return resolve(explicit);
-    return resolveCompilerUiStaticRoot();
+    return resolveInterfUiStaticRoot();
 }
 function contentType(filePath) {
     switch (extname(filePath)) {
@@ -283,23 +283,23 @@ function safeStaticPath(root, relativePath) {
     return absolute;
 }
 /**
- * Resolve the on-disk root path for a method id. Used by the
- * `/v1/methods/<id>/files/<relpath>` route. Resolution order matches
+ * Resolve the on-disk root path for a Build Plan id. Used by the
+ * `/v1/build-plans/<id>/files/<relpath>` route. Resolution order matches
  * the runtime: preparation-draft (if a prep id is supplied) → user
- * library → built-in. Returns `null` when the method id resolves
+ * library → built-in. Returns `null` when the Build Plan id resolves
  * nowhere.
  */
-function resolveMethodPackageRoot(methodId, prepDataDir) {
+function resolveBuildPlanPackageRoot(buildPlanId, prepDataDir) {
     if (prepDataDir) {
-        const localPath = methodDefinitionPath(prepDataDir, methodId);
-        if (existsSync(join(localPath, "method.json")))
+        const localPath = buildPlanDefinitionPath(prepDataDir, buildPlanId);
+        if (existsSync(join(localPath, "build-plan.json")))
             return localPath;
     }
-    if (userMethodExists(methodId)) {
-        return userMethodPath(methodId);
+    if (userBuildPlanExists(buildPlanId)) {
+        return userBuildPlanPath(buildPlanId);
     }
-    const builtinPath = builtinMethodPackagePath(methodId);
-    if (existsSync(join(builtinPath, "method.json")))
+    const builtinPath = builtinBuildPlanPackagePath(buildPlanId);
+    if (existsSync(join(builtinPath, "build-plan.json")))
         return builtinPath;
     return null;
 }
@@ -328,9 +328,17 @@ function sendFile(res, filePath) {
         return false;
     }
 }
+function isUsableInterfUiIndexHtml(filePath) {
+    if (!existsSync(filePath))
+        return false;
+    const html = readFileSync(filePath, "utf8");
+    return html.includes("</html>")
+        && html.includes("</script>")
+        && html.includes("_next/static/");
+}
 /**
  * Reject any path that contains `..` or absolute segments — used by the
- * 0.16 file-serving endpoints (`/v1/methods/<id>/files/...`,
+ * 0.16 file-serving endpoints (`/v1/build-plans/<id>/files/...`,
  * `/v1/preparations/<id>/files/...`). The `safeStaticPath` helper used
  * by the static-asset path silently strips traversal segments; for the
  * API endpoints we want a hard reject so the response is unambiguous.
@@ -347,11 +355,15 @@ function isTraversalRelativePath(relPath) {
         return true;
     return false;
 }
-function sendCompilerUiAsset(req, res, _runtime) {
-    const staticRoot = compilerUiStaticRoot();
+function sendInterfUiAsset(req, res, _runtime) {
+    const staticRoot = interfUiStaticRoot();
     const url = parseRequestUrl(req);
     if (url.pathname === "/") {
         const indexPath = join(staticRoot, "index.html");
+        if (!isUsableInterfUiIndexHtml(indexPath)) {
+            sendText(res, 503, "Interf UI assets are invalid. Run `npm run web:build`, then restart `interf web`.\n");
+            return true;
+        }
         if (sendFile(res, indexPath))
             return true;
         sendText(res, 503, "Interf UI assets are missing. Run `npm run web:build`, then restart `interf web`.\n");
@@ -384,6 +396,78 @@ async function routeApi(req, res, runtime) {
     const method = req.method ?? "GET";
     const origin = originHeaderValue(req);
     const allowed = buildAllowedOrigins(runtime.host, runtime.port);
+    const prepDataDirsForInstance = () => {
+        const dirs = listStoredPreparations().map((prep) => prep.prepDataDir);
+        return dirs.length > 0 ? dirs : [runtime.rootPath];
+    };
+    const listInstanceRuns = () => {
+        return prepDataDirsForInstance()
+            .flatMap((prepDataDir) => runtime.listRunObservability(prepDataDir))
+            .sort((left, right) => {
+            const leftMs = Date.parse(left.started_at ?? left.created_at ?? left.finished_at ?? "");
+            const rightMs = Date.parse(right.started_at ?? right.created_at ?? right.finished_at ?? "");
+            return (Number.isFinite(rightMs) ? rightMs : 0) - (Number.isFinite(leftMs) ? leftMs : 0);
+        });
+    };
+    const findInstanceRun = (runId) => {
+        for (const prepDataDir of prepDataDirsForInstance()) {
+            const run = runtime.getRunObservability(prepDataDir, runId);
+            if (run)
+                return run;
+        }
+        return null;
+    };
+    const findInstanceJob = (runId) => {
+        for (const prepDataDir of prepDataDirsForInstance()) {
+            const job = runtime.getJob(prepDataDir, runId);
+            if (job)
+                return { job, prepDataDir };
+        }
+        return null;
+    };
+    const listInstanceBuildPlans = () => {
+        const byId = new Map();
+        for (const prepDataDir of prepDataDirsForInstance()) {
+            for (const buildPlanResource of runtime.listBuildPlans(prepDataDir)) {
+                const existing = byId.get(buildPlanResource.id);
+                if (!existing) {
+                    byId.set(buildPlanResource.id, buildPlanResource);
+                    continue;
+                }
+                const preferred = existing.built_in && !buildPlanResource.built_in
+                    ? buildPlanResource
+                    : existing;
+                byId.set(buildPlanResource.id, {
+                    ...preferred,
+                    active_for_preparations: Array.from(new Set([
+                        ...existing.active_for_preparations,
+                        ...buildPlanResource.active_for_preparations,
+                    ])).sort(),
+                });
+            }
+        }
+        return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+    };
+    const findInstanceBuildPlan = (buildPlanId) => {
+        return listInstanceBuildPlans().find((buildPlanResource) => buildPlanResource.id === buildPlanId) ?? null;
+    };
+    const listInstanceBuildPlanRuns = (buildPlanId) => {
+        return prepDataDirsForInstance()
+            .flatMap((prepDataDir) => runtime.listBuildPlanRuns(prepDataDir, buildPlanId))
+            .sort((left, right) => {
+            const leftMs = Date.parse(left.started_at ?? left.created_at ?? left.finished_at ?? "");
+            const rightMs = Date.parse(right.started_at ?? right.created_at ?? right.finished_at ?? "");
+            return (Number.isFinite(rightMs) ? rightMs : 0) - (Number.isFinite(leftMs) ? leftMs : 0);
+        });
+    };
+    const resolveInstanceBuildPlanPackageRoot = (buildPlanId) => {
+        for (const prepDataDir of prepDataDirsForInstance()) {
+            const localPath = buildPlanDefinitionPath(prepDataDir, buildPlanId);
+            if (existsSync(join(localPath, "build-plan.json")))
+                return localPath;
+        }
+        return resolveBuildPlanPackageRoot(buildPlanId);
+    };
     // CORS preflight — answered for allowed origins, refused otherwise.
     if (method === "OPTIONS") {
         if (!isOriginAllowed(origin, allowed)) {
@@ -431,7 +515,8 @@ async function routeApi(req, res, runtime) {
             resources: {
                 instance: LOCAL_SERVICE_ROUTES.instance,
                 preparations: LOCAL_SERVICE_ROUTES.preparations,
-                methods: LOCAL_SERVICE_ROUTES.methods,
+                build_plans: LOCAL_SERVICE_ROUTES.buildPlans,
+                build_runs: LOCAL_SERVICE_ROUTES.buildRuns,
                 runs: LOCAL_SERVICE_ROUTES.runs,
                 action_proposals: LOCAL_SERVICE_ROUTES.actionProposals,
                 executor: LOCAL_SERVICE_ROUTES.executor,
@@ -489,39 +574,24 @@ async function routeApi(req, res, runtime) {
     // POST /v1/preparations — create a new preparation.
     if (method === "POST" && path === LOCAL_SERVICE_ROUTES.preparations) {
         try {
-            const body = (await readJsonBody(req));
-            if (!body || typeof body !== "object") {
-                sendError(res, 400, "Request body must be a JSON object.");
-                return true;
-            }
-            if (!body.id || typeof body.id !== "string") {
-                sendError(res, 400, "Missing required field: id");
-                return true;
-            }
-            if (!body.method_id || typeof body.method_id !== "string") {
-                sendError(res, 400, "Missing required field: method_id");
-                return true;
-            }
-            if (!body.source || typeof body.source !== "object" || !body.source.locator) {
-                sendError(res, 400, "Missing required field: source.locator");
-                return true;
-            }
+            const body = PreparationCreateRequestSchema.parse(await readJsonBody(req));
             // TODO(cloud): activate remote-folder validator branch when the
             // cloud variant lands. The local binary only knows how to read
             // bytes from a local path; a `remote-folder` binding requires
             // the cloud variant's per-account object-storage mount layer.
             // Until then, reject any kind other than `local-folder` so the
             // wire shape and runtime stay consistent.
-            const requestedKind = typeof body.source.kind === "string" ? body.source.kind : "local-folder";
-            if (requestedKind !== "local-folder") {
-                sendError(res, 400, `Unsupported source kind: ${requestedKind}. The local engine only accepts local-folder bindings; remote-folder requires the cloud variant.`);
+            if (body.source.kind !== "local-folder") {
+                sendError(res, 400, `Unsupported source kind: ${body.source.kind}. The local engine only accepts local-folder bindings; remote-folder requires the cloud variant.`);
                 return true;
             }
             const stored = createStoredPreparation(runtime, {
                 id: body.id,
                 source: { kind: "local-folder", locator: body.source.locator },
-                method_id: body.method_id,
+                build_plan_id: body.build_plan_id,
                 about: body.about,
+                requested_artifacts: body.requested_artifacts,
+                source_profile: body.source_profile,
                 checks: body.checks,
                 max_attempts: body.max_attempts,
                 max_loops: body.max_loops,
@@ -551,20 +621,26 @@ async function routeApi(req, res, runtime) {
         if (subPath === "") {
             // Bare /v1/preparations/{id}
             if (method === "GET") {
-                sendJson(res, 200, preparationWireShape(storedPrep));
+                const preparation = runtime.getPreparation(storedPrep.prepDataDir, storedPrep.id);
+                sendJson(res, 200, preparation
+                    ? {
+                        ...preparation,
+                        source: storedPrep.source,
+                        about: storedPrep.about,
+                        config_path: storedPrep.configPath,
+                    }
+                    : preparationWireShape(storedPrep));
                 return true;
             }
             if (method === "PATCH") {
                 try {
-                    const body = (await readJsonBody(req));
-                    if (!body || typeof body !== "object") {
-                        sendError(res, 400, "Request body must be a JSON object.");
-                        return true;
-                    }
+                    const body = PreparationUpdateRequestSchema.parse(await readJsonBody(req));
                     const updated = updateStoredPreparation(decodedPrepId, {
-                        method_id: body.method_id,
+                        build_plan_id: body.build_plan_id,
                         about: body.about,
                         ...(body.checks !== undefined ? { checks: body.checks } : {}),
+                        ...(body.requested_artifacts !== undefined ? { requested_artifacts: body.requested_artifacts } : {}),
+                        ...(body.source_profile !== undefined ? { source_profile: body.source_profile } : {}),
                     });
                     sendJson(res, 200, preparationWireShape(updated));
                 }
@@ -579,10 +655,10 @@ async function routeApi(req, res, runtime) {
                 return true;
             }
         }
-        else if (subPath === PREPARATION_SUBRESOURCES.compileRuns) {
+        else if (subPath === PREPARATION_SUBRESOURCES.buildRuns) {
             if (method === "POST") {
-                if (!storedPrep.methodId) {
-                    sendError(res, 400, `Preparation ${storedPrep.id} has no method bound. Set one via PATCH /v1/preparations/${storedPrep.id} { "method_id": "<id>" } before compiling.`);
+                if (!storedPrep.buildPlanId) {
+                    sendError(res, 400, `Preparation ${storedPrep.id} has no Build Plan selected. Select one via PATCH /v1/preparations/${storedPrep.id} { "build_plan_id": "<id>" } before building.`);
                     return true;
                 }
                 try {
@@ -594,18 +670,18 @@ async function routeApi(req, res, runtime) {
                         : idempotencyKeyRaw;
                     const trimmedKey = typeof idempotencyKey === "string" ? idempotencyKey.trim() : "";
                     const dedupedRunId = trimmedKey
-                        ? runtime.findIdempotentCompileRun(storedPrep.prepDataDir, trimmedKey)
+                        ? runtime.findIdempotentBuildRun(storedPrep.prepDataDir, trimmedKey)
                         : null;
                     if (dedupedRunId) {
-                        const existing = runtime.getCompileRun(storedPrep.prepDataDir, dedupedRunId);
+                        const existing = runtime.getBuildRun(storedPrep.prepDataDir, dedupedRunId);
                         if (existing) {
                             sendJson(res, 200, existing);
                             return true;
                         }
                     }
-                    const resource = await runtime.createCompileRun(storedPrep.prepDataDir, request);
+                    const resource = await runtime.createBuildRun(storedPrep.prepDataDir, request);
                     if (trimmedKey) {
-                        runtime.recordIdempotentCompileRun(storedPrep.prepDataDir, trimmedKey, resource.run.run_id);
+                        runtime.recordIdempotentBuildRun(storedPrep.prepDataDir, trimmedKey, resource.run.run_id);
                     }
                     sendJson(res, 201, resource);
                 }
@@ -617,8 +693,8 @@ async function routeApi(req, res, runtime) {
         }
         else if (subPath === PREPARATION_SUBRESOURCES.verifyRuns) {
             if (method === "POST") {
-                if (!storedPrep.methodId) {
-                    sendError(res, 400, `Preparation ${storedPrep.id} has no method bound. Set one via PATCH /v1/preparations/${storedPrep.id} { "method_id": "<id>" } before verifying.`);
+                if (!storedPrep.buildPlanId) {
+                    sendError(res, 400, `Preparation ${storedPrep.id} has no Build Plan selected. Select one via PATCH /v1/preparations/${storedPrep.id} { "build_plan_id": "<id>" } before verifying.`);
                     return true;
                 }
                 try {
@@ -633,11 +709,11 @@ async function routeApi(req, res, runtime) {
                 return true;
             }
         }
-        else if (subPath === PREPARATION_SUBRESOURCES.methodAuthoringRuns) {
+        else if (subPath === PREPARATION_SUBRESOURCES.buildPlanDraftRuns) {
             if (method === "POST") {
                 try {
                     const body = (await readJsonBody(req));
-                    const job = await runtime.createMethodAuthoringRun(storedPrep.prepDataDir, body);
+                    const job = await runtime.createBuildPlanAuthoringRun(storedPrep.prepDataDir, body);
                     sendJson(res, 202, job);
                 }
                 catch (error) {
@@ -646,11 +722,11 @@ async function routeApi(req, res, runtime) {
                 return true;
             }
         }
-        else if (subPath === PREPARATION_SUBRESOURCES.methodImprovementRuns) {
+        else if (subPath === PREPARATION_SUBRESOURCES.buildPlanImprovementRuns) {
             if (method === "POST") {
                 try {
                     const body = (await readJsonBody(req));
-                    const job = await runtime.createMethodAuthoringRun(storedPrep.prepDataDir, body, "method-improvement");
+                    const job = await runtime.createBuildPlanAuthoringRun(storedPrep.prepDataDir, body, "build-plan-improvement");
                     sendJson(res, 202, job);
                 }
                 catch (error) {
@@ -688,7 +764,7 @@ async function routeApi(req, res, runtime) {
             if (method === "POST") {
                 try {
                     const body = (await readJsonBody(req));
-                    const request = { preparation: storedPrep.id, scope: "compile", ...(body ?? {}) };
+                    const request = { preparation: storedPrep.id, scope: "build", ...(body ?? {}) };
                     const result = runtime.applyReset(storedPrep.prepDataDir, request);
                     sendJson(res, 200, result);
                 }
@@ -707,7 +783,7 @@ async function routeApi(req, res, runtime) {
         }
         else if (subPath === PREPARATION_SUBRESOURCES.runs) {
             if (method === "GET") {
-                const runs = runtime.listCompileRunsForPreparation(storedPrep.prepDataDir, storedPrep.id);
+                const runs = runtime.listBuildRunsForPreparation(storedPrep.prepDataDir, storedPrep.id);
                 sendJson(res, 200, { runs });
                 return true;
             }
@@ -720,11 +796,11 @@ async function routeApi(req, res, runtime) {
                 return true;
             }
         }
-        else if (subPath === PREPARATION_SUBRESOURCES.portableContext) {
+        else if (subPath === PREPARATION_SUBRESOURCES.verifiableContext) {
             if (method === "GET") {
-                const context = runtime.getPortableContext(storedPrep.prepDataDir, storedPrep.id);
+                const context = runtime.getVerifiableContext(storedPrep.prepDataDir, storedPrep.id);
                 if (!context)
-                    sendError(res, 404, "Portable context not found.");
+                    sendError(res, 404, "Verifiable context not found.");
                 else
                     sendJson(res, 200, context);
                 return true;
@@ -732,7 +808,7 @@ async function routeApi(req, res, runtime) {
         }
         else if (subPath.startsWith(`${PREPARATION_SUBRESOURCES.files}/`)) {
             // GET /v1/preparations/<id>/files/<relpath> — read-only file
-            // serving inside the prep's portable-context root. Used by the
+            // serving inside the prep's verifiable-context root. Used by the
             // locator pattern's `api-served` kind.
             if (method === "GET") {
                 const rawRelPath = subPath.slice(PREPARATION_SUBRESOURCES.files.length + 1);
@@ -745,12 +821,12 @@ async function routeApi(req, res, runtime) {
                     return true;
                 }
                 if (isTraversalRelativePath(relPath)) {
-                    sendError(res, 400, "File path escapes portable-context root.");
+                    sendError(res, 400, "File path escapes verifiable-context root.");
                     return true;
                 }
-                const safePath = safeStaticPath(storedPrep.portableContextPath, relPath);
+                const safePath = safeStaticPath(storedPrep.verifiableContextPath, relPath);
                 if (!safePath) {
-                    sendError(res, 400, "File path escapes portable-context root.");
+                    sendError(res, 400, "File path escapes verifiable-context root.");
                     return true;
                 }
                 if (!sendFile(res, safePath)) {
@@ -761,7 +837,7 @@ async function routeApi(req, res, runtime) {
         }
         else if (subPath.startsWith(`${PREPARATION_SUBRESOURCES.artifacts}/`)) {
             // GET /v1/preparations/<id>/artifacts/<artifact-id> — per-Artifact
-            // status from the latest compile run. 0.17.
+            // status from the latest Build run.
             if (method === "GET") {
                 const rawArtifactId = subPath.slice(PREPARATION_SUBRESOURCES.artifacts.length + 1);
                 let artifactId;
@@ -786,63 +862,75 @@ async function routeApi(req, res, runtime) {
         return true;
     }
     // ─────────────────────────────────────────────────────────────────────────
-    // Method resources — preparation-independent (workspace draft + user lib + bundled).
+    // Build Plan resources — preparation-independent (Preparation-local + user lib + bundled).
     // ─────────────────────────────────────────────────────────────────────────
-    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.methods) {
-        // The runtime needs SOME prep data dir to discover preparation-draft methods.
-        // Fall back to the first registered preparation (if any) so user-library
-        // and bundled methods still surface even when no preparation has drafts.
-        const firstPrep = listStoredPreparations()[0];
-        sendJson(res, 200, { methods: runtime.listMethods(firstPrep?.prepDataDir ?? runtime.rootPath) });
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.buildPlans) {
+        sendJson(res, 200, { build_plans: listInstanceBuildPlans() });
         return true;
     }
-    const methodMatch = path.match(/^\/v1\/methods\/([^/]+)$/);
-    if (method === "GET" && methodMatch?.[1]) {
-        const firstPrep = listStoredPreparations()[0];
-        const methodResource = runtime.getMethod(firstPrep?.prepDataDir ?? runtime.rootPath, decodeURIComponent(methodMatch[1]));
-        if (!methodResource)
-            sendError(res, 404, "Method not found.");
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.buildPlans) {
+        try {
+            const body = BuildPlanSaveRequestSchema.parse(await readJsonBody(req));
+            const installed = installUserBuildPlan({
+                sourceDir: body.source_path,
+                id: body.id,
+                overwrite: body.overwrite,
+            });
+            sendJson(res, 201, {
+                build_plan_id: installed.id,
+                installed: true,
+                path: installed.path,
+            });
+        }
+        catch (error) {
+            sendError(res, 400, error instanceof Error ? error.message : String(error));
+        }
+        return true;
+    }
+    const buildPlanMatch = path.match(/^\/v1\/build-plans\/([^/]+)$/);
+    if (method === "GET" && buildPlanMatch?.[1]) {
+        const buildPlanResource = findInstanceBuildPlan(decodeURIComponent(buildPlanMatch[1]));
+        if (!buildPlanResource)
+            sendError(res, 404, "Build Plan not found.");
         else
-            sendJson(res, 200, methodResource);
+            sendJson(res, 200, buildPlanResource);
         return true;
     }
-    const methodRunsMatch = path.match(/^\/v1\/methods\/([^/]+)\/runs$/);
-    if (method === "GET" && methodRunsMatch?.[1]) {
-        const firstPrep = listStoredPreparations()[0];
-        const runs = runtime.listMethodRuns(firstPrep?.prepDataDir ?? runtime.rootPath, decodeURIComponent(methodRunsMatch[1]));
+    const buildPlanRunsMatch = path.match(/^\/v1\/build-plans\/([^/]+)\/runs$/);
+    if (method === "GET" && buildPlanRunsMatch?.[1]) {
+        const runs = listInstanceBuildPlanRuns(decodeURIComponent(buildPlanRunsMatch[1]));
         sendJson(res, 200, { runs });
         return true;
     }
-    // GET /v1/methods/<id>/files/<relpath> — read-only file serving inside
-    // the method root. Used by the locator pattern's `api-served` kind so
+    // GET /v1/build-plans/<id>/files/<relpath> — read-only file serving inside
+    // the Build Plan package root. Used by the locator pattern's `api-served` kind so
     // the UI can render SKILL.md / contract files in a side drawer over a
     // remote engine. Resolution: prep-draft (when first prep exists) →
     // user library → built-in. Path-guard rejects any traversal outside
     // the resolved root.
-    const methodFilesMatch = path.match(/^\/v1\/methods\/([^/]+)\/files\/(.+)$/);
-    if (method === "GET" && methodFilesMatch?.[1] && methodFilesMatch[2]) {
-        const methodId = decodeURIComponent(methodFilesMatch[1]);
+    const buildPlanFilesMatch = path.match(/^\/v1\/build-plans\/([^/]+)\/files\/(.+)$/);
+    if (method === "GET" && buildPlanFilesMatch?.[1] && buildPlanFilesMatch[2]) {
+        const buildPlanId = decodeURIComponent(buildPlanFilesMatch[1]);
         let relPath;
         try {
-            relPath = decodeURIComponent(methodFilesMatch[2]);
+            relPath = decodeURIComponent(buildPlanFilesMatch[2]);
         }
         catch {
             sendError(res, 400, "File path is not valid URI-encoded UTF-8.");
             return true;
         }
         if (isTraversalRelativePath(relPath)) {
-            sendError(res, 400, "File path escapes method root.");
+            sendError(res, 400, "File path escapes Build Plan root.");
             return true;
         }
-        const firstPrep = listStoredPreparations()[0];
-        const root = resolveMethodPackageRoot(methodId, firstPrep?.prepDataDir);
+        const root = resolveInstanceBuildPlanPackageRoot(buildPlanId);
         if (!root) {
-            sendError(res, 404, `Method not found: ${methodId}`);
+            sendError(res, 404, `Build Plan not found: ${buildPlanId}`);
             return true;
         }
         const safePath = safeStaticPath(root, relPath);
         if (!safePath) {
-            sendError(res, 400, "File path escapes method root.");
+            sendError(res, 400, "File path escapes Build Plan root.");
             return true;
         }
         if (!sendFile(res, safePath)) {
@@ -851,18 +939,16 @@ async function routeApi(req, res, runtime) {
         return true;
     }
     // ─────────────────────────────────────────────────────────────────────────
-    // Run observability — instance-wide. Each run record carries a workspace,
-    // so the runtime takes a "first prep" hint to scan registered preparations.
+    // Run observability — instance-wide. The runtime takes a "first prep" hint
+    // to scan registered Preparations.
     // ─────────────────────────────────────────────────────────────────────────
     if (method === "GET" && path === LOCAL_SERVICE_ROUTES.runs) {
-        const firstPrep = listStoredPreparations()[0];
-        sendJson(res, 200, { runs: runtime.listRunObservability(firstPrep?.prepDataDir ?? runtime.rootPath) });
+        sendJson(res, 200, { runs: listInstanceRuns() });
         return true;
     }
     const observableRunMatch = path.match(/^\/v1\/runs\/([^/]+)$/);
     if (method === "GET" && observableRunMatch?.[1]) {
-        const firstPrep = listStoredPreparations()[0];
-        const run = runtime.getRunObservability(firstPrep?.prepDataDir ?? runtime.rootPath, decodeURIComponent(observableRunMatch[1]));
+        const run = findInstanceRun(decodeURIComponent(observableRunMatch[1]));
         if (!run)
             sendError(res, 404, "Run not found.");
         else
@@ -910,53 +996,53 @@ async function routeApi(req, res, runtime) {
         }
     }
     // ─────────────────────────────────────────────────────────────────────────
-    // Compile-run sub-resources (instance-wide; runs are addressable by run_id).
+    // Build-run sub-resources (instance-wide; runs are addressable by run_id).
     // ─────────────────────────────────────────────────────────────────────────
-    const compileRunMatch = path.match(/^\/v1\/compile-runs\/([^/]+)(?:\/([^/]+))?$/);
-    if (compileRunMatch?.[1]) {
-        const runId = decodeURIComponent(compileRunMatch[1]);
-        const child = compileRunMatch[2];
+    const buildRunMatch = path.match(/^\/v1\/build-runs\/([^/]+)(?:\/([^/]+))?$/);
+    if (buildRunMatch?.[1]) {
+        const runId = decodeURIComponent(buildRunMatch[1]);
+        const child = buildRunMatch[2];
         const firstPrep = listStoredPreparations()[0];
         const prepDataDir = firstPrep?.prepDataDir ?? runtime.rootPath;
         if (method === "GET" && !child) {
-            const run = runtime.getCompileRun(prepDataDir, runId);
+            const run = runtime.getBuildRun(prepDataDir, runId);
             if (!run)
-                sendError(res, 404, "Compile run not found.");
+                sendError(res, 404, "Build run not found.");
             else
                 sendJson(res, 200, run);
             return true;
         }
         if (method === "GET" && child === "events") {
-            const events = runtime.getCompileRunEvents(prepDataDir, runId);
+            const events = runtime.getBuildRunEvents(prepDataDir, runId);
             if (!events)
-                sendError(res, 404, "Compile run not found.");
+                sendError(res, 404, "Build run not found.");
             else
                 sendJson(res, 200, { events });
             return true;
         }
         if (method === "GET" && child === "proof") {
-            const proof = runtime.getCompileRunProof(prepDataDir, runId);
+            const proof = runtime.getBuildRunProof(prepDataDir, runId);
             if (!proof)
-                sendError(res, 404, "Compile run not found.");
+                sendError(res, 404, "Build run not found.");
             else
                 sendJson(res, 200, { proof });
             return true;
         }
         if (method === "GET" && child === "artifacts") {
-            const artifacts = runtime.getCompileRunArtifacts(prepDataDir, runId);
+            const artifacts = runtime.getBuildRunArtifacts(prepDataDir, runId);
             if (!artifacts)
-                sendError(res, 404, "Compile run not found.");
+                sendError(res, 404, "Build run not found.");
             else
                 sendJson(res, 200, { artifacts });
             return true;
         }
         if (method === "POST" && child === "cancel") {
-            const existing = runtime.getCompileRun(prepDataDir, runId);
+            const existing = runtime.getBuildRun(prepDataDir, runId);
             if (!existing) {
-                sendError(res, 404, "Compile run not found.");
+                sendError(res, 404, "Build run not found.");
                 return true;
             }
-            const result = runtime.cancelCompileRun(runId);
+            const result = runtime.cancelBuildRun(runId);
             sendJson(res, 200, result);
             return true;
         }
@@ -975,18 +1061,16 @@ async function routeApi(req, res, runtime) {
     if (jobMatch?.[1]) {
         const runId = decodeURIComponent(jobMatch[1]);
         const child = jobMatch[2];
-        const firstPrep = listStoredPreparations()[0];
-        const prepDataDir = firstPrep?.prepDataDir ?? runtime.rootPath;
+        const found = findInstanceJob(runId);
         if (method === "GET" && !child) {
-            const job = runtime.getJob(prepDataDir, runId);
-            if (!job)
+            if (!found)
                 sendError(res, 404, "Job run not found.");
             else
-                sendJson(res, 200, job);
+                sendJson(res, 200, found.job);
             return true;
         }
         if (method === "GET" && child === "events") {
-            const events = runtime.getJobEvents(prepDataDir, runId);
+            const events = found ? runtime.getJobEvents(found.prepDataDir, runId) : null;
             if (!events)
                 sendError(res, 404, "Job run not found.");
             else
@@ -1108,8 +1192,8 @@ async function routeApi(req, res, runtime) {
         const body = OpenPathRequestSchema.parse(await readJsonBody(req));
         // Permit opening:
         //  - any registered preparation root or its bound source folder
-        //  - the user method library at `~/.interf/methods/`
-        //  - the bundled built-in method root inside the installed package
+        //  - the user buildPlan library at `~/.interf/build-plans/`
+        //  - the bundled built-in buildPlan root inside the installed package
         //    (so SKILL.md / contract files in `interf-default` open correctly)
         const allowedRoots = [];
         for (const stored of listStoredPreparations()) {
@@ -1117,8 +1201,8 @@ async function routeApi(req, res, runtime) {
             if (stored.source.locator)
                 allowedRoots.push(stored.source.locator);
         }
-        allowedRoots.push(userMethodsRoot());
-        allowedRoots.push(packageRoot()); // covers <pkg>/builtin-methods/...
+        allowedRoots.push(userBuildPlansRoot());
+        allowedRoots.push(packageRoot()); // covers <pkg>/public-repo/build-plans/...
         const openedPath = await openLocalPath(allowedRoots, body.path);
         sendJson(res, 202, { opened: true, path: openedPath });
         return true;
@@ -1131,7 +1215,7 @@ export function createLocalServiceServer(runtime) {
             // Pre-attach a CORS context so static-asset GETs and the 404
             // fallback emit the right headers even before routeApi has a
             // chance to set its own. The OPTIONS preflight handling and the
-            // mutating-method guards still happen inside routeApi.
+            // mutating-buildPlan guards still happen inside routeApi.
             const origin = originHeaderValue(req);
             const allowed = buildAllowedOrigins(runtime.host, runtime.port);
             attachResponseContext(res, { cors: corsHeadersFor(origin, allowed) });
@@ -1139,7 +1223,7 @@ export function createLocalServiceServer(runtime) {
                 const routed = await routeApi(req, res, runtime);
                 if (routed)
                     return;
-                if (sendCompilerUiAsset(req, res, runtime))
+                if (sendInterfUiAsset(req, res, runtime))
                     return;
                 sendText(res, 404, "Not found.\n");
             }
@@ -1241,8 +1325,8 @@ export async function startLocalService(options = {}) {
     if (options.tokenValidator) {
         runtime.setTokenValidator(options.tokenValidator);
     }
-    // Rehydrate 0.13 preparations as synthetic workspaces so subsequent
-    // compile / test / readiness calls find them after a service restart.
+    // Rehydrate saved preparations so subsequent
+    // build / test / readiness calls find them after a service restart.
     try {
         rehydratePreparations(runtime);
     }
@@ -1265,7 +1349,6 @@ export async function startLocalService(options = {}) {
                 port: boundPort,
                 url,
                 started_at: startedAt,
-                workspaces: runtime.registeredPreparationSnapshots(),
                 ...(authToken ? { auth_token: authToken } : {}),
             }));
         }
@@ -1275,8 +1358,8 @@ export async function startLocalService(options = {}) {
     };
     writeRegistryEntry();
     runtime.setOnRegistryChanged(writeRegistryEntry);
-    // Write the 0.13 single-record CLI connection so `interf prep`,
-    // `interf compile`, etc. can find this engine without a pointer file.
+    // Write the single-record CLI connection so `interf prep`,
+    // `interf build`, etc. can find this engine without a pointer file.
     try {
         writeConnection({ url, auth_token: authToken });
     }