@interf/compiler 0.13.0 → 0.18.0

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

@@ -1,22 +1,30 @@
 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 { ArtifactSchema, ArtifactIdSchema, ArtifactPathShapeSchema, ArtifactStatusSchema, CheckSchema, LocatorSchema, PreparationNameSchema, ReadinessSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, MethodIdSchema, TestTargetTypeSchema, } from "../../contracts/lib/schema.js";
+import { ReadinessCheckRunSchema, } from "../verify/lib/schema.js";
 const JsonObjectSchema = z.record(z.string(), z.unknown());
 // ───────────────────────────────────────────────────────────────────────────
 // 0.13 — preparation-first additions
 // ───────────────────────────────────────────────────────────────────────────
-/** Source binding shape on the API (only `local-folder` ships in 0.13). */
+/**
+ * Source binding shape on the API. `local-folder` is the only kind the
+ * local binary accepts in 0.17; `remote-folder` rides in the type
+ * plumbing for the future cloud variant (B4.4 cloud-variant seam) and
+ * is rejected at the validator branch in server.ts. See `TODO(cloud)`
+ * marker there.
+ */
 export const SourceBindingSchema = z.object({
-    kind: z.enum(["local-folder"]),
+    kind: z.enum(["local-folder", "remote-folder"]),
     locator: z.string().min(1),
 }).strict();
