@interf/compiler 0.21.0 → 0.22.2

package/dist/packages/build-plans/package/build-plan-definitions.js

@@ -0,0 +1,214 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { builtinBuildPlanPackagePath, isBuildPlanId, listLocalBuildPlanDefinitions, loadLocalBuildPlanDefinition, loadBuildPlanDefinitionFromDir, mergeStagePolicyNotesForStages, } from "./local-build-plans.js";
+import { listUserBuildPlanDefinitions, loadUserBuildPlanDefinition, } from "./user-build-plans.js";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { buildPlanPackagePathForVerifiableContext } from "../../engine/build/verifiable-context-paths.js";
+import { asPreparationDataDir, preparationBuildPlanPackagePath } from "../../contracts/lib/preparation-paths.js";
+import { resolveSourceControlPath } from "../../project/interf.js";
+import { deriveBuildPlanInputsFromContextInterface, } from "./context-interface.js";
+const DEFAULT_BUILD_PLAN_ID = "interf-default";
+let builtinDefaultBuildPlanCache = null;
+function toBuildPlanStages(stages) {
+    return stages.map((stage) => ({
+        id: stage.id,
+        label: stage.label,
+        description: stage.description ?? stage.label,
+        contractType: stage.contract_type,
+        skillDir: stage.skill_dir ?? stage.id,
+        role: stage.role && stage.role.trim().length > 0 ? stage.role : "general",
+        reads: [...stage.reads],
+        writes: [...stage.writes],
+    }));
+}
+export function standaloneBuildPlanDefinitionFromLocalPackage(local) {
+    if (!local.stages || local.stages.length === 0) {
+        throw new Error(`Build Plan package "${local.id}" is missing explicit stages. Local Build Plan packages must be standalone.`);
+    }
+    const stages = toBuildPlanStages(local.stages);
+    const contextInterface = local.build_plan_schema;
+    const inputs = local.inputs?.length
+        ? [...local.inputs]
+        : deriveBuildPlanInputsFromContextInterface(contextInterface);
+    return {
+        id: local.id,
+        engineApi: local.engine_api ?? {
+            kind: "build",
+            version: 1,
+        },
+        ...(local.purpose
+            ? {
+                purpose: {
+                    label: local.purpose.label,
+                    taskHint: local.purpose.task_hint,
+                },
+            }
+            : {}),
+        inputs,
+        label: local.label,
+        hint: local.hint,
+        recommended: false,
+        contextInterface,
+        ...(contextInterface ? { schema: contextInterface } : {}),
+        stages,
+        stagePolicyNotes: mergeStagePolicyNotesForStages(stages, undefined, local.stage_policy_notes),
+        starterDocs: [...local.starter_docs],
+        scope: "local",
+    };
+}
+function getBuiltinDefaultBuildPlan() {
+    if (builtinDefaultBuildPlanCache)
+        return builtinDefaultBuildPlanCache;
+    const local = loadBuildPlanDefinitionFromDir(builtinBuildPlanPackagePath(DEFAULT_BUILD_PLAN_ID));
+    if (!local) {
+        throw new Error(`Missing built-in Interf Build Plan package at public-repo/build-plans/${DEFAULT_BUILD_PLAN_ID}.`);
+    }
+    const resolved = standaloneBuildPlanDefinitionFromLocalPackage(local);
+    builtinDefaultBuildPlanCache = {
+        ...resolved,
+        id: DEFAULT_BUILD_PLAN_ID,
+        recommended: true,
+        scope: "builtin",
+    };
+    return builtinDefaultBuildPlanCache;
+}
+function listBuiltinBuildPlans() {
+    return [getBuiltinDefaultBuildPlan()];
+}
+function resolveBuildPlanFromLocal(buildPlanId, prepDataDir) {
+    const local = loadLocalBuildPlanDefinition(prepDataDir, buildPlanId);
+    if (!local)
+        return null;
+    const resolved = standaloneBuildPlanDefinitionFromLocalPackage(local);
+    return resolved;
+}
+function resolveBuildPlanFromUserLibrary(buildPlanId) {
+    const user = loadUserBuildPlanDefinition(buildPlanId);
+    if (!user)
+        return null;
+    const resolved = standaloneBuildPlanDefinitionFromLocalPackage(user);
+    return { ...resolved, scope: "user" };
+}
+export function listBuildPlanChoices(prepDataDir) {
+    const builtins = listBuiltinBuildPlans();
+    const buildPlansById = new Map();
+    for (const buildPlan of builtins) {
+        buildPlansById.set(buildPlan.id, buildPlan);
+    }
+    for (const definition of listUserBuildPlanDefinitions()) {
+        try {
+            const buildPlan = resolveBuildPlanFromUserLibrary(definition.id);
+            if (buildPlan)
+                buildPlansById.set(buildPlan.id, buildPlan);
+        }
+        catch (error) {
+            warnInterf(`Warning: skipping user Build Plan "${definition.id}" because it could not be resolved cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!prepDataDir)
+        return [...buildPlansById.values()];
+    for (const definition of listLocalBuildPlanDefinitions(prepDataDir)) {
+        try {
+            const buildPlan = resolveBuildPlanFromLocal(definition.id, prepDataDir);
+            if (buildPlan)
+                buildPlansById.set(buildPlan.id, buildPlan);
+        }
+        catch (error) {
+            warnInterf(`Warning: skipping local Build Plan "${definition.id}" because it could not be resolved cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return [...buildPlansById.values()];
+}
+export function getBuildPlan(buildPlanId, options = {}) {
+    if (options.prepDataDir) {
+        const local = resolveBuildPlanFromLocal(buildPlanId, options.prepDataDir);
+        if (local)
+            return local;
+    }
+    const user = resolveBuildPlanFromUserLibrary(buildPlanId);
+    if (user)
+        return user;
+    const builtin = listBuiltinBuildPlans().find((candidate) => candidate.id === buildPlanId);
+    if (builtin)
+        return builtin;
+    if (options.prepDataDir) {
+        throw new Error(`No Build Plan package "${buildPlanId}" found in this Preparation, in your user library, or among bundled Build Plan packages. Looked under ${preparationBuildPlanPackagePath(asPreparationDataDir(options.prepDataDir), buildPlanId)} and ~/.interf/build-plans/${buildPlanId}.`);
+    }
+    throw new Error(`Build Plan package "${buildPlanId}" is not built-in and no Preparation data directory was provided to look for a local override.`);
+}
+export function getActiveBuildPlan(verifiableContextPath) {
+    const buildPlanPath = buildPlanPackagePathForVerifiableContext(verifiableContextPath);
+    if (existsSync(join(buildPlanPath, "build-plan.json"))) {
+        const local = loadBuildPlanDefinitionFromDir(buildPlanPath);
+        if (!local) {
+            throw new Error(`Local Build Plan package at ${buildPlanPath} is missing or invalid. Interf build runs the local package directly; recreate or reseed this verifiable context.`);
+        }
+        return standaloneBuildPlanDefinitionFromLocalPackage(local);
+    }
+    throw new Error(`Missing local Build Plan package at ${buildPlanPath}. Interf build runs the local package directly, so recreate or reseed this verifiable context under ${resolveSourceControlPath(verifiableContextPath)}.`);
+}
+export function resolveVerifiableContextBuildPlanId(value) {
+    if (typeof value === "string" && isBuildPlanId(value)) {
+        return value;
+    }
+    return null;
+}
+export function resolveBuildPlanFromConfig(config) {
+    if (!config || typeof config !== "object")
+        return null;
+    const raw = config;
+    return resolveVerifiableContextBuildPlanId(raw.build_plan);
+}
+export function resolveRequiredBuildPlanFromConfig(config, label = "verifiable-context config") {
+    const buildPlanId = resolveBuildPlanFromConfig(config);
+    if (!buildPlanId) {
+        throw new Error(`Missing or invalid Build Plan in ${label}.`);
+    }
+    return buildPlanId;
+}
+function resolveBuildPlanDefinitionForStageMetadata(buildPlanId, prepDataDir) {
+    if (prepDataDir &&
+        existsSync(join(buildPlanPackagePathForVerifiableContext(prepDataDir), "build-plan.json"))) {
+        return getActiveBuildPlan(prepDataDir);
+    }
+    return getBuildPlan(buildPlanId, { prepDataDir });
+}
+function formatBuildPlanStageLabel(buildPlan, stage) {
+    const stageIndex = buildPlan.stages.findIndex((candidate) => candidate.id === stage);
+    if (stageIndex === -1) {
+        throw new Error(`Stage "${stage}" is not part of the build runtime.`);
+    }
+    const stageDefinition = buildPlan.stages[stageIndex];
+    if (!stageDefinition) {
+        throw new Error(`Stage "${stage}" is not part of the build runtime.`);
+    }
+    return `Stage ${stageIndex + 1}/${buildPlan.stages.length} - ${stageDefinition.label}`;
+}
+export function getBuildPlanStageDefinition(buildPlanId, stage, prepDataDir) {
+    const buildPlan = resolveBuildPlanDefinitionForStageMetadata(buildPlanId, prepDataDir);
+    return buildPlan.stages.find((candidate) => candidate.id === stage) ?? null;
+}
+export function getBuildPlanStagePosition(buildPlanId, stage, prepDataDir) {
+    const stages = getBuildPlanStages(buildPlanId, prepDataDir);
+    const stageIndex = stages.findIndex((candidate) => candidate === stage);
+    if (stageIndex === -1)
+        return null;
+    return {
+        stageIndex: stageIndex + 1,
+        stageTotal: stages.length,
+        stages: [...stages],
+    };
+}
+export function getBuildPlanStages(buildPlanId, prepDataDir) {
+    return resolveBuildPlanDefinitionForStageMetadata(buildPlanId, prepDataDir).stages.map((definition) => definition.id);
+}
+export function getActiveBuildPlanStages(verifiableContextPath) {
+    return getActiveBuildPlan(verifiableContextPath).stages.map((definition) => definition.id);
+}
+export function getActiveBuildPlanStagePolicyNotes(verifiableContextPath, stage) {
+    const buildPlan = getActiveBuildPlan(verifiableContextPath);
+    return [...(buildPlan.stagePolicyNotes?.[stage] ?? [])];
+}
+export function formatActiveBuildPlanStageLabel(verifiableContextPath, stage) {
+    return formatBuildPlanStageLabel(getActiveBuildPlan(verifiableContextPath), stage);
+}

package/dist/packages/{methods/package/method-helpers.d.ts → build-plans/package/build-plan-helpers.d.ts}

@@ -1,14 +1,14 @@
-import { type LocalInstructionMode, type RuntimeInstructionMode, type RuntimeStageInstructions } from "../../engine/compile/lib/schema.js";
-export interface MethodReporter {
+import { type LocalInstructionMode, type RuntimeInstructionMode, type RuntimeStageInstructions } from "../../engine/build/lib/schema.js";
+export interface BuildPlanReporter {
     line?: (message: string) => void;
     blankLine?: () => void;
 }
-export interface MethodStageResult {
+export interface BuildPlanStageResult {
     ok: boolean;
     code: number;
     summary?: string | null;
 }
-export declare function methodCompileStageDirectory(stageDir: string): string;
+export declare function buildPlanStageDirectory(stageDir: string): string;
 export interface LocalSkillContractExtension {
     reads: string[];
     count: number;
@@ -19,6 +19,6 @@ export interface LocalSkillContractExtension {
 }
 export declare function buildLocalSkillContractExtension(rootPath: string, directories: string[], purpose: string): LocalSkillContractExtension;
 export declare function buildStageInstructions(stageSkillDir: string, localSkills: LocalSkillContractExtension): RuntimeStageInstructions;
-export declare function reportLine(reporter: MethodReporter | undefined, message: string): void;
-export declare function reportBlankLine(reporter: MethodReporter | undefined): void;
-export declare function reportValidationFailure(reporter: MethodReporter | undefined, summary: string, errors?: string[]): void;
+export declare function reportLine(reporter: BuildPlanReporter | undefined, message: string): void;
+export declare function reportBlankLine(reporter: BuildPlanReporter | undefined): void;
+export declare function reportValidationFailure(reporter: BuildPlanReporter | undefined, summary: string, errors?: string[]): void;

package/dist/packages/{methods/package/method-helpers.js → build-plans/package/build-plan-helpers.js}

@@ -3,10 +3,10 @@ import { join, relative, sep } from "node:path";
 import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { parseJsonFrontmatter } from "../../contracts/utils/parse.js";
 import { isMarkdownFile } from "../../contracts/utils/file-types.js";
-import { COMPILED_METHOD_DIR, methodPackagePathForCompiled } from "../../engine/compile/compiled-paths.js";
+import { VERIFIABLE_CONTEXT_BUILD_PLAN_DIR, buildPlanPackagePathForVerifiableContext } from "../../engine/build/verifiable-context-paths.js";
 const LOCAL_SKILL_READ_LIMIT = 50;
-export function methodCompileStageDirectory(stageDir) {
-    return `${COMPILED_METHOD_DIR}/compile/stages/${stageDir}`;
+export function buildPlanStageDirectory(stageDir) {
+    return `${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}/build/stages/${stageDir}`;
 }
 function emptyLocalSkillContractExtension() {
     return {
@@ -30,10 +30,10 @@ function readLocalInstructionMode(filePath) {
 }
 function collectLocalSkillDocs(rootPath, directories) {
     const docs = new Map();
-    const methodRoot = methodPackagePathForCompiled(rootPath);
-    const rootReadme = join(methodRoot, "README.md");
+    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(rootPath);
+    const rootReadme = join(buildPlanRoot, "README.md");
     if (existsSync(rootReadme)) {
-        const read = projectMethodReadPath(rootPath, rootReadme);
+        const read = projectBuildPlanReadPath(rootPath, rootReadme);
         docs.set(read, {
             read,
             absolutePath: rootReadme,
@@ -43,7 +43,7 @@ function collectLocalSkillDocs(rootPath, directories) {
     for (const directory of directories) {
         const absoluteDirectory = resolveAuthoringDirectory(rootPath, directory);
         for (const filePath of listFilesRecursive(absoluteDirectory, isMarkdownFile)) {
-            const read = projectMethodReadPath(rootPath, filePath);
+            const read = projectBuildPlanReadPath(rootPath, filePath);
             docs.set(read, {
                 read,
                 absolutePath: filePath,
@@ -56,21 +56,21 @@ function collectLocalSkillDocs(rootPath, directories) {
         .slice(0, LOCAL_SKILL_READ_LIMIT);
 }
 function resolveAuthoringDirectory(rootPath, directory) {
-    if (directory === COMPILED_METHOD_DIR) {
-        return methodPackagePathForCompiled(rootPath);
+    if (directory === VERIFIABLE_CONTEXT_BUILD_PLAN_DIR) {
+        return buildPlanPackagePathForVerifiableContext(rootPath);
     }
-    if (directory.startsWith(`${COMPILED_METHOD_DIR}${sep}`) || directory.startsWith(`${COMPILED_METHOD_DIR}/`)) {
-        const relativeMethodPath = directory.replace(/^method[\\/]/, "");
-        return join(methodPackagePathForCompiled(rootPath), relativeMethodPath);
+    if (directory.startsWith(`${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}${sep}`) || directory.startsWith(`${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}/`)) {
+        const relativeBuildPlanPath = directory.replace(/^build-plan[\\/]/, "");
+        return join(buildPlanPackagePathForVerifiableContext(rootPath), relativeBuildPlanPath);
     }
     return join(rootPath, directory);
 }
-function projectMethodReadPath(rootPath, absolutePath) {
-    const methodRoot = methodPackagePathForCompiled(rootPath);
-    const normalizedMethodRoot = `${methodRoot}${sep}`;
-    if (absolutePath === methodRoot || absolutePath.startsWith(normalizedMethodRoot)) {
-        const relativeMethodPath = relative(methodRoot, absolutePath);
-        return relative(rootPath, join(rootPath, COMPILED_METHOD_DIR, relativeMethodPath));
+function projectBuildPlanReadPath(rootPath, absolutePath) {
+    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(rootPath);
+    const normalizedBuildPlanRoot = `${buildPlanRoot}${sep}`;
+    if (absolutePath === buildPlanRoot || absolutePath.startsWith(normalizedBuildPlanRoot)) {
+        const relativeBuildPlanPath = relative(buildPlanRoot, absolutePath);
+        return relative(rootPath, join(rootPath, VERIFIABLE_CONTEXT_BUILD_PLAN_DIR, relativeBuildPlanPath));
     }
     return relative(rootPath, absolutePath);
 }
@@ -98,8 +98,8 @@ function buildContractExtensionFromDocs(docs, directories, purpose) {
         notes: [
             readNotice,
             localMode === "override"
-                ? `${purpose} One or more local docs declare \`mode: override\`, so their Method instructions replace Interf's bundled stage instructions for this run. They still do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`
-                : `${purpose} These local Method docs can refine the stage, but they do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`,
+                ? `${purpose} One or more local docs declare \`mode: override\`, so their Build Plan instructions replace Interf's bundled stage instructions for this run. They still do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`
+                : `${purpose} These local Build Plan docs can refine the stage, but they do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`,
         ],
         localMode,
         effectiveMode: localMode ?? "builtin",

package/dist/packages/build-plans/package/build-plan-review-paths.d.ts

@@ -0,0 +1,10 @@
+import type { BuildPlanImprovementContext } from "../../engine/build/lib/schema.js";
+export interface BuildPlanImprovementReviewSourcePaths {
+    verifiableContextRuntime: string | null;
+    readinessRuns: string | null;
+    executionShells: string | null;
+    targetTestRuns: string | null;
+    targetTestSandboxes: string | null;
+}
+export declare function resolveBuildPlanImprovementReviewSourcePaths(verifiableContextPath: string): BuildPlanImprovementReviewSourcePaths;
+export declare function resolveBuildPlanImprovementReviewPaths(verifiableContextPath: string): BuildPlanImprovementContext["review_paths"];

package/dist/packages/build-plans/package/build-plan-review-paths.js

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { testRootForVerifiableContext, targetTestRunsRootForVerifiableContext, targetTestSandboxesRootForVerifiableContext, stageExecutionShellsRoot, verifiableContextRuntimeRoot, } from "../../engine/build/verifiable-context-paths.js";
+export function resolveBuildPlanImprovementReviewSourcePaths(verifiableContextPath) {
+    const verifiableContextRuntime = verifiableContextRuntimeRoot(verifiableContextPath);
+    const readinessRuns = testRootForVerifiableContext(verifiableContextPath);
+    const executionShells = stageExecutionShellsRoot(verifiableContextPath);
+    const targetTestRuns = targetTestRunsRootForVerifiableContext(verifiableContextPath);
+    const targetTestSandboxes = targetTestSandboxesRootForVerifiableContext(verifiableContextPath);
+    return {
+        verifiableContextRuntime: existsSync(verifiableContextRuntime) ? verifiableContextRuntime : null,
+        readinessRuns: existsSync(join(readinessRuns, "latest.json")) ||
+            existsSync(join(readinessRuns, "latest.md"))
+            ? readinessRuns
+            : null,
+        executionShells: existsSync(executionShells) ? executionShells : null,
+        targetTestRuns: existsSync(targetTestRuns) ? targetTestRuns : null,
+        targetTestSandboxes: existsSync(targetTestSandboxes) ? targetTestSandboxes : null,
+    };
+}
+export function resolveBuildPlanImprovementReviewPaths(verifiableContextPath) {
+    const sources = resolveBuildPlanImprovementReviewSourcePaths(verifiableContextPath);
+    return {
+        build_plan_root: "build-plan",
+        verifiable_context_runtime: sources.verifiableContextRuntime ? "artifacts/verifiable-context-runtime" : null,
+        readiness_runs: sources.readinessRuns ? "artifacts/readiness-runs" : null,
+        execution_shells: sources.executionShells ? "artifacts/execution-shells" : null,
+        test_runs: sources.targetTestRuns ? "artifacts/test-runs" : null,
+        test_sandboxes: sources.targetTestSandboxes ? "artifacts/test-sandboxes" : null,
+    };
+}

package/dist/packages/{methods/package/method-stage-runner.d.ts → build-plans/package/build-plan-stage-runner.d.ts}

@@ -1,26 +1,26 @@
-import { type MethodExecutor } from "../../engine/agents/lib/executors.js";
-import { type RuntimeStageInstructions } from "../../engine/compile/lib/schema.js";
+import { type AgentExecutor } from "../../engine/agents/lib/executors.js";
+import { type RuntimeStageInstructions } from "../../engine/build/lib/schema.js";
 import type { RuntimeContractType } from "../../contracts/lib/schema.js";
-import { type RuntimeStageContractDraft } from "../../engine/compile/runtime.js";
-import { type MethodReporter, type MethodStageResult } from "./method-helpers.js";
-interface MethodStageShape<TContractType extends RuntimeContractType> {
+import { type RuntimeStageContractDraft } from "../../engine/build/runtime.js";
+import { type BuildPlanReporter, type BuildPlanStageResult } from "./build-plan-helpers.js";
+interface BuildPlanStageShape<TContractType extends RuntimeContractType> {
     id: string;
     label: string;
     contractType: TContractType;
 }
 interface ExecuteValidatedStageOptions<TContractType extends RuntimeContractType> {
-    executor: MethodExecutor;
-    compiledPath: string;
+    executor: AgentExecutor;
+    verifiableContextPath: string;
     executionPath?: string;
     targetName: string;
-    method: string;
-    methodSourcePath?: string;
-    stageDefinition: MethodStageShape<TContractType>;
+    buildPlan: string;
+    buildPlanSourcePath?: string;
+    stageDefinition: BuildPlanStageShape<TContractType>;
     instructions: RuntimeStageInstructions;
     summary: string;
     contract: RuntimeStageContractDraft;
     statusLines: string[];
-    reporter?: MethodReporter;
+    reporter?: BuildPlanReporter;
     completionCheck?: (() => boolean) | null;
     onStatus?: (line: string) => void;
     syncWrites?: (() => void) | null;
@@ -34,5 +34,5 @@ interface ExecuteValidatedStageOptions<TContractType extends RuntimeContractType
 export declare function findStageByContractType<TStage extends {
     contractType: string;
 }>(stages: TStage[], contractType: TStage["contractType"]): TStage;
-export declare function executeValidatedStage<TContractType extends RuntimeContractType>(options: ExecuteValidatedStageOptions<TContractType>): Promise<MethodStageResult>;
+export declare function executeValidatedStage<TContractType extends RuntimeContractType>(options: ExecuteValidatedStageOptions<TContractType>): Promise<BuildPlanStageResult>;
 export {};

package/dist/packages/{methods/package/method-stage-runner.js → build-plans/package/build-plan-stage-runner.js}

@@ -1,9 +1,9 @@
-import { markRuntimeRunSucceededAfterValidation, buildStagePrompt, markRuntimeRunFailedAfterValidation, runExecutorStage, } from "../../engine/compile/runtime.js";
-import { reportValidationFailure, } from "./method-helpers.js";
+import { markRuntimeRunSucceededAfterValidation, buildStagePrompt, markRuntimeRunFailedAfterValidation, runExecutorStage, } from "../../engine/build/runtime.js";
+import { reportValidationFailure, } from "./build-plan-helpers.js";
 export function findStageByContractType(stages, contractType) {
     const stage = stages.find((candidate) => candidate.contractType === contractType);
     if (!stage) {
-        throw new Error(`Missing method stage for contract type: ${contractType}`);
+        throw new Error(`Missing Build Plan stage for contract type: ${contractType}`);
     }
     return stage;
 }
@@ -17,11 +17,11 @@ export async function executeValidatedStage(options) {
         : undefined;
     const code = await runExecutorStage({
         executor: options.executor,
-        compiledPath: options.compiledPath,
+        verifiableContextPath: options.verifiableContextPath,
         executionPath: options.executionPath,
-        compiledName: options.targetName,
-        method: options.method,
-        methodSourcePath: options.methodSourcePath,
+        verifiableContextName: options.targetName,
+        buildPlan: options.buildPlan,
+        buildPlanSourcePath: options.buildPlanSourcePath,
         stage: options.stageDefinition.id,
         stageLabel: options.stageDefinition.label,
         contractType: options.stageDefinition.contractType,
@@ -53,7 +53,7 @@ function finalizeValidatedStage(options, code) {
         if (completionSatisfied) {
             const validation = refreshAndValidate();
             if (validation.ok) {
-                markRuntimeRunSucceededAfterValidation(options.compiledPath, validation.summary);
+                markRuntimeRunSucceededAfterValidation(options.verifiableContextPath, validation.summary);
                 return {
                     ok: true,
                     code: 0,
@@ -61,7 +61,7 @@ function finalizeValidatedStage(options, code) {
                 };
             }
             reportValidationFailure(options.reporter, validation.summary);
-            markRuntimeRunFailedAfterValidation(options.compiledPath, validation.summary);
+            markRuntimeRunFailedAfterValidation(options.verifiableContextPath, validation.summary);
             return {
                 ok: false,
                 code,
@@ -73,7 +73,7 @@ function finalizeValidatedStage(options, code) {
     const validation = refreshAndValidate();
     if (!validation.ok) {
         reportValidationFailure(options.reporter, validation.summary);
-        markRuntimeRunFailedAfterValidation(options.compiledPath, validation.summary);
+        markRuntimeRunFailedAfterValidation(options.verifiableContextPath, validation.summary);
     }
     return {
         ok: validation.ok,

package/dist/packages/build-plans/package/builtin-build-plan.d.ts

@@ -0,0 +1,37 @@
+import { type BuildPlanArtifactKind } from "../../engine/build/build-plan-primitives.js";
+declare const BUILTIN_BUILD_PLAN_STAGE_IDS: {
+    readonly SUMMARIZE: "summarize";
+    readonly STRUCTURE: "structure";
+    readonly SHAPE: "shape";
+};
+type BuiltinBuildStageId = typeof BUILTIN_BUILD_PLAN_STAGE_IDS[keyof typeof BUILTIN_BUILD_PLAN_STAGE_IDS];
+export declare const BUILTIN_BUILD_PLAN_ARTIFACT_IDS: {
+    readonly SUMMARIES: "summaries";
+    readonly KNOWLEDGE_ENTITIES: "knowledge-entities";
+    readonly KNOWLEDGE_CLAIMS: "knowledge-claims";
+    readonly KNOWLEDGE_INDEXES: "knowledge-indexes";
+    readonly HOME: "atlas";
+    readonly RUNTIME: "runtime";
+};
+export type BuiltinBuildPlanArtifactId = typeof BUILTIN_BUILD_PLAN_ARTIFACT_IDS[keyof typeof BUILTIN_BUILD_PLAN_ARTIFACT_IDS];
+export interface BuiltinBuildPlanArtifactSpec {
+    id: BuiltinBuildPlanArtifactId;
+    role: "input" | "working" | "output" | "runtime";
+    path: string;
+    kind: BuildPlanArtifactKind;
+    required: boolean;
+    description: string;
+}
+export interface BuiltinBuildStageAccessPattern {
+    id: BuiltinBuildStageId;
+    contract_type: string;
+    reads: BuiltinBuildPlanArtifactId[];
+    writes: BuiltinBuildPlanArtifactId[];
+}
+export declare function listBuiltinBuildPlanArtifactSpecs(): BuiltinBuildPlanArtifactSpec[];
+export declare function listBuiltinBuildPlanFallbackStages(): BuiltinBuildStageAccessPattern[];
+export declare function requiredBuildPlanArtifactOwners<TStage extends {
+    id: string;
+    writes: readonly string[];
+}>(stages: readonly TStage[], artifactId: BuiltinBuildPlanArtifactId): string[];
+export {};

package/dist/packages/build-plans/package/builtin-build-plan.js

@@ -0,0 +1,91 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { BuildPlanContextSchemaSchema } from "../../engine/build/lib/schema.js";
+import { PACKAGE_ROOT } from "./lib/package-root.js";
+const BUILTIN_BUILD_PLAN_STAGE_IDS = {
+    SUMMARIZE: "summarize",
+    STRUCTURE: "structure",
+    SHAPE: "shape",
+};
+export const BUILTIN_BUILD_PLAN_ARTIFACT_IDS = {
+    SUMMARIES: "summaries",
+    KNOWLEDGE_ENTITIES: "knowledge-entities",
+    KNOWLEDGE_CLAIMS: "knowledge-claims",
+    KNOWLEDGE_INDEXES: "knowledge-indexes",
+    HOME: "atlas",
+    RUNTIME: "runtime",
+};
+const BUILTIN_ARTIFACT_ID_SET = new Set(Object.values(BUILTIN_BUILD_PLAN_ARTIFACT_IDS));
+const BUILTIN_STAGE_ID_SET = new Set(Object.values(BUILTIN_BUILD_PLAN_STAGE_IDS));
+const BuiltinBuildPlanStageSchema = z.object({
+    id: z.string(),
+    contract_type: z.string(),
+    reads: z.array(z.string()),
+    writes: z.array(z.string()).min(1),
+});
+const BuiltinBuildPlanPackageSchema = z.object({
+    stages: z.array(BuiltinBuildPlanStageSchema).min(1),
+});
+let builtinBuildPlanContractCache = null;
+const BUILTIN_DEFAULT_WORKFLOW_ROOT = join(PACKAGE_ROOT, "public-repo", "build-plans", "interf-default");
+function assertBuiltinArtifactId(value) {
+    if (!BUILTIN_ARTIFACT_ID_SET.has(value)) {
+        throw new Error(`Built-in Interf Build Plan schema declares unsupported Artifact id "${value}".`);
+    }
+    return value;
+}
+function assertBuiltinStageId(value) {
+    if (!BUILTIN_STAGE_ID_SET.has(value)) {
+        throw new Error(`Built-in Interf Build Plan package declares unsupported stage id "${value}".`);
+    }
+    return value;
+}
+function loadBuiltinBuildPlanContract() {
+    if (builtinBuildPlanContractCache)
+        return builtinBuildPlanContractCache;
+    const schemaPath = join(BUILTIN_DEFAULT_WORKFLOW_ROOT, "build-plan.schema.json");
+    const buildPlanPath = join(BUILTIN_DEFAULT_WORKFLOW_ROOT, "build-plan.json");
+    const schema = readJsonFileWithSchema(schemaPath, "built-in Interf Build Plan schema", BuildPlanContextSchemaSchema);
+    if (!schema) {
+        throw new Error(`Missing or invalid built-in Build Plan package schema at ${schemaPath}.`);
+    }
+    const buildPlan = readJsonFileWithSchema(buildPlanPath, "built-in Interf Build Plan package", BuiltinBuildPlanPackageSchema);
+    if (!buildPlan) {
+        throw new Error(`Missing or invalid built-in Build Plan package at ${buildPlanPath}.`);
+    }
+    const artifacts = schema.artifacts.map((artifact) => {
+        const path = artifact.shape.path;
+        return {
+            id: assertBuiltinArtifactId(artifact.id),
+            role: "output",
+            path,
+            kind: artifact.shape.artifact_kind,
+            required: true,
+            description: artifact.description,
+        };
+    });
+    const stages = buildPlan.stages.map((stage) => ({
+        id: assertBuiltinStageId(stage.id),
+        contract_type: stage.contract_type,
+        reads: stage.reads.map(assertBuiltinArtifactId),
+        writes: stage.writes.map(assertBuiltinArtifactId),
+    }));
+    builtinBuildPlanContractCache = { artifacts, stages };
+    return builtinBuildPlanContractCache;
+}
+export function listBuiltinBuildPlanArtifactSpecs() {
+    return loadBuiltinBuildPlanContract().artifacts.map((artifact) => ({ ...artifact }));
+}
+export function listBuiltinBuildPlanFallbackStages() {
+    return loadBuiltinBuildPlanContract().stages.map((stage) => ({
+        ...stage,
+        reads: [...stage.reads],
+        writes: [...stage.writes],
+    }));
+}
+export function requiredBuildPlanArtifactOwners(stages, artifactId) {
+    return Array.from(new Set(stages
+        .filter((stage) => stage.writes.includes(artifactId))
+        .map((stage) => stage.id)));
+}

package/dist/packages/{methods → build-plans}/package/context-interface.d.ts

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import { type MethodCompiledSchema, type MethodCompiledArtifact, type MethodArtifactId } from "../../engine/compile/lib/schema.js";
-export declare const CONTEXT_INTERFACE_FILE = "method.schema.json";
+import { type BuildPlanContextSchema, type BuildPlanArtifact, type BuildPlanArtifactId } from "../../engine/build/lib/schema.js";
+export declare const CONTEXT_INTERFACE_FILE = "build-plan.schema.json";
 export declare const ContextInterfaceSchema: z.ZodObject<{
-    kind: z.ZodLiteral<"method-schema">;
+    kind: z.ZodLiteral<"build-plan-schema">;
     version: z.ZodLiteral<1>;
-    target_type: z.ZodLiteral<"compiled">;
+    target_type: z.ZodLiteral<"verifiable-context">;
     label: z.ZodString;
     artifacts: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -37,17 +37,17 @@ export declare const ContextInterfaceSchema: z.ZodObject<{
         built_by_stages: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-export declare const MethodInputSpecSchema: z.ZodObject<{
+export declare const BuildPlanInputSpecSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
     description: z.ZodString;
     required: z.ZodDefault<z.ZodBoolean>;
     examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
-export type ContextInterface = MethodCompiledSchema;
-export type ContextInterfaceArtifact = MethodCompiledArtifact;
-export type ContextInterfaceArtifactId = MethodArtifactId;
-export type MethodInputSpec = z.infer<typeof MethodInputSpecSchema>;
+export type ContextInterface = BuildPlanContextSchema;
+export type ContextInterfaceArtifact = BuildPlanArtifact;
+export type ContextInterfaceArtifactId = BuildPlanArtifactId;
+export type BuildPlanInputSpec = z.infer<typeof BuildPlanInputSpecSchema>;
 interface ContextInterfaceStageLike {
     id: string;
     writes: readonly string[];
@@ -62,10 +62,10 @@ export declare function listContextInterfaceArtifacts(contextInterface: ContextI
 export declare function contextInterfaceFilePath(rootPath: string): string;
 export declare function resolveContextInterfacePath(rootPath: string): string | null;
 export declare function contextInterfaceExists(rootPath: string): boolean;
-export declare function contextInterfaceArtifactAbsolutePath(compiledPath: string, artifact: Pick<ContextInterfaceArtifact, "path">): string;
+export declare function contextInterfaceArtifactAbsolutePath(verifiableContextPath: string, artifact: Pick<ContextInterfaceArtifact, "path">): string;
 export declare function contextInterfaceArtifactPath(artifact: Pick<ContextInterfaceArtifact, "path" | "kind">): string;
 export declare function summarizeContextInterface(contextInterface: ContextInterface): ContextInterfaceSummary;
-export declare function deriveMethodInputsFromContextInterface(contextInterface: ContextInterface | null | undefined): MethodInputSpec[];
+export declare function deriveBuildPlanInputsFromContextInterface(contextInterface: ContextInterface | null | undefined): BuildPlanInputSpec[];
 export declare function buildContextInterface(stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
 export declare function writeContextInterfaceFile(rootPath: string, stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
 export declare function writeContextInterface(rootPath: string, contextInterface: ContextInterface): ContextInterface;