@interf/compiler 0.18.0 → 0.21.0

package/dist/packages/engine/runtime.js

@@ -16,7 +16,7 @@ import { findSourcePreparationConfig, fingerprintReadinessChecks, listSourcePrep
 import { listSourceFolderChoices, } from "../project/source-folders.js";
 import { asPreparationDataDir, preparationPortableContextPath, userMethodsRoot, preparationConfigPath, preparationMethodPackagePath, preparationMethodsRoot, } from "../contracts/lib/preparation-paths.js";
 import { getCompiledMethod, listCompiledMethodChoices, } from "../methods/package/method-definitions.js";
-import { computeArtifactStatuses, } from "./compile/artifact-status.js";
+import { aggregateArtifactVerdict, computeArtifactStatuses, } from "./compile/artifact-status.js";
 import { JsonlBillingEventSink, buildCompilationEventsForRun, defaultBillingEventLogPath, } from "./compile/billing-events.js";
 import { methodDefinitionPath, resolveMethodPackageSourcePath, } from "../methods/package/local-methods.js";
 import { seedLocalMethodPackageFromBase, } from "../methods/package/interf-method-package.js";
@@ -30,14 +30,33 @@ import { ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema,
 import { buildLocalServiceUrl, } from "./routes.js";
 import { MethodAuthoringActionValuesSchema, PreparationSetupActionValuesSchema, } from "./action-values.js";
 import { compileRunToObservability, jobRunToObservability, verifyRunToObservability, uniqueArtifacts, } from "./run-observability.js";
+import { artifactRequirementsFromRequestedArtifacts } from "./requested-artifacts.js";
 /** TTL for `POST /v1/compile-runs` idempotency-key dedupe entries. */
 const IDEMPOTENCY_TTL_MS = 60 * 60 * 1000;
 /** Idempotency cache size at which to schedule an opportunistic prune. */
 const IDEMPOTENCY_PRUNE_THRESHOLD = 64;
 const INTERRUPTED_COMPILE_RUN_MESSAGE = "Compile run interrupted because the Interf engine stopped before the run reached a terminal state.";
+const INTERRUPTED_JOB_RUN_MESSAGE = "Job interrupted because the Interf engine stopped before the job reached a terminal state.";
 function isTerminalCompileRunStatus(status) {
     return status === "succeeded" || status === "failed" || status === "cancelled";
 }
+function isTerminalJobStatus(status) {
+    return status === "succeeded" || status === "failed" || status === "cancelled";
+}
+function countsFromCompiledState(state) {
+    const counts = {};
+    for (const stage of Object.values(state.stages ?? {})) {
+        for (const [key, value] of Object.entries(stage.counts ?? {})) {
+            if (Number.isFinite(value))
+                counts[key] = Math.max(counts[key] ?? 0, value);
+        }
+        for (const [key, value] of Object.entries(stage.artifact_counts ?? {})) {
+            if (Number.isFinite(value))
+                counts[key] = Math.max(counts[key] ?? 0, value);
+        }
+    }
+    return counts;
+}
 export class LocalServiceRuntime {
     host;
     port;
@@ -173,6 +192,7 @@ export class LocalServiceRuntime {
         };
         this.preparationContexts.set(resolved, context);
         this.finalizeInterruptedCompileRuns(resolved);
+        this.finalizeInterruptedJobRuns(resolved);
         this.onRegistryChanged?.();
         return context;
     }
@@ -342,6 +362,13 @@ export class LocalServiceRuntime {
         const compileRun = this.listCompileRunsForPreparation(prepDataDir, preparation.name)[0] ?? null;
         const verifyRun = this.listVerifyRunsForPreparation(prepDataDir, preparation.name)[0] ?? null;
         const readinessRun = this.readLatestReadinessRun(prepDataDir, preparation.name);
+        const artifactStatuses = compileRun?.artifacts ?? [];
+        const hasArtifactContract = artifactStatuses.length > 0;
+        const artifactVerdict = aggregateArtifactVerdict(artifactStatuses);
+        const artifactFailures = artifactStatuses.filter((artifact) => artifact.status !== "ready");
+        const artifactProofs = artifactStatuses.flatMap((artifact) => artifact.proofs ?? []);
+        const requiredArtifactProofs = artifactProofs.filter((proof) => proof.required !== false);
+        const passedArtifactProofs = requiredArtifactProofs.filter((proof) => proof.passed);
         const configuredChecks = preparation.checks.length;
         const currentFingerprint = configuredChecks > 0 ? fingerprintReadinessChecks(preparation.checks) : null;
         const readinessRunFingerprint = readinessRun?.checks_fingerprint ?? null;
@@ -407,13 +434,25 @@ export class LocalServiceRuntime {
                 artifact_path: contextReady ? compiledPath : null,
             },
             compileCheck,
+            {
+                gate: "artifact-checks",
+                ok: !hasArtifactContract || artifactVerdict === "ready",
+                status: !hasArtifactContract
+                    ? "not-configured"
+                    : artifactVerdict === "ready" ? "ready" : "not-ready",
+                summary: !hasArtifactContract
+                    ? "No Artifacts are declared by the selected Build Plan."
+                    : artifactVerdict === "ready"
+                        ? `${artifactStatuses.length} Artifact${artifactStatuses.length === 1 ? "" : "s"} ready; ${passedArtifactProofs.length}/${requiredArtifactProofs.length} required Artifact check${requiredArtifactProofs.length === 1 ? "" : "s"} passed.`
+                        : `${artifactFailures.length} Artifact${artifactFailures.length === 1 ? "" : "s"} not ready.`,
+            },
             {
                 gate: "readiness-checks",
-                ok: configuredChecks > 0,
+                ok: true,
                 status: configuredChecks > 0 ? "built" : "not-configured",
                 summary: configuredChecks > 0
                     ? `${configuredChecks} readiness check${configuredChecks === 1 ? "" : "s"} configured.`
-                    : "No readiness checks are configured.",
+                    : "No optional readiness checks are configured.",
             },
             {
                 gate: "checks-current",
@@ -433,10 +472,12 @@ export class LocalServiceRuntime {
                 return "failed";
             if (!compileRun || !contextReady)
                 return "not-built";
-            if (configuredChecks === 0)
-                return "not-configured";
+            if (hasArtifactContract && artifactVerdict !== "ready")
+                return "not-ready";
             if (checksStale)
                 return "stale";
+            if (configuredChecks === 0)
+                return hasArtifactContract ? "ready" : "built";
             if (!contextResult)
                 return "built";
             return contextResult.total > 0 && contextResult.passed === contextResult.total ? "ready" : "not-ready";
@@ -535,7 +576,7 @@ export class LocalServiceRuntime {
         // method roots. Key the cache off mtimes for the three roots; if
         // any of them changes (a new local Method, an edit to the user
         // library, etc.) the cache misses and we re-resolve.
-        const builtinRoot = join(PACKAGE_ROOT, "builtin-methods");
+        const builtinRoot = join(PACKAGE_ROOT, "public-repo", "methods");
         const localRoot = preparationMethodsRoot(asPreparationDataDir(prepDataDir));
         const userRoot = userMethodsRoot();
         return this.methodListingCache.get(prepDataDir, [builtinRoot, localRoot, userRoot], () => {
@@ -550,6 +591,8 @@ export class LocalServiceRuntime {
                     path: resolveMethodPackageSourcePath(prepDataDir, method.id) ?? method.id,
                     label: method.label,
                     hint: method.hint,
+                    purpose: method.purpose,
+                    inputs: method.inputs,
                     source_kind: method.scope === "builtin" ? "builtin" : "local",
                     built_in: method.scope === "builtin",
                     active_for_preparations: activeForPreparations,
@@ -754,7 +797,10 @@ export class LocalServiceRuntime {
     }
     listRunObservability(prepDataDir) {
         return [
-            ...this.listCompileRuns(prepDataDir).map((resource) => compileRunToObservability(resource.run)),
+            ...this.listCompileRuns(prepDataDir).map((resource) => compileRunToObservability({
+                ...resource.run,
+                readiness: this.getReadiness(prepDataDir, resource.run.preparation),
+            })),
             ...this.listVerifyRuns(prepDataDir).map(verifyRunToObservability),
             ...this.listJobs(prepDataDir).map(jobRunToObservability),
         ].sort((left, right) => {
@@ -767,7 +813,7 @@ export class LocalServiceRuntime {
         return this.listRunObservability(prepDataDir).find((run) => run.run_id === runId) ?? null;
     }
     /**
-     * Method-scoped runs: every method-authoring or method-improvement job
+     * Method Activity runs: every method-authoring or method-improvement job
      * whose `method` matches `methodId`. Surfaced through
      * `GET /v1/methods/<id>/runs` so Method Detail can show the full audit
      * trail of authoring + improvement work for a Method.
@@ -966,11 +1012,16 @@ export class LocalServiceRuntime {
     applyPreparationSetup(prepDataDir, requestValue) {
         const request = PreparationSetupCreateRequestSchema.parse(requestValue);
         const preparationConfig = request.preparation;
-        const methodId = methodIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_METHOD_ID;
-        const normalizedPreparationConfig = {
-            ...preparationConfig,
-            method: methodId,
-        };
+        const methodId = methodIdForSourcePreparationConfig(preparationConfig);
+        if (request.setup_mode === "select-method" && !methodId) {
+            throw new Error("Build Plan is required when selecting a Build Plan for a Preparation.");
+        }
+        const normalizedPreparationConfig = methodId
+            ? { ...preparationConfig, method: methodId }
+            : (() => {
+                const { method: _method, ...withoutMethod } = preparationConfig;
+                return withoutMethod;
+            })();
         const sourceFolderPath = resolveSourcePreparationPath(prepDataDir, normalizedPreparationConfig);
         if (!existsSync(sourceFolderPath) || !statSync(sourceFolderPath).isDirectory()) {
             throw new Error(`Source folder "${preparationConfig.path}" is not available.`);
@@ -989,14 +1040,16 @@ export class LocalServiceRuntime {
             version: 1,
             operation,
             preparation: normalizedPreparationConfig.name,
-            method: methodId,
+            method: methodId ?? null,
             source_folder_path: sourceFolderPath,
             config_path: preparationConfigPath(asPreparationDataDir(prepDataDir)),
             portable_context_path: preparationPortableContextPath(asPreparationDataDir(prepDataDir), normalizedPreparationConfig.name),
             changed: true,
             message: operation === "select-method"
-                ? `Preparation ${normalizedPreparationConfig.name} now uses Method ${methodId}.`
-                : `Preparation ${normalizedPreparationConfig.name} is saved.`,
+                ? `Preparation ${normalizedPreparationConfig.name} now uses Build Plan ${methodId}.`
+                : methodId
+                    ? `Preparation ${normalizedPreparationConfig.name} is saved with Build Plan ${methodId}.`
+                    : `Preparation ${normalizedPreparationConfig.name} is saved. Draft or select a Build Plan before compiling.`,
         });
     }
     applyPreparationChange(prepDataDir, requestValue) {
@@ -1051,7 +1104,17 @@ export class LocalServiceRuntime {
         });
     }
     async createMethodAuthoringRun(prepDataDir, requestValue, jobType = "method-authoring") {
-        const request = MethodAuthoringCreateRequestSchema.parse(requestValue);
+        const parsedRequest = MethodAuthoringCreateRequestSchema.parse(requestValue);
+        const savedPreparation = parsedRequest.preparation
+            ? findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), parsedRequest.preparation)
+            : null;
+        const request = {
+            ...parsedRequest,
+            requested_artifacts: parsedRequest.requested_artifacts.length > 0
+                ? parsedRequest.requested_artifacts
+                : savedPreparation?.requested_artifacts ?? [],
+            source_profile: parsedRequest.source_profile ?? savedPreparation?.source_profile ?? null,
+        };
         const isImprovement = jobType === "method-improvement";
         const job = this.createJobRun(prepDataDir, {
             job_type: jobType,
@@ -1068,6 +1131,7 @@ export class LocalServiceRuntime {
                         preparation: request.preparation ?? null,
                         source_folder_path: request.source_folder_path,
                         checks: request.checks.length,
+                        requested_artifacts: request.requested_artifacts.length,
                     },
                 },
                 {
@@ -1077,6 +1141,7 @@ export class LocalServiceRuntime {
                         method_id: request.method_id,
                         label: request.label,
                         task_prompt: request.task_prompt,
+                        requested_artifacts: request.requested_artifacts.length,
                         artifact_requirements: request.artifact_requirements.length,
                     },
                 },
@@ -1097,6 +1162,7 @@ export class LocalServiceRuntime {
                 preparation: request.preparation ?? null,
                 source_folder_path: request.source_folder_path,
                 checks: request.checks.length,
+                requested_artifacts: request.requested_artifacts.length,
             },
         });
         this.appendJobRunEvent(prepDataDir, job.run_id, {
@@ -1106,6 +1172,7 @@ export class LocalServiceRuntime {
             output: {
                 source_folder_path: request.source_folder_path,
                 checks: request.checks.length,
+                requested_artifacts: request.requested_artifacts.length,
             },
         });
         this.appendJobRunEvent(prepDataDir, job.run_id, {
@@ -1116,6 +1183,7 @@ export class LocalServiceRuntime {
                 method_id: request.method_id,
                 label: request.label,
                 task_prompt: request.task_prompt,
+                requested_artifacts: request.requested_artifacts.length,
                 artifact_requirements: request.artifact_requirements.length,
             },
         });
@@ -1157,7 +1225,7 @@ export class LocalServiceRuntime {
             const compiledPath = preparationPortableContextPath(asPreparationDataDir(prepDataDir), preparationName);
             return byCreatedAtDesc(listJsonFiles(compileRunsRoot(compiledPath))
                 .map(readCompileRunAt)
-                .filter((run) => run !== null));
+                .filter((run) => run !== null)).map((run) => this.hydrateCompileRunFromRuntime(prepDataDir, compiledPath, run));
         }, (run) => run.run_id);
     }
     getCompileRun(prepDataDir, runId) {
@@ -1633,18 +1701,35 @@ export class LocalServiceRuntime {
                 },
             });
             if (result.status === "updated" || result.status === "no-change") {
+                let selectedPreparation = null;
+                if (request.preparation) {
+                    const selected = this.resolvePreparationConfig(prepDataDir, request.preparation, {
+                        method: request.method_id,
+                    });
+                    upsertSourcePreparationConfig(prepDataDir, selected);
+                    this.readinessCache.invalidatePreparation(prepDataDir, selected.name);
+                    this.compileRunCache.invalidatePreparation(prepDataDir, selected.name);
+                    this.verifyRunCache.invalidatePreparation(prepDataDir, selected.name);
+                    this.methodListingCache.invalidate(prepDataDir);
+                    selectedPreparation = selected.name;
+                }
                 this.appendJobRunEvent(prepDataDir, runId, {
                     type: "step.completed",
                     step_id: "validate-package",
-                    message: result.summary,
+                    message: selectedPreparation
+                        ? `${result.summary} Selected Build Plan ${request.method_id} for Preparation ${selectedPreparation}.`
+                        : result.summary,
                     output: {
                         status: result.status,
                         validation: result.validation ?? null,
+                        selected_preparation: selectedPreparation,
                     },
                 });
                 this.appendJobRunEvent(prepDataDir, runId, {
                     type: "job.completed",
-                    message: result.summary,
+                    message: selectedPreparation
+                        ? `${result.summary} Selected Build Plan ${request.method_id} for Preparation ${selectedPreparation}.`
+                        : result.summary,
                 });
             }
             else {
@@ -1700,7 +1785,7 @@ export class LocalServiceRuntime {
             return ActionProposalPlanSchema.parse({
                 action_type: "clarification",
                 ...(request.preparation ? { preparation: request.preparation } : {}),
-                assistant_message: "No local action planner is configured for this Interf Workspace.",
+                assistant_message: "No local action planner is configured for this Interf instance.",
             });
         }
         const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir));
@@ -1885,6 +1970,9 @@ export class LocalServiceRuntime {
                 hint,
                 task_prompt: taskPrompt,
                 checks: preparationConfig?.checks ?? [],
+                requested_artifacts: preparationConfig?.requested_artifacts ?? [],
+                source_profile: preparationConfig?.source_profile ?? null,
+                artifact_requirements: artifactRequirementsFromRequestedArtifacts(preparationConfig?.requested_artifacts ?? []),
             };
             const commandPreview = (usePlannerText ? plan.command_preview : undefined) ??
                 actionCommandPreview(actionType, preparationConfig?.name ?? null, methodId, proposalValues);
@@ -2002,6 +2090,9 @@ export class LocalServiceRuntime {
                 hint,
                 task_prompt: taskPrompt,
                 checks: preparationConfig.checks ?? [],
+                requested_artifacts: preparationConfig.requested_artifacts ?? [],
+                source_profile: preparationConfig.source_profile ?? null,
+                artifact_requirements: artifactRequirementsFromRequestedArtifacts(preparationConfig.requested_artifacts ?? []),
             };
         })();
         const title = (() => {
@@ -2108,6 +2199,12 @@ export class LocalServiceRuntime {
     readCompileRun(compiledPath, runId) {
         return readCompileRunAt(compileRunPath(compiledPath, runId));
     }
+    hydrateCompileRunFromRuntime(prepDataDir, compiledPath, run) {
+        if (!isTerminalCompileRunStatus(run.status))
+            return run;
+        this.refreshCompileRunFromRuntime(prepDataDir, compiledPath, run.run_id);
+        return this.readCompileRun(compiledPath, run.run_id) ?? run;
+    }
     finalizeInterruptedCompileRuns(prepDataDir) {
         let preparations;
         try {
@@ -2148,6 +2245,33 @@ export class LocalServiceRuntime {
             }
         }
     }
+    finalizeInterruptedJobRuns(prepDataDir) {
+        for (const run of this.listJobs(prepDataDir)) {
+            if (isTerminalJobStatus(run.status))
+                continue;
+            const timestamp = createRunEventTimestamp();
+            const interruptedRun = LocalJobRunResourceSchema.parse({
+                ...run,
+                steps: run.steps.map((step) => {
+                    if (step.status !== "running")
+                        return step;
+                    return {
+                        ...step,
+                        status: "failed",
+                        finished_at: step.finished_at ?? timestamp,
+                        summary: step.summary ?? INTERRUPTED_JOB_RUN_MESSAGE,
+                    };
+                }),
+            });
+            this.writeJobRun(prepDataDir, applyEventToLocalJob(interruptedRun, {
+                type: "job.failed",
+                event_id: createRunEventId("event"),
+                run_id: run.run_id,
+                timestamp,
+                message: INTERRUPTED_JOB_RUN_MESSAGE,
+            }));
+        }
+    }
     /**
      * 0.17 — emit per-Artifact billing events when a compile run reaches
      * a terminal state. STUB FORM: writes a JSONL file alongside the run
@@ -2281,6 +2405,7 @@ export class LocalServiceRuntime {
                 method,
                 compiledPath,
                 stageRuns: next.stages,
+                counts: countsFromCompiledState(state),
             });
         }
         catch {

package/dist/packages/engine/server.js

@@ -4,7 +4,7 @@ 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, } 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";
@@ -124,7 +124,7 @@ function packageRoot() {
 }
 export function resolveCompilerUiStaticRoot(rootPath = packageRoot()) {
     const distRoot = join(rootPath, "dist", "compiler-ui");
-    const sourceExportRoot = join(rootPath, "apps", "compiler-ui", "out");
+    const sourceExportRoot = join(rootPath, "src", "apps", "compiler-ui", "out");
     if (existsSync(join(distRoot, "index.html")))
         return distRoot;
     if (existsSync(join(sourceExportRoot, "index.html")))
@@ -384,6 +384,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 listInstanceMethods = () => {
+        const byId = new Map();
+        for (const prepDataDir of prepDataDirsForInstance()) {
+            for (const methodResource of runtime.listMethods(prepDataDir)) {
+                const existing = byId.get(methodResource.id);
+                if (!existing) {
+                    byId.set(methodResource.id, methodResource);
+                    continue;
+                }
+                const preferred = existing.built_in && !methodResource.built_in
+                    ? methodResource
+                    : existing;
+                byId.set(methodResource.id, {
+                    ...preferred,
+                    active_for_preparations: Array.from(new Set([
+                        ...existing.active_for_preparations,
+                        ...methodResource.active_for_preparations,
+                    ])).sort(),
+                });
+            }
+        }
+        return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+    };
+    const findInstanceMethod = (methodId) => {
+        return listInstanceMethods().find((methodResource) => methodResource.id === methodId) ?? null;
+    };
+    const listInstanceMethodRuns = (methodId) => {
+        return prepDataDirsForInstance()
+            .flatMap((prepDataDir) => runtime.listMethodRuns(prepDataDir, methodId))
+            .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 resolveInstanceMethodPackageRoot = (methodId) => {
+        for (const prepDataDir of prepDataDirsForInstance()) {
+            const localPath = methodDefinitionPath(prepDataDir, methodId);
+            if (existsSync(join(localPath, "method.json")))
+                return localPath;
+        }
+        return resolveMethodPackageRoot(methodId);
+    };
     // CORS preflight — answered for allowed origins, refused otherwise.
     if (method === "OPTIONS") {
         if (!isOriginAllowed(origin, allowed)) {
@@ -489,32 +561,15 @@ 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, {
@@ -522,6 +577,8 @@ async function routeApi(req, res, runtime) {
                 source: { kind: "local-folder", locator: body.source.locator },
                 method_id: body.method_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 +608,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,
                         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));
                 }
@@ -582,7 +645,7 @@ async function routeApi(req, res, runtime) {
         else if (subPath === PREPARATION_SUBRESOURCES.compileRuns) {
             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.`);
+                    sendError(res, 400, `Preparation ${storedPrep.id} has no Build Plan selected. Select one via PATCH /v1/preparations/${storedPrep.id} { "method_id": "<id>" } before compiling.`);
                     return true;
                 }
                 try {
@@ -618,7 +681,7 @@ 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.`);
+                    sendError(res, 400, `Preparation ${storedPrep.id} has no Build Plan selected. Select one via PATCH /v1/preparations/${storedPrep.id} { "method_id": "<id>" } before verifying.`);
                     return true;
                 }
                 try {
@@ -789,17 +852,12 @@ async function routeApi(req, res, runtime) {
     // Method resources — preparation-independent (workspace draft + 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) });
+        sendJson(res, 200, { methods: listInstanceMethods() });
         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]));
+        const methodResource = findInstanceMethod(decodeURIComponent(methodMatch[1]));
         if (!methodResource)
             sendError(res, 404, "Method not found.");
         else
@@ -808,8 +866,7 @@ async function routeApi(req, res, runtime) {
     }
     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 runs = listInstanceMethodRuns(decodeURIComponent(methodRunsMatch[1]));
         sendJson(res, 200, { runs });
         return true;
     }
@@ -834,8 +891,7 @@ async function routeApi(req, res, runtime) {
             sendError(res, 400, "File path escapes method root.");
             return true;
         }
-        const firstPrep = listStoredPreparations()[0];
-        const root = resolveMethodPackageRoot(methodId, firstPrep?.prepDataDir);
+        const root = resolveInstanceMethodPackageRoot(methodId);
         if (!root) {
             sendError(res, 404, `Method not found: ${methodId}`);
             return true;
@@ -855,14 +911,12 @@ async function routeApi(req, res, runtime) {
     // so 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
@@ -975,18 +1029,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
@@ -1118,7 +1170,7 @@ async function routeApi(req, res, runtime) {
                 allowedRoots.push(stored.source.locator);
         }
         allowedRoots.push(userMethodsRoot());
-        allowedRoots.push(packageRoot()); // covers <pkg>/builtin-methods/...
+        allowedRoots.push(packageRoot()); // covers <pkg>/public-repo/methods/...
         const openedPath = await openLocalPath(allowedRoots, body.path);
         sendJson(res, 202, { opened: true, path: openedPath });
         return true;

package/dist/packages/engine/verify/verify-execution.js

@@ -203,7 +203,7 @@ function buildTestQueryPrompt(target, testCase, answerPath, tracePath) {
             "Answer the check question the same way you would answer a real user inside this portable context.",
             "Prefer the Method-declared portable-context outputs before consulting source references.",
             "This sandbox is self-contained: the copied portable context has source references in `.interf/runtime/source-snapshot.json`.",
-            "The original Interf Workspace is intentionally absent from this sandbox. Use the source locators only when the portable context needs verification.",
+            "The original Interf instance state is intentionally absent from this sandbox. Use the source locators only when the portable context needs verification.",
         ]
         : [
             "You are running an Interf baseline test inside an isolated source-files test shell.",