-/** Discriminated locator for an artifact returned by the API. */
-export const ArtifactLocatorSchema = z.object({
-    kind: z.enum(["local-path", "remote-url"]),
-    value: 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"),
@@ -30,17 +38,40 @@ export const InstanceResourceSchema = z.object({
     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_id: MethodIdSchema,
+    /**
+     * 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(),
+    /**
+     * Replace the full quality-check list. Use the empty array to clear
+     * every check. Each item is a `SourceReadinessCheck`
+     * (`{ question, answer?, strictness?, expect? }`).
+     */
+    checks: z.array(SourceReadinessCheckSchema).optional(),
+}).strict();
 /** Body of `POST /v1/methods` — install a Method package by path. */
 export const MethodInstallRequestSchema = z.object({
     source_path: z.string().min(1),
@@ -55,6 +86,15 @@ export const PreparationDeleteResponseSchema = z.object({
     deleted: z.boolean(),
     id: PreparationNameSchema,
 }).strict();
+export const PreparationWireShapeSchema = z.object({
+    id: PreparationNameSchema,
+    source: SourceBindingSchema,
+    method_id: MethodIdSchema.nullable(),
+    about: z.string().min(1).nullable(),
+    config_path: z.string().min(1),
+    portable_context: ArtifactLocatorSchema,
+    checks: z.array(SourceReadinessCheckSchema).default([]),
+}).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
@@ -105,21 +145,6 @@ export const ServiceRegistryEntrySchema = z.object({
 export const ServiceRegistrySchema = z.object({
     services: z.array(ServiceRegistryEntrySchema).default([]),
 }).strict();
-export const WorkspaceRegistrationRequestSchema = z.object({
-    control_path: z.string().min(1),
-}).strict();
-export const WorkspaceRegistrationResponseSchema = z.object({
-    workspace: ServiceRegistryWorkspaceSchema,
-    service: ServiceRegistryEntrySchema,
-}).strict();
-export const WorkspaceListResponseSchema = z.object({
-    workspaces: z.array(ServiceRegistryWorkspaceSchema),
-}).strict();
-export const WorkspaceDeregisterResponseSchema = z.object({
-    deregistered: z.boolean(),
-    control_path: z.string().min(1),
-    remaining_workspaces: z.number().int().min(0),
-}).strict();
 export const LocalServiceHealthSchema = z.object({
     kind: z.literal("interf-local-service-health"),
     version: z.literal(1),
@@ -176,10 +201,15 @@ export const PreparationResourceSchema = z.object({
     checks: z.array(SourceReadinessCheckSchema).default([]),
     portable_context: PortableContextMappingSchema,
     portable_context_path: z.string().min(1).nullable(),
-    readiness: ReadinessStateSchema,
+    readiness: ReadinessSchema,
     runs: PreparationRunLinkageSchema,
     latest_compile_run_id: z.string().min(1).nullable().optional(),
     latest_test_run_id: z.string().min(1).nullable().optional(),
+    // 0.17 — per-Artifact status from the latest compile run, mirrored
+    // here so the UI/CLI can render artifact rows without a separate
+    // GET /v1/preparations/<id>/runs fetch. Empty when the Method
+    // no compile run has produced artifacts yet.
+    artifacts: z.array(ArtifactStatusSchema).default([]),
 }).strict();
 export const MethodResourceSchema = z.object({
     id: MethodIdSchema,
@@ -190,16 +220,21 @@ export const MethodResourceSchema = z.object({
     source_kind: z.enum(["builtin", "local"]).default("local"),
     built_in: z.boolean().default(false),
     active_for_preparations: z.array(PreparationNameSchema).default([]),
-    output_paths: z.array(z.string().min(1)).default([]),
+    artifacts: z.array(ArtifactSchema).default([]),
     stages: z.array(z.object({
         id: z.string().min(1),
         label: z.string().min(1),
         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(),
     }).strict()).default([]),
 }).strict();
 export const CompileRunCreateRequestSchema = z.object({
@@ -313,24 +348,6 @@ export const PreparationSetupResultSchema = z.object({
     submitted_run_id: z.string().min(1).nullable().optional(),
     submitted_run_type: z.literal("compile-run").nullable().optional(),
 }).strict();
-export const WorkspaceBootstrapCreateRequestSchema = z.object({
-    source_folder: z.object({
-        path: z.string().min(1),
-    }).strict().optional(),
-    seed_default_method: z.boolean().default(true),
-}).strict();
-export const WorkspaceBootstrapResultSchema = z.object({
-    kind: z.literal("interf-workspace-bootstrap-result"),
-    version: z.literal(1),
-    control_path: z.string().min(1),
-    config_path: z.string().min(1),
-    source_folder_path: z.string().min(1).nullable(),
-    preparations: z.number().int().min(0),
-    seeded_default_method: z.boolean(),
-    default_method_id: MethodIdSchema.nullable(),
-    changed: z.boolean(),
-    message: z.string().min(1),
-}).strict();
 export const MethodChangeCreateRequestSchema = z.discriminatedUnion("operation", [
     z.object({
         action_type: z.literal("method-change").optional(),
@@ -399,6 +416,13 @@ export const ReadinessCheckDraftCreateRequestSchema = z.object({
 export const ReadinessCheckDraftResultSchema = z.object({
     checks: z.array(SourceReadinessCheckSchema).default([]),
 }).strict();
+export const MethodAuthoringArtifactRequirementSchema = z.object({
+    id: ArtifactIdSchema,
+    description: z.string().min(1).optional(),
+    shape: ArtifactPathShapeSchema,
+    checks: z.array(CheckSchema).default([]),
+    stage_hint: z.string().min(1).optional(),
+}).strict();
 export const MethodAuthoringCreateRequestSchema = z.object({
     preparation: PreparationNameSchema.nullable().optional(),
     source_folder_path: z.string().min(1),
@@ -409,6 +433,7 @@ export const MethodAuthoringCreateRequestSchema = z.object({
     hint: z.string().min(1),
     task_prompt: z.string().min(1),
     checks: z.array(SourceReadinessCheckSchema).default([]),
+    artifact_requirements: z.array(MethodAuthoringArtifactRequirementSchema).default([]),
 }).strict();
 export const MethodAuthoringResultSchema = z.object({
     status: z.enum(["updated", "no-change", "invalid", "executor-failed"]),
@@ -446,22 +471,32 @@ 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 = RunStatusSchema;
-export const TestRunCreateRequestSchema = z.object({
+export const VerifyRunStatusSchema = RunStatusSchema;
+/**
+ * 0.17 — verify runs choose their judge target. `compiled` (default)
+ * judges against the latest portable-context output; `source-files`
+ * judges against the raw source folder for a baseline that reveals
+ * how much value the Method actually adds. The 0.15 cleanup made
+ * verify compiled-only on the wire because the source-files branch
+ * had been retired in 0.13.1; 0.17 restores it because the QA tab and
+ * `verify/README.md` have always claimed the option exists, and the
+ * sandbox + spec builders for source-files have remained in tree
+ * since 0.13.
+ */
+export const VerifyRunCreateRequestSchema = z.object({
     preparation: PreparationNameSchema,
-    mode: TestRunModeSchema.default("both"),
+    target: TestTargetTypeSchema.default("compiled"),
 }).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(),
     finished_at: z.string().nullable().optional(),
     readiness_run: ReadinessCheckRunSchema.nullable(),
-    readiness: ReadinessStateSchema.nullable().optional(),
+    readiness: ReadinessSchema.nullable().optional(),
     events: z.array(InterfRunEventSchema).default([]),
     error: z.string().min(1).nullable().optional(),
 }).strict();
@@ -556,7 +591,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", [
@@ -570,7 +605,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"),
@@ -589,13 +624,13 @@ export const PortableContextResourceSchema = z.object({
     preparation: PreparationNameSchema,
     path: z.string().min(1),
     exists: z.boolean(),
-    readiness: ReadinessStateSchema,
+    readiness: ReadinessSchema,
     method: MethodIdSchema.nullable().optional(),
     latest_compile_run_id: z.string().min(1).nullable().optional(),
     latest_test_run_id: z.string().min(1).nullable().optional(),
     artifacts: z.array(ArtifactRefSchema).default([]),
 }).strict();
-export const ReadinessResourceSchema = ReadinessStateSchema;
+export const ReadinessResourceSchema = ReadinessSchema;
 export const SourceFileResourceSchema = z.object({
     preparation: PreparationNameSchema,
     path: z.string().min(1),
@@ -630,9 +665,14 @@ export const LocalServiceDiscoverySchema = z.object({
         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(),
@@ -645,7 +685,7 @@ export const OpenPathResponseSchema = z.object({
     path: z.string().min(1),
 }).strict();
 export const PreparationListResponseSchema = z.object({
-    preparations: z.array(PreparationResourceSchema),
+    preparations: z.array(PreparationWireShapeSchema),
 }).strict();
 export const MethodListResponseSchema = z.object({
     methods: z.array(MethodResourceSchema),
@@ -656,8 +696,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 { listCompiledSchemaArtifacts, 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,
@@ -83,9 +87,9 @@ function printSavedReadinessOutcome(prefix, outcome) {
 }
 function bestVariationRestorePaths(compiledPath) {
     const schema = readCompiledSchemaFile(methodPackagePathForCompiled(compiledPath));
-    const zonePaths = (schema?.zones ?? [])
-        .filter((zone) => zone.kind !== "runtime")
-        .map((zone) => zone.path);
+    const artifactPaths = (schema ? listCompiledSchemaArtifacts(schema) : [])
+        .filter((artifact) => artifact.kind !== "runtime")
+        .map((artifact) => artifact.path);
     return [
         "AGENTS.md",
         "CLAUDE.md",
@@ -95,7 +99,7 @@ function bestVariationRestorePaths(compiledPath) {
         ".cursor",
         ".interf/interf.json",
         ".interf/method",
-        ...zonePaths,
+        ...artifactPaths,
     ];
 }
 function copyRelativePathIfPresent(sourceRoot, targetRoot, relativePath) {
@@ -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,38 @@ 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,
+                target: request.target,
             });
-            const missingSourceFiles = (request.mode === "source-files" || request.mode === "both") && !result.sourceFilesOutcome;
-            const missingPortableContext = (request.mode === "compiled" || request.mode === "both") && !result.compiledOutcome;
-            if (missingSourceFiles || missingPortableContext) {
+            const outcome = request.target === "source-files"
+                ? result.sourceFilesOutcome
+                : result.compiledOutcome;
+            if (!outcome) {
+                const targetLabel = request.target === "source-files"
+                    ? "Source files"
+                    : "Portable Context";
                 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: `${targetLabel} is not ready for readiness checks.`,
                 };
             }
             return {
@@ -609,6 +660,7 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
                 hint: request.hint,
                 taskPrompt: request.task_prompt,
                 checks: request.checks,
+                artifactRequirements: request.artifact_requirements,
                 executor,
                 onStatus: (line) => context.emit({
                     type: "log.appended",

package/dist/packages/{local-service → engine}/preparation-store.d.ts

@@ -19,7 +19,7 @@
  *
  * Public callers reach this through the preparation-keyed HTTP routes.
  */
-import type { SourcePreparationConfig } from "../project-model/lib/schema.js";
+import type { SourcePreparationConfig } from "../project/lib/schema.js";
 import type { LocalServiceRuntime } from "./runtime.js";
 export interface PreparationCreateInput {
     id: string;
@@ -27,7 +27,8 @@ export interface PreparationCreateInput {
         kind: "local-folder";
         locator: string;
     };
-    method_id: string;
+    /** Method binding. Null/undefined means "not bound yet" — bind later via update. */
+    method_id?: string | null;
     about?: string;
     checks?: Array<{
         question: string;
@@ -38,6 +39,16 @@ export interface PreparationCreateInput {
     max_attempts?: number;
     max_loops?: number;
 }
+export interface PreparationUpdateInput {
+    method_id?: string | null;
+    about?: string | null;
+    checks?: Array<{
+        question: string;
+        answer?: string;
+        strictness?: string;
+        expect?: string;
+    }>;
+}
 export interface StoredPreparation {
     id: string;
     prepDataDir: string;
@@ -45,7 +56,8 @@ export interface StoredPreparation {
         kind: "local-folder";
         locator: string;
     };
-    methodId: string;
+    /** Null when no method has been bound to this preparation yet. */
+    methodId: string | null;
     about: string | null;
     config: SourcePreparationConfig;
     portableContextPath: string;
@@ -69,6 +81,12 @@ export declare function createStoredPreparation(runtime: LocalServiceRuntime, in
  * 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.
@@ -81,7 +99,7 @@ export declare function preparationWireShape(stored: StoredPreparation): {
         kind: string;
         locator: string;
     };
-    method_id: string;
+    method_id: string | null;
     about: string | null;
     config_path: string;
     portable_context: {