@interf/compiler 0.9.5 → 0.16.0

package/dist/packages/{local-service → engine}/lib/schema.js

@@ -1,15 +1,129 @@
 import { z } from "zod";
-import { ArtifactRefSchema, CompileRunSchema, CompileRunStatusSchema, InterfRunEventSchema, ProofRecordSchema, RunObservabilitySchema, } from "../../execution/lib/schema.js";
-import { SourcePreparationConfigSchema, SourceReadinessCheckSchema, } from "../../project-model/lib/schema.js";
-import { PreparationNameSchema, ReadinessStateSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, MethodIdSchema, } from "../../contracts/lib/schema.js";
-import { ReadinessCheckRunSchema, TestRunModeSchema, } from "../../testing/lib/schema.js";
+import { ArtifactRefSchema, CompileRunSchema, CompileRunStatusSchema, InterfRunEventSchema, ProofRecordSchema, RunObservabilitySchema, } from "../execution/lib/schema.js";
+import { SourcePreparationConfigSchema, SourceReadinessCheckSchema, } from "../../project/lib/schema.js";
+import { LocatorSchema, PreparationNameSchema, ReadinessStateSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, MethodIdSchema, } from "../../contracts/lib/schema.js";
+import { ReadinessCheckRunSchema, } from "../verify/lib/schema.js";
 const JsonObjectSchema = z.record(z.string(), z.unknown());
-export const LocalServiceHostSchema = z.string().min(1);
+// ───────────────────────────────────────────────────────────────────────────
+// 0.13 — preparation-first additions
+// ───────────────────────────────────────────────────────────────────────────
+/** Source binding shape on the API (only `local-folder` ships in 0.13). */
+export const SourceBindingSchema = z.object({
+    kind: z.enum(["local-folder"]),
+    locator: z.string().min(1),
+}).strict();
+/**
+ * Discriminated locator for an artifact returned by the API. Aliases the
+ * canonical `LocatorSchema` from contracts so all three kinds —
+ * `local-path`, `remote-url`, `api-served` — flow through the same
+ * resource-access pattern.
+ */
+export const ArtifactLocatorSchema = LocatorSchema;
+/** Per-instance metadata from `GET /v1/instance` (replaces /v1/status). */
+export const InstanceResourceSchema = z.object({
+    kind: z.literal("interf-instance"),
+    version: z.literal(1),
+    url: z.string().min(1),
+    host: z.string().min(1),
+    port: z.number().int().min(1).max(65535),
+    started_at: z.string().min(1),
+    package_version: z.string().min(1).optional(),
+    preparation_count: z.number().int().min(0),
+    active_run_count: z.number().int().min(0),
+    idle_for_seconds: z.number().int().min(0),
+    auth_required: z.boolean(),
+    /**
+     * 0.16 — locator-pattern connection mode. `local` means the engine
+     * is bound to a loopback host the user's UI can target with OS-shell
+     * actions; `remote` means OS-open is unavailable and resources must
+     * be fetched via api-served / signed URLs.
+     */
+    connection_kind: z.enum(["local", "remote"]).optional(),
+}).strict();
+/** Body of `POST /v1/preparations` — the 0.13 preparation create request. */
+export const PreparationCreateRequestSchema = z.object({
+    id: PreparationNameSchema,
+    source: SourceBindingSchema,
+    /**
+     * Method binding. Optional — a preparation can be created with no
+     * method bound, then have one selected (or drafted) later before the
+     * first compile. Null/missing means "method not chosen yet".
+     */
+    method_id: MethodIdSchema.nullable().optional(),
+    about: z.string().min(1).optional(),
+    checks: z.array(SourceReadinessCheckSchema).default([]),
+    max_attempts: SourceCompiledMaxAttemptsSchema.optional(),
+    max_loops: SourceCompiledMaxLoopsSchema.optional(),
+}).strict();
+/** Body of `PATCH /v1/preparations/<id>` — update mutable preparation fields. */
+export const PreparationUpdateRequestSchema = z.object({
+    method_id: MethodIdSchema.nullable().optional(),
+    about: z.string().nullable().optional(),
+}).strict();
+/** Body of `POST /v1/methods` — install a Method package by path. */
+export const MethodInstallRequestSchema = z.object({
+    source_path: z.string().min(1),
+    overwrite: z.boolean().default(false),
+}).strict();
+export const MethodInstallResultSchema = z.object({
+    method_id: MethodIdSchema,
+    installed: z.boolean(),
+    path: z.string().min(1),
+}).strict();
+export const PreparationDeleteResponseSchema = z.object({
+    deleted: z.boolean(),
+    id: PreparationNameSchema,
+}).strict();
+/**
+ * The local service must only ever bind to a loopback interface. Any other
+ * host (LAN IP, 0.0.0.0, public address) lets a remote browser tab POST at
+ * the service, which is the CSRF model we are explicitly rejecting. Keep
+ * the allowlist literal — refactoring to a `.refine()` over `z.string()`
+ * would lose the static type narrowing.
+ */
+export const LOCAL_SERVICE_LOOPBACK_HOSTS = ["127.0.0.1", "localhost", "::1"];
+export const LocalServiceHostSchema = z
+    .string()
+    .min(1)
+    .refine((value) => LOCAL_SERVICE_LOOPBACK_HOSTS.includes(value), {
+    message: `Local service host must be one of: ${LOCAL_SERVICE_LOOPBACK_HOSTS.join(", ")}.`,
+});
 export const LocalServicePortSchema = z.number().int().min(1).max(65535);
