@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/build-plans/authoring/build-plan-edit-session.d.ts

@@ -1,4 +1,4 @@
-import type { AgentExecutor } from "../../engine/agents/lib/executors.js";
+import type { AgentExecutor } from "../../runtime/agents/lib/executors.js";
 import type { BuildPlanValidationResult } from "../package/local-build-plans.js";
 import { type BuildPlanEditShellArtifacts } from "./lib/build-plan-edit-utils.js";
 export interface BuildPlanEditSessionResult {
@@ -7,6 +7,15 @@ export interface BuildPlanEditSessionResult {
     validation: BuildPlanValidationResult | null;
     summary: string;
 }
+/**
+ * Stable Build Plan editing rules shared verbatim by every prompt that edits a
+ * Build Plan package — the from-scratch authoring prompt
+ * (`build-plan-authoring.ts`) and the validation-repair prompt below. Defined
+ * once so the wording cannot drift between the two prompts. Each entry is the
+ * bare rule text; the repair prompt renders it as a `- ` bullet, the authoring
+ * prompt renders it as a plain line.
+ */
+export declare const SHARED_BUILD_PLAN_EDIT_RULES: readonly string[];
 export declare function runBuildPlanEditSession(options: {
     executor: AgentExecutor;
     buildPlanPath: string;

package/dist/packages/build-plans/authoring/build-plan-edit-session.js

@@ -1,6 +1,19 @@
 import { appendFileSync, existsSync, realpathSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { copyDirectory, directoriesMatch, } from "./lib/build-plan-edit-utils.js";
+/**
+ * Stable Build Plan editing rules shared verbatim by every prompt that edits a
+ * Build Plan package — the from-scratch authoring prompt
+ * (`build-plan-authoring.ts`) and the validation-repair prompt below. Defined
+ * once so the wording cannot drift between the two prompts. Each entry is the
+ * bare rule text; the repair prompt renders it as a `- ` bullet, the authoring
+ * prompt renders it as a plain line.
+ */
+export const SHARED_BUILD_PLAN_EDIT_RULES = [
+    "Use kebab-case ids everywhere: stage ids, skill_dir values, requested output ids, reads/writes values, and package ids. Never use underscores.",
+    "Use `runtime/authoring-context.json.check_param_contracts` as the exact parameter contract for each check kind.",
+    "Every deterministic diagnostic must include a human-readable `description` that names the user's assertion; keep `kind` and `params` as the machine evaluator and never as user copy.",
+];
 export async function runBuildPlanEditSession(options) {
     const editableBuildPlanPath = join(options.shell.rootPath, "build-plan");
     copyDirectory(options.buildPlanPath, options.shell.buildPlanBeforePath);
@@ -17,6 +30,7 @@ export async function runBuildPlanEditSession(options) {
             code = await options.executor.execute(options.shell.rootPath, prompt, {
                 eventLogPath: options.shell.eventLogPath,
                 statusLogPath: options.shell.statusLogPath,
+                reasoningLogPath: options.shell.reasoningLogPath,
                 completionCheck: () => {
                     try {
                         if (directoriesMatch(options.shell.buildPlanBeforePath, editableBuildPlanPath))
@@ -94,12 +108,21 @@ export async function runBuildPlanEditSession(options) {
             "",
             "Rules:",
             "- Edit only files under `build-plan/`.",
-            "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
+            // Stable kebab-case-id rule (shared with the authoring prompt).
+            `- ${SHARED_BUILD_PLAN_EDIT_RULES[0]}`,
+            "- Stage `reads` may only contain requested output ids declared in `build-plan.schema.json` and produced by an earlier stage. Source files are implicit input; never use `source` or source paths in `reads`.",
+            "- Keep coverage expectations, requested outputs, and backed output ids aligned with the Project intent.",
+            "- If `runtime/authoring-context.json.artifact_requirements[]` is non-empty, copy every required output `id`, `shape`, and `checks[]` exactly into `build-plan.schema.json`.",
+            "- Do not rename, move, merge, split, or reinterpret required outputs while repairing validation errors.",
             "- Keep every stage `skill_dir` matched by `build-plan/build/stages/<skill_dir>/SKILL.md`.",
-            "- Keep `build-plan.schema.json` Artifact paths unique and non-overlapping.",
-            "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+            "- Keep `build-plan.schema.json` requested output paths unique. Child outputs may live under the required layer directories `summaries/`, `knowledge/`, and `artifacts/`; unrelated output paths must not overlap.",
+            "- Keep deterministic validation on requested output `checks[]` minimal; do not add stage `acceptance` blocks.",
             "- Use only CheckKind values listed in `runtime/authoring-context.json`; replace invented aliases with valid kinds.",
-            "- If the Build Plan writes an agent entrypoint, keep it declared as an Artifact owned by the producing stage.",
+            // Stable check-param-contract + diagnostic-description rules (shared with
+            // the authoring prompt).
+            `- ${SHARED_BUILD_PLAN_EDIT_RULES[1]}`,
+            `- ${SHARED_BUILD_PLAN_EDIT_RULES[2]}`,
+            "- If the Build Plan writes a graph index, keep it declared as a requested output owned by the producing stage.",
             "- Stop as soon as the package should validate.",
         ].join("\n");
         appendFileSync(options.shell.promptLogPath, `\n\n---\n\n${prompt}\n`);

package/dist/packages/build-plans/authoring/build-plan-improvement.d.ts

@@ -1,8 +1,7 @@
-import type { AgentExecutor } from "../../engine/agents/lib/executors.js";
+import type { AgentExecutor } from "../../runtime/agents/lib/executors.js";
 import { type BuildPlanValidationResult } from "../package/local-build-plans.js";
-import type { SourcePreparationConfig } from "../../project/lib/schema.js";
-import type { BuildPlanImprovementLoopSummary } from "../../engine/build/lib/schema.js";
-export interface BuildPlanImprovementRunResult {
+import type { BuildPlanImprovementLoopSummary } from "../../runtime/build/lib/schema.js";
+interface BuildPlanImprovementRunResult {
     status: "updated" | "no-change" | "invalid" | "executor-failed";
     changed: boolean;
     validation: BuildPlanValidationResult | null;
@@ -12,12 +11,16 @@ export interface BuildPlanImprovementRunResult {
 }
 export declare function runBuildPlanImprovementLoop(options: {
     executor: AgentExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     buildPlanId: string;
-    verifiableContextConfig: Pick<SourcePreparationConfig, "checks">;
+    benchmarkChecks: Array<{
+        id: string;
+        question: string;
+    }>;
     runId: string;
     loopIndex: number;
     maxLoops: number;
     maxAttempts: number;
     previousVariations: BuildPlanImprovementLoopSummary[];
 }): Promise<BuildPlanImprovementRunResult>;
+export {};

package/dist/packages/build-plans/authoring/build-plan-improvement.js

@@ -1,16 +1,16 @@
 import { appendFileSync, existsSync, mkdirSync, writeFileSync, } from "node:fs";
 import { join, relative } from "node:path";
-import { createBuildPlanImprovementShell, freezeBuildPlanImprovementShell, } from "../../engine/agents/lib/shells.js";
-import { validateBuildPlanPackage } from "../package/local-build-plans.js";
+import { createBuildPlanImprovementShell, freezeBuildPlanImprovementShell, } from "../../runtime/agents/lib/shells.js";
 import { CONTEXT_INTERFACE_FILE } from "../package/context-interface.js";
 import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
 import { resolveBuildPlanImprovementReviewPaths } from "../package/build-plan-review-paths.js";
-import { targetTestRunsRootForVerifiableContext, targetTestSandboxesRootForVerifiableContext, buildPlanImprovementRunRoot, buildPlanPackagePathForVerifiableContext, } from "../../engine/build/verifiable-context-paths.js";
-import { readInterfConfig } from "../../project/interf.js";
-import { saveVerifiableContextInterfConfig } from "../../project/source-config.js";
-import { BuildPlanImprovementRunLedgerSchema, } from "../../engine/build/lib/schema.js";
+import { targetTestRunsRootForContextGraph, targetTestSandboxesRootForContextGraph, buildPlanImprovementRunRoot, buildPlanPackagePathForContextGraph, } from "../../runtime/build/context-graph-paths.js";
+import { readInterfConfig, resolveSourceFolderPath } from "../../projects/interf.js";
+import { scanSourceContext } from "../../runtime/agents/lib/source-context-scan.js";
+import { saveContextGraphInterfConfig } from "../../projects/source-config.js";
+import { BuildPlanImprovementRunLedgerSchema, } from "../../runtime/build/lib/schema.js";
 import { runBuildPlanEditSession } from "./build-plan-edit-session.js";
-import { ensureStageRoles } from "./build-plan-authoring.js";
+import { ensureStageRoles, validateImproveTailoringNonRegression, validateLifecycleBuildPlanPackage, } from "./build-plan-authoring.js";
 function toShellArtifactPath(absolutePath, sourceRoot, shellRoot) {
     if (!absolutePath)
         return null;
@@ -21,39 +21,61 @@ function toShellArtifactPath(absolutePath, sourceRoot, shellRoot) {
     const relativePath = relative(sourceRoot, absolutePath);
     return join(shellRoot, relativePath);
 }
-function mapLoopSummaryForShell(summary, verifiableContextPath) {
+function mapLoopSummaryForShell(summary, contextGraphPath) {
     const shellTestRunsRoot = "artifacts/test-runs";
     const shellTestSandboxesRoot = "artifacts/test-sandboxes";
     return {
         ...summary,
-        test_run_path: toShellArtifactPath(summary.test_run_path, targetTestRunsRootForVerifiableContext(verifiableContextPath), shellTestRunsRoot) ?? summary.test_run_path ?? null,
-        test_sandbox_path: toShellArtifactPath(summary.test_sandbox_path, targetTestSandboxesRootForVerifiableContext(verifiableContextPath), shellTestSandboxesRoot) ?? summary.test_sandbox_path ?? null,
+        test_run_path: toShellArtifactPath(summary.test_run_path, targetTestRunsRootForContextGraph(contextGraphPath), shellTestRunsRoot) ?? summary.test_run_path ?? null,
+        test_sandbox_path: toShellArtifactPath(summary.test_sandbox_path, targetTestSandboxesRootForContextGraph(contextGraphPath), shellTestSandboxesRoot) ?? summary.test_sandbox_path ?? null,
     };
 }
 function buildLoopContext(options) {
-    const previousVariations = options.previousVariations.map((summary) => mapLoopSummaryForShell(summary, options.verifiableContextPath));
+    const previousVariations = options.previousVariations.map((summary) => mapLoopSummaryForShell(summary, options.contextGraphPath));
     const latestFailure = previousVariations.at(-1) ?? null;
     return {
         kind: "interf-build-plan-improvement-loop",
         version: 1,
         generated_at: new Date().toISOString(),
-        target_name: readInterfConfig(options.verifiableContextPath)?.name ?? "verifiable-context",
+        target_name: readInterfConfig(options.contextGraphPath)?.name ?? "context-graph",
         build_plan_id: options.buildPlanId,
         loop_index: options.loopIndex,
         max_loops: options.maxLoops,
         max_attempts: options.maxAttempts,
-        review_paths: resolveBuildPlanImprovementReviewPaths(options.verifiableContextPath),
-        readiness_checks: {
-            count: options.verifiableContextConfig.checks.length,
-            questions: options.verifiableContextConfig.checks.map((check, index) => ({
-                id: check.id ?? `check-${index + 1}`,
-                question: check.question,
-            })),
+        review_paths: resolveBuildPlanImprovementReviewPaths(options.contextGraphPath),
+        benchmark_questions: {
+            count: options.benchmarkChecks.length,
+            questions: options.benchmarkChecks,
         },
         previous_variations: previousVariations,
         latest_failure: latestFailure,
     };
 }
+/**
+ * Resolve the SAME cheap, contents-free Source inventory the draft path scans,
+ * but from the Context Graph the improvement loop is editing. The Context
+ * Graph's `interf.json` carries the Project's Source binding, so the improve
+ * path CAN reach the Source (`resolveSourceFolderPath` → `scanSourceContext`)
+ * exactly like the draft path does — it is not blind to the Source.
+ *
+ * Returns null (and the tailoring non-regression guard becomes a no-op) only
+ * when there is genuinely nothing to scan: no Source binding in the config, or
+ * the Source has no readable files. A null here never fabricates an inventory.
+ */
+function resolveImproveSourceContext(contextGraphPath) {
+    const config = readInterfConfig(contextGraphPath);
+    let sourceFolderPath;
+    try {
+        sourceFolderPath = resolveSourceFolderPath(contextGraphPath, config);
+    }
+    catch {
+        // No Source binding in the Context Graph config — nothing to tailor
+        // against. The draft path always has a Source folder; the improve path may
+        // run against a Context Graph whose binding is missing, so degrade quietly.
+        return null;
+    }
+    return scanSourceContext(sourceFolderPath) ?? null;
+}
 function buildBuildPlanImprovementPrompt() {
     return [
         "This is an automated Interf Build Plan improvement run, not an open-ended chat session.",
@@ -62,12 +84,12 @@ function buildBuildPlanImprovementPrompt() {
         `Then read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, \`build-plan/${CONTEXT_INTERFACE_FILE}\`, and \`build-plan/improve/SKILL.md\` if it exists.`,
         "Review preserved evidence from earlier failures under `artifacts/` before you edit the Build Plan.",
         "Treat `build-plan/improve/SKILL.md` as guidance for how to improve the Build Plan, not as the default file to edit.",
-        "Treat the Build Plan package as four aligned layers: purpose, inputs, context interface, and stages.",
-        "Prefer editing the stage docs, Build Plan contract, input contract, or schema ownership that actually change verifiable-context outputs.",
+        "Treat the Build Plan package as four aligned layers: purpose, inputs, requested output contract, and stages.",
+        "Prefer editing the stage docs, Build Plan contract, input contract, or requested output ownership that actually change graph outputs.",
         "Edit only files under `build-plan/`.",
-        "Do not edit checks, test specs, source files, or generated verifiable-context outputs.",
+        "Do not edit checks, benchmark specs, source files, or generated requested outputs.",
         "Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
-        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read outputs.",
         "Do not make one stage point at files or notes that are only created later by another stage.",
         "Prefer small, defensible changes to Build Plan docs, stage docs, stage policies, or schema ownership over random churn.",
         "Do not narrate plans or ask follow-up questions.",
@@ -76,7 +98,7 @@ function buildBuildPlanImprovementPrompt() {
     ].join("\n");
 }
 function updateBuildPlanOrigin(options) {
-    const current = readInterfConfig(options.verifiableContextPath);
+    const current = readInterfConfig(options.contextGraphPath);
     if (!current)
         return;
     const nextConfig = {
@@ -86,27 +108,27 @@ function updateBuildPlanOrigin(options) {
             ...(options.localDraft ? { local_draft: true } : {}),
         },
     };
-    saveVerifiableContextInterfConfig(options.verifiableContextPath, nextConfig);
+    saveContextGraphInterfConfig(options.contextGraphPath, nextConfig);
 }
-function buildPlanImprovementRunLedgerPath(verifiableContextPath, runId) {
-    return join(buildPlanImprovementRunRoot(verifiableContextPath, runId), "run.json");
+function buildPlanImprovementRunLedgerPath(contextGraphPath, runId) {
+    return join(buildPlanImprovementRunRoot(contextGraphPath, runId), "run.json");
 }
-function buildPlanImprovementLoopHistoryPath(verifiableContextPath, runId) {
-    return join(buildPlanImprovementRunRoot(verifiableContextPath, runId), "loop-history.jsonl");
+function buildPlanImprovementLoopHistoryPath(contextGraphPath, runId) {
+    return join(buildPlanImprovementRunRoot(contextGraphPath, runId), "loop-history.jsonl");
 }
 function buildPlanImprovementLoopRecordPath(loopRootPath) {
     return join(loopRootPath, "loop.json");
 }
-function readBuildPlanImprovementRunLedger(verifiableContextPath, runId) {
-    const ledgerPath = buildPlanImprovementRunLedgerPath(verifiableContextPath, runId);
+function readBuildPlanImprovementRunLedger(contextGraphPath, runId) {
+    const ledgerPath = buildPlanImprovementRunLedgerPath(contextGraphPath, runId);
     if (!existsSync(ledgerPath))
         return null;
     return readJsonFileWithSchema(ledgerPath, "Build Plan improvement run ledger", BuildPlanImprovementRunLedgerSchema);
 }
-function writeBuildPlanImprovementRunLedger(verifiableContextPath, runId, record, options) {
-    const runRoot = buildPlanImprovementRunRoot(verifiableContextPath, runId);
+function writeBuildPlanImprovementRunLedger(contextGraphPath, runId, record, options) {
+    const runRoot = buildPlanImprovementRunRoot(contextGraphPath, runId);
     mkdirSync(runRoot, { recursive: true });
-    const existing = readBuildPlanImprovementRunLedger(verifiableContextPath, runId);
+    const existing = readBuildPlanImprovementRunLedger(contextGraphPath, runId);
     const generatedAt = existing?.generated_at ?? new Date().toISOString();
     const ledger = {
         kind: "interf-build-plan-improvement-run",
@@ -120,9 +142,9 @@ function writeBuildPlanImprovementRunLedger(verifiableContextPath, runId, record
         max_attempts: options.maxAttempts,
         loops: [...(existing?.loops ?? []), record],
     };
-    writeFileSync(buildPlanImprovementRunLedgerPath(verifiableContextPath, runId), `${JSON.stringify(ledger, null, 2)}\n`);
+    writeFileSync(buildPlanImprovementRunLedgerPath(contextGraphPath, runId), `${JSON.stringify(ledger, null, 2)}\n`);
     writeFileSync(buildPlanImprovementLoopRecordPath(record.loop_root_path), `${JSON.stringify(record, null, 2)}\n`);
-    appendFileSync(buildPlanImprovementLoopHistoryPath(verifiableContextPath, runId), `${JSON.stringify(record)}\n`);
+    appendFileSync(buildPlanImprovementLoopHistoryPath(contextGraphPath, runId), `${JSON.stringify(record)}\n`);
 }
 function buildBuildPlanImprovementLoopRecord(options) {
     return {
@@ -145,38 +167,67 @@ function buildBuildPlanImprovementLoopRecord(options) {
         prompt_log_path: options.promptLogPath,
         event_log_path: options.eventLogPath,
         status_log_path: options.statusLogPath,
+        // Same canonical location the shell teed reasoning to and the freeze
+        // preserved (derived from shell_path, like context_path above).
+        reasoning_path: join(options.shellPath, "runtime", "agent-reasoning.jsonl"),
         preserved_shell_manifest_path: options.preservedShellManifestPath,
         validation: options.validation,
     };
 }
 export async function runBuildPlanImprovementLoop(options) {
-    const verifiableContextName = readInterfConfig(options.verifiableContextPath)?.name ?? "verifiable-context";
+    const contextGraphName = readInterfConfig(options.contextGraphPath)?.name ?? "context-graph";
     const context = buildLoopContext(options);
     const shell = createBuildPlanImprovementShell({
-        verifiableContextPath: options.verifiableContextPath,
-        verifiableContextName,
+        contextGraphPath: options.contextGraphPath,
+        contextGraphName,
         buildPlanId: options.buildPlanId,
         runId: options.runId,
         loopIndex: options.loopIndex,
         context,
     });
-    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(options.verifiableContextPath);
+    const buildPlanRoot = buildPlanPackagePathForContextGraph(options.contextGraphPath);
+    // Scan the Source ONCE (from the Context Graph's own binding) so the tailoring
+    // non-regression guard below compares before/after against one stable
+    // inventory. Null when there is no Source binding or no readable files, which
+    // makes that guard a no-op.
+    const improveSourceContext = resolveImproveSourceContext(options.contextGraphPath);
     const session = await runBuildPlanEditSession({
         executor: options.executor,
         buildPlanPath: buildPlanRoot,
         shell,
         prompt: buildBuildPlanImprovementPrompt(),
-        validate: validateBuildPlanPackage,
+        // Run the SHARED lifecycle validator (base + product-critical backlink and
+        // canonical-top-level-layer invariants), PLUS a tailoring non-regression
+        // delta. An improvement edit must not silently strip those invariants, and
+        // — closing the original C1 gap — it must not DE-TAILOR a plan that was
+        // tailored to the Source back to a generic skeleton. The scaffold-removal,
+        // artifact-requirement, and ABSOLUTE tailoring guards stay authoring-only
+        // (draft-time concerns); the improve path enforces the non-regression delta
+        // so it never false-rejects a faithful improvement to a generic-by-design
+        // plan such as `interf-default`.
+        validate: (afterBuildPlanPath) => {
+            const lifecycle = validateLifecycleBuildPlanPackage(afterBuildPlanPath);
+            const tailoringErrors = validateImproveTailoringNonRegression(shell.buildPlanBeforePath, afterBuildPlanPath, improveSourceContext);
+            if (tailoringErrors.length === 0)
+                return lifecycle;
+            const errors = [...lifecycle.errors, ...tailoringErrors];
+            return {
+                ok: false,
+                summary: `Build Plan package has ${errors.length} issue(s).`,
+                errors,
+                counts: lifecycle.counts,
+            };
+        },
         maxValidationRepairAttempts: 1,
     });
     if (session.status === "updated") {
-        // 0.15 — fill role=general on any stage the improvement run
+        // fill role=general on any stage the improvement run
         // dropped a role from. Idempotent and silent when complete.
         ensureStageRoles(buildPlanRoot);
     }
     const preservedShellManifestPath = freezeBuildPlanImprovementShell(shell.rootPath);
-    writeBuildPlanImprovementRunLedger(options.verifiableContextPath, options.runId, buildBuildPlanImprovementLoopRecord({
-        targetName: verifiableContextName,
+    writeBuildPlanImprovementRunLedger(options.contextGraphPath, options.runId, buildBuildPlanImprovementLoopRecord({
+        targetName: contextGraphName,
         buildPlanId: options.buildPlanId,
         runId: options.runId,
         loopIndex: options.loopIndex,
@@ -193,14 +244,14 @@ export async function runBuildPlanImprovementLoop(options) {
         result: session.status,
         summary: session.summary,
     }), {
-        targetName: verifiableContextName,
+        targetName: contextGraphName,
         buildPlanId: options.buildPlanId,
         maxLoops: options.maxLoops,
         maxAttempts: options.maxAttempts,
     });
     if (session.status === "updated") {
         updateBuildPlanOrigin({
-            verifiableContextPath: options.verifiableContextPath,
+            contextGraphPath: options.contextGraphPath,
             selectedBuildPlanId: options.buildPlanId,
             localDraft: true,
         });

package/dist/packages/build-plans/authoring/lib/build-plan-edit-utils.d.ts

@@ -7,4 +7,5 @@ export interface BuildPlanEditShellArtifacts {
     promptLogPath: string;
     eventLogPath: string;
     statusLogPath: string;
+    reasoningLogPath: string;
 }

package/dist/packages/build-plans/authoring/lib/build-plan-edit-utils.js

@@ -5,10 +5,10 @@ export function copyDirectory(sourcePath, targetPath) {
     mkdirSync(targetPath, { recursive: true });
     cpSync(sourcePath, targetPath, { recursive: true });
 }
-function listFileSnapshot(dirPath) {
-    const snapshot = new Map();
+function listFileState(dirPath) {
+    const fileState = new Map();
     if (!existsSync(dirPath))
-        return snapshot;
+        return fileState;
     const collect = (currentPath) => {
         for (const entry of readdirSync(currentPath)) {
             const fullPath = join(currentPath, entry);
@@ -19,15 +19,15 @@ function listFileSnapshot(dirPath) {
             }
             if (!stat.isFile())
                 continue;
-            snapshot.set(relative(dirPath, fullPath), readFileSync(fullPath, "utf8"));
+            fileState.set(relative(dirPath, fullPath), readFileSync(fullPath, "utf8"));
         }
     };
     collect(dirPath);
-    return snapshot;
+    return fileState;
 }
 export function directoriesMatch(leftPath, rightPath) {
-    const left = listFileSnapshot(leftPath);
-    const right = listFileSnapshot(rightPath);
+    const left = listFileState(leftPath);
+    const right = listFileState(rightPath);
     if (left.size !== right.size)
         return false;
     for (const [relativePath, content] of left.entries()) {

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

@@ -2,5 +2,5 @@ export declare const DEFAULT_BUILD_PLAN_ID = "interf-default";
 export interface BuildPlanSelectionLike {
     build_plan?: string | null;
 }
-export declare function buildPlanIdForSourcePreparationConfig(preparationConfig: BuildPlanSelectionLike | null | undefined): string | null;
+export declare function buildPlanIdForProjectConfig(projectConfig: BuildPlanSelectionLike | null | undefined): string | null;
 export declare function resolveBuildPlanId(selection: BuildPlanSelectionLike | null | undefined, fallback?: string): string;

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

@@ -1,7 +1,7 @@
 export const DEFAULT_BUILD_PLAN_ID = "interf-default";
-export function buildPlanIdForSourcePreparationConfig(preparationConfig) {
-    return preparationConfig?.build_plan ?? null;
+export function buildPlanIdForProjectConfig(projectConfig) {
+    return projectConfig?.build_plan ?? null;
 }
 export function resolveBuildPlanId(selection, fallback = DEFAULT_BUILD_PLAN_ID) {
-    return buildPlanIdForSourcePreparationConfig(selection) ?? fallback;
+    return buildPlanIdForProjectConfig(selection) ?? fallback;
 }

package/dist/packages/build-plans/index.d.ts

@@ -1,2 +1,2 @@
 export * as buildPlanResolution from "./build-plan-resolution.js";
-export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForSourcePreparationConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";
+export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForProjectConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";

package/dist/packages/build-plans/index.js

@@ -1,2 +1,2 @@
 export * as buildPlanResolution from "./build-plan-resolution.js";
-export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForSourcePreparationConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";
+export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForProjectConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";

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

@@ -1,7 +1,8 @@
 import { type LocalBuildPlanDefinition } from "./local-build-plans.js";
-import type { BuildPlanEngineApi } from "../../engine/build/lib/schema.js";
+import type { BuildPlanRuntimeApi } from "../../runtime/build/lib/schema.js";
 import type { BuildPlanId, RuntimeContractType } from "../../contracts/lib/schema.js";
 import { type ContextInterface, type ContextInterfaceArtifactId, type BuildPlanInputSpec } from "./context-interface.js";
+import type { BuildPlanAuthoringBrief } from "../authoring/brief.js";
 export interface BuildPlanStarterDoc {
     relativePath: string;
     content: string;
@@ -23,17 +24,17 @@ export interface BuildPlanStageDefinition {
 }
 export interface BuildPlanDefinition<TId extends string> {
     id: TId;
-    engineApi?: BuildPlanEngineApi;
+    runtimeApi?: BuildPlanRuntimeApi;
     purpose?: {
         label: string;
         taskHint: string;
     };
+    brief?: BuildPlanAuthoringBrief;
     inputs?: BuildPlanInputSpec[];
     label: string;
     hint: string;
     recommended?: boolean;
     contextInterface?: ContextInterface;
-    schema?: ContextInterface;
     stages: BuildPlanStageDefinition[];
     stagePolicyNotes?: Record<string, string[]>;
     starterDocs?: BuildPlanStarterDoc[];
@@ -41,21 +42,21 @@ export interface BuildPlanDefinition<TId extends string> {
 }
 export type ResolvedBuildPlanId = string;
 export declare function standaloneBuildPlanDefinitionFromLocalPackage(local: LocalBuildPlanDefinition): BuildPlanDefinition<string>;
-export declare function listBuildPlanChoices(prepDataDir?: string): BuildPlanDefinition<string>[];
+export declare function listBuildPlanChoices(projectDataDir?: string): BuildPlanDefinition<string>[];
 export declare function getBuildPlan(buildPlanId: ResolvedBuildPlanId, options?: {
-    prepDataDir?: string;
+    projectDataDir?: string;
 }): BuildPlanDefinition<string>;
-export declare function getActiveBuildPlan(verifiableContextPath: string): BuildPlanDefinition<string>;
-export declare function resolveVerifiableContextBuildPlanId(value: unknown): ResolvedBuildPlanId | null;
+export declare function getActiveBuildPlan(contextGraphPath: string): BuildPlanDefinition<string>;
+export declare function resolveContextGraphBuildPlanId(value: unknown): ResolvedBuildPlanId | null;
 export declare function resolveBuildPlanFromConfig(config: unknown): ResolvedBuildPlanId | null;
 export declare function resolveRequiredBuildPlanFromConfig(config: unknown, label?: string): ResolvedBuildPlanId;
-export declare function getBuildPlanStageDefinition(buildPlanId: BuildPlanId, stage: string, prepDataDir?: string): BuildPlanStageDefinition | null;
-export declare function getBuildPlanStagePosition(buildPlanId: BuildPlanId, stage: string, prepDataDir?: string): {
+export declare function getBuildPlanStageDefinition(buildPlanId: BuildPlanId, stage: string, projectDataDir?: string): BuildPlanStageDefinition | null;
+export declare function getBuildPlanStagePosition(buildPlanId: BuildPlanId, stage: string, projectDataDir?: string): {
     stageIndex: number;
     stageTotal: number;
     stages: string[];
 } | null;
-export declare function getBuildPlanStages(buildPlanId: BuildPlanId, prepDataDir?: string): string[];
-export declare function getActiveBuildPlanStages(verifiableContextPath: string): string[];
-export declare function getActiveBuildPlanStagePolicyNotes(verifiableContextPath: string, stage: string): string[];
-export declare function formatActiveBuildPlanStageLabel(verifiableContextPath: string, stage: string): string;
+export declare function getBuildPlanStages(buildPlanId: BuildPlanId, projectDataDir?: string): string[];
+export declare function getActiveBuildPlanStages(contextGraphPath: string): string[];
+export declare function getActiveBuildPlanStagePolicyNotes(contextGraphPath: string, stage: string): string[];
+export declare function formatActiveBuildPlanStageLabel(contextGraphPath: string, stage: string): string;