@interf/compiler 0.21.0 → 0.22.0

package/dist/packages/engine/{compile → build}/validate.js

@@ -1,15 +1,15 @@
 import { existsSync, readFileSync, statSync, } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
-import { listCompiledSchemaArtifacts, readCompiledSchemaFile } from "./compiled-schema.js";
-import { methodPackagePathForCompiled } from "./compiled-paths.js";
+import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./verifiable-context-schema.js";
+import { buildPlanPackagePathForVerifiableContext } from "./verifiable-context-paths.js";
 import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { readInterfConfig } from "../../project/interf-detect.js";
 import { parseJsonFrontmatter } from "../../contracts/utils/parse.js";
-import { compiledInterfConfigPath } from "./compiled-paths.js";
+import { verifiableContextInterfConfigPath } from "./verifiable-context-paths.js";
 const MIN_ABSTRACT_WORDS = 5;
 const WIKILINK_PATTERN = /!?\[\[([^[\]]+)\]\]/g;
-export function readCompiledConfig(dirPath) {
-    const configPath = compiledInterfConfigPath(dirPath);
+export function readVerifiableContextConfig(dirPath) {
+    const configPath = verifiableContextInterfConfigPath(dirPath);
     const value = readInterfConfig(dirPath);
     const present = existsSync(configPath);
     if (!present) {
@@ -25,7 +25,7 @@ export function readCompiledConfig(dirPath) {
         valid: value !== null,
         value,
         typeMatch() {
-            return value?.type === "compiled" && typeof value?.source?.path === "string";
+            return value?.type === "verifiable-context" && typeof value?.source?.path === "string";
         },
     };
 }
@@ -51,9 +51,9 @@ export function validateSynthFiles(files, options) {
         short_abstracts: shortAbstracts,
     };
 }
-export function countBrokenWikilinks(compiledRoot, noteIndexRoots, linkScanRoots) {
-    const artifactPathById = compiledArtifactDirectoryPaths(compiledRoot);
-    const directoryLeafParents = compiledDirectoryLeafParents(artifactPathById);
+export function countBrokenWikilinks(verifiableContextRoot, noteIndexRoots, linkScanRoots) {
+    const artifactPathById = verifiableContextArtifactDirectoryPaths(verifiableContextRoot);
+    const directoryLeafParents = verifiableContextDirectoryLeafParents(artifactPathById);
     const noteIndex = new Set();
     for (const filePath of dedupeFiles(noteIndexRoots)) {
         for (const target of collectWikilinkTargets(filePath)) {
@@ -74,15 +74,15 @@ export function countBrokenWikilinks(compiledRoot, noteIndexRoots, linkScanRoots
             if (!target)
                 continue;
             if (target.includes("/")) {
-                if (!wikilinkPathExists(compiledRoot, target, artifactPathById, directoryLeafParents, filePath)) {
+                if (!wikilinkPathExists(verifiableContextRoot, target, artifactPathById, directoryLeafParents, filePath)) {
                     brokenLinks += 1;
                 }
                 continue;
             }
             if (!noteIndex.has(target.toLowerCase()) &&
                 !noteIndex.has(noteName(target).toLowerCase()) &&
-                !wikilinkPathExists(compiledRoot, target, artifactPathById, directoryLeafParents, filePath) &&
-                !wikilinkPathExists(compiledRoot, noteName(target), artifactPathById, directoryLeafParents, filePath)) {
+                !wikilinkPathExists(verifiableContextRoot, target, artifactPathById, directoryLeafParents, filePath) &&
+                !wikilinkPathExists(verifiableContextRoot, noteName(target), artifactPathById, directoryLeafParents, filePath)) {
                 brokenLinks += 1;
             }
         }
@@ -171,28 +171,28 @@ function countWords(text) {
 function noteName(filePath) {
     return basename(filePath, extname(filePath));
 }
-function wikilinkPathExists(compiledRoot, target, artifactPathById, directoryLeafParents, sourceFilePath) {
-    return linkPathCandidates(compiledRoot, target, artifactPathById, directoryLeafParents, sourceFilePath)
+function wikilinkPathExists(verifiableContextRoot, target, artifactPathById, directoryLeafParents, sourceFilePath) {
+    return linkPathCandidates(verifiableContextRoot, target, artifactPathById, directoryLeafParents, sourceFilePath)
         .some((candidate) => existsSync(candidate));
 }
-function linkPathCandidates(compiledRoot, target, artifactPathById, directoryLeafParents, sourceFilePath) {
+function linkPathCandidates(verifiableContextRoot, target, artifactPathById, directoryLeafParents, sourceFilePath) {
     const candidates = new Set();
-    addPathCandidate(candidates, join(compiledRoot, target));
+    addPathCandidate(candidates, join(verifiableContextRoot, target));
     if (sourceFilePath && (target.startsWith("./") || target.startsWith("../"))) {
-        addPathCandidateIfInside(candidates, compiledRoot, resolve(dirname(sourceFilePath), target));
+        addPathCandidateIfInside(candidates, verifiableContextRoot, resolve(dirname(sourceFilePath), target));
     }
     const [firstSegment] = target.split("/");
     if (firstSegment) {
         const parentPath = directoryLeafParents.get(firstSegment);
         if (parentPath) {
-            addPathCandidate(candidates, join(compiledRoot, parentPath, target));
+            addPathCandidate(candidates, join(verifiableContextRoot, parentPath, target));
         }
     }
     if (firstSegment) {
         const normalizedPrefix = artifactPathById.get(firstSegment);
         if (normalizedPrefix) {
             const remainder = target.slice(firstSegment.length).replace(/^\/+/, "");
-            addPathCandidate(candidates, join(compiledRoot, normalizedPrefix, remainder));
+            addPathCandidate(candidates, join(verifiableContextRoot, normalizedPrefix, remainder));
         }
     }
     return Array.from(candidates);
@@ -201,23 +201,23 @@ function addPathCandidate(candidates, absolutePath) {
     candidates.add(absolutePath);
     candidates.add(`${absolutePath}.md`);
 }
-function addPathCandidateIfInside(candidates, compiledRoot, absolutePath) {
-    const root = resolve(compiledRoot);
+function addPathCandidateIfInside(candidates, verifiableContextRoot, absolutePath) {
+    const root = resolve(verifiableContextRoot);
     const candidate = resolve(absolutePath);
     if (candidate !== root && !candidate.startsWith(`${root}/`))
         return;
     addPathCandidate(candidates, candidate);
 }
-function compiledArtifactDirectoryPaths(compiledRoot) {
-    const methodRoot = methodPackagePathForCompiled(compiledRoot);
-    const schema = readCompiledSchemaFile(methodRoot);
+function verifiableContextArtifactDirectoryPaths(verifiableContextRoot) {
+    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(verifiableContextRoot);
+    const schema = readBuildPlanContextFile(buildPlanRoot);
     if (!schema)
         return new Map();
-    return new Map(listCompiledSchemaArtifacts(schema)
+    return new Map(listBuildPlanContextArtifacts(schema)
         .filter((artifact) => artifact.kind === "directory")
         .map((artifact) => [artifact.id, artifact.path]));
 }
-function compiledDirectoryLeafParents(artifactPathById) {
+function verifiableContextDirectoryLeafParents(artifactPathById) {
     const parents = new Map();
     for (const artifactPath of artifactPathById.values()) {
         const [root, leaf, ...rest] = artifactPath.split("/");
@@ -256,4 +256,4 @@ function addFrontmatterLinkTarget(targets, value) {
         }
     }
 }
-export { validateCompiled, validateCompiledStage, validateCompiledMethod, validateCompiledSummarize, validateCompiledStructure, validateCompiledCompile, } from "./validate-compiled.js";
+export { validateVerifiableContextSetup, validateBuildStage, validateVerifiableContext, validateBuildSummarize, validateVerifiableContextStructure, validateBuildOutput, } from "./validate-verifiable-context.js";

package/dist/packages/engine/build/verifiable-context-paths.d.ts

@@ -0,0 +1,47 @@
+export declare const VERIFIABLE_CONTEXT_INTERF_DIR = ".interf";
+export declare const VERIFIABLE_CONTEXT_CONFIG_FILE = "interf.json";
+export declare const VERIFIABLE_CONTEXT_BUILD_PLAN_DIR = "build-plan";
+export declare const VERIFIABLE_CONTEXT_TEST_DIR = "tests";
+export declare const VERIFIABLE_CONTEXT_TEST_TARGETS_DIR = "targets";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_DIR = "runtime";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_STATE_FILE = "state.json";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_HEALTH_FILE = "health.json";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_SOURCE_FILES_FILE = "source-files.json";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_SOURCE_SNAPSHOT_FILE = "source-snapshot.json";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_STAGE_INPUTS_DIR = "stages";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_STAGE_INPUTS_FILE = "inputs.json";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_INVENTORY_FILE = "inventory.json";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_RUN_FILE = "run.json";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
+export declare const VERIFIABLE_CONTEXT_RUNTIME_STAGE_CONTRACT_FILE = "stage-contract.json";
+export declare function verifiableContextRuntimeRoot(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeFilePath(verifiableContextPath: string, fileName: string): string;
+export declare function verifiableContextInterfRoot(verifiableContextPath: string): string;
+export declare function verifiableContextInterfConfigPath(verifiableContextPath: string): string;
+export declare function buildPlanPackagePathForVerifiableContext(verifiableContextPath: string): string;
+export declare function testRootForVerifiableContext(verifiableContextPath: string): string;
+export declare function testTargetsRootForVerifiableContext(verifiableContextPath: string): string;
+export declare function stageExecutionShellsRoot(verifiableContextPath: string): string;
+export declare function buildPlanImprovementLoopsRoot(verifiableContextPath: string): string;
+export declare function buildPlanImprovementRunRoot(verifiableContextPath: string, runId: string): string;
+export declare function buildPlanImprovementLoopRoot(verifiableContextPath: string, runId: string, loopIndex: number): string;
+export declare function targetTestRunsRootForVerifiableContext(verifiableContextPath: string): string;
+export declare function targetTestSandboxesRootForVerifiableContext(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeLogsRoot(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeArchivedStageContractPath(verifiableContextPath: string, runId: string): string;
+export declare function verifiableContextQueryAcceptanceRoot(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeStatePath(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeHealthPath(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeViewSpecPath(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeSourceFilesPath(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeSourceSnapshotPath(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeStagesRoot(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeStageRoot(verifiableContextPath: string, stageId: string): string;
+export declare function verifiableContextRuntimeStageInputsPath(verifiableContextPath: string, stageId: string): string;
+export declare function verifiableContextRuntimeInventoryPath(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeRunPath(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeRunHistoryPath(verifiableContextPath: string): string;
+export declare function verifiableContextRuntimeStageContractPath(verifiableContextPath: string): string;
+export declare function resolveSourceControlPathForVerifiableContext(verifiableContextPath: string): string;
+export declare function defaultControlPathForVerifiableContext(verifiableContextPath: string): string;

package/dist/packages/engine/build/verifiable-context-paths.js

@@ -0,0 +1,121 @@
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+export const VERIFIABLE_CONTEXT_INTERF_DIR = ".interf";
+export const VERIFIABLE_CONTEXT_CONFIG_FILE = "interf.json";
+export const VERIFIABLE_CONTEXT_BUILD_PLAN_DIR = "build-plan";
+export const VERIFIABLE_CONTEXT_TEST_DIR = "tests";
+export const VERIFIABLE_CONTEXT_TEST_TARGETS_DIR = "targets";
+export const VERIFIABLE_CONTEXT_RUNTIME_DIR = "runtime";
+export const VERIFIABLE_CONTEXT_RUNTIME_STATE_FILE = "state.json";
+export const VERIFIABLE_CONTEXT_RUNTIME_HEALTH_FILE = "health.json";
+export const VERIFIABLE_CONTEXT_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
+export const VERIFIABLE_CONTEXT_RUNTIME_SOURCE_FILES_FILE = "source-files.json";
+export const VERIFIABLE_CONTEXT_RUNTIME_SOURCE_SNAPSHOT_FILE = "source-snapshot.json";
+export const VERIFIABLE_CONTEXT_RUNTIME_STAGE_INPUTS_DIR = "stages";
+export const VERIFIABLE_CONTEXT_RUNTIME_STAGE_INPUTS_FILE = "inputs.json";
+export const VERIFIABLE_CONTEXT_RUNTIME_INVENTORY_FILE = "inventory.json";
+export const VERIFIABLE_CONTEXT_RUNTIME_RUN_FILE = "run.json";
+export const VERIFIABLE_CONTEXT_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
+export const VERIFIABLE_CONTEXT_RUNTIME_STAGE_CONTRACT_FILE = "stage-contract.json";
+export function verifiableContextRuntimeRoot(verifiableContextPath) {
+    return join(verifiableContextPath, VERIFIABLE_CONTEXT_INTERF_DIR, VERIFIABLE_CONTEXT_RUNTIME_DIR);
+}
+export function verifiableContextRuntimeFilePath(verifiableContextPath, fileName) {
+    return join(verifiableContextRuntimeRoot(verifiableContextPath), fileName);
+}
+export function verifiableContextInterfRoot(verifiableContextPath) {
+    return join(verifiableContextPath, VERIFIABLE_CONTEXT_INTERF_DIR);
+}
+export function verifiableContextInterfConfigPath(verifiableContextPath) {
+    return join(verifiableContextInterfRoot(verifiableContextPath), VERIFIABLE_CONTEXT_CONFIG_FILE);
+}
+export function buildPlanPackagePathForVerifiableContext(verifiableContextPath) {
+    return join(verifiableContextInterfRoot(verifiableContextPath), VERIFIABLE_CONTEXT_BUILD_PLAN_DIR);
+}
+export function testRootForVerifiableContext(verifiableContextPath) {
+    return join(verifiableContextInterfRoot(verifiableContextPath), VERIFIABLE_CONTEXT_TEST_DIR);
+}
+export function testTargetsRootForVerifiableContext(verifiableContextPath) {
+    return join(testRootForVerifiableContext(verifiableContextPath), VERIFIABLE_CONTEXT_TEST_TARGETS_DIR);
+}
+export function stageExecutionShellsRoot(verifiableContextPath) {
+    return join(verifiableContextRuntimeRoot(verifiableContextPath), "execution-shells");
+}
+export function buildPlanImprovementLoopsRoot(verifiableContextPath) {
+    return join(verifiableContextRuntimeRoot(verifiableContextPath), "improvement-loops");
+}
+export function buildPlanImprovementRunRoot(verifiableContextPath, runId) {
+    return join(buildPlanImprovementLoopsRoot(verifiableContextPath), runId);
+}
+export function buildPlanImprovementLoopRoot(verifiableContextPath, runId, loopIndex) {
+    return join(buildPlanImprovementRunRoot(verifiableContextPath, runId), `loop-${String(loopIndex).padStart(2, "0")}`);
+}
+export function targetTestRunsRootForVerifiableContext(verifiableContextPath) {
+    return join(testTargetsRootForVerifiableContext(verifiableContextPath), "runs");
+}
+export function targetTestSandboxesRootForVerifiableContext(verifiableContextPath) {
+    return join(testTargetsRootForVerifiableContext(verifiableContextPath), "sandboxes");
+}
+export function verifiableContextRuntimeLogsRoot(verifiableContextPath) {
+    return join(verifiableContextRuntimeRoot(verifiableContextPath), "logs");
+}
+export function verifiableContextRuntimeArchivedStageContractPath(verifiableContextPath, runId) {
+    return join(verifiableContextRuntimeLogsRoot(verifiableContextPath), `${runId}.stage-contract.json`);
+}
+export function verifiableContextQueryAcceptanceRoot(verifiableContextPath) {
+    return join(verifiableContextRuntimeRoot(verifiableContextPath), "query-acceptance");
+}
+export function verifiableContextRuntimeStatePath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_STATE_FILE);
+}
+export function verifiableContextRuntimeHealthPath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_HEALTH_FILE);
+}
+export function verifiableContextRuntimeViewSpecPath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_VIEW_SPEC_FILE);
+}
+export function verifiableContextRuntimeSourceFilesPath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_SOURCE_FILES_FILE);
+}
+export function verifiableContextRuntimeSourceSnapshotPath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_SOURCE_SNAPSHOT_FILE);
+}
+export function verifiableContextRuntimeStagesRoot(verifiableContextPath) {
+    return join(verifiableContextRuntimeRoot(verifiableContextPath), VERIFIABLE_CONTEXT_RUNTIME_STAGE_INPUTS_DIR);
+}
+export function verifiableContextRuntimeStageRoot(verifiableContextPath, stageId) {
+    return join(verifiableContextRuntimeStagesRoot(verifiableContextPath), stageId);
+}
+export function verifiableContextRuntimeStageInputsPath(verifiableContextPath, stageId) {
+    return join(verifiableContextRuntimeStageRoot(verifiableContextPath, stageId), VERIFIABLE_CONTEXT_RUNTIME_STAGE_INPUTS_FILE);
+}
+export function verifiableContextRuntimeInventoryPath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_INVENTORY_FILE);
+}
+export function verifiableContextRuntimeRunPath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_RUN_FILE);
+}
+export function verifiableContextRuntimeRunHistoryPath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_RUN_HISTORY_FILE);
+}
+export function verifiableContextRuntimeStageContractPath(verifiableContextPath) {
+    return verifiableContextRuntimeFilePath(verifiableContextPath, VERIFIABLE_CONTEXT_RUNTIME_STAGE_CONTRACT_FILE);
+}
+export function resolveSourceControlPathForVerifiableContext(verifiableContextPath) {
+    // Flat preparation data layout: the verifiable context lives at
+    // `<preparation-data-dir>/<preparation>/`, so the preparation data folder is
+    // the parent of the verifiable context. Reject the filesystem root and the
+    // legacy `<root>/interf/<preparation>/` shape so stale fixtures fail loudly.
+    const verifiableContextAbsolute = resolve(verifiableContextPath);
+    const parent = dirname(verifiableContextAbsolute);
+    if (parent === verifiableContextAbsolute) {
+        throw new Error(`Verifiable context is not under the canonical Interf preparation data layout: ${verifiableContextPath}`);
+    }
+    if (basename(parent) === "interf") {
+        throw new Error(`Verifiable context is not under the canonical Interf preparation data layout: ${verifiableContextPath}`);
+    }
+    return parent;
+}
+export function defaultControlPathForVerifiableContext(verifiableContextPath) {
+    const relativePath = relative(verifiableContextPath, resolveSourceControlPathForVerifiableContext(verifiableContextPath));
+    return relativePath.length > 0 ? relativePath.split(sep).join("/") : ".";
+}

package/dist/packages/engine/build/verifiable-context-schema.d.ts

@@ -0,0 +1,21 @@
+import { type BuildPlanContextSchema, type BuildPlanArtifact, type BuildPlanArtifactId } from "./lib/schema.js";
+export interface BuildPlanSchemaStageLike {
+    id: string;
+    writes: readonly string[];
+}
+export declare const BUILD_PLAN_SCHEMA_FILE = "build-plan.schema.json";
+export declare function buildPlanSchemaFilePath(rootPath: string): string;
+export declare function resolveBuildPlanSchemaPath(rootPath: string): string | null;
+export declare function buildPlanSchemaExists(rootPath: string): boolean;
+export declare function buildPlanSchemaRelativePath(): string;
+export declare function listBuildPlanContextArtifacts(schema: BuildPlanContextSchema): BuildPlanArtifact[];
+export declare function findBuildPlanContextArtifact(schema: BuildPlanContextSchema, artifactId: BuildPlanArtifactId): BuildPlanArtifact | null;
+export declare function verifiableContextArtifactAbsolutePath(verifiableContextPath: string, artifact: Pick<BuildPlanArtifact, "path">): string;
+export declare function verifiableContextArtifactPath(artifact: Pick<BuildPlanArtifact, "path" | "kind">): string;
+export declare function verifiableContextArtifactPathsForArtifactIds(schema: BuildPlanContextSchema, artifactIds: readonly BuildPlanArtifactId[]): string[];
+export declare function ensureBuildPlanArtifactTargets(verifiableContextPath: string, schema: BuildPlanContextSchema): void;
+export declare function buildBuildPlanContextSchema(stages: BuildPlanSchemaStageLike[], label?: string): BuildPlanContextSchema;
+export declare function writeBuildPlanContextSchemaFile(rootPath: string, stages: BuildPlanSchemaStageLike[], label?: string): BuildPlanContextSchema;
+export declare function writeBuildPlanContextSchemaDocument(rootPath: string, schema: BuildPlanContextSchema): BuildPlanContextSchema;
+export declare function readBuildPlanContextSchemaFile(rootPath: string): BuildPlanContextSchema | null;
+export declare function readBuildPlanContextFile(rootPath: string): BuildPlanContextSchema | null;

package/dist/packages/engine/build/verifiable-context-schema.js

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { readJsonFileUnchecked } from "../../contracts/utils/parse.js";
+import { listBuiltinBuildPlanArtifactSpecs, requiredBuildPlanArtifactOwners, } from "../../build-plans/package/builtin-build-plan.js";
+import { BuildPlanContextSchemaSchema, } from "./lib/schema.js";
+export const BUILD_PLAN_SCHEMA_FILE = "build-plan.schema.json";
+export function buildPlanSchemaFilePath(rootPath) {
+    return join(rootPath, BUILD_PLAN_SCHEMA_FILE);
+}
+export function resolveBuildPlanSchemaPath(rootPath) {
+    const path = buildPlanSchemaFilePath(rootPath);
+    return existsSync(path) ? path : null;
+}
+export function buildPlanSchemaExists(rootPath) {
+    return existsSync(buildPlanSchemaFilePath(rootPath));
+}
+export function buildPlanSchemaRelativePath() {
+    return `build-plan/${BUILD_PLAN_SCHEMA_FILE}`;
+}
+export function listBuildPlanContextArtifacts(schema) {
+    return schema.artifacts.map(artifactToBuildPlanArtifact);
+}
+export function findBuildPlanContextArtifact(schema, artifactId) {
+    return listBuildPlanContextArtifacts(schema).find((artifact) => artifact.id === artifactId) ?? null;
+}
+export function verifiableContextArtifactAbsolutePath(verifiableContextPath, artifact) {
+    return join(verifiableContextPath, artifact.path);
+}
+export function verifiableContextArtifactPath(artifact) {
+    if (artifact.kind === "file")
+        return artifact.path;
+    return artifact.path.endsWith("/") ? artifact.path : `${artifact.path}/`;
+}
+export function verifiableContextArtifactPathsForArtifactIds(schema, artifactIds) {
+    return artifactIds.map((artifactId) => {
+        const artifact = findBuildPlanContextArtifact(schema, artifactId);
+        if (!artifact) {
+            throw new Error(`Build Plan schema is missing declared Artifact "${artifactId}".`);
+        }
+        return verifiableContextArtifactPath(artifact);
+    });
+}
+export function ensureBuildPlanArtifactTargets(verifiableContextPath, schema) {
+    for (const artifact of listBuildPlanContextArtifacts(schema)) {
+        if (artifact.kind === "directory" || artifact.kind === "runtime") {
+            mkdirSync(verifiableContextArtifactAbsolutePath(verifiableContextPath, artifact), { recursive: true });
+            continue;
+        }
+        mkdirSync(dirname(verifiableContextArtifactAbsolutePath(verifiableContextPath, artifact)), { recursive: true });
+    }
+}
+function normalizeBuildPlanContextSchema(schema) {
+    return {
+        ...schema,
+        kind: "build-plan-schema",
+    };
+}
+function artifactToBuildPlanArtifact(artifact) {
+    if (artifact.shape.kind !== "path") {
+        return {
+            id: artifact.id,
+            role: "output",
+            path: artifact.id,
+            kind: "directory",
+            required: true,
+            owned_by: [...artifact.built_by_stages],
+            description: artifact.description,
+        };
+    }
+    return {
+        id: artifact.id,
+        role: "output",
+        path: artifact.shape.path,
+        kind: artifact.shape.artifact_kind,
+        required: true,
+        owned_by: [...artifact.built_by_stages],
+        description: artifact.description,
+    };
+}
+export function buildBuildPlanContextSchema(stages, label = "Build Plan schema") {
+    return {
+        kind: "build-plan-schema",
+        version: 1,
+        target_type: "verifiable-context",
+        label,
+        artifacts: listBuiltinBuildPlanArtifactSpecs().map((artifact) => ({
+            id: artifact.id,
+            description: artifact.description,
+            shape: {
+                kind: "path",
+                path: artifact.path,
+                artifact_kind: artifact.kind === "file" ? "file" : "directory",
+            },
+            checks: [],
+            built_by_stages: requiredBuildPlanArtifactOwners(stages, artifact.id),
+        })),
+    };
+}
+export function writeBuildPlanContextSchemaFile(rootPath, stages, label) {
+    const schema = buildBuildPlanContextSchema(stages, label);
+    writeBuildPlanContextSchemaDocument(rootPath, schema);
+    return schema;
+}
+export function writeBuildPlanContextSchemaDocument(rootPath, schema) {
+    const normalized = normalizeBuildPlanContextSchema(schema);
+    writeFileSync(buildPlanSchemaFilePath(rootPath), `${JSON.stringify(normalized, null, 2)}\n`);
+    return normalized;
+}
+export function readBuildPlanContextSchemaFile(rootPath) {
+    const path = buildPlanSchemaFilePath(rootPath);
+    if (!existsSync(path))
+        return null;
+    const raw = readJsonFileUnchecked(path, "Build Plan schema");
+    if (raw === null)
+        return null;
+    const parsed = BuildPlanContextSchemaSchema.safeParse(raw);
+    if (!parsed.success) {
+        warnInterf(`Warning: failed to validate Build Plan schema at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    return normalizeBuildPlanContextSchema(parsed.data);
+}
+export function readBuildPlanContextFile(rootPath) {
+    return readBuildPlanContextSchemaFile(rootPath);
+}

package/dist/packages/engine/client.d.ts

@@ -1,4 +1,4 @@
-import { type ActionProposalApprovalRequest, type ActionProposalCreateRequest, type ActionProposalResource, type CompileRunCreateRequest, type CompileRunResource, type LocalJobRunResource, type LocalServiceHealth, type ReadinessCheckDraftCreateRequest, type ReadinessCheckDraftResult, type ResetRequest, type ResetResult, type VerifyRunCreateRequest, type VerifyRunResource, type MethodAuthoringCreateRequest, type MethodAuthoringResult } from "./lib/schema.js";
+import { type ActionProposalApprovalRequest, type ActionProposalCreateRequest, type ActionProposalResource, type BuildRunCreateRequest, type BuildRunResource, type LocalJobRunResource, type LocalServiceHealth, type ReadinessCheckDraftCreateRequest, type ReadinessCheckDraftResult, type ResetRequest, type ResetResult, type VerifyRunCreateRequest, type VerifyRunResource, type BuildPlanAuthoringCreateRequest, type BuildPlanAuthoringResult } from "./lib/schema.js";
 export interface FindOrStartLocalServiceOptions {
     url?: string;
     authToken?: string;
@@ -33,13 +33,13 @@ export declare function resolveLocalServiceAuthToken(): string | null;
 export declare function findLocalService(options?: {
     timeoutMs?: number;
 }): Promise<LocalServiceConnection | null>;
-export declare function submitCompileRunToLocalService(options: {
+export declare function submitBuildRunToLocalService(options: {
     preparationId: string;
-    request: CompileRunCreateRequest;
+    request: BuildRunCreateRequest;
     idempotencyKey?: string;
 }): Promise<{
     serviceUrl: string;
-    resource: CompileRunResource;
+    resource: BuildRunResource;
 } | null>;
 export declare function submitVerifyRunToLocalService(options: {
     preparationId: string;
@@ -76,33 +76,33 @@ export declare function approveActionProposalInLocalService(options: {
     serviceUrl: string;
     resource: ActionProposalResource;
 } | null>;
-export declare function getLocalCompileRun(options: {
+export declare function getLocalBuildRun(options: {
     serviceUrl: string;
     runId: string;
     authToken?: string | null;
-}): Promise<CompileRunResource>;
-export interface LocalCompileRunCancelResult {
+}): Promise<BuildRunResource>;
+export interface LocalBuildRunCancelResult {
     cancelled: boolean;
     reason?: string;
 }
 /**
- * Ask the local service to cancel a running compile run by id. Resolves
+ * Ask the local service to cancel a running Build run by id. Resolves
  * with the typed cancel result on success and throws when the service
  * returns 404 (unknown run id) or any non-2xx status.
  */
-export declare function cancelLocalCompileRun(options: {
+export declare function cancelLocalBuildRun(options: {
     serviceUrl: string;
     runId: string;
     timeoutMs?: number;
     authToken?: string | null;
-}): Promise<LocalCompileRunCancelResult>;
-export declare function waitForLocalCompileRun(options: {
+}): Promise<LocalBuildRunCancelResult>;
+export declare function waitForLocalBuildRun(options: {
     serviceUrl: string;
     runId: string;
     pollMs?: number;
     authToken?: string | null;
-    onUpdate?: (resource: CompileRunResource) => void;
-}): Promise<CompileRunResource>;
+    onUpdate?: (resource: BuildRunResource) => void;
+}): Promise<BuildRunResource>;
 export declare function getLocalVerifyRun(options: {
     serviceUrl: string;
     runId: string;
@@ -134,12 +134,12 @@ export declare function submitReadinessCheckDraftToLocalService(options: {
     onSubmitted?: (submission: LocalServiceJobSubmitted) => void;
     onUpdate?: (job: LocalJobRunResource) => void;
 }): Promise<LocalServiceJobSubmission<ReadinessCheckDraftResult> | null>;
-export declare function submitMethodAuthoringRunToLocalService(options: {
+export declare function submitBuildPlanAuthoringRunToLocalService(options: {
     preparationId: string;
-    request: MethodAuthoringCreateRequest;
+    request: BuildPlanAuthoringCreateRequest;
     onSubmitted?: (submission: LocalServiceJobSubmitted) => void;
     onUpdate?: (job: LocalJobRunResource) => void;
-}): Promise<LocalServiceJobSubmission<MethodAuthoringResult> | null>;
+}): Promise<LocalServiceJobSubmission<BuildPlanAuthoringResult> | null>;
 /**
  * Fetch the engine instance health/status.
  */