+/**
+ * Per-instance bearer token. Generated at startup with crypto.randomBytes(32)
+ * and rendered as a 64-char hex string. Any deviation should fail validation
+ * loud and early.
+ */
+export const LocalServiceAuthTokenSchema = z
+    .string()
+    .regex(/^[0-9a-f]{64}$/i, "Auth token must be a 64-character hex string.");
 export const LocalServiceConfigSchema = z.object({
     host: LocalServiceHostSchema.default("127.0.0.1"),
     port: LocalServicePortSchema.default(4873),
 }).strict();
+export const ServiceRegistryWorkspaceSchema = z.object({
+    control_path: z.string().min(1),
+    registered_at: z.string().min(1),
+    last_activity: z.string().min(1),
+}).strict();
+export const ServiceRegistryEntrySchema = z.object({
+    pid: z.number().int().positive(),
+    host: LocalServiceHostSchema,
+    port: LocalServicePortSchema,
+    url: z.string().min(1),
+    started_at: z.string().min(1),
+    /**
+     * Bearer token mutating clients must send. Optional in the schema so
+     * older registry files (pre-0.12.1) keep parsing; the runtime treats a
+     * missing token as "open" only when the entry already exists on disk —
+     * fresh entries always have one.
+     */
+    auth_token: LocalServiceAuthTokenSchema.optional(),
+    workspaces: z.array(ServiceRegistryWorkspaceSchema).default([]),
+}).strict();
+export const ServiceRegistrySchema = z.object({
+    services: z.array(ServiceRegistryEntrySchema).default([]),
+}).strict();
 export const LocalServiceHealthSchema = z.object({
     kind: z.literal("interf-local-service-health"),
     version: z.literal(1),
@@ -21,6 +135,10 @@ export const LocalServiceHealthSchema = z.object({
     source_folder_path: z.string().min(1).nullable().optional(),
     started_at: z.string().min(1).optional(),
     package_version: z.string().min(1).optional(),
+    instance_started_at: z.string().min(1).optional(),
+    registered_workspaces: z.array(ServiceRegistryWorkspaceSchema).default([]),
+    active_runs: z.number().int().min(0).default(0),
+    idle_for_seconds: z.number().int().min(0).default(0),
 }).strict();
 export const LocalServiceErrorSchema = z.object({
     error: z.object({
@@ -35,8 +153,12 @@ export const LocalServicePointerSchema = z.object({
     pid: z.number().int().positive(),
     control_path: z.string().min(1),
     started_at: z.string().min(1),
+    /**
+     * Per-workspace copy of the bearer token. Optional so legacy pointer
+     * files keep parsing during upgrades; new pointers always include it.
+     */
+    auth_token: LocalServiceAuthTokenSchema.optional(),
 }).strict();
-export const PreparationReadinessStateSchema = ReadinessStateSchema;
 export const PortableContextMappingSchema = z.object({
     preparation: PreparationNameSchema,
     path: z.string().min(1).nullable(),
@@ -58,7 +180,7 @@ export const PreparationResourceSchema = z.object({
     checks: z.array(SourceReadinessCheckSchema).default([]),
     portable_context: PortableContextMappingSchema,
     portable_context_path: z.string().min(1).nullable(),
-    readiness: PreparationReadinessStateSchema,
+    readiness: ReadinessStateSchema,
     runs: PreparationRunLinkageSchema,
     latest_compile_run_id: z.string().min(1).nullable().optional(),
     latest_test_run_id: z.string().min(1).nullable().optional(),
@@ -79,6 +201,12 @@ export const MethodResourceSchema = z.object({
         description: z.string().min(1).optional(),
         contract_type: z.string().min(1),
         skill_dir: z.string().min(1),
+        /**
+         * 0.15 — role hint Methods declare per stage. Defaults to
+         * `general` at the runtime layer; the wire shape mirrors that
+         * default so older /v1/methods clients always see a string.
+         */
+        role: z.string().min(1).default("general"),
         reads: z.array(z.string().min(1)).default([]),
         writes: z.array(z.string().min(1)).default([]),
         acceptance: z.record(z.string(), z.unknown()).optional(),
@@ -110,13 +238,14 @@ export const LocalJobTypeSchema = z.enum([
     "method-authoring",
     "method-improvement",
 ]);
-export const LocalJobStatusSchema = z.enum([
+export const RunStatusSchema = z.enum([
     "queued",
     "running",
     "succeeded",
     "failed",
     "cancelled",
 ]);
+export const LocalJobStatusSchema = RunStatusSchema;
 export const LocalRunHandlerResultSchema = z.object({
     ok: z.boolean(),
     error: z.string().min(1).optional(),
@@ -309,22 +438,23 @@ export const LocalJobRunResourceSchema = z.object({
     result: z.record(z.string(), z.unknown()).nullable().optional(),
     error: z.string().min(1).nullable().optional(),
 }).strict();
-export const TestRunStatusSchema = z.enum([
-    "queued",
-    "running",
-    "succeeded",
-    "failed",
-    "cancelled",
-]);
-export const TestRunCreateRequestSchema = z.object({
+export const VerifyRunStatusSchema = RunStatusSchema;
+/**
+ * 0.15 cleanup — `mode` was a 0.13 hold-over from when verify could
+ * judge against either the source-files baseline or the compiled
+ * portable context. 0.13.1 redirected every verify run to compiled-
+ * only, which made `mode` a vestigial field. We drop it here so the
+ * wire shape matches the runtime behavior. Older clients sending
+ * `mode` get it ignored by the strict-but-tolerant runtime parser
+ * upstream.
+ */
+export const VerifyRunCreateRequestSchema = z.object({
     preparation: PreparationNameSchema,
-    mode: TestRunModeSchema.default("both"),
 }).strict();
-export const TestRunResourceSchema = z.object({
+export const VerifyRunResourceSchema = z.object({
     run_id: z.string().min(1),
-    status: TestRunStatusSchema,
+    status: VerifyRunStatusSchema,
     preparation: PreparationNameSchema,
-    mode: TestRunModeSchema,
     source_path: z.string().min(1),
     portable_context_path: z.string().min(1).nullable(),
     started_at: z.string().nullable().optional(),
@@ -425,7 +555,7 @@ const ActionProposalResourceBaseSchema = z.object({
     proposed_by_executor: LocalJobAgentSchema.nullable().optional(),
     approval: ActionProposalApprovalSchema.nullable().optional(),
     submitted_run_id: z.string().min(1).nullable().optional(),
-    submitted_run_type: z.enum(["compile-run", "test-run", "job-run"]).nullable().optional(),
+    submitted_run_type: z.enum(["compile-run", "verify-run", "job-run"]).nullable().optional(),
     error: z.string().min(1).nullable().optional(),
 }).strict();
 export const ActionProposalResourceSchema = z.discriminatedUnion("action_type", [
@@ -439,7 +569,7 @@ export const ActionProposalResourceSchema = z.discriminatedUnion("action_type",
     }).strict(),
     ActionProposalResourceBaseSchema.extend({
         action_type: z.literal("test"),
-        request: TestRunCreateRequestSchema,
+        request: VerifyRunCreateRequestSchema,
     }).strict(),
     ActionProposalResourceBaseSchema.extend({
         action_type: z.literal("readiness-check-draft"),
@@ -464,7 +594,7 @@ export const PortableContextResourceSchema = z.object({
     latest_test_run_id: z.string().min(1).nullable().optional(),
     artifacts: z.array(ArtifactRefSchema).default([]),
 }).strict();
-export const ReadinessResourceSchema = PreparationReadinessStateSchema;
+export const ReadinessResourceSchema = ReadinessStateSchema;
 export const SourceFileResourceSchema = z.object({
     preparation: PreparationNameSchema,
     path: z.string().min(1),
@@ -494,13 +624,21 @@ export const LocalServiceDiscoverySchema = z.object({
         preparation_setups: z.string().min(1),
         preparation_changes: z.string().min(1),
         method_changes: z.string().min(1),
+        workspace_bootstraps: z.string().min(1).optional(),
         readiness_check_drafts: z.string().min(1),
         method_authoring_runs: z.string().min(1),
         method_improvement_runs: z.string().min(1),
         compile_runs: z.string().min(1),
-        test_runs: z.string().min(1),
+        verify_runs: z.string().min(1),
         reset: z.string().min(1),
         executor: z.string().min(1),
+        /**
+         * 0.15 — connected agents primitive. Optional during the 0.14 →
+         * 0.15 rollout so older clients don't fail discovery validation.
+         */
+        agents: z.string().min(1).optional(),
+        workspaces: z.string().min(1).optional(),
+        status: z.string().min(1).optional(),
     }).strict(),
 }).strict();
 export const OpenPathRequestSchema = z.object({
@@ -510,56 +648,6 @@ export const OpenPathResponseSchema = z.object({
     opened: z.boolean(),
     path: z.string().min(1),
 }).strict();
-export const LocalServiceResourceSchema = z.discriminatedUnion("kind", [
-    z.object({
-        kind: z.literal("preparation"),
-        value: PreparationResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("method"),
-        value: MethodResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("compile-run"),
-        value: CompileRunResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("job-run"),
-        value: LocalJobRunResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("test-run"),
-        value: TestRunResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("run-observability"),
-        value: RunObservabilityResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("executor-status"),
-        value: LocalExecutorStatusSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("action-proposal"),
-        value: ActionProposalResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("portable-context"),
-        value: PortableContextResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("readiness"),
-        value: ReadinessResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("source-file"),
-        value: SourceFileResourceSchema,
-    }).strict(),
-    z.object({
-        kind: z.literal("workspace-file"),
-        value: WorkspaceFileResourceSchema,
-    }).strict(),
-]);
 export const PreparationListResponseSchema = z.object({
     preparations: z.array(PreparationResourceSchema),
 }).strict();
@@ -572,8 +660,8 @@ export const CompileRunListResponseSchema = z.object({
 export const LocalJobRunListResponseSchema = z.object({
     jobs: z.array(LocalJobRunResourceSchema),
 }).strict();
-export const TestRunListResponseSchema = z.object({
-    test_runs: z.array(TestRunResourceSchema),
+export const VerifyRunListResponseSchema = z.object({
+    verify_runs: z.array(VerifyRunResourceSchema),
 }).strict();
 export const RunObservabilityListResponseSchema = z.object({
     runs: z.array(RunObservabilityResourceSchema),

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

@@ -1,7 +1,8 @@
-import type { MethodExecutionProfile, MethodExecutor } from "../agents/lib/executors.js";
-import type { SourcePreparationConfig } from "../project-model/lib/schema.js";
-import type { StageShellRetentionMode } from "../compiler/method-runs.js";
-import type { RunEventSink } from "../execution/events.js";
+import { type ResolveStageExecutor } from "./compile/method-runs.js";
+import type { MethodExecutionProfile, MethodExecutor } from "./agents/lib/executors.js";
+import type { SourcePreparationConfig } from "../project/lib/schema.js";
+import type { StageShellRetentionMode } from "./compile/method-runs.js";
+import { type RunEventSink } from "./execution/events.js";
 import type { LocalServiceRunHandlers } from "./runtime.js";
 export interface NativeLocalServiceRunHandlerOptions {
     executor?: MethodExecutor;
@@ -10,6 +11,7 @@ export interface NativeLocalServiceRunHandlerOptions {
 export declare function runConfiguredCompiledCompile(options: {
     executor: MethodExecutor;
     testExecutor?: MethodExecutor | null;
+    resolveStageExecutor?: ResolveStageExecutor;
     compiledPath: string;
     sourcePath: string;
     compiledConfig: SourcePreparationConfig | null;
@@ -20,4 +22,4 @@ export declare function runConfiguredCompiledCompile(options: {
     runId?: string;
     events?: RunEventSink;
 }): Promise<boolean>;
-export declare function createNativeLocalServiceRunHandlers(options?: NativeLocalServiceRunHandlerOptions): Pick<LocalServiceRunHandlers, "planActionProposal" | "createCompileRun" | "createTestRun" | "createReadinessCheckDraft" | "createMethodAuthoringRun">;
+export declare function createNativeLocalServiceRunHandlers(options?: NativeLocalServiceRunHandlerOptions): Pick<LocalServiceRunHandlers, "planActionProposal" | "createCompileRun" | "createVerifyRun" | "createReadinessCheckDraft" | "createMethodAuthoringRun">;

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

@@ -2,19 +2,22 @@ import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import chalk from "chalk";
-import { compileCompiled, } from "../compiler/method-runs.js";
-import { readInterfConfig } from "../project-model/interf.js";
-import { resolveLocalExecutor, } from "../agents/lib/executors.js";
-import { formatMethodExecutionProfile } from "../agents/lib/execution-profile.js";
-import { clearCompiledRuntimeDerivedArtifacts, } from "../compiler/reset.js";
-import { formatActiveCompiledMethodStageStep, resolveRequiredCompiledMethodFromConfig, } from "../method-package/method-definitions.js";
-import { loadCompiledPreparationConfig, resolvePreparationCompileMaxAttempts, resolvePreparationCompileMaxLoops, } from "../project-model/source-config.js";
-import { runMethodImprovementLoop } from "../method-authoring/method-improvement.js";
-import { stageExecutionShellsRoot, methodPackagePathForCompiled, } from "../compiler/compiled-paths.js";
-import { readCompiledSchemaFile } from "../compiler/compiled-schema.js";
-import { initializeCompiledRuntimeState } from "../compiler/state.js";
-import { readinessPassRate, runReadinessChecksForExecutor, runSavedPortableContextCheck, } from "../testing/readiness-check-run.js";
-import { runMethodAuthoringDraft, } from "../method-authoring/method-authoring.js";
+import { compileCompiled, } from "./compile/method-runs.js";
+import { readInterfConfig } from "../project/interf.js";
+import { resolveLocalExecutor, } from "./agents/lib/executors.js";
+import { formatMethodExecutionProfile } from "./agents/lib/execution-profile.js";
+import { loadAgentsRegistry } from "./agents/registry.js";
+import { buildRoleExecutorBundle } from "./agents/role-executors.js";
+import { clearCompiledRuntimeDerivedArtifacts, } from "./compile/reset.js";
+import { formatActiveCompiledMethodStageStep, resolveRequiredCompiledMethodFromConfig, } from "../methods/package/method-definitions.js";
+import { createRunEventId, createRunEventTimestamp, } from "./execution/events.js";
+import { loadCompiledPreparationConfig, resolvePreparationCompileMaxAttempts, resolvePreparationCompileMaxLoops, } from "../project/source-config.js";
+import { runMethodImprovementLoop } from "../methods/authoring/method-improvement.js";
+import { stageExecutionShellsRoot, methodPackagePathForCompiled, } from "./compile/compiled-paths.js";
+import { readCompiledSchemaFile } from "./compile/compiled-schema.js";
+import { initializeCompiledRuntimeState } from "./compile/state.js";
+import { readinessPassRate, runReadinessChecksForExecutor, runSavedPortableContextCheck, } from "./verify/readiness-check-run.js";
+import { runMethodAuthoringDraft, } from "../methods/authoring/method-authoring.js";
 import { draftReadinessChecks, } from "./readiness-check-draft.js";
 import { planActionProposalWithExecutor, } from "./action-planner.js";
 import { ActionProposalPlanSchema, } from "./lib/schema.js";
@@ -46,6 +49,7 @@ async function compileCompiledWithReporter(executor, compiledPath, options = {})
     };
     const result = await compileCompiled({
         executor,
+        resolveStageExecutor: options.resolveStageExecutor,
         compiledPath,
         reporter,
         preserveStageShells: options.preserveStageShells,
@@ -84,7 +88,7 @@ function printSavedReadinessOutcome(prefix, outcome) {
 function bestVariationRestorePaths(compiledPath) {
     const schema = readCompiledSchemaFile(methodPackagePathForCompiled(compiledPath));
     const zonePaths = (schema?.zones ?? [])
-        .filter((zone) => zone.id !== "raw" && zone.kind !== "runtime")
+        .filter((zone) => zone.kind !== "runtime")
         .map((zone) => zone.path);
     return [
         "AGENTS.md",
@@ -144,6 +148,7 @@ async function runMethodVariation(options) {
                 preserveStageShells: options.preserveStageShells,
                 runId: options.runId,
                 events: options.events,
+                resolveStageExecutor: options.resolveStageExecutor,
             });
             if (!result.ok) {
                 printCompileFailure(options.compiledPath, result.failedStage);
@@ -269,14 +274,14 @@ function printStageShellReviewHint(compiledPath, preserveStageShells, result) {
 function printPostCompileNextStep(options) {
     console.log(chalk.dim(`  Portable Context: ${options.compiledPath}`));
     if (options.checks === 0) {
-        console.log(chalk.dim("  Next: run `interf` to add readiness checks, then `interf test`."));
+        console.log(chalk.dim("  Next: run `interf` to add readiness checks, then `interf verify`."));
         return;
     }
     if (options.testedDuringCompile) {
-        console.log(chalk.dim("  Next: inspect the Portable Context agents will use, or run `interf test` if you also want readiness evidence for source files and Portable Context."));
+        console.log(chalk.dim("  Next: inspect the Portable Context agents will use, or run `interf verify` if you also want readiness evidence for source files and Portable Context."));
         return;
     }
-    console.log(chalk.dim("  Next: run `interf test` to collect readiness evidence for source files and Portable Context."));
+    console.log(chalk.dim("  Next: run `interf verify` to collect readiness evidence for source files and Portable Context."));
 }
 function formatVariationReadinessSummary(summary) {
     return `${summary.passed_questions}/${summary.total_questions}`;
@@ -329,6 +334,7 @@ export async function runConfiguredCompiledCompile(options) {
             preserveStageShells,
             runId: options.runId,
             events: options.events,
+            resolveStageExecutor: options.resolveStageExecutor,
         });
         if (!result.ok) {
             process.exitCode = 1;
@@ -377,6 +383,7 @@ export async function runConfiguredCompiledCompile(options) {
         const baseline = await runMethodVariation({
             executor: options.executor,
             testExecutor: options.testExecutor,
+            resolveStageExecutor: options.resolveStageExecutor,
             compiledPath: options.compiledPath,
             sourcePath: options.sourcePath,
             compiledConfig,
@@ -436,6 +443,7 @@ export async function runConfiguredCompiledCompile(options) {
                 const variation = await runMethodVariation({
                     executor: options.executor,
                     testExecutor: options.testExecutor,
+                    resolveStageExecutor: options.resolveStageExecutor,
                     compiledPath: options.compiledPath,
                     sourcePath: options.sourcePath,
                     compiledConfig,
@@ -528,9 +536,38 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
         async createCompileRun(request, context) {
             const executor = resolveHandlerExecutor(options.executor);
             const testExecutor = resolveHandlerExecutor(options.testExecutor ?? options.executor);
+            const registry = loadAgentsRegistry();
+            const bundle = buildRoleExecutorBundle({
+                agents: registry.agents,
+                roleMap: registry.roleMap,
+                activeAgent: registry.activeAgent,
+                defaultExecutor: executor,
+            });
             const ok = await runConfiguredCompiledCompile({
                 executor,
                 testExecutor,
+                resolveStageExecutor(stage) {
+                    const role = stage.role && stage.role.trim().length > 0 ? stage.role : "general";
+                    const { executor: stageExecutor, resolved } = bundle.resolveExecutorForRole(role);
+                    // Best-effort audit trail — do not block the stage if event
+                    // emission fails. Emits a `log.appended` system event so the
+                    // run record shows which agent ran which stage.
+                    try {
+                        void context.events?.emit({
+                            type: "log.appended",
+                            event_id: createRunEventId("event"),
+                            run_id: context.runId,
+                            timestamp: createRunEventTimestamp(),
+                            stage_id: stage.id,
+                            stream: "system",
+                            message: `Role ${role} → agent ${resolved.agent.name} (${resolved.source}).`,
+                        });
+                    }
+                    catch {
+                        /* best effort */
+                    }
+                    return stageExecutor;
+                },
                 compiledPath: context.compiledPath,
                 sourcePath: context.sourcePath,
                 compiledConfig: context.preparationConfig,
@@ -542,24 +579,31 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
             });
             return { ok };
         },
-        async createTestRun(request, context) {
-            const executor = resolveHandlerExecutor(options.testExecutor ?? options.executor);
+        async createVerifyRun(request, context) {
+            const fallbackExecutor = resolveHandlerExecutor(options.testExecutor ?? options.executor);
+            const registry = loadAgentsRegistry();
+            const bundle = buildRoleExecutorBundle({
+                agents: registry.agents,
+                roleMap: registry.roleMap,
+                activeAgent: registry.activeAgent,
+                defaultExecutor: fallbackExecutor,
+            });
+            // Verify runs always use the `verifier` role. We resolve here
+            // for symmetry with compile runs — verify-run events are not
+            // streamed in 0.15, so the resolution shows up only in the
+            // executor field on the saved test run record.
+            const { executor } = bundle.resolveExecutorForRole("verifier");
             const result = await runReadinessChecksForExecutor({
                 sourcePath: context.sourcePath,
                 preparationConfig: context.preparationConfig,
                 portableContextPath: context.compiledPath,
-                mode: request.mode,
                 executor,
             });
-            const missingSourceFiles = (request.mode === "raw" || request.mode === "both") && !result.rawOutcome;
-            const missingPortableContext = (request.mode === "compiled" || request.mode === "both") && !result.compiledOutcome;
-            if (missingSourceFiles || missingPortableContext) {
+            if (!result.compiledOutcome) {
                 return {
                     ok: false,
                     readiness_run: result.readinessRun,
-                    error: missingPortableContext
-                        ? "Portable Context is not ready for readiness checks."
-                        : "Source files are not ready for readiness checks.",
+                    error: "Portable Context is not ready for readiness checks.",
                 };
             }
             return {
@@ -601,7 +645,7 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
                 message: `Using ${executor.displayName} for Method authoring.`,
             });
             const result = await runMethodAuthoringDraft({
-                sourcePath: context.sourcePath,
+                prepDataDir: context.sourcePath,
                 sourceFolderPath: request.source_folder_path,
                 baseMethodId: request.reference_method_id ?? request.base_method_id,
                 methodId: request.method_id,

package/dist/packages/engine/preparation-store.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 0.13 preparation store.
+ *
+ * Each preparation lives at `~/.interf/preparations/<id>/` and is also
+ * registered with the runtime as a synthetic workspace so the existing
+ * compile / test / readiness machinery (preparation-keyed under the hood)
+ * keeps working without a parallel implementation.
+ *
+ *   ~/.interf/preparations/<id>/
+ *     interf.json          ← preparation config, single preparation entry name=<id>
+ *     <id>/                ← portable context (matches preparation name)
+ *
+ * NOTE: We keep the synthetic `interf.json` shape (with a `preparations[]`
+ * array of length 1, name=id, path=id) so the existing compile/test
+ * machinery stays functional. The doc-shape `config.json` /
+ * `portable-context/` from `instance-paths.ts` is aspirational; transitioning
+ * the entire compile pipeline to read those names is out of scope for the
+ * 0.13 cutover.
+ *
+ * Public callers reach this through the preparation-keyed HTTP routes.
+ */
+import type { SourcePreparationConfig } from "../project/lib/schema.js";
+import type { LocalServiceRuntime } from "./runtime.js";
+export interface PreparationCreateInput {
+    id: string;
+    source: {
+        kind: "local-folder";
+        locator: string;
+    };
+    /** Method binding. Null/undefined means "not bound yet" — bind later via update. */
+    method_id?: string | null;
+    about?: string;
+    checks?: Array<{
+        question: string;
+        answer?: string;
+        strictness?: string;
+        expect?: string;
+    }>;
+    max_attempts?: number;
+    max_loops?: number;
+}
+export interface PreparationUpdateInput {
+    method_id?: string | null;
+    about?: string | null;
+}
+export interface StoredPreparation {
+    id: string;
+    prepDataDir: string;
+    source: {
+        kind: "local-folder";
+        locator: string;
+    };
+    /** Null when no method has been bound to this preparation yet. */
+    methodId: string | null;
+    about: string | null;
+    config: SourcePreparationConfig;
+    portableContextPath: string;
+    configPath: string;
+}
+/** List every preparation registered under `~/.interf/preparations/`. */
+export declare function listStoredPreparations(): StoredPreparation[];
+/** Read one preparation by id. Returns null when missing. */
+export declare function getStoredPreparation(prepId: string): StoredPreparation | null;
+/**
+ * Create a preparation: scaffold its data dir, write the synthetic
+ * workspace config, and register it with the runtime so subsequent
+ * compile / test / readiness calls find it.
+ *
+ * Throws on validation errors (bad id, bad method id, source missing).
+ */
+export declare function createStoredPreparation(runtime: LocalServiceRuntime, input: PreparationCreateInput): StoredPreparation;
+/**
+ * Delete a preparation: deregister its synthetic workspace and remove
+ * `~/.interf/preparations/<id>/` from disk. Returns true when something
+ * was actually removed.
+ */
+export declare function deleteStoredPreparation(runtime: LocalServiceRuntime, prepId: string): boolean;
+/**
+ * Update mutable fields on an existing preparation (method binding,
+ * about text). Returns the freshly-loaded record. Throws if the
+ * preparation does not exist.
+ */
+export declare function updateStoredPreparation(prepId: string, patch: PreparationUpdateInput): StoredPreparation;
+/**
+ * Re-register every preparation directory with the runtime on startup so
+ * synthetic workspaces survive a `interf web` restart.
+ */
+export declare function rehydratePreparations(runtime: LocalServiceRuntime): void;
+/** Build the wire shape for `GET /v1/preparations/<id>` given a stored preparation. */
+export declare function preparationWireShape(stored: StoredPreparation): {
+    id: string;
+    source: {
+        kind: string;
+        locator: string;
+    };
+    method_id: string | null;
+    about: string | null;
+    config_path: string;
+    portable_context: {
+        kind: "local-path";
+        value: string;
+    };
+    checks: SourcePreparationConfig["checks"];
+};