@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/{engine → runtime}/build/billing-events.js

@@ -1,24 +1,21 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { z } from "zod";
+import { contextGraphRuntimeRoot } from "./context-graph-paths.js";
 /**
- * 0.17 — per-Artifact billing event record.
+ * Per-Artifact billing event record.
  *
  * Emitted once per Artifact each time a Build run produces it.
- * `account_id` is `null` for loopback (no auth); the cloud variant
- * fills it from the `tokenValidator` (B4.3) result.
- *
- * `event_kind`:
- * - `fresh` — first-time build of this Artifact in this run
- * - `resync` — incremental rebuild (deferred to 0.18+; not emitted in 0.17)
+ * `account_id` is `null` for loopback engines; hosted variants can fill it
+ * from the service auth layer.
  */
 export const BillingEventKindSchema = z.enum(["fresh", "resync"]);
-export const CompilationEventSchema = z.object({
-    kind: z.literal("interf-compilation-event"),
+export const BuildBillingEventSchema = z.object({
+    kind: z.literal("interf-build-billing-event"),
     version: z.literal(1),
     timestamp: z.string().min(1),
     run_id: z.string().min(1),
-    preparation: z.string().min(1),
+    project: z.string().min(1),
     artifact_id: z.string().min(1),
     build_plan_id: z.string().min(1),
     account_id: z.string().min(1).nullable(),
@@ -32,27 +29,28 @@ export class JsonlBillingEventSink {
         this.logPath = logPath;
     }
     emit(event) {
-        const validated = CompilationEventSchema.parse(event);
+        const validated = BuildBillingEventSchema.parse(event);
         mkdirSync(dirname(this.logPath), { recursive: true });
         appendFileSync(this.logPath, `${JSON.stringify(validated)}\n`);
     }
 }
 /**
  * Default sink path for a run. Each Build run gets its own JSONL
- * file alongside its other on-disk artifacts.
+ * file under hidden runtime metadata, not beside agent-facing Artifacts.
  */
 export function defaultBillingEventLogPath(options) {
-    return join(options.preparationDataDir, options.preparationName, "runs", options.runId, "billing-events.jsonl");
+    const contextGraphPath = join(options.projectDataDir, options.projectName);
+    return join(contextGraphRuntimeRoot(contextGraphPath), "billing-events", options.runId, "billing-events.jsonl");
 }
 /**
- * Convert a list of per-Artifact statuses into compilation events for
+ * Convert a list of per-Artifact statuses into build events for
  * the run. Only `ready` and `failed` artifacts emit events — `skipped`
  * and `not_ready` represent work that didn't happen and shouldn't bill.
  *
- * 0.17 ships `event_kind: "fresh"` only. The resync optimization that
- * differentiates cached-vs-rebuilt artifacts lands in 0.18+.
+ * Local builds currently emit `event_kind: "fresh"` only. The `resync` value is
+ * reserved for incremental rebuilds.
  */
-export function buildCompilationEventsForRun(options) {
+export function buildBillingEventsForRun(options) {
     const timestamp = options.timestamp ?? new Date().toISOString();
     const durationMs = options.startedAt && options.finishedAt
         ? Math.max(0, new Date(options.finishedAt).getTime() - new Date(options.startedAt).getTime())
@@ -60,11 +58,11 @@ export function buildCompilationEventsForRun(options) {
     return options.artifacts
         .filter((status) => status.status === "ready" || status.status === "failed")
         .map((status) => ({
-        kind: "interf-compilation-event",
+        kind: "interf-build-billing-event",
         version: 1,
         timestamp,
         run_id: options.runId,
-        preparation: options.preparation,
+        project: options.project,
         artifact_id: status.artifact_id,
         build_plan_id: options.buildPlanId,
         account_id: options.accountId,

package/dist/packages/runtime/build/build-evidence.d.ts

@@ -0,0 +1,15 @@
+import { type BuildEvidenceResource, type Readiness } from "../../contracts/lib/schema.js";
+import type { BuildRun } from "../execution/lib/schema.js";
+import type { StageEvidenceReconciliation } from "./lib/schema.js";
+interface BuildBuildEvidenceInput {
+    projectId: string;
+    buildRun?: BuildRun | null;
+    readiness?: Readiness | null;
+    sourceFileCount: number;
+    expectedStageCount?: number;
+    expectedOutputCount?: number;
+    stageEvidence?: readonly StageEvidenceReconciliation[];
+    generatedAt?: string;
+}
+export declare function buildBuildEvidence(input: BuildBuildEvidenceInput): BuildEvidenceResource;
+export {};

package/dist/packages/runtime/build/build-evidence.js

@@ -0,0 +1,173 @@
+import { BuildEvidenceResourceSchema, } from "../../contracts/lib/schema.js";
+function issueState(observed, total, options) {
+    if (options?.hardFailure)
+        return "fail";
+    if (typeof total !== "number")
+        return undefined;
+    if (total === 0)
+        return options?.reviewWhenEmpty ? "review" : undefined;
+    return observed >= total ? "pass" : "missing";
+}
+function metric(observed, total, unit) {
+    return {
+        observed: Math.max(0, Math.trunc(observed)),
+        ...(typeof total === "number" ? { total: Math.max(0, Math.trunc(total)) } : {}),
+        ...(unit ? { unit } : {}),
+    };
+}
+function sourceFilesProcessed(stages) {
+    let observed = 0;
+    for (const stage of stages) {
+        const value = stage.latest_evidence?.files_processed;
+        if (typeof value === "number" && Number.isFinite(value)) {
+            observed = Math.max(observed, Math.trunc(value));
+        }
+    }
+    return observed;
+}
+function requiredArtifactCheckResults(artifacts) {
+    return artifacts
+        .flatMap((artifact) => artifact.check_results ?? [])
+        .filter((result) => result.required !== false);
+}
+function stageCheckCounts(stages) {
+    const checks = stages.flatMap((stage) => stage.latest_evidence?.checks ?? []);
+    return {
+        passed: checks.filter((check) => check.ok).length,
+        total: checks.length,
+    };
+}
+function rowStateIssue(state, missingMessage, failMessage) {
+    if (!state)
+        return {};
+    if (state === "missing")
+        return { issue_state: state, issue: missingMessage };
+    if (state === "fail")
+        return { issue_state: state, issue: failMessage ?? missingMessage };
+    return { issue_state: state };
+}
+function rowsHaveBlockingIssue(rows) {
+    return rows.some((row) => row.issue_state === "missing" || row.issue_state === "fail");
+}
+export function buildBuildEvidence(input) {
+    const generatedAt = input.generatedAt ?? new Date().toISOString();
+    const buildRun = input.buildRun ?? null;
+    const stages = buildRun?.stages ?? [];
+    const artifactStatuses = buildRun?.artifacts ?? [];
+    const acceptedEvidenceCounts = (input.stageEvidence ?? []).flatMap((entry) => entry.accepted.counts);
+    const rows = [];
+    const filesTotal = Math.max(0, Math.trunc(input.sourceFileCount));
+    const hasAcceptedStageEvidence = (input.stageEvidence ?? []).length > 0;
+    const acceptedFilesProcessed = acceptedEvidenceCounts
+        .filter((count) => count.key === "files_processed")
+        .reduce((max, count) => Math.max(max, count.value), 0);
+    const filesObserved = buildRun
+        ? Math.min(hasAcceptedStageEvidence ? acceptedFilesProcessed : sourceFilesProcessed(stages), filesTotal)
+        : 0;
+    const filesState = issueState(filesObserved, filesTotal, { reviewWhenEmpty: true });
+    rows.push({
+        id: "files-processed",
+        assertion: "Source files processed",
+        metric: metric(filesObserved, filesTotal, filesTotal === 1 ? "file" : "files"),
+        evidence: {
+            kind: buildRun ? "stage-record" : "source-inventory",
+            label: buildRun ? "Build stage records" : "Source inventory",
+            ...(buildRun ? { run_id: buildRun.run_id, ref: `run:${buildRun.run_id}` } : { ref: "source-files" }),
+        },
+        ...rowStateIssue(filesState, `${filesTotal - filesObserved} Source file${filesTotal - filesObserved === 1 ? "" : "s"} lack accepted Build evidence.`),
+    });
+    const stageTotal = input.expectedStageCount ?? stages[0]?.stage_total ?? stages.length;
+    const stagesSucceeded = stages.filter((stage) => stage.status === "succeeded").length;
+    const stagesState = issueState(stagesSucceeded, stageTotal);
+    rows.push({
+        id: "stages-completed",
+        assertion: "Build Plan stages completed",
+        metric: metric(stagesSucceeded, stageTotal, stageTotal === 1 ? "stage" : "stages"),
+        evidence: {
+            kind: "stage-record",
+            label: "Build stage ledger",
+            ...(buildRun ? { run_id: buildRun.run_id, ref: `run:${buildRun.run_id}` } : { ref: "run:none" }),
+        },
+        ...rowStateIssue(stagesState, `${stageTotal - stagesSucceeded} stage${stageTotal - stagesSucceeded === 1 ? "" : "s"} did not complete.`),
+    });
+    const outputTotal = input.expectedOutputCount ?? Math.max(artifactStatuses.length, buildRun?.artifacts.length ?? 0);
+    const outputsReady = artifactStatuses.filter((artifact) => artifact.status === "ready").length;
+    const outputsState = issueState(outputsReady, outputTotal);
+    rows.push({
+        id: "outputs-ready",
+        assertion: "Build Plan outputs ready",
+        metric: metric(outputsReady, outputTotal, outputTotal === 1 ? "output" : "outputs"),
+        evidence: {
+            kind: "output",
+            label: "Accepted Build outputs",
+            ...(buildRun ? { run_id: buildRun.run_id, ref: `run:${buildRun.run_id}:artifacts` } : { ref: "outputs:none" }),
+        },
+        ...rowStateIssue(outputsState, `${outputTotal - outputsReady} output${outputTotal - outputsReady === 1 ? "" : "s"} are not ready.`),
+    });
+    const artifactCheckResults = requiredArtifactCheckResults(artifactStatuses);
+    const checkCounts = artifactCheckResults.length > 0
+        ? {
+            passed: artifactCheckResults.filter((result) => result.passed).length,
+            total: artifactCheckResults.length,
+        }
+        : stageCheckCounts(stages);
+    const checksState = issueState(checkCounts.passed, checkCounts.total, { reviewWhenEmpty: true });
+    rows.push({
+        id: "checks-passed",
+        assertion: "Build checks passed",
+        metric: metric(checkCounts.passed, checkCounts.total, checkCounts.total === 1 ? "check" : "checks"),
+        evidence: {
+            kind: artifactCheckResults.length > 0 ? "validator" : "stage-record",
+            label: artifactCheckResults.length > 0 ? "Runtime validators" : "Stage evidence records",
+            ...(buildRun ? { run_id: buildRun.run_id, ref: `run:${buildRun.run_id}:evidence` } : { ref: "checks:none" }),
+        },
+        ...rowStateIssue(checksState, `${checkCounts.total - checkCounts.passed} required check${checkCounts.total - checkCounts.passed === 1 ? "" : "s"} failed or are missing.`),
+    });
+    for (const count of acceptedEvidenceCounts.filter((entry) => entry.key !== "files_processed")) {
+        const countState = issueState(count.value, count.total);
+        rows.push({
+            id: `stage-evidence-${count.key.replaceAll("_", "-").replaceAll(".", "-").replaceAll(":", "-")}`,
+            assertion: count.label,
+            metric: metric(count.value, count.total, count.unit),
+            evidence: {
+                kind: "stage-evidence",
+                label: "Accepted stage evidence",
+                ...(count.stage_id ? { stage_id: count.stage_id } : {}),
+                ...(count.artifact_id ? { artifact_id: count.artifact_id } : {}),
+                ...(buildRun ? { run_id: buildRun.run_id, ref: `run:${buildRun.run_id}:stage-evidence` } : {}),
+            },
+            ...rowStateIssue(countState, `${count.label} is below the declared expectation.`),
+        });
+    }
+    const failed = buildRun?.status === "failed";
+    const hasBlockingRows = rowsHaveBlockingIssue(rows);
+    // Build evidence explains the runtime readiness verdict; it does not
+    // create a second readiness source of truth.
+    const ready = Boolean(input.readiness?.ready) && !failed;
+    const summary = failed
+        ? "Latest Build failed before the Context Graph was ready."
+        : ready
+            ? hasBlockingRows
+                ? "Ready by runtime readiness; review Build evidence rows for follow-up."
+                : "Ready for agent task."
+            : "Context Graph is not ready; review missing Build evidence.";
+    return BuildEvidenceResourceSchema.parse({
+        kind: "interf-build-evidence",
+        version: 1,
+        generated_at: generatedAt,
+        project_id: input.projectId,
+        build_run_id: buildRun?.run_id ?? null,
+        ready,
+        summary,
+        rows: failed
+            ? rows.map((row) => row.id === "stages-completed"
+                ? {
+                    ...row,
+                    issue_state: "fail",
+                    issue: buildRun?.stages.find((stage) => stage.status === "failed")?.failure ??
+                        "Latest Build failed.",
+                }
+                : row)
+            : rows,
+    });
+}

package/dist/packages/{engine → runtime}/build/build-pipeline.d.ts

@@ -18,15 +18,16 @@ export type StageShellRetentionMode = "on-failure" | "always";
 /**
  * Per-stage executor resolver. When provided, the pipeline calls this
  * for each stage and uses the returned executor instead of the
- * top-level `executor`. The top-level `executor` stays as the default
- * fallback so single-active-agent setups keep working without any
- * resolver wired up.
+ * top-level `executor`. If no resolver is provided, the top-level
+ * `executor` is the explicit single-agent execution path. Resolver
+ * failures are not swallowed: a broken role map must fail visibly
+ * instead of silently running a different agent.
  */
-export type ResolveStageExecutor = (stage: BuildStageExecutionDefinition) => AgentExecutor;
+export type ResolveStageExecutor = (stage: BuildStageExecutionDefinition) => AgentExecutor | null | undefined;
 export declare function runBuildSummarize(options: {
     executor: AgentExecutor;
     resolveStageExecutor?: ResolveStageExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     reporter?: BuildPlanReporter;
     reportSummary?: boolean;
     reportStep?: boolean;
@@ -34,23 +35,26 @@ export declare function runBuildSummarize(options: {
     fullPass?: boolean;
     runId?: string;
     events?: RunEventSink;
+    maxStageValidationAttempts?: number;
 }): Promise<BuildSummarizeResult>;
 export declare function runBuildStages(options: {
     executor: AgentExecutor;
     resolveStageExecutor?: ResolveStageExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     reporter?: BuildPlanReporter;
     reportStep?: boolean;
     preserveStageShells?: StageShellRetentionMode;
     runId?: string;
     events?: RunEventSink;
+    maxStageValidationAttempts?: number;
 }): Promise<BuildPlanStageResult>;
-export declare function buildVerifiableContext(options: {
+export declare function buildContextGraph(options: {
     executor: AgentExecutor;
     resolveStageExecutor?: ResolveStageExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     reporter?: BuildPlanReporter;
     preserveStageShells?: StageShellRetentionMode;
     runId?: string;
     events?: RunEventSink;
+    maxStageValidationAttempts?: number;
 }): Promise<BuildResult>;

package/dist/packages/runtime/build/build-pipeline.js

@@ -0,0 +1,304 @@
+import { refreshContextGraphBootstrapGuidance, } from "../agents/lib/context-graph-bootstrap.js";
+import { validateBuildPlanPackage } from "../../build-plans/package/local-build-plans.js";
+import { reportValidationFailure, } from "../../build-plans/package/build-plan-helpers.js";
+import { validateContextGraph, } from "./validate.js";
+import { pruneStageExecutionShells, } from "../agents/lib/shells.js";
+import { buildExecutionStages, resolveBuildContext, } from "./build-target.js";
+import { runBuildStage } from "./build-stage-runner.js";
+import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
+import { runSourceInventory } from "./source-inventory.js";
+import { stageReuseDecision } from "./stage-reuse.js";
+import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
+function pickStageExecutor(fallback, stage, resolve) {
+    if (!resolve)
+        return fallback;
+    const resolved = resolve(stage);
+    if (!resolved) {
+        throw new Error(`No executor resolved for Build Plan stage "${stage.id}" (role "${stage.role}").`);
+    }
+    return resolved;
+}
+function stageReadsSource(stage) {
+    if (stage.contractType === "build-file-evidence")
+        return true;
+    return stage.reads.includes("source");
+}
+function pickSourceInventoryExecutor(fallback, stages, resolve) {
+    const sourceReadingStage = stages.find(stageReadsSource) ?? stages[0];
+    if (!sourceReadingStage)
+        return fallback;
+    return pickStageExecutor(fallback, sourceReadingStage, resolve);
+}
+async function emitReusedStagePassed(options) {
+    if (!options.events || !options.runId)
+        return;
+    await options.events.emit({
+        type: "stage.started",
+        event_id: createRunEventId("event"),
+        run_id: options.runId,
+        timestamp: createRunEventTimestamp(),
+        stage_id: options.stageId,
+        ...(typeof options.stageIndex === "number" ? { stage_index: options.stageIndex } : {}),
+        ...(typeof options.stageTotal === "number" ? { stage_total: options.stageTotal } : {}),
+    });
+    await options.events.emit({
+        type: "stage.passed",
+        event_id: createRunEventId("event"),
+        run_id: options.runId,
+        timestamp: createRunEventTimestamp(),
+        stage_id: options.stageId,
+        summary: options.summary,
+    });
+}
+function reusedStageResult(summary = "reused (verified, unchanged)") {
+    return { ok: true, code: 0, summary };
+}
+export async function runBuildSummarize(options) {
+    const context = resolveBuildContext(options.contextGraphPath);
+    const stageDefinition = options.stageDefinition
+        ?? buildExecutionStages(context.buildPlanId, options.contextGraphPath).find((stage) => stage.id === "summarize");
+    if (!stageDefinition) {
+        return {
+            ok: false,
+            code: 1,
+            plan: { sourceCount: 0, summaryCount: 0, targetCount: 0 },
+            summary: "Build Plan does not declare a summarize stage.",
+        };
+    }
+    const sourceRuntime = await runSourceInventory({
+        executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
+        contextGraphPath: options.contextGraphPath,
+        project: context.contextGraphName,
+        sourceLocator: context.sourcePath,
+        buildPlanId: context.buildPlanId,
+        stageIds: [stageDefinition.id],
+        stages: [stageDefinition],
+        runId: options.runId ?? null,
+        events: options.events,
+        maxAttempts: options.maxStageValidationAttempts,
+    });
+    if (!sourceRuntime.ok || !sourceRuntime.manifest) {
+        return {
+            ok: false,
+            code: 1,
+            plan: { sourceCount: 0, summaryCount: 0, targetCount: 0 },
+            summary: sourceRuntime.summary,
+        };
+    }
+    const sourceCount = sourceRuntime.manifest.source_total;
+    const reuse = stageReuseDecision({
+        contextGraphPath: options.contextGraphPath,
+        stageDefinition,
+    });
+    if (reuse.reuse) {
+        await emitReusedStagePassed({
+            events: options.events,
+            runId: options.runId,
+            stageId: stageDefinition.id,
+            stageIndex: 0,
+            stageTotal: 1,
+            summary: reuse.summary,
+        });
+        return {
+            ...reusedStageResult(reuse.summary),
+            plan: {
+                sourceCount,
+                summaryCount: 0,
+                targetCount: sourceCount,
+            },
+        };
+    }
+    const result = await runBuildStage({
+        executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
+        contextGraphPath: options.contextGraphPath,
+        reporter: options.reporter,
+        reportStep: options.reportStep,
+        stageDefinition,
+        runId: options.runId,
+        events: options.events,
+        maxValidationAttempts: options.maxStageValidationAttempts,
+    });
+    return {
+        ...result,
+        plan: {
+            sourceCount,
+            summaryCount: 0,
+            targetCount: sourceCount,
+        },
+    };
+}
+export async function runBuildStages(options) {
+    const preserveMode = options.preserveStageShells ?? "on-failure";
+    if (preserveMode !== "always") {
+        pruneStageExecutionShells(options.contextGraphPath);
+    }
+    let lastResult = { ok: true, code: 0 };
+    try {
+        const context = resolveBuildContext(options.contextGraphPath);
+        const stages = buildExecutionStages(context.buildPlanId, options.contextGraphPath);
+        const sourceInventoryExecutor = pickSourceInventoryExecutor(options.executor, stages, options.resolveStageExecutor);
+        const sourceRuntime = await runSourceInventory({
+            executor: sourceInventoryExecutor,
+            contextGraphPath: options.contextGraphPath,
+            project: context.contextGraphName,
+            sourceLocator: context.sourcePath,
+            buildPlanId: context.buildPlanId,
+            stageIds: stages.map((stage) => stage.id),
+            stages,
+            runId: options.runId ?? null,
+            events: options.events,
+            maxAttempts: options.maxStageValidationAttempts,
+        });
+        if (!sourceRuntime.ok)
+            return sourceRuntime;
+        let forceRunFromHere = false;
+        for (const [index, stageDefinition] of stages.entries()) {
+            if (!forceRunFromHere) {
+                const reuse = stageReuseDecision({
+                    contextGraphPath: options.contextGraphPath,
+                    stageDefinition,
+                });
+                if (reuse.reuse) {
+                    await emitReusedStagePassed({
+                        events: options.events,
+                        runId: options.runId,
+                        stageId: stageDefinition.id,
+                        stageIndex: index,
+                        stageTotal: stages.length,
+                        summary: reuse.summary,
+                    });
+                    lastResult = reusedStageResult(reuse.summary);
+                    continue;
+                }
+            }
+            forceRunFromHere = true;
+            const result = await runBuildStage({
+                executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
+                contextGraphPath: options.contextGraphPath,
+                reporter: options.reporter,
+                reportStep: options.reportStep,
+                stageDefinition,
+                runId: options.runId,
+                events: options.events,
+                stageIndex: index,
+                stageTotal: stages.length,
+                maxValidationAttempts: options.maxStageValidationAttempts,
+            });
+            lastResult = result;
+            if (!result.ok)
+                return result;
+        }
+        return lastResult;
+    }
+    finally {
+        if (preserveMode !== "always" && lastResult.ok) {
+            pruneStageExecutionShells(options.contextGraphPath);
+        }
+    }
+}
+export async function buildContextGraph(options) {
+    const preserveMode = options.preserveStageShells ?? "on-failure";
+    if (preserveMode !== "always") {
+        pruneStageExecutionShells(options.contextGraphPath);
+    }
+    let result = {
+        ok: true,
+        stageResults: {},
+        failedStage: null,
+    };
+    try {
+        refreshContextGraphBootstrapGuidance(options.contextGraphPath);
+        const buildPlanValidation = validateBuildPlanPackage(buildPlanPackagePathForContextGraph(options.contextGraphPath));
+        if (!buildPlanValidation.ok) {
+            reportValidationFailure(options.reporter, buildPlanValidation.summary, buildPlanValidation.errors);
+            return {
+                ...result,
+                ok: false,
+                failedStage: "build-plan",
+                stageResults: {
+                    ...result.stageResults,
+                    "build-plan": {
+                        ok: false,
+                        code: 1,
+                        summary: buildPlanValidation.summary,
+                    },
+                },
+            };
+        }
+        const context = resolveBuildContext(options.contextGraphPath);
+        const stages = buildExecutionStages(context.buildPlanId, options.contextGraphPath);
+        const sourceInventoryExecutor = pickSourceInventoryExecutor(options.executor, stages, options.resolveStageExecutor);
+        const sourceRuntime = await runSourceInventory({
+            executor: sourceInventoryExecutor,
+            contextGraphPath: options.contextGraphPath,
+            project: context.contextGraphName,
+            sourceLocator: context.sourcePath,
+            buildPlanId: context.buildPlanId,
+            stageIds: stages.map((stage) => stage.id),
+            stages,
+            runId: options.runId ?? null,
+            events: options.events,
+            maxAttempts: options.maxStageValidationAttempts,
+        });
+        if (!sourceRuntime.ok) {
+            result.ok = false;
+            result.failedStage = "source-inventory";
+            result.stageResults["source-inventory"] = sourceRuntime;
+            return result;
+        }
+        let forceRunFromHere = false;
+        for (const [index, stageDefinition] of stages.entries()) {
+            if (!forceRunFromHere) {
+                const reuse = stageReuseDecision({
+                    contextGraphPath: options.contextGraphPath,
+                    stageDefinition,
+                });
+                if (reuse.reuse) {
+                    await emitReusedStagePassed({
+                        events: options.events,
+                        runId: options.runId,
+                        stageId: stageDefinition.id,
+                        stageIndex: index,
+                        stageTotal: stages.length,
+                        summary: reuse.summary,
+                    });
+                    result.stageResults[stageDefinition.id] = reusedStageResult(reuse.summary);
+                    continue;
+                }
+            }
+            forceRunFromHere = true;
+            const stageResult = await runBuildStage({
+                executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
+                contextGraphPath: options.contextGraphPath,
+                reporter: options.reporter,
+                reportStep: true,
+                stageDefinition,
+                runId: options.runId,
+                events: options.events,
+                stageIndex: index,
+                stageTotal: stages.length,
+                maxValidationAttempts: options.maxStageValidationAttempts,
+            });
+            result.stageResults[stageDefinition.id] = stageResult;
+            if (!stageResult.ok) {
+                result.ok = false;
+                result.failedStage = stageDefinition.id;
+                return result;
+            }
+        }
+        const buildPlanValidationResult = validateContextGraph(options.contextGraphPath);
+        result.ok = buildPlanValidationResult.ok;
+        result.failedStage = buildPlanValidationResult.ok ? null : buildPlanValidationResult.stage;
+        result.stageResults["context-graph"] = {
+            ok: buildPlanValidationResult.ok,
+            code: buildPlanValidationResult.ok ? 0 : 1,
+            summary: buildPlanValidationResult.summary,
+        };
+        return result;
+    }
+    finally {
+        if (preserveMode !== "always" && result.ok) {
+            pruneStageExecutionShells(options.contextGraphPath);
+        }
+    }
+}

package/dist/packages/{engine → runtime}/build/build-plan-primitives.d.ts

@@ -1,2 +1,2 @@
-export declare const BUILD_PLAN_ARTIFACT_KINDS: readonly ["directory", "file", "runtime"];
+export declare const BUILD_PLAN_ARTIFACT_KINDS: readonly ["directory", "file"];
 export type BuildPlanArtifactKind = typeof BUILD_PLAN_ARTIFACT_KINDS[number];

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

@@ -1,5 +1,4 @@
 export const BUILD_PLAN_ARTIFACT_KINDS = [
     "directory",
     "file",
-    "runtime",
 ];

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

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