@interf/compiler 0.21.0 → 0.22.2

package/dist/packages/engine/{compile/method-primitives.js → build/build-plan-primitives.js}

@@ -1,4 +1,4 @@
-export const COMPILED_ARTIFACT_KINDS = [
+export const BUILD_PLAN_ARTIFACT_KINDS = [
     "directory",
     "file",
     "runtime",

package/dist/packages/engine/build/build-plan-runs.d.ts

@@ -0,0 +1,14 @@
+import { type InterfConfig } from "../../project/interf-detect.js";
+export type { BuildPlanReporter } from "../../build-plans/package/build-plan-helpers.js";
+export type BuildCheck = "verifiable-context" | "stage";
+export interface DetectedInterfTarget {
+    path: string;
+    kind: "verifiable-context";
+    engineType: "build";
+    config: InterfConfig;
+}
+export declare function detectVerifiableContext(cwd: string): DetectedInterfTarget | null;
+export declare function createVerifiableContext(name: string, sourcePath: string, buildPlanId: string | undefined, about: string | undefined, sourceFolderPath: string): string;
+export declare function verifyBuildCheck(check: BuildCheck, verifiableContextPath: string): import("./validate-verifiable-context.js").VerifiableContextValidation;
+export { runBuildSummarize, runBuildStages, buildVerifiableContext, resolveBuildContext, buildExecutionStages, } from "./build-execution.js";
+export type { BuildSummarizeResult, BuildResult, BuildStageExecutionDefinition, StageShellRetentionMode, ResolveStageExecutor, } from "./build-execution.js";

package/dist/packages/engine/build/build-plan-runs.js

@@ -0,0 +1,31 @@
+import { createVerifiableContext as createVerifiableContextScaffold, } from "../../project/interf-scaffold.js";
+import { detectInterf } from "../../project/interf-detect.js";
+import { validateBuildOutput, } from "./validate.js";
+import { DEFAULT_BUILD_PLAN_ID } from "../../build-plans/build-plan-resolution.js";
+export function detectVerifiableContext(cwd) {
+    const detected = detectInterf(cwd);
+    if (!detected)
+        return null;
+    return {
+        path: detected.path,
+        kind: "verifiable-context",
+        engineType: "build",
+        config: detected.config,
+    };
+}
+export function createVerifiableContext(name, sourcePath, buildPlanId, about, sourceFolderPath) {
+    return createVerifiableContextScaffold(name, sourcePath, buildPlanId ?? DEFAULT_BUILD_PLAN_ID, about, sourceFolderPath);
+}
+export function verifyBuildCheck(check, verifiableContextPath) {
+    switch (check) {
+        case "verifiable-context":
+            return validateBuildOutput(verifiableContextPath);
+        case "stage":
+            return validateBuildOutput(verifiableContextPath);
+        default: {
+            const exhaustiveCheck = check;
+            throw new Error(`Unknown build check: ${exhaustiveCheck}`);
+        }
+    }
+}
+export { runBuildSummarize, runBuildStages, buildVerifiableContext, resolveBuildContext, buildExecutionStages, } from "./build-execution.js";

package/dist/packages/engine/build/build-stage-plan.d.ts

@@ -0,0 +1,16 @@
+import { type RuntimeStageContractDraft } from "./runtime.js";
+import { type BuildPlanStageDefinition } from "../../build-plans/package/build-plan-definitions.js";
+import { resolveBuildContext, type BuildStageExecutionDefinition } from "./build-target.js";
+import type { RuntimeStageInstructions } from "./lib/schema.js";
+export declare function resolveStageContractArtifacts(verifiableContextPath: string, stageDefinition: Pick<BuildPlanStageDefinition, "id" | "reads" | "writes">): {
+    reads: string[];
+    writes: string[];
+    writeContracts: RuntimeStageContractDraft["artifacts"]["write_contracts"];
+};
+export declare function buildStageCounts(verifiableContextPath: string, stageDefinition: BuildPlanStageDefinition): Record<string, number>;
+export declare function buildStageContract(verifiableContextPath: string, stageDefinition: BuildPlanStageDefinition, instructions: RuntimeStageInstructions): RuntimeStageContractDraft;
+export declare function buildBuildStageExecutionPlan(verifiableContextPath: string, stageDefinition: BuildStageExecutionDefinition): {
+    context: ReturnType<typeof resolveBuildContext>;
+    contract: RuntimeStageContractDraft;
+    instructions: RuntimeStageInstructions;
+};

package/dist/packages/engine/build/build-stage-plan.js

@@ -0,0 +1,100 @@
+import { join } from "node:path";
+import { buildRuntimeStageContract, } from "./runtime.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { verifiableContextArtifactPath, verifiableContextArtifactPathsForArtifactIds, findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./verifiable-context-schema.js";
+import { buildLocalSkillContractExtension, buildStageInstructions, buildPlanStageDirectory, } from "../../build-plans/package/build-plan-helpers.js";
+import { getActiveBuildPlanStagePolicyNotes, } from "../../build-plans/package/build-plan-definitions.js";
+import { buildPlanPackagePathForVerifiableContext } from "./verifiable-context-paths.js";
+import { readInterfConfig } from "../../project/interf-detect.js";
+import { resolveBuildContext, } from "./build-target.js";
+function artifactCount(verifiableContextPath, artifactPath, kind) {
+    const absolutePath = join(verifiableContextPath, artifactPath);
+    try {
+        if (kind === "file") {
+            return listFilesRecursive(absolutePath).length > 0 ? 1 : 0;
+        }
+    }
+    catch {
+        if (kind === "file")
+            return 0;
+    }
+    return listFilesRecursive(absolutePath).length;
+}
+export function resolveStageContractArtifacts(verifiableContextPath, stageDefinition) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(verifiableContextPath));
+    if (!schema) {
+        throw new Error(`Missing Build Plan schema for stage "${stageDefinition.id}" at ${buildPlanPackagePathForVerifiableContext(verifiableContextPath)}.`);
+    }
+    return {
+        reads: verifiableContextArtifactPathsForArtifactIds(schema, stageDefinition.reads),
+        writes: verifiableContextArtifactPathsForArtifactIds(schema, stageDefinition.writes),
+        writeContracts: stageDefinition.writes.map((artifactId) => {
+            const artifact = schema.artifacts.find((candidate) => candidate.id === artifactId);
+            if (!artifact) {
+                throw new Error(`Build Plan schema is missing declared Artifact "${artifactId}".`);
+            }
+            const path = artifact.shape.kind === "path"
+                ? verifiableContextArtifactPath({
+                    path: artifact.shape.path,
+                    kind: artifact.shape.artifact_kind,
+                })
+                : artifact.id;
+            return {
+                artifact_id: artifact.id,
+                path,
+                checks: artifact.checks ?? [],
+            };
+        }),
+    };
+}
+export function buildStageCounts(verifiableContextPath, stageDefinition) {
+    const context = resolveBuildContext(verifiableContextPath);
+    const sourceTotal = discoverSourceFiles(context.sourcePath, verifiableContextPath).totalCount;
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(verifiableContextPath));
+    const artifactCounts = {};
+    if (schema) {
+        for (const artifactId of new Set([...stageDefinition.reads, ...stageDefinition.writes])) {
+            const artifact = findBuildPlanContextArtifact(schema, artifactId);
+            if (!artifact)
+                continue;
+            artifactCounts[artifactId] = artifactCount(verifiableContextPath, artifact.path, artifact.kind);
+        }
+    }
+    return {
+        source_total: sourceTotal,
+        read_artifact_total: stageDefinition.reads.length,
+        write_artifact_total: stageDefinition.writes.length,
+        ...artifactCounts,
+    };
+}
+export function buildStageContract(verifiableContextPath, stageDefinition, instructions) {
+    const config = readInterfConfig(verifiableContextPath);
+    const stageArtifacts = resolveStageContractArtifacts(verifiableContextPath, stageDefinition);
+    return buildRuntimeStageContract({
+        verifiableContextName: config?.name ?? "verifiable-context",
+        stageId: stageDefinition.id,
+        stageLabel: stageDefinition.label,
+        counts: buildStageCounts(verifiableContextPath, stageDefinition),
+        extraReadArtifacts: [
+            ".interf/runtime/source-snapshot.json",
+            `.interf/runtime/stages/${stageDefinition.id}/inputs.json`,
+        ],
+        stageReadArtifacts: stageArtifacts.reads,
+        stageWriteArtifacts: stageArtifacts.writes,
+        stageWriteContracts: stageArtifacts.writeContracts,
+        buildPlanNotes: getActiveBuildPlanStagePolicyNotes(verifiableContextPath, stageDefinition.id),
+        localSkillDocs: instructions.local_docs,
+        instructions,
+    });
+}
+export function buildBuildStageExecutionPlan(verifiableContextPath, stageDefinition) {
+    const context = resolveBuildContext(verifiableContextPath);
+    const localSkills = buildLocalSkillContractExtension(verifiableContextPath, [buildPlanStageDirectory(stageDefinition.skillDir)], "Use them to refine this Build Plan stage while still honoring the declared reads, writes, and proof rules.");
+    const instructions = buildStageInstructions(stageDefinition.skillDir, localSkills);
+    return {
+        context,
+        instructions,
+        contract: buildStageContract(verifiableContextPath, stageDefinition, instructions),
+    };
+}

