@interf/compiler 0.9.4 → 0.13.0

package/dist/{cli/commands/compile-controller.js → packages/local-service/native-run-handlers.js}

@@ -2,16 +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 { readInterfConfig } from "../../packages/project-model/interf.js";
-import { clearCompiledRuntimeDerivedArtifacts, } from "../../packages/compiler/reset.js";
-import { formatActiveCompiledMethodStageStep, resolveRequiredCompiledMethodFromConfig, } from "../../packages/method-package/method-definitions.js";
-import { loadCompiledPreparationConfig, resolvePreparationCompileMaxAttempts, resolvePreparationCompileMaxLoops, } from "../../packages/project-model/source-config.js";
-import { runMethodImprovementLoop } from "../../packages/method-authoring/method-improvement.js";
-import { stageExecutionShellsRoot, methodPackagePathForCompiled, } from "../../packages/compiler/compiled-paths.js";
-import { readCompiledSchemaFile } from "../../packages/compiler/compiled-schema.js";
-import { initializeCompiledRuntimeState } from "../../packages/compiler/state.js";
-import { compileCompiledWithReporter } from "./compiled-flow.js";
-import { printSavedTestOutcome, readinessPassRate, runSavedCompiledTest, } from "./test-flow.js";
+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 { draftReadinessChecks, } from "./readiness-check-draft.js";
+import { planActionProposalWithExecutor, } from "./action-planner.js";
+import { ActionProposalPlanSchema, } from "./lib/schema.js";
 function printCompileFailure(compiledPath, failedStage) {
     resolveRequiredCompiledMethodFromConfig(readInterfConfig(compiledPath), `.interf/interf.json for ${compiledPath}`);
     let failedStageLabel = failedStage ? `Stage "${failedStage}"` : "Compile";
@@ -26,10 +32,59 @@ function printCompileFailure(compiledPath, failedStage) {
 function testScore(outcome) {
     return (outcome.result.passedCases * 1000) + outcome.result.passedChecks;
 }
+async function compileCompiledWithReporter(executor, compiledPath, options = {}) {
+    console.log();
+    console.log(chalk.bold(`  ${options.heading ?? "Building Portable Context..."}`));
+    const profileLabel = formatMethodExecutionProfile(executor.executionProfile);
+    if (profileLabel) {
+        console.log(chalk.dim(`  Execution profile: ${profileLabel}`));
+    }
+    console.log();
+    const reporter = {
+        line: (message) => console.log(chalk.dim(`  ${message}`)),
+        blankLine: () => console.log(),
+    };
+    const result = await compileCompiled({
+        executor,
+        compiledPath,
+        reporter,
+        preserveStageShells: options.preserveStageShells,
+        runId: options.runId,
+        events: options.events,
+    });
+    if (!result.ok)
+        return result;
+    console.log();
+    console.log(chalk.green(`  ${options.successMessage ?? "Portable Context ready."}`));
+    return result;
+}
+function printSavedReadinessOutcome(prefix, outcome) {
+    const color = outcome.result.ok ? chalk.green : chalk.red;
+    const status = outcome.result.ok ? chalk.green("PASS") : chalk.red("FAIL");
+    console.log(chalk.bold(`  ${prefix}`));
+    console.log();
+    console.log(color(`  ${status} ${outcome.result.passedCases}/${outcome.result.totalCases} readiness checks`));
+    console.log();
+    for (const [index, caseResult] of outcome.result.caseResults.entries()) {
+        const caseStatus = caseResult.ok ? chalk.green("PASS") : chalk.red("FAIL");
+        console.log(`  ${caseStatus} Check ${index + 1}`);
+        console.log(chalk.dim(`       ${caseResult.question}`));
+        const failedChecks = caseResult.checks.filter((entry) => !entry.ok).slice(0, 3);
+        for (const failedCheck of failedChecks) {
+            console.log(chalk.dim(`       Failed criterion: ${failedCheck.label}: ${failedCheck.detail}`));
+        }
+    }
+    console.log();
+    if (outcome.result.sandbox_path) {
+        console.log(chalk.dim(`  Preserved sandbox: ${outcome.result.sandbox_path}`));
+        console.log();
+    }
+    console.log(chalk.dim(`  Saved run: ${outcome.displayRunPath ?? outcome.runPath}`));
+}
 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",
@@ -107,12 +162,11 @@ async function runMethodVariation(options) {
                     fatalError: null,
                 };
             }
-            const outcome = await runSavedCompiledTest({
+            const outcome = await runSavedPortableContextCheck({
                 sourcePath: options.sourcePath,
                 preparationConfig: options.compiledConfig,
                 executor: options.testExecutor,
-                executionProfile: options.executionProfile,
-                compiledPath: options.compiledPath,
+                portableContextPath: options.compiledPath,
                 preserveSandboxes: options.preserveStageShells === "always" ? "always" : "on-failure",
             });
             if (!outcome) {
@@ -123,11 +177,11 @@ async function runMethodVariation(options) {
                     bestOutcome,
                     bestSnapshotPath,
                     bestAttempt,
-                    fatalError: "Could not run the saved Portable Context comparison after compile.",
+                    fatalError: "Could not run saved readiness checks against the Portable Context after prepare.",
                 };
             }
             console.log();
-            printSavedTestOutcome(`${options.variationLabel} · attempt ${attempt}/${options.maxAttempts}`, outcome);
+            printSavedReadinessOutcome(`${options.variationLabel} · attempt ${attempt}/${options.maxAttempts}`, outcome);
             if (!bestOutcome || testScore(outcome) > testScore(bestOutcome)) {
                 if (bestSnapshotPath) {
                     rmSync(bestSnapshotPath, { recursive: true, force: true });
@@ -185,7 +239,7 @@ function summarizeMethodVariation(options) {
         : options.result.bestOutcome
             ? `Best result: ${passedChecks}/${totalChecks} readiness checks passed.`
             : options.result.failedStage
-                ? `Compile failed at stage ${options.result.failedStage} before any saved comparison result.`
+                ? `Prepare failed at stage ${options.result.failedStage} before any saved readiness result.`
                 : "Method variation did not produce a passing result.";
     return {
         variation: options.variation,
@@ -219,10 +273,10 @@ function printPostCompileNextStep(options) {
         return;
     }
     if (options.testedDuringCompile) {
-        console.log(chalk.dim("  Next: inspect the Portable Context agents will use, or run `interf test` if you also want a source files versus Portable Context comparison."));
+        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."));
         return;
     }
-    console.log(chalk.dim("  Next: run `interf test` to compare source files and Portable Context."));
+    console.log(chalk.dim("  Next: run `interf test` to collect readiness evidence for source files and Portable Context."));
 }
 function formatVariationReadinessSummary(summary) {
     return `${summary.passed_questions}/${summary.total_questions}`;
@@ -300,7 +354,7 @@ export async function runConfiguredCompiledCompile(options) {
         const compiledConfig = options.compiledConfig
             ?? loadCompiledPreparationConfig(options.compiledPath)
             ?? {
-                name: readInterfConfig(options.compiledPath)?.name ?? "compiled",
+                name: readInterfConfig(options.compiledPath)?.name ?? "preparation",
                 path: "./source-folder",
                 checks: [],
             };
@@ -443,3 +497,133 @@ export async function runConfiguredCompiledCompile(options) {
         }
     }
 }
+function resolveHandlerExecutor(configured) {
+    if (configured)
+        return configured;
+    const resolved = resolveLocalExecutor({ preflight: true });
+    if (!resolved.executor) {
+        throw new Error(resolved.error ?? "No local agent detected.");
+    }
+    return resolved.executor;
+}
+export function createNativeLocalServiceRunHandlers(options = {}) {
+    return {
+        async planActionProposal(request, context) {
+            const resolved = options.executor
+                ? { executor: options.executor, error: null }
+                : resolveLocalExecutor({ preflight: true });
+            if (!resolved.executor) {
+                return ActionProposalPlanSchema.parse({
+                    action_type: "clarification",
+                    preparation: request.preparation,
+                    assistant_message: resolved.error ?? "No local agent detected for action planning.",
+                });
+            }
+            return planActionProposalWithExecutor({
+                request,
+                context,
+                executor: resolved.executor,
+            });
+        },
+        async createCompileRun(request, context) {
+            const executor = resolveHandlerExecutor(options.executor);
+            const testExecutor = resolveHandlerExecutor(options.testExecutor ?? options.executor);
+            const ok = await runConfiguredCompiledCompile({
+                executor,
+                testExecutor,
+                compiledPath: context.compiledPath,
+                sourcePath: context.sourcePath,
+                compiledConfig: context.preparationConfig,
+                maxAttemptsOverride: request.max_attempts ?? null,
+                maxLoopsOverride: request.max_loops ?? null,
+                preserveStageShells: request.preserve_stage_shells,
+                runId: context.runId,
+                events: context.events,
+            });
+            return { ok };
+        },
+        async createTestRun(request, context) {
+            const executor = resolveHandlerExecutor(options.testExecutor ?? options.executor);
+            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) {
+                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.",
+                };
+            }
+            return {
+                ok: true,
+                readiness_run: result.readinessRun,
+            };
+        },
+        async createReadinessCheckDraft(request, context) {
+            const executor = resolveHandlerExecutor(options.executor);
+            context.emit({
+                type: "log.appended",
+                step_id: "agent-draft",
+                message: `Using ${executor.displayName} to draft readiness checks.`,
+            });
+            const drafted = await draftReadinessChecks({
+                preparationName: request.preparation,
+                sourceFolderPath: request.source_folder_path,
+                about: request.about,
+                executor,
+                targetCount: request.target_count,
+                onStatus: (line) => context.emit({
+                    type: "log.appended",
+                    step_id: "agent-draft",
+                    message: line,
+                }),
+            });
+            if (!drafted.checks) {
+                throw new Error(drafted.error ?? "Could not draft readiness checks from this Source Folder.");
+            }
+            return {
+                checks: drafted.checks,
+            };
+        },
+        async createMethodAuthoringRun(request, context) {
+            const executor = resolveHandlerExecutor(options.executor);
+            context.emit({
+                type: "log.appended",
+                step_id: "draft-package",
+                message: `Using ${executor.displayName} for Method authoring.`,
+            });
+            const result = await runMethodAuthoringDraft({
+                prepDataDir: context.sourcePath,
+                sourceFolderPath: request.source_folder_path,
+                baseMethodId: request.reference_method_id ?? request.base_method_id,
+                methodId: request.method_id,
+                label: request.label,
+                hint: request.hint,
+                taskPrompt: request.task_prompt,
+                checks: request.checks,
+                executor,
+                onStatus: (line) => context.emit({
+                    type: "log.appended",
+                    step_id: "draft-package",
+                    message: line,
+                }),
+            });
+            return {
+                status: result.status,
+                changed: result.changed,
+                summary: result.summary,
+                validation: result.validation,
+                method_path: result.methodPath,
+                shell_path: result.shellPath,
+            };
+        },
+    };
+}

package/dist/packages/local-service/preparation-store.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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-model/lib/schema.js";
+import type { LocalServiceRuntime } from "./runtime.js";
+export interface PreparationCreateInput {
+    id: string;
+    source: {
+        kind: "local-folder";
+        locator: string;
+    };
+    method_id: string;
+    about?: string;
+    checks?: Array<{
+        question: string;
+        answer?: string;
+        strictness?: string;
+        expect?: string;
+    }>;
+    max_attempts?: number;
+    max_loops?: number;
+}
+export interface StoredPreparation {
+    id: string;
+    prepDataDir: string;
+    source: {
+        kind: "local-folder";
+        locator: string;
+    };
+    methodId: string;
+    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;
+/**
+ * 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;
+    about: string | null;
+    config_path: string;
+    portable_context: {
+        kind: "local-path";
+        value: string;
+    };
+    checks: SourcePreparationConfig["checks"];
+};

package/dist/packages/local-service/preparation-store.js

@@ -0,0 +1,171 @@
+/**
+ * 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 { existsSync, mkdirSync, readdirSync, readFileSync, 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";
+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())
+        return null;
+    const config = loadSourceFolderConfig(prepDataDir);
+    if (!config)
+        return null;
+    const preparation = config.preparations?.find((p) => p.name === prepId);
+    if (!preparation)
+        return null;
+    const binding = readSourceFolderBindingFromInterfJson(prepDataDir);
+    if (!binding?.path)
+        return null;
+    return {
+        id: prepId,
+        prepDataDir,
+        source: { kind: "local-folder", locator: binding.path },
+        methodId: preparation.method ?? "interf-default",
+        about: binding.about ?? null,
+        config: preparation,
+        portableContextPath: join(prepDataDir, prepId),
+        configPath: join(prepDataDir, "interf.json"),
+    };
+}
+/** List every preparation registered under `~/.interf/preparations/`. */
+export function listStoredPreparations() {
+    const root = preparationsRoot();
+    if (!existsSync(root))
+        return [];
+    const entries = readdirSync(root, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const stored = loadStoredPreparation(entry.name);
+        if (stored)
+            out.push(stored);
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Read one preparation by id. Returns null when missing. */
+export function getStoredPreparation(prepId) {
+    return loadStoredPreparation(prepId);
+}
+/**
+ * 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 function createStoredPreparation(runtime, input) {
+    PreparationNameSchema.parse(input.id);
+    MethodIdSchema.parse(input.method_id);
+    const sourceLocator = resolve(input.source.locator);
+    if (!existsSync(sourceLocator)) {
+        throw new Error(`Source folder does not exist: ${sourceLocator}`);
+    }
+    if (!statSync(sourceLocator).isDirectory()) {
+        throw new Error(`Source folder is not a directory: ${sourceLocator}`);
+    }
+    ensurePreparationsRoot();
+    const prepDataDir = preparationDataDir(input.id);
+    if (existsSync(prepDataDir) && loadStoredPreparation(input.id)) {
+        throw new Error(`Preparation already exists: ${input.id}`);
+    }
+    mkdirSync(prepDataDir, { recursive: true });
+    const preparation = {
+        name: input.id,
+        path: input.id,
+        method: input.method_id,
+        checks: (input.checks ?? []).map((check) => ({
+            question: check.question,
+            ...(check.answer ? { answer: check.answer } : {}),
+            ...(check.strictness ? { strictness: check.strictness } : {}),
+            ...(check.expect ? { expect: check.expect } : {}),
+        })),
+        ...(input.about ? { about: input.about } : {}),
+        ...(input.max_attempts ? { max_attempts: input.max_attempts } : {}),
+        ...(input.max_loops ? { max_loops: input.max_loops } : {}),
+    };
+    saveSourceFolderConfig(prepDataDir, {
+        source_folder: { path: sourceLocator, ...(input.about ? { about: input.about } : {}) },
+        preparations: [preparation],
+    });
+    // Hand the synthetic workspace to the runtime so the existing
+    // compile/test/readiness paths see it.
+    runtime.registerPreparation(prepDataDir);
+    const stored = loadStoredPreparation(input.id);
+    if (!stored)
+        throw new Error(`Failed to load freshly-created preparation ${input.id}`);
+    return stored;
+}
+/**
+ * Delete a preparation: deregister its synthetic workspace and remove
+ * `~/.interf/preparations/<id>/` from disk. Returns true when something
+ * was actually removed.
+ */
+export function deleteStoredPreparation(runtime, prepId) {
+    const prepDataDir = preparationDataDir(prepId);
+    if (!existsSync(prepDataDir))
+        return false;
+    runtime.deregisterPreparation(prepDataDir);
+    rmSync(prepDataDir, { recursive: true, force: true });
+    return true;
+}
+/**
+ * Re-register every preparation directory with the runtime on startup so
+ * synthetic workspaces survive a `interf web` restart.
+ */
+export function rehydratePreparations(runtime) {
+    for (const stored of listStoredPreparations()) {
+        runtime.registerPreparation(stored.prepDataDir);
+    }
+}
+/** Build the wire shape for `GET /v1/preparations/<id>` given a stored preparation. */
+export function preparationWireShape(stored) {
+    return {
+        id: stored.id,
+        source: stored.source,
+        method_id: stored.methodId,
+        about: stored.about,
+        config_path: stored.configPath,
+        portable_context: { kind: "local-path", value: stored.portableContextPath },
+        checks: stored.config.checks ?? [],
+    };
+}

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

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

package/dist/packages/local-service/routes.d.ts

@@ -1,27 +1,49 @@
 export declare const LOCAL_SERVICE_DEFAULT_HOST = "127.0.0.1";
 export declare const LOCAL_SERVICE_DEFAULT_PORT = 4873;
-export declare const LOCAL_SERVICE_INSTANCE_POINTER_PATH: readonly ["interf", ".service", "local-instance.json"];
 export declare const LOCAL_SERVICE_ROUTES: {
     readonly root: "/";
     readonly api: "/v1";
     readonly health: "/health";
+    readonly instance: "/v1/instance";
     readonly preparations: "/v1/preparations";
-    readonly workspaceFiles: "/v1/workspace-files";
-    readonly sourceFiles: "/v1/source-files";
     readonly methods: "/v1/methods";
-    readonly jobs: "/v1/jobs";
-    readonly readinessCheckDrafts: "/v1/readiness-check-drafts";
-    readonly methodAuthoringRuns: "/v1/method-authoring-runs";
     readonly runs: "/v1/runs";
-    readonly executor: "/v1/executor";
     readonly actionProposals: "/v1/action-proposals";
-    readonly compileRuns: "/v1/compile-runs";
-    readonly testRuns: "/v1/test-runs";
-    readonly portableContexts: "/v1/portable-contexts";
-    readonly readiness: "/v1/readiness";
+    readonly executor: "/v1/executor";
     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 methodAuthoringRuns: "method-authoring-runs";
+    readonly methodImprovementRuns: "method-improvement-runs";
+    readonly readinessCheckDrafts: "readiness-check-drafts";
+    readonly changes: "changes";
+    readonly reset: "reset";
+    readonly runs: "runs";
+    readonly readiness: "readiness";
+    readonly sourceFiles: "source-files";
+    readonly portableContext: "portable-context";
+};
+/** Run-scoped sub-resources (relative to /v1/runs/<run-id>/). */
+export declare const RUN_SUBRESOURCES: {
+    readonly events: "events";
+    readonly cancel: "cancel";
+    readonly proof: "proof";
+    readonly artifacts: "artifacts";
+};
 export declare function buildLocalServiceUrl(options?: {
     host?: string;
     port?: number;
 }): string;
+/** Path builder: /v1/preparations/<id>. */
+export declare function preparationResourcePath(prepId: string): string;
+/** Path builder: /v1/preparations/<id>/<subresource>. */
+export declare function preparationSubresourcePath(prepId: string, sub: keyof typeof PREPARATION_SUBRESOURCES): string;
+/** Path builder: /v1/runs/<run-id>. */
+export declare function runResourcePath(runId: string): string;
+/** Path builder: /v1/runs/<run-id>/<subresource>. */
+export declare function runSubresourcePath(runId: string, sub: keyof typeof RUN_SUBRESOURCES): string;
+/** Path builder: /v1/methods/<id>. */
+export declare function methodResourcePath(methodId: string): string;