@interf/compiler 0.22.2 → 0.50.0

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

@@ -3,11 +3,11 @@ 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 { buildPlanPackagePathForContextGraph } from "../../runtime/build/context-graph-paths.js";
+import { asProjectDataDir, projectBuildPlanPackagePath } from "../../contracts/lib/project-paths.js";
+import { resolveSourceControlPath } from "../../projects/interf.js";
 import { deriveBuildPlanInputsFromContextInterface, } from "./context-interface.js";
-const DEFAULT_BUILD_PLAN_ID = "interf-default";
+import { DEFAULT_BUILD_PLAN_ID } from "../build-plan-resolution.js";
 let builtinDefaultBuildPlanCache = null;
 function toBuildPlanStages(stages) {
     return stages.map((stage) => ({
@@ -16,7 +16,10 @@ function toBuildPlanStages(stages) {
         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",
+        // Store the TRIMMED role so a padded value like "  general  " maps to the
+        // same agent-role-map key the validity check (`.trim().length > 0`) tested,
+        // matching how `ensureStageRoles` (build-plan-authoring.ts) stores roles.
+        role: stage.role && stage.role.trim().length > 0 ? stage.role.trim() : "general",
         reads: [...stage.reads],
         writes: [...stage.writes],
     }));
@@ -32,7 +35,7 @@ export function standaloneBuildPlanDefinitionFromLocalPackage(local) {
         : deriveBuildPlanInputsFromContextInterface(contextInterface);
     return {
         id: local.id,
-        engineApi: local.engine_api ?? {
+        runtimeApi: local.runtime_api ?? {
             kind: "build",
             version: 1,
         },
@@ -44,12 +47,12 @@ export function standaloneBuildPlanDefinitionFromLocalPackage(local) {
                 },
             }
             : {}),
+        ...(local.brief ? { brief: local.brief } : {}),
         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],
@@ -75,8 +78,8 @@ function getBuiltinDefaultBuildPlan() {
 function listBuiltinBuildPlans() {
     return [getBuiltinDefaultBuildPlan()];
 }
-function resolveBuildPlanFromLocal(buildPlanId, prepDataDir) {
-    const local = loadLocalBuildPlanDefinition(prepDataDir, buildPlanId);
+function resolveBuildPlanFromLocal(buildPlanId, projectDataDir) {
+    const local = loadLocalBuildPlanDefinition(projectDataDir, buildPlanId);
     if (!local)
         return null;
     const resolved = standaloneBuildPlanDefinitionFromLocalPackage(local);
@@ -89,7 +92,7 @@ function resolveBuildPlanFromUserLibrary(buildPlanId) {
     const resolved = standaloneBuildPlanDefinitionFromLocalPackage(user);
     return { ...resolved, scope: "user" };
 }
-export function listBuildPlanChoices(prepDataDir) {
+export function listBuildPlanChoices(projectDataDir) {
     const builtins = listBuiltinBuildPlans();
     const buildPlansById = new Map();
     for (const buildPlan of builtins) {
@@ -105,11 +108,11 @@ export function listBuildPlanChoices(prepDataDir) {
             warnInterf(`Warning: skipping user Build Plan "${definition.id}" because it could not be resolved cleanly: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    if (!prepDataDir)
+    if (!projectDataDir)
         return [...buildPlansById.values()];
-    for (const definition of listLocalBuildPlanDefinitions(prepDataDir)) {
+    for (const definition of listLocalBuildPlanDefinitions(projectDataDir)) {
         try {
-            const buildPlan = resolveBuildPlanFromLocal(definition.id, prepDataDir);
+            const buildPlan = resolveBuildPlanFromLocal(definition.id, projectDataDir);
             if (buildPlan)
                 buildPlansById.set(buildPlan.id, buildPlan);
         }
@@ -120,8 +123,8 @@ export function listBuildPlanChoices(prepDataDir) {
     return [...buildPlansById.values()];
 }
 export function getBuildPlan(buildPlanId, options = {}) {
-    if (options.prepDataDir) {
-        const local = resolveBuildPlanFromLocal(buildPlanId, options.prepDataDir);
+    if (options.projectDataDir) {
+        const local = resolveBuildPlanFromLocal(buildPlanId, options.projectDataDir);
         if (local)
             return local;
     }
@@ -131,23 +134,23 @@ export function getBuildPlan(buildPlanId, options = {}) {
     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}.`);
+    if (options.projectDataDir) {
+        throw new Error(`No Build Plan package "${buildPlanId}" found in this Project, in your user library, or among bundled Build Plan packages. Looked under ${projectBuildPlanPackagePath(asProjectDataDir(options.projectDataDir), 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.`);
+    throw new Error(`Build Plan package "${buildPlanId}" is not built-in and no Project data directory was provided to look for a local override.`);
 }
-export function getActiveBuildPlan(verifiableContextPath) {
-    const buildPlanPath = buildPlanPackagePathForVerifiableContext(verifiableContextPath);
+export function getActiveBuildPlan(contextGraphPath) {
+    const buildPlanPath = buildPlanPackagePathForContextGraph(contextGraphPath);
     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.`);
+            throw new Error(`Local Build Plan package at ${buildPlanPath} is missing or invalid. Interf builds the local package directly; recreate or reseed this Context Graph.`);
         }
         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)}.`);
+    throw new Error(`Missing local Build Plan package at ${buildPlanPath}. Interf builds the local package directly, so recreate or reseed this Context Graph under ${resolveSourceControlPath(contextGraphPath)}.`);
 }
-export function resolveVerifiableContextBuildPlanId(value) {
+export function resolveContextGraphBuildPlanId(value) {
     if (typeof value === "string" && isBuildPlanId(value)) {
         return value;
     }
@@ -157,21 +160,21 @@ export function resolveBuildPlanFromConfig(config) {
     if (!config || typeof config !== "object")
         return null;
     const raw = config;
-    return resolveVerifiableContextBuildPlanId(raw.build_plan);
+    return resolveContextGraphBuildPlanId(raw.build_plan);
 }
-export function resolveRequiredBuildPlanFromConfig(config, label = "verifiable-context config") {
+export function resolveRequiredBuildPlanFromConfig(config, label = "Context Graph 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);
+function resolveBuildPlanDefinitionForStageMetadata(buildPlanId, projectDataDir) {
+    if (projectDataDir &&
+        existsSync(join(buildPlanPackagePathForContextGraph(projectDataDir), "build-plan.json"))) {
+        return getActiveBuildPlan(projectDataDir);
     }
-    return getBuildPlan(buildPlanId, { prepDataDir });
+    return getBuildPlan(buildPlanId, { projectDataDir });
 }
 function formatBuildPlanStageLabel(buildPlan, stage) {
     const stageIndex = buildPlan.stages.findIndex((candidate) => candidate.id === stage);
@@ -184,12 +187,12 @@ function formatBuildPlanStageLabel(buildPlan, stage) {
     }
     return `Stage ${stageIndex + 1}/${buildPlan.stages.length} - ${stageDefinition.label}`;
 }
-export function getBuildPlanStageDefinition(buildPlanId, stage, prepDataDir) {
-    const buildPlan = resolveBuildPlanDefinitionForStageMetadata(buildPlanId, prepDataDir);
+export function getBuildPlanStageDefinition(buildPlanId, stage, projectDataDir) {
+    const buildPlan = resolveBuildPlanDefinitionForStageMetadata(buildPlanId, projectDataDir);
     return buildPlan.stages.find((candidate) => candidate.id === stage) ?? null;
 }
-export function getBuildPlanStagePosition(buildPlanId, stage, prepDataDir) {
-    const stages = getBuildPlanStages(buildPlanId, prepDataDir);
+export function getBuildPlanStagePosition(buildPlanId, stage, projectDataDir) {
+    const stages = getBuildPlanStages(buildPlanId, projectDataDir);
     const stageIndex = stages.findIndex((candidate) => candidate === stage);
     if (stageIndex === -1)
         return null;
@@ -199,16 +202,16 @@ export function getBuildPlanStagePosition(buildPlanId, stage, prepDataDir) {
         stages: [...stages],
     };
 }
-export function getBuildPlanStages(buildPlanId, prepDataDir) {
-    return resolveBuildPlanDefinitionForStageMetadata(buildPlanId, prepDataDir).stages.map((definition) => definition.id);
+export function getBuildPlanStages(buildPlanId, projectDataDir) {
+    return resolveBuildPlanDefinitionForStageMetadata(buildPlanId, projectDataDir).stages.map((definition) => definition.id);
 }
-export function getActiveBuildPlanStages(verifiableContextPath) {
-    return getActiveBuildPlan(verifiableContextPath).stages.map((definition) => definition.id);
+export function getActiveBuildPlanStages(contextGraphPath) {
+    return getActiveBuildPlan(contextGraphPath).stages.map((definition) => definition.id);
 }
-export function getActiveBuildPlanStagePolicyNotes(verifiableContextPath, stage) {
-    const buildPlan = getActiveBuildPlan(verifiableContextPath);
+export function getActiveBuildPlanStagePolicyNotes(contextGraphPath, stage) {
+    const buildPlan = getActiveBuildPlan(contextGraphPath);
     return [...(buildPlan.stagePolicyNotes?.[stage] ?? [])];
 }
-export function formatActiveBuildPlanStageLabel(verifiableContextPath, stage) {
-    return formatBuildPlanStageLabel(getActiveBuildPlan(verifiableContextPath), stage);
+export function formatActiveBuildPlanStageLabel(contextGraphPath, stage) {
+    return formatBuildPlanStageLabel(getActiveBuildPlan(contextGraphPath), stage);
 }

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

@@ -1,4 +1,4 @@
-import { type LocalInstructionMode, type RuntimeInstructionMode, type RuntimeStageInstructions } from "../../engine/build/lib/schema.js";
+import { type LocalInstructionMode, type RuntimeInstructionMode, type RuntimeStageInstructions } from "../../runtime/build/lib/schema.js";
 export interface BuildPlanReporter {
     line?: (message: string) => void;
     blankLine?: () => void;
@@ -9,7 +9,7 @@ export interface BuildPlanStageResult {
     summary?: string | null;
 }
 export declare function buildPlanStageDirectory(stageDir: string): string;
-export interface LocalSkillContractExtension {
+interface LocalSkillContractExtension {
     reads: string[];
     count: number;
     notes: string[];
@@ -22,3 +22,4 @@ export declare function buildStageInstructions(stageSkillDir: string, localSkill
 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;
+export {};

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

@@ -1,12 +1,12 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 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 { VERIFIABLE_CONTEXT_BUILD_PLAN_DIR, buildPlanPackagePathForVerifiableContext } from "../../engine/build/verifiable-context-paths.js";
+import { CONTEXT_GRAPH_BUILD_PLAN_DIR, buildPlanPackagePathForContextGraph } from "../../runtime/build/context-graph-paths.js";
 const LOCAL_SKILL_READ_LIMIT = 50;
 export function buildPlanStageDirectory(stageDir) {
-    return `${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}/build/stages/${stageDir}`;
+    return `${CONTEXT_GRAPH_BUILD_PLAN_DIR}/build/stages/${stageDir}`;
 }
 function emptyLocalSkillContractExtension() {
     return {
@@ -28,11 +28,23 @@ function readLocalInstructionMode(filePath) {
         return null;
     }
 }
+function isRegularFileInside(rootPath, filePath) {
+    try {
+        if (!lstatSync(filePath).isFile())
+            return false;
+        const root = realpathSync(rootPath);
+        const file = realpathSync(filePath);
+        return file === root || file.startsWith(`${root}${sep}`);
+    }
+    catch {
+        return false;
+    }
+}
 function collectLocalSkillDocs(rootPath, directories) {
     const docs = new Map();
-    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(rootPath);
+    const buildPlanRoot = buildPlanPackagePathForContextGraph(rootPath);
     const rootReadme = join(buildPlanRoot, "README.md");
-    if (existsSync(rootReadme)) {
+    if (existsSync(rootReadme) && isRegularFileInside(buildPlanRoot, rootReadme)) {
         const read = projectBuildPlanReadPath(rootPath, rootReadme);
         docs.set(read, {
             read,
@@ -43,6 +55,8 @@ function collectLocalSkillDocs(rootPath, directories) {
     for (const directory of directories) {
         const absoluteDirectory = resolveAuthoringDirectory(rootPath, directory);
         for (const filePath of listFilesRecursive(absoluteDirectory, isMarkdownFile)) {
+            if (!isRegularFileInside(buildPlanRoot, filePath))
+                continue;
             const read = projectBuildPlanReadPath(rootPath, filePath);
             docs.set(read, {
                 read,
@@ -56,21 +70,21 @@ function collectLocalSkillDocs(rootPath, directories) {
         .slice(0, LOCAL_SKILL_READ_LIMIT);
 }
 function resolveAuthoringDirectory(rootPath, directory) {
-    if (directory === VERIFIABLE_CONTEXT_BUILD_PLAN_DIR) {
-        return buildPlanPackagePathForVerifiableContext(rootPath);
+    if (directory === CONTEXT_GRAPH_BUILD_PLAN_DIR) {
+        return buildPlanPackagePathForContextGraph(rootPath);
     }
-    if (directory.startsWith(`${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}${sep}`) || directory.startsWith(`${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}/`)) {
+    if (directory.startsWith(`${CONTEXT_GRAPH_BUILD_PLAN_DIR}${sep}`) || directory.startsWith(`${CONTEXT_GRAPH_BUILD_PLAN_DIR}/`)) {
         const relativeBuildPlanPath = directory.replace(/^build-plan[\\/]/, "");
-        return join(buildPlanPackagePathForVerifiableContext(rootPath), relativeBuildPlanPath);
+        return join(buildPlanPackagePathForContextGraph(rootPath), relativeBuildPlanPath);
     }
     return join(rootPath, directory);
 }
 function projectBuildPlanReadPath(rootPath, absolutePath) {
-    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(rootPath);
+    const buildPlanRoot = buildPlanPackagePathForContextGraph(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, join(rootPath, CONTEXT_GRAPH_BUILD_PLAN_DIR, relativeBuildPlanPath));
     }
     return relative(rootPath, absolutePath);
 }
@@ -98,8 +112,8 @@ function buildContractExtensionFromDocs(docs, directories, purpose) {
         notes: [
             readNotice,
             localMode === "override"
-                ? `${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.`,
+                ? `${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 evidence, evidence weighting, required writes, or deterministic runtime reconciliation.`
+                : `${purpose} These local Build Plan docs can refine the stage, but they do not bypass coverage evidence, evidence weighting, required writes, or deterministic runtime reconciliation.`,
         ],
         localMode,
         effectiveMode: localMode ?? "builtin",

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

@@ -1,10 +1,10 @@
-import type { BuildPlanImprovementContext } from "../../engine/build/lib/schema.js";
+import type { BuildPlanImprovementContext } from "../../runtime/build/lib/schema.js";
 export interface BuildPlanImprovementReviewSourcePaths {
-    verifiableContextRuntime: string | null;
-    readinessRuns: string | null;
+    contextGraphRuntime: string | null;
+    benchmarkRuns: 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"];
+export declare function resolveBuildPlanImprovementReviewSourcePaths(contextGraphPath: string): BuildPlanImprovementReviewSourcePaths;
+export declare function resolveBuildPlanImprovementReviewPaths(contextGraphPath: string): BuildPlanImprovementContext["review_paths"];

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

@@ -1,29 +1,29 @@
 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);
+import { testRootForContextGraph, targetTestRunsRootForContextGraph, targetTestSandboxesRootForContextGraph, stageExecutionShellsRoot, contextGraphRuntimeRoot, } from "../../runtime/build/context-graph-paths.js";
+export function resolveBuildPlanImprovementReviewSourcePaths(contextGraphPath) {
+    const contextGraphRuntime = contextGraphRuntimeRoot(contextGraphPath);
+    const benchmarkRuns = testRootForContextGraph(contextGraphPath);
+    const executionShells = stageExecutionShellsRoot(contextGraphPath);
+    const targetTestRuns = targetTestRunsRootForContextGraph(contextGraphPath);
+    const targetTestSandboxes = targetTestSandboxesRootForContextGraph(contextGraphPath);
     return {
-        verifiableContextRuntime: existsSync(verifiableContextRuntime) ? verifiableContextRuntime : null,
-        readinessRuns: existsSync(join(readinessRuns, "latest.json")) ||
-            existsSync(join(readinessRuns, "latest.md"))
-            ? readinessRuns
+        contextGraphRuntime: existsSync(contextGraphRuntime) ? contextGraphRuntime : null,
+        benchmarkRuns: existsSync(join(benchmarkRuns, "latest.json")) ||
+            existsSync(join(benchmarkRuns, "latest.md"))
+            ? benchmarkRuns
             : null,
         executionShells: existsSync(executionShells) ? executionShells : null,
         targetTestRuns: existsSync(targetTestRuns) ? targetTestRuns : null,
         targetTestSandboxes: existsSync(targetTestSandboxes) ? targetTestSandboxes : null,
     };
 }
-export function resolveBuildPlanImprovementReviewPaths(verifiableContextPath) {
-    const sources = resolveBuildPlanImprovementReviewSourcePaths(verifiableContextPath);
+export function resolveBuildPlanImprovementReviewPaths(contextGraphPath) {
+    const sources = resolveBuildPlanImprovementReviewSourcePaths(contextGraphPath);
     return {
         build_plan_root: "build-plan",
-        verifiable_context_runtime: sources.verifiableContextRuntime ? "artifacts/verifiable-context-runtime" : null,
-        readiness_runs: sources.readinessRuns ? "artifacts/readiness-runs" : null,
+        context_graph_runtime: sources.contextGraphRuntime ? "artifacts/context-graph-runtime" : null,
+        benchmark_runs: sources.benchmarkRuns ? "artifacts/benchmark-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/build-plans/package/build-plan-stage-runner.d.ts

@@ -1,7 +1,7 @@
-import { type AgentExecutor } from "../../engine/agents/lib/executors.js";
-import { type RuntimeStageInstructions } from "../../engine/build/lib/schema.js";
+import { type AgentExecutor } from "../../runtime/agents/lib/executors.js";
+import { type RuntimeStageInstructions } from "../../runtime/build/lib/schema.js";
 import type { RuntimeContractType } from "../../contracts/lib/schema.js";
-import { type RuntimeStageContractDraft } from "../../engine/build/runtime.js";
+import { type RuntimeStageContractDraft } from "../../runtime/build/runtime.js";
 import { type BuildPlanReporter, type BuildPlanStageResult } from "./build-plan-helpers.js";
 interface BuildPlanStageShape<TContractType extends RuntimeContractType> {
     id: string;
@@ -10,11 +10,12 @@ interface BuildPlanStageShape<TContractType extends RuntimeContractType> {
 }
 interface ExecuteValidatedStageOptions<TContractType extends RuntimeContractType> {
     executor: AgentExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     executionPath?: string;
     targetName: string;
     buildPlan: string;
     buildPlanSourcePath?: string;
+    buildRunId?: string | null;
     stageDefinition: BuildPlanStageShape<TContractType>;
     instructions: RuntimeStageInstructions;
     summary: string;

package/dist/packages/build-plans/package/build-plan-stage-runner.js

@@ -1,4 +1,4 @@
-import { markRuntimeRunSucceededAfterValidation, buildStagePrompt, markRuntimeRunFailedAfterValidation, runExecutorStage, } from "../../engine/build/runtime.js";
+import { markExecutionStageLedgerSucceededAfterValidation, buildStagePrompt, markExecutionStageLedgerFailedAfterValidation, runExecutorStage, } from "../../runtime/build/runtime.js";
 import { reportValidationFailure, } from "./build-plan-helpers.js";
 export function findStageByContractType(stages, contractType) {
     const stage = stages.find((candidate) => candidate.contractType === contractType);
@@ -11,17 +11,19 @@ export async function executeValidatedStage(options) {
     const completionCheck = options.completionCheck
         ? () => {
             options.syncWrites?.();
-            options.reconcile?.();
+            if (options.reconcile?.() === false)
+                return false;
             return options.completionCheck?.() === true;
         }
         : undefined;
     const code = await runExecutorStage({
         executor: options.executor,
-        verifiableContextPath: options.verifiableContextPath,
+        contextGraphPath: options.contextGraphPath,
         executionPath: options.executionPath,
-        verifiableContextName: options.targetName,
+        contextGraphName: options.targetName,
         buildPlan: options.buildPlan,
         buildPlanSourcePath: options.buildPlanSourcePath,
+        buildRunId: options.buildRunId ?? null,
         stage: options.stageDefinition.id,
         stageLabel: options.stageDefinition.label,
         contractType: options.stageDefinition.contractType,
@@ -36,16 +38,22 @@ export async function executeValidatedStage(options) {
 function finalizeValidatedStage(options, code) {
     const refreshAndValidate = () => {
         options.syncWrites?.();
-        options.reconcile?.();
+        const reconciled = options.reconcile?.() ?? true;
         options.refreshArtifacts?.();
-        return options.validate();
+        const validation = options.validate();
+        if (!reconciled && validation.ok) {
+            return {
+                ok: false,
+                summary: "Stage did not update any declared requested output.",
+            };
+        }
+        return validation;
     };
     if (code !== 0) {
         let completionSatisfied = false;
         try {
             options.syncWrites?.();
-            options.reconcile?.();
-            completionSatisfied = options.completionCheck?.() === true;
+            completionSatisfied = options.reconcile?.() !== false && options.completionCheck?.() === true;
         }
         catch {
             completionSatisfied = false;
@@ -53,7 +61,7 @@ function finalizeValidatedStage(options, code) {
         if (completionSatisfied) {
             const validation = refreshAndValidate();
             if (validation.ok) {
-                markRuntimeRunSucceededAfterValidation(options.verifiableContextPath, validation.summary);
+                markExecutionStageLedgerSucceededAfterValidation(options.contextGraphPath, validation.summary);
                 return {
                     ok: true,
                     code: 0,
@@ -61,19 +69,23 @@ function finalizeValidatedStage(options, code) {
                 };
             }
             reportValidationFailure(options.reporter, validation.summary);
-            markRuntimeRunFailedAfterValidation(options.verifiableContextPath, validation.summary);
+            markExecutionStageLedgerFailedAfterValidation(options.contextGraphPath, validation.summary);
             return {
                 ok: false,
                 code,
                 summary: validation.summary,
             };
         }
+        markExecutionStageLedgerFailedAfterValidation(options.contextGraphPath, `${options.stageDefinition.label} failed with exit code ${code}.`);
         return { ok: false, code };
     }
     const validation = refreshAndValidate();
     if (!validation.ok) {
         reportValidationFailure(options.reporter, validation.summary);
-        markRuntimeRunFailedAfterValidation(options.verifiableContextPath, validation.summary);
+        markExecutionStageLedgerFailedAfterValidation(options.contextGraphPath, validation.summary);
+    }
+    else {
+        markExecutionStageLedgerSucceededAfterValidation(options.contextGraphPath, validation.summary);
     }
     return {
         ok: validation.ok,

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

@@ -1,22 +1,21 @@
-import { type BuildPlanArtifactKind } from "../../engine/build/build-plan-primitives.js";
+import { type BuildPlanArtifactKind } from "../../runtime/build/build-plan-primitives.js";
 declare const BUILTIN_BUILD_PLAN_STAGE_IDS: {
     readonly SUMMARIZE: "summarize";
-    readonly STRUCTURE: "structure";
-    readonly SHAPE: "shape";
+    readonly KNOWLEDGE: "knowledge";
+    readonly ENTRYPOINT: "entrypoint";
 };
 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 KNOWLEDGE: "knowledge";
+    readonly ARTIFACTS: "artifacts";
+    readonly HOME: "home";
     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";
+    role: "output";
     path: string;
     kind: BuildPlanArtifactKind;
     required: boolean;

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

@@ -1,19 +1,18 @@
 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 { BuildPlanContextSchemaSchema } from "../../runtime/build/lib/schema.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
 const BUILTIN_BUILD_PLAN_STAGE_IDS = {
     SUMMARIZE: "summarize",
-    STRUCTURE: "structure",
-    SHAPE: "shape",
+    KNOWLEDGE: "knowledge",
+    ENTRYPOINT: "entrypoint",
 };
 export const BUILTIN_BUILD_PLAN_ARTIFACT_IDS = {
     SUMMARIES: "summaries",
-    KNOWLEDGE_ENTITIES: "knowledge-entities",
-    KNOWLEDGE_CLAIMS: "knowledge-claims",
-    KNOWLEDGE_INDEXES: "knowledge-indexes",
-    HOME: "atlas",
+    KNOWLEDGE: "knowledge",
+    ARTIFACTS: "artifacts",
+    HOME: "home",
     RUNTIME: "runtime",
 };
 const BUILTIN_ARTIFACT_ID_SET = new Set(Object.values(BUILTIN_BUILD_PLAN_ARTIFACT_IDS));
@@ -28,10 +27,10 @@ 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");
+const BUILTIN_DEFAULT_BUILD_PLAN_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}".`);
+        throw new Error(`Built-in Interf Build Plan schema declares unsupported requested output id "${value}".`);
     }
     return value;
 }
@@ -44,8 +43,8 @@ function assertBuiltinStageId(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 schemaPath = join(BUILTIN_DEFAULT_BUILD_PLAN_ROOT, "build-plan.schema.json");
+    const buildPlanPath = join(BUILTIN_DEFAULT_BUILD_PLAN_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}.`);

package/dist/packages/build-plans/package/context-interface.d.ts

@@ -1,30 +1,38 @@
 import { z } from "zod";
-import { type BuildPlanContextSchema, type BuildPlanArtifact, type BuildPlanArtifactId } from "../../engine/build/lib/schema.js";
+import { type BuildPlanContextSchema, type BuildPlanArtifact, type BuildPlanArtifactId } from "../../runtime/build/lib/schema.js";
 export declare const CONTEXT_INTERFACE_FILE = "build-plan.schema.json";
 export declare const ContextInterfaceSchema: z.ZodObject<{
     kind: z.ZodLiteral<"build-plan-schema">;
     version: z.ZodLiteral<1>;
-    target_type: z.ZodLiteral<"verifiable-context">;
+    target_type: z.ZodLiteral<"context-graph">;
     label: z.ZodString;
     artifacts: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
-        shape: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        shape: z.ZodObject<{
             kind: z.ZodLiteral<"path">;
             path: z.ZodString;
             artifact_kind: z.ZodEnum<{
                 file: "file";
                 directory: "directory";
             }>;
-        }, z.core.$strict>], "kind">;
+        }, z.core.$strict>;
         checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodEnum<{
                 file_exists: "file_exists";
+                source_manifest_valid: "source_manifest_valid";
                 min_file_count: "min_file_count";
                 min_file_count_matches_source: "min_file_count_matches_source";
+                source_summary_folders: "source_summary_folders";
+                source_page_coverage: "source_page_coverage";
                 frontmatter_valid: "frontmatter_valid";
                 frontmatter_required_keys: "frontmatter_required_keys";
+                frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
+                source_refs_required: "source_refs_required";
+                summary_backlinks_present: "summary_backlinks_present";
+                knowledge_web_connectivity: "knowledge_web_connectivity";
+                graph_notes_connected: "graph_notes_connected";
                 wikilinks_valid: "wikilinks_valid";
                 must_not_contain: "must_not_contain";
                 must_contain: "must_contain";
@@ -53,19 +61,16 @@ interface ContextInterfaceStageLike {
     writes: readonly string[];
 }
 interface ContextInterfaceSummary {
-    inputArtifacts: ContextInterfaceArtifact[];
-    workingArtifacts: ContextInterfaceArtifact[];
     outputArtifacts: ContextInterfaceArtifact[];
-    runtimeArtifacts: ContextInterfaceArtifact[];
 }
 export declare function listContextInterfaceArtifacts(contextInterface: ContextInterface): ContextInterfaceArtifact[];
 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(verifiableContextPath: string, artifact: Pick<ContextInterfaceArtifact, "path">): string;
+export declare function contextInterfaceArtifactAbsolutePath(contextGraphPath: 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 deriveBuildPlanInputsFromContextInterface(contextInterface: ContextInterface | null | undefined): BuildPlanInputSpec[];
+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;