package/dist/packages/engine/build/build-stage-runner.d.ts

@@ -0,0 +1,15 @@
+import { type AgentExecutor } from "../agents/lib/executors.js";
+import { type BuildPlanReporter, type BuildPlanStageResult } from "../../build-plans/package/build-plan-helpers.js";
+import { type BuildStageExecutionDefinition } from "./build-target.js";
+import { type RunEventSink } from "../execution/events.js";
+export declare function runBuildStage(options: {
+    executor: AgentExecutor;
+    verifiableContextPath: string;
+    reporter?: BuildPlanReporter;
+    reportStep?: boolean;
+    stageDefinition: BuildStageExecutionDefinition;
+    runId?: string;
+    events?: RunEventSink;
+    stageIndex?: number;
+    stageTotal?: number;
+}): Promise<BuildPlanStageResult>;

package/dist/packages/engine/{compile/compiled-stage-runner.js → build/build-stage-runner.js}

@@ -1,23 +1,23 @@
 import { createStageExecutionShell, freezeStageExecutionShell, syncStageExecutionShellWrites, } from "../agents/lib/shells.js";
-import { reconcileCompiledStageRun } from "./runtime-reconcile.js";
-import { refreshCompiledArtifacts } from "./state.js";
-import { validateCompiledStage } from "./validate.js";
-import { executeValidatedStage, } from "../../methods/package/method-stage-runner.js";
-import { formatActiveCompiledMethodStageStep, } from "../../methods/package/method-definitions.js";
-import { reportBlankLine, reportLine, } from "../../methods/package/method-helpers.js";
-import { buildCompiledStageExecutionPlan, } from "./compiled-stage-plan.js";
+import { reconcileBuildStageRun } from "./runtime-reconcile.js";
+import { refreshVerifiableContextArtifacts } from "./state.js";
+import { validateBuildStage } from "./validate.js";
+import { executeValidatedStage, } from "../../build-plans/package/build-plan-stage-runner.js";
+import { formatActiveBuildPlanStageLabel, } from "../../build-plans/package/build-plan-definitions.js";
+import { reportBlankLine, reportLine, } from "../../build-plans/package/build-plan-helpers.js";
+import { buildBuildStageExecutionPlan, } from "./build-stage-plan.js";
 import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
 async function emitRunEvent(sink, event) {
     await sink?.emit(event);
 }
