@interf/compiler 0.13.0 → 0.16.0

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

@@ -1,8 +1,8 @@
 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());
 // ───────────────────────────────────────────────────────────────────────────
 // 0.13 — preparation-first additions
@@ -12,11 +12,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. */
-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 +32,34 @@ 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(),
+}).strict();
 /** Body of `POST /v1/methods` — install a Method package by path. */
 export const MethodInstallRequestSchema = z.object({
     source_path: z.string().min(1),
@@ -105,21 +124,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),
@@ -197,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(),
@@ -313,24 +323,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(),
@@ -446,16 +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 = RunStatusSchema;
-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(),
@@ -556,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", [
@@ -570,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"),
@@ -630,9 +629,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(),
@@ -656,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,
@@ -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 === "source-files" || request.mode === "both") && !result.sourceFilesOutcome;
-            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 {

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,10 @@ export interface PreparationCreateInput {
     max_attempts?: number;
     max_loops?: number;
 }
+export interface PreparationUpdateInput {
+    method_id?: string | null;
+    about?: string | null;
+}
 export interface StoredPreparation {
     id: string;
     prepDataDir: string;
@@ -45,7 +50,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 +75,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 +93,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: {

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

@@ -19,29 +19,14 @@
  *
  * Public callers reach this through the preparation-keyed HTTP routes.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, } from "node:fs";
 import { join, resolve } from "node:path";
 import { PreparationNameSchema, MethodIdSchema, } from "../contracts/lib/schema.js";
 import { preparationDataDir, preparationsRoot, } from "./instance-paths.js";
-import { saveSourceFolderConfig, loadSourceFolderConfig, } from "../project-model/source-config.js";
+import { saveSourceFolderConfig, loadSourceFolderConfig, } from "../project/source-config.js";
 function ensurePreparationsRoot() {
     mkdirSync(preparationsRoot(), { recursive: true });
 }
-function readSourceFolderBindingFromInterfJson(prepDataDir) {
-    const filePath = join(prepDataDir, "interf.json");
-    if (!existsSync(filePath))
-        return null;
-    try {
-        const raw = JSON.parse(readFileSync(filePath, "utf8"));
-        const sourceFolder = raw.source_folder;
-        if (!sourceFolder?.path)
-            return null;
-        return { path: sourceFolder.path, about: sourceFolder.about ?? null };
-    }
-    catch {
-        return null;
-    }
-}
 function loadStoredPreparation(prepId) {
     const prepDataDir = preparationDataDir(prepId);
     if (!existsSync(prepDataDir) || !statSync(prepDataDir).isDirectory())
@@ -52,15 +37,15 @@ function loadStoredPreparation(prepId) {
     const preparation = config.preparations?.find((p) => p.name === prepId);
     if (!preparation)
         return null;
-    const binding = readSourceFolderBindingFromInterfJson(prepDataDir);
-    if (!binding?.path)
+    const sourceFolderPath = config.source_folder?.path;
+    if (!sourceFolderPath)
         return null;
     return {
         id: prepId,
         prepDataDir,
-        source: { kind: "local-folder", locator: binding.path },
-        methodId: preparation.method ?? "interf-default",
-        about: binding.about ?? null,
+        source: { kind: "local-folder", locator: sourceFolderPath },
+        methodId: preparation.method ?? null,
+        about: preparation.about ?? null,
         config: preparation,
         portableContextPath: join(prepDataDir, prepId),
         configPath: join(prepDataDir, "interf.json"),
@@ -95,7 +80,9 @@ export function getStoredPreparation(prepId) {
  */
 export function createStoredPreparation(runtime, input) {
     PreparationNameSchema.parse(input.id);
-    MethodIdSchema.parse(input.method_id);
+    if (input.method_id != null) {
+        MethodIdSchema.parse(input.method_id);
+    }
     const sourceLocator = resolve(input.source.locator);
     if (!existsSync(sourceLocator)) {
         throw new Error(`Source folder does not exist: ${sourceLocator}`);
@@ -112,7 +99,7 @@ export function createStoredPreparation(runtime, input) {
     const preparation = {
         name: input.id,
         path: input.id,
-        method: input.method_id,
+        ...(input.method_id ? { method: input.method_id } : {}),
         checks: (input.checks ?? []).map((check) => ({
             question: check.question,
             ...(check.answer ? { answer: check.answer } : {}),
@@ -124,7 +111,7 @@ export function createStoredPreparation(runtime, input) {
         ...(input.max_loops ? { max_loops: input.max_loops } : {}),
     };
     saveSourceFolderConfig(prepDataDir, {
-        source_folder: { path: sourceLocator, ...(input.about ? { about: input.about } : {}) },
+        source_folder: { path: sourceLocator },
         preparations: [preparation],
     });
     // Hand the synthetic workspace to the runtime so the existing
@@ -148,6 +135,42 @@ export function deleteStoredPreparation(runtime, prepId) {
     rmSync(prepDataDir, { recursive: true, force: true });
     return true;
 }
+/**
+ * Update mutable fields on an existing preparation (method binding,
+ * about text). Returns the freshly-loaded record. Throws if the
+ * preparation does not exist.
+ */
+export function updateStoredPreparation(prepId, patch) {
+    const stored = loadStoredPreparation(prepId);
+    if (!stored)
+        throw new Error(`Preparation not found: ${prepId}`);
+    if (patch.method_id !== undefined && patch.method_id !== null) {
+        MethodIdSchema.parse(patch.method_id);
+    }
+    const nextPreparation = {
+        ...stored.config,
+        ...(patch.method_id === null
+            ? { method: undefined }
+            : patch.method_id !== undefined
+                ? { method: patch.method_id }
+                : {}),
+    };
+    const aboutPatch = patch.about === undefined ? stored.about : patch.about;
+    const preparationWithAbout = aboutPatch
+        ? { ...nextPreparation, about: aboutPatch }
+        : (() => {
+            const { about: _omitAbout, ...rest } = nextPreparation;
+            return rest;
+        })();
+    saveSourceFolderConfig(stored.prepDataDir, {
+        source_folder: { path: stored.source.locator },
+        preparations: [preparationWithAbout],
+    });
+    const next = loadStoredPreparation(prepId);
+    if (!next)
+        throw new Error(`Failed to reload updated preparation ${prepId}`);
+    return next;
+}
 /**
  * Re-register every preparation directory with the runtime on startup so
  * synthetic workspaces survive a `interf web` restart.

package/dist/packages/{local-service → engine}/readiness-check-draft.d.ts

@@ -1,5 +1,5 @@
-import type { MethodExecutor } from "../agents/lib/executors.js";
-import type { SourceReadinessCheck } from "../project-model/lib/schema.js";
+import type { MethodExecutor } from "./agents/lib/executors.js";
+import type { SourceReadinessCheck } from "../project/lib/schema.js";
 export declare function buildReadinessCheckDraftPrompt(options: {
     preparationName: string;
     sourceFolderPath: string;

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

@@ -9,13 +9,23 @@ export declare const LOCAL_SERVICE_ROUTES: {
     readonly methods: "/v1/methods";
     readonly runs: "/v1/runs";
     readonly actionProposals: "/v1/action-proposals";
+    /**
+     * 0.14 single-active-agent shortcut. Kept as a back-compat shim
+     * over the role-map's `general` row in 0.15+.
+     */
     readonly executor: "/v1/executor";
+    /**
+     * 0.15 connected-agents primitive — registry, role-map, role list.
+     * `agents/{name}` and `agents/role-map` are sub-resources handled
+     * by string match in `server.ts`.
+     */
+    readonly agents: "/v1/agents";
     readonly openPath: "/v1/open-path";
 };
 /** Preparation-scoped sub-resources (relative to /v1/preparations/<id>/). */
 export declare const PREPARATION_SUBRESOURCES: {
     readonly compileRuns: "compile-runs";
-    readonly testRuns: "test-runs";
+    readonly verifyRuns: "verify-runs";
     readonly methodAuthoringRuns: "method-authoring-runs";
     readonly methodImprovementRuns: "method-improvement-runs";
     readonly readinessCheckDrafts: "readiness-check-drafts";
@@ -25,6 +35,23 @@ export declare const PREPARATION_SUBRESOURCES: {
     readonly readiness: "readiness";
     readonly sourceFiles: "source-files";
     readonly portableContext: "portable-context";
+    /**
+     * 0.16 — read a portable-context file (read-only, path-guarded
+     * inside the prep's portable-context root). Used by the locator
+     * pattern's `api-served` kind:
+     *   GET /v1/preparations/<id>/files/<relpath>
+     */
+    readonly files: "files";
+};
+/** Method-scoped sub-resources (relative to /v1/methods/<id>/). */
+export declare const METHOD_SUBRESOURCES: {
+    readonly runs: "runs";
+    /**
+     * 0.16 — read a method package file (read-only, path-guarded inside
+     * the method root). Used by the locator pattern's `api-served` kind:
+     *   GET /v1/methods/<id>/files/<relpath>
+     */
+    readonly files: "files";
 };
 /** Run-scoped sub-resources (relative to /v1/runs/<run-id>/). */
 export declare const RUN_SUBRESOURCES: {
@@ -47,3 +74,5 @@ export declare function runResourcePath(runId: string): string;
 export declare function runSubresourcePath(runId: string, sub: keyof typeof RUN_SUBRESOURCES): string;
 /** Path builder: /v1/methods/<id>. */
 export declare function methodResourcePath(methodId: string): string;
+/** Path builder: /v1/methods/<id>/<subresource>. */
+export declare function methodSubresourcePath(methodId: string, sub: keyof typeof METHOD_SUBRESOURCES): string;