-export async function runCompiledStage(options) {
+export async function runBuildStage(options) {
     const stageDefinition = options.stageDefinition;
-    const plan = buildCompiledStageExecutionPlan(options.compiledPath, stageDefinition);
+    const plan = buildBuildStageExecutionPlan(options.verifiableContextPath, stageDefinition);
     if (options.reportStep !== false) {
         reportBlankLine(options.reporter);
-        reportLine(options.reporter, `${formatActiveCompiledMethodStageStep(options.compiledPath, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
+        reportLine(options.reporter, `${formatActiveBuildPlanStageLabel(options.verifiableContextPath, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
     }
-    const shell = createStageExecutionShell(options.compiledPath, plan.context.compiledName, plan.context.methodId, stageDefinition, plan.contract.artifacts.writes);
+    const shell = createStageExecutionShell(options.verifiableContextPath, plan.context.verifiableContextName, plan.context.buildPlanId, stageDefinition, plan.contract.artifacts.writes);
     try {
         if (options.runId && options.events) {
             await emitRunEvent(options.events, {
@@ -32,11 +32,11 @@ export async function runCompiledStage(options) {
         }
         const result = await executeValidatedStage({
             executor: options.executor,
-            compiledPath: options.compiledPath,
+            verifiableContextPath: options.verifiableContextPath,
             executionPath: shell.rootPath,
-            targetName: plan.context.compiledName,
-            method: plan.context.methodId,
-            methodSourcePath: options.compiledPath,
+            targetName: plan.context.verifiableContextName,
+            buildPlan: plan.context.buildPlanId,
+            buildPlanSourcePath: options.verifiableContextPath,
             stageDefinition,
             instructions: plan.instructions,
             summary: `Executing ${stageDefinition.label.toLowerCase()}.`,
@@ -44,11 +44,11 @@ export async function runCompiledStage(options) {
             statusLines: [
                 `Emit exactly one startup line: STATUS: loaded ${stageDefinition.label.toLowerCase()} stage.`,
                 "Emit STATUS: reading declared inputs after you confirm the shell contract and local docs.",
-                "Emit STATUS: writing declared outputs after the stage starts updating the compiled Artifacts.",
+                "Emit STATUS: writing declared outputs after the stage starts updating the built Artifacts.",
                 `Emit DONE: ${stageDefinition.id} complete when the declared outputs and proof are on disk.`,
             ],
             reporter: options.reporter,
-            completionCheck: () => validateCompiledStage(options.compiledPath, stageDefinition.id).ok,
+            completionCheck: () => validateBuildStage(options.verifiableContextPath, stageDefinition.id).ok,
             onStatus: options.runId && options.events
                 ? (line) => {
                     void options.events?.emit({
@@ -62,10 +62,10 @@ export async function runCompiledStage(options) {
                     });
                 }
                 : undefined,
-            syncWrites: () => syncStageExecutionShellWrites(options.compiledPath, shell.rootPath, stageDefinition, plan.contract.artifacts.writes),
-            reconcile: () => reconcileCompiledStageRun(options.compiledPath, stageDefinition),
-            refreshArtifacts: () => refreshCompiledArtifacts(options.compiledPath, { ensureViewSpec: true }),
-            validate: () => validateCompiledStage(options.compiledPath, stageDefinition.id),
+            syncWrites: () => syncStageExecutionShellWrites(options.verifiableContextPath, shell.rootPath, stageDefinition, plan.contract.artifacts.writes),
+            reconcile: () => reconcileBuildStageRun(options.verifiableContextPath, stageDefinition),
+            refreshArtifacts: () => refreshVerifiableContextArtifacts(options.verifiableContextPath, { ensureViewSpec: true }),
+            validate: () => validateBuildStage(options.verifiableContextPath, stageDefinition.id),
         });
         if (options.runId && options.events) {
             await emitRunEvent(options.events, result.ok

package/dist/packages/engine/build/build-target.d.ts

@@ -0,0 +1,11 @@
+import { type BuildPlanStageDefinition } from "../../build-plans/package/build-plan-definitions.js";
+import { type ResolvedBuildPlanId } from "../../build-plans/package/build-plan-definitions.js";
+export interface BuildStageExecutionDefinition extends BuildPlanStageDefinition {
+}
+export declare function resolveBuildContext(verifiableContextPath: string): {
+    verifiableContextName: string;
+    sourcePath: string;
+    prepDataDir: string;
+    buildPlanId: ResolvedBuildPlanId;
+};
+export declare function buildExecutionStages(_buildPlanId: ResolvedBuildPlanId, verifiableContextPath: string): BuildStageExecutionDefinition[];

package/dist/packages/engine/build/build-target.js

@@ -0,0 +1,16 @@
+import { getActiveBuildPlan, resolveRequiredBuildPlanFromConfig, } from "../../build-plans/package/build-plan-definitions.js";
+import { readInterfConfig, resolveSourceFolderPath, resolveSourceControlPath, } from "../../project/interf-detect.js";
+export function resolveBuildContext(verifiableContextPath) {
+    const config = readInterfConfig(verifiableContextPath);
+    const buildPlanId = resolveRequiredBuildPlanFromConfig(config, `.interf/interf.json for ${verifiableContextPath}`);
+    return {
+        verifiableContextName: config?.name ?? "verifiable-context",
+        sourcePath: resolveSourceFolderPath(verifiableContextPath, config),
+        prepDataDir: resolveSourceControlPath(verifiableContextPath),
+        buildPlanId,
+    };
+}
+export function buildExecutionStages(_buildPlanId, verifiableContextPath) {
+    return getActiveBuildPlan(verifiableContextPath)
+        .stages;
+}

package/dist/packages/engine/{compile → build}/check-evaluator.d.ts

@@ -7,7 +7,7 @@ import { type Check, type CheckKind, type Proof } from "../../contracts/lib/sche
  * runtime context (counts, source-file totals); it returns a Proof.
  *
  * The same evaluator serves stage-level checks, artifact-level checks,
- * and (for `qa_match`) user-level checks. Methods and user-defined
+ * and (for `qa_match`) user-level checks. Build Plans and user-defined
  * verification declare `Check[]`; the runtime invokes this evaluator
  * to produce `Proof[]`.
  *
@@ -18,7 +18,7 @@ import { type Check, type CheckKind, type Proof } from "../../contracts/lib/sche
 export interface CheckEvaluationContext {
     /**
      * Filesystem root the check evaluates against. For artifact checks
-     * this is the portable-context root; the artifact's path is
+     * this is the verifiable-context root; the artifact's path is
      * resolved relative to it. For stage checks this can be the same
      * root or a stage-output sub-directory.
      */
@@ -33,13 +33,13 @@ export interface CheckEvaluationContext {
     /**
      * Optional runtime-derived counts used by `min_file_count_matches_source`
      * and similar rules. `source_total` is the canonical key for "how
-     * many source files were processed." Methods reference it in check
+     * many source files were processed." Build Plans reference it in check
      * params via `{ match: "source_total" }`.
      */
     counts?: Record<string, number>;
     /**
      * Optional: the agent's answer for a `qa_match` check. Provided by
-     * the verify-run flow, not relevant for compile-time evaluation.
+     * the verify-run flow, not relevant for build-time evaluation.
      */
     agentAnswer?: string;
 }

package/dist/packages/engine/{compile → build}/check-evaluator.js

@@ -26,7 +26,7 @@ function resolveTargetPath(check, context) {
     const root = resolve(context.rootPath);
     const absolute = resolve(root, target);
     // Defense in depth — schema-level validation already rejects path
-    // traversal, but a hand-edited Method or stale on-disk fixture could
+    // traversal, but a hand-edited Build Plan or stale on-disk fixture could
     // slip through. Reject anything that escapes the root.
     if (absolute !== root && !absolute.startsWith(`${root}/`)) {
         return null;

package/dist/packages/engine/{compile → build}/discovery.d.ts

@@ -3,5 +3,5 @@ export interface DiscoveryResult {
     totalCount: number;
     ignoredCount: number;
 }
-export declare function discoverSourceFiles(sourcePath: string, compiledPath: string): DiscoveryResult;
-export declare function loadIgnorePatterns(compiledPath: string): string[];
+export declare function discoverSourceFiles(sourcePath: string, verifiableContextPath: string): DiscoveryResult;
+export declare function loadIgnorePatterns(verifiableContextPath: string): string[];

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

@@ -12,8 +12,8 @@ const DEFAULT_IGNORE_DIRS = new Set([
 const DEFAULT_IGNORE_FILES = new Set([
     "interf.json",
 ]);
-export function discoverSourceFiles(sourcePath, compiledPath) {
-    const userPatterns = loadIgnorePatterns(compiledPath);
+export function discoverSourceFiles(sourcePath, verifiableContextPath) {
+    const userPatterns = loadIgnorePatterns(verifiableContextPath);
     let ignoredCount = 0;
     const allFiles = listFilesRecursive(sourcePath, (filePath) => {
         const rel = relative(sourcePath, filePath);
@@ -36,8 +36,8 @@ export function discoverSourceFiles(sourcePath, compiledPath) {
         ignoredCount,
     };
 }
-export function loadIgnorePatterns(compiledPath) {
-    const ignorePath = join(compiledPath, ".interfignore");
+export function loadIgnorePatterns(verifiableContextPath) {
+    const ignorePath = join(verifiableContextPath, ".interfignore");
     if (!existsSync(ignorePath))
         return [];
     return readFileSync(ignorePath, "utf-8")

package/dist/packages/engine/{compile → build}/index.d.ts

@@ -1,7 +1,7 @@
-export * as primitives from "./method-primitives.js";
+export * as primitives from "./build-plan-primitives.js";
 export * as schema from "./lib/schema.js";
-export * as compiledSchema from "./compiled-schema.js";
-export * as compile from "./compiled-compile.js";
+export * as verifiableContextSchema from "./verifiable-context-schema.js";
+export * as buildExecution from "./build-execution.js";
 export * as runtime from "./runtime.js";
 export * as runtimeContracts from "./runtime-contracts.js";
 export * as runtimeInventory from "./runtime-inventory.js";
@@ -18,7 +18,7 @@ export * as stateIo from "./state-io.js";
 export * as statePaths from "./state-paths.js";
 export * as stateView from "./state-view.js";
 export * as validate from "./validate.js";
-export * as validateCompiled from "./validate-compiled.js";
+export * as validateVerifiableContextSetup from "./validate-verifiable-context.js";
 export * as validateHelpers from "./validate-helpers.js";
-export * as methods from "./method-runs.js";
-export type { CompiledCompileResult, CompiledSummarizeResult, StageShellRetentionMode, } from "./method-runs.js";
+export * as buildPlanRuns from "./build-plan-runs.js";
+export type { BuildResult, BuildSummarizeResult, StageShellRetentionMode, } from "./build-plan-runs.js";

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

@@ -1,7 +1,7 @@
-export * as primitives from "./method-primitives.js";
+export * as primitives from "./build-plan-primitives.js";
 export * as schema from "./lib/schema.js";
-export * as compiledSchema from "./compiled-schema.js";
-export * as compile from "./compiled-compile.js";
+export * as verifiableContextSchema from "./verifiable-context-schema.js";
+export * as buildExecution from "./build-execution.js";
 export * as runtime from "./runtime.js";
 export * as runtimeContracts from "./runtime-contracts.js";
 export * as runtimeInventory from "./runtime-inventory.js";
@@ -18,6 +18,6 @@ export * as stateIo from "./state-io.js";
 export * as statePaths from "./state-paths.js";
 export * as stateView from "./state-view.js";
 export * as validate from "./validate.js";
-export * as validateCompiled from "./validate-compiled.js";
+export * as validateVerifiableContextSetup from "./validate-verifiable-context.js";
 export * as validateHelpers from "./validate-helpers.js";
-export * as methods from "./method-runs.js";
+export * as buildPlanRuns from "./build-plan-runs.js";