@interf/compiler 0.22.0 → 0.33.0

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

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

package/dist/packages/runtime/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(contextGraphPath: string, stageDefinition: Pick<BuildPlanStageDefinition, "id" | "reads" | "writes">): {
+    reads: string[];
+    writes: string[];
+    writeContracts: RuntimeStageContractDraft["artifacts"]["write_contracts"];
+};
+export declare function buildStageCounts(contextGraphPath: string, stageDefinition: BuildPlanStageDefinition): Record<string, number>;
+export declare function buildStageContract(contextGraphPath: string, stageDefinition: BuildPlanStageDefinition, instructions: RuntimeStageInstructions): RuntimeStageContractDraft;
+export declare function buildBuildStageExecutionPlan(contextGraphPath: string, stageDefinition: BuildStageExecutionDefinition): {
+    context: ReturnType<typeof resolveBuildContext>;
+    contract: RuntimeStageContractDraft;
+    instructions: RuntimeStageInstructions;
+};

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

@@ -1,15 +1,15 @@
 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 { contextGraphArtifactPath, contextGraphArtifactPathsForArtifactIds, findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./context-graph-schema.js";
 import { buildLocalSkillContractExtension, buildStageInstructions, buildPlanStageDirectory, } from "../../build-plans/package/build-plan-helpers.js";
+import { loadContextGraphSourceManifest } from "./source-manifest.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 { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
+import { readInterfConfig } from "../../projects/interf-detect.js";
 import { resolveBuildContext, } from "./build-target.js";
-function artifactCount(verifiableContextPath, artifactPath, kind) {
-    const absolutePath = join(verifiableContextPath, artifactPath);
+function artifactCount(contextGraphPath, artifactPath, kind) {
+    const absolutePath = join(contextGraphPath, artifactPath);
     try {
         if (kind === "file") {
             return listFilesRecursive(absolutePath).length > 0 ? 1 : 0;
@@ -21,21 +21,21 @@ function artifactCount(verifiableContextPath, artifactPath, kind) {
     }
     return listFilesRecursive(absolutePath).length;
 }
-export function resolveStageContractArtifacts(verifiableContextPath, stageDefinition) {
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(verifiableContextPath));
+export function resolveStageContractArtifacts(contextGraphPath, stageDefinition) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
     if (!schema) {
-        throw new Error(`Missing Build Plan schema for stage "${stageDefinition.id}" at ${buildPlanPackagePathForVerifiableContext(verifiableContextPath)}.`);
+        throw new Error(`Missing Build Plan schema for stage "${stageDefinition.id}" at ${buildPlanPackagePathForContextGraph(contextGraphPath)}.`);
     }
     return {
-        reads: verifiableContextArtifactPathsForArtifactIds(schema, stageDefinition.reads),
-        writes: verifiableContextArtifactPathsForArtifactIds(schema, stageDefinition.writes),
+        reads: contextGraphArtifactPathsForArtifactIds(schema, stageDefinition.reads),
+        writes: contextGraphArtifactPathsForArtifactIds(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({
+                ? contextGraphArtifactPath({
                     path: artifact.shape.path,
                     kind: artifact.shape.artifact_kind,
                 })
@@ -48,17 +48,16 @@ export function resolveStageContractArtifacts(verifiableContextPath, stageDefini
         }),
     };
 }
-export function buildStageCounts(verifiableContextPath, stageDefinition) {
-    const context = resolveBuildContext(verifiableContextPath);
-    const sourceTotal = discoverSourceFiles(context.sourcePath, verifiableContextPath).totalCount;
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(verifiableContextPath));
+export function buildStageCounts(contextGraphPath, stageDefinition) {
+    const sourceTotal = loadContextGraphSourceManifest(contextGraphPath)?.source_total ?? 0;
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
     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);
+            artifactCounts[artifactId] = artifactCount(contextGraphPath, artifact.path, artifact.kind);
         }
     }
     return {
@@ -68,33 +67,33 @@ export function buildStageCounts(verifiableContextPath, stageDefinition) {
         ...artifactCounts,
     };
 }
-export function buildStageContract(verifiableContextPath, stageDefinition, instructions) {
-    const config = readInterfConfig(verifiableContextPath);
-    const stageArtifacts = resolveStageContractArtifacts(verifiableContextPath, stageDefinition);
+export function buildStageContract(contextGraphPath, stageDefinition, instructions) {
+    const config = readInterfConfig(contextGraphPath);
+    const stageArtifacts = resolveStageContractArtifacts(contextGraphPath, stageDefinition);
     return buildRuntimeStageContract({
-        verifiableContextName: config?.name ?? "verifiable-context",
+        contextGraphName: config?.name ?? "context-graph",
         stageId: stageDefinition.id,
         stageLabel: stageDefinition.label,
-        counts: buildStageCounts(verifiableContextPath, stageDefinition),
+        counts: buildStageCounts(contextGraphPath, stageDefinition),
         extraReadArtifacts: [
-            ".interf/runtime/source-snapshot.json",
-            `.interf/runtime/stages/${stageDefinition.id}/inputs.json`,
+            "runtime/source-manifest.json",
+            "runtime/stage-inputs.json",
         ],
         stageReadArtifacts: stageArtifacts.reads,
         stageWriteArtifacts: stageArtifacts.writes,
         stageWriteContracts: stageArtifacts.writeContracts,
-        buildPlanNotes: getActiveBuildPlanStagePolicyNotes(verifiableContextPath, stageDefinition.id),
+        buildPlanNotes: getActiveBuildPlanStagePolicyNotes(contextGraphPath, 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.");
+export function buildBuildStageExecutionPlan(contextGraphPath, stageDefinition) {
+    const context = resolveBuildContext(contextGraphPath);
+    const localSkills = buildLocalSkillContractExtension(contextGraphPath, [buildPlanStageDirectory(stageDefinition.skillDir)], "Use them to refine this Build Plan stage while still honoring the declared reads, writes, and evidence rules.");
     const instructions = buildStageInstructions(stageDefinition.skillDir, localSkills);
     return {
         context,
         instructions,
-        contract: buildStageContract(verifiableContextPath, stageDefinition, instructions),
+        contract: buildStageContract(contextGraphPath, stageDefinition, instructions),
     };
 }

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

@@ -4,7 +4,7 @@ import { type BuildStageExecutionDefinition } from "./build-target.js";
 import { type RunEventSink } from "../execution/events.js";
 export declare function runBuildStage(options: {
     executor: AgentExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     reporter?: BuildPlanReporter;
     reportStep?: boolean;
     stageDefinition: BuildStageExecutionDefinition;
@@ -12,4 +12,5 @@ export declare function runBuildStage(options: {
     events?: RunEventSink;
     stageIndex?: number;
     stageTotal?: number;
+    maxValidationAttempts?: number;
 }): Promise<BuildPlanStageResult>;

package/dist/packages/runtime/build/build-stage-runner.js

@@ -0,0 +1,165 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createStageExecutionShell, freezeStageExecutionShell, syncStageExecutionShellWrites, validateStageExecutionShellInputs, } from "../agents/lib/shells.js";
+import { reconcileBuildStageRun } from "./runtime-reconcile.js";
+import { refreshContextGraphArtifacts } from "./state.js";
+import { validateBuildStage } from "./validate.js";
+import { reconcileStageEvidence, stageEvidenceAcceptanceFailure, supportsStageEvidenceHarness, } from "./stage-evidence.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);
+}
+function boundedStageValidationAttempts(value) {
+    if (value === undefined)
+        return 2;
+    if (!Number.isFinite(value))
+        return 2;
+    return Math.max(1, Math.min(5, Math.trunc(value)));
+}
+function stageValidationRetryStatusLines(options) {
+    if (!options.lastFailureSummary || options.attempt <= 1)
+        return [];
+    return [
+        `Previous service validation for this stage failed on attempt ${options.attempt - 1}/${options.maxValidationAttempts}: ${options.lastFailureSummary}`,
+        "Inspect the existing outputs in this same shell, fix the exact validation failure, then rerun `node runtime/check-stage.mjs` until it prints `VALID:`.",
+    ];
+}
+export async function runBuildStage(options) {
+    const stageDefinition = options.stageDefinition;
+    const plan = buildBuildStageExecutionPlan(options.contextGraphPath, stageDefinition);
+    if (options.reportStep !== false) {
+        reportBlankLine(options.reporter);
+        reportLine(options.reporter, `${formatActiveBuildPlanStageLabel(options.contextGraphPath, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
+    }
+    const shell = createStageExecutionShell(options.contextGraphPath, plan.context.contextGraphName, plan.context.buildPlanId, stageDefinition, plan.contract.artifacts.writes);
+    const stageEvidenceHarness = supportsStageEvidenceHarness(stageDefinition);
+    const maxValidationAttempts = boundedStageValidationAttempts(options.maxValidationAttempts);
+    const validateStageOutputsAndEvidence = () => {
+        const shellInputValidation = validateStageExecutionShellInputs({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot: shell.rootPath,
+            stage: stageDefinition,
+        });
+        if (!shellInputValidation.ok)
+            return shellInputValidation;
+        const outputValidation = validateBuildStage(options.contextGraphPath, stageDefinition.id);
+        if (!outputValidation.ok || !stageEvidenceHarness)
+            return outputValidation;
+        const reconciliation = reconcileStageEvidence({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot: shell.rootPath,
+            stage: stageDefinition,
+        });
+        const evidenceFailure = stageEvidenceAcceptanceFailure(reconciliation);
+        if (evidenceFailure) {
+            return { ok: false, summary: evidenceFailure };
+        }
+        return outputValidation;
+    };
+    let lastResult = { ok: false, code: 1 };
+    let lastFailureSummary = null;
+    try {
+        for (let attempt = 1; attempt <= maxValidationAttempts; attempt += 1) {
+            if (options.runId && options.events) {
+                await emitRunEvent(options.events, {
+                    type: "stage.started",
+                    event_id: createRunEventId("event"),
+                    run_id: options.runId,
+                    timestamp: createRunEventTimestamp(),
+                    stage_id: stageDefinition.id,
+                    ...(typeof options.stageIndex === "number" ? { stage_index: options.stageIndex } : {}),
+                    ...(typeof options.stageTotal === "number" ? { stage_total: options.stageTotal } : {}),
+                });
+            }
+            const result = await executeValidatedStage({
+                executor: options.executor,
+                contextGraphPath: options.contextGraphPath,
+                executionPath: shell.rootPath,
+                targetName: plan.context.contextGraphName,
+                buildPlan: plan.context.buildPlanId,
+                buildPlanSourcePath: options.contextGraphPath,
+                stageDefinition,
+                instructions: plan.instructions,
+                summary: `Executing ${stageDefinition.label.toLowerCase()}.`,
+                contract: plan.contract,
+                statusLines: [
+                    `Emit exactly one startup line: STATUS: loaded ${stageDefinition.label.toLowerCase()} stage.`,
+                    ...(stageEvidenceHarness
+                        ? [
+                            "Read `runtime/stage.md` after the JSON contract.",
+                            "Write `runtime/stage-evidence.json` with source/output refs before DONE; status text alone is not accepted evidence.",
+                        ]
+                        : []),
+                    ...stageValidationRetryStatusLines({ attempt, maxValidationAttempts, lastFailureSummary }),
+                    "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 built Artifacts.",
+                    `Emit DONE: ${stageDefinition.id} complete when the declared outputs and evidence are on disk.`,
+                ],
+                reporter: options.reporter,
+                completionCheck: () => validateStageOutputsAndEvidence().ok,
+                onStatus: options.runId && options.events
+                    ? (line) => {
+                        void options.events?.emit({
+                            type: "log.appended",
+                            event_id: createRunEventId("event"),
+                            run_id: options.runId,
+                            timestamp: createRunEventTimestamp(),
+                            stage_id: stageDefinition.id,
+                            stream: "status",
+                            message: line,
+                        });
+                    }
+                    : undefined,
+                syncWrites: () => syncStageExecutionShellWrites(options.contextGraphPath, shell.rootPath, stageDefinition, plan.contract.artifacts.writes),
+                reconcile: () => reconcileBuildStageRun(options.contextGraphPath, stageDefinition),
+                refreshArtifacts: () => refreshContextGraphArtifacts(options.contextGraphPath, { ensureViewSpec: true }),
+                validate: validateStageOutputsAndEvidence,
+            });
+            lastResult = result;
+            if (result.ok) {
+                if (options.runId && options.events) {
+                    await emitRunEvent(options.events, {
+                        type: "stage.passed",
+                        event_id: createRunEventId("event"),
+                        run_id: options.runId,
+                        timestamp: createRunEventTimestamp(),
+                        stage_id: stageDefinition.id,
+                        summary: result.summary ?? `${stageDefinition.label} completed.`,
+                    });
+                }
+                return result;
+            }
+            lastFailureSummary = result.summary ?? `${stageDefinition.label} failed with code ${result.code}.`;
+            writeFileSync(join(shell.rootPath, "runtime", "last-validation-failure.txt"), `${lastFailureSummary}\n`);
+            if (attempt < maxValidationAttempts && options.runId && options.events) {
+                await emitRunEvent(options.events, {
+                    type: "log.appended",
+                    event_id: createRunEventId("event"),
+                    run_id: options.runId,
+                    timestamp: createRunEventTimestamp(),
+                    stage_id: stageDefinition.id,
+                    stream: "system",
+                    message: `Retrying ${stageDefinition.id} after service validation failed (${attempt}/${maxValidationAttempts}).`,
+                });
+            }
+        }
+        if (options.runId && options.events) {
+            await emitRunEvent(options.events, {
+                type: "stage.failed",
+                event_id: createRunEventId("event"),
+                run_id: options.runId,
+                timestamp: createRunEventTimestamp(),
+                stage_id: stageDefinition.id,
+                error: lastResult.summary ?? `${stageDefinition.label} failed.`,
+            });
+        }
+        return lastResult;
+    }
+    finally {
+        freezeStageExecutionShell(shell.rootPath);
+    }
+}

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

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

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

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

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

@@ -1,24 +1,22 @@
-import { type Check, type CheckKind, type Proof } from "../../contracts/lib/schema.js";
+import { type Check, type CheckKind, type CheckResult } from "../../contracts/lib/schema.js";
 /**
- * 0.17 — Check evaluator for the locked verification vocabulary.
+ * Check evaluator for the locked verification vocabulary.
  *
  * One evaluator per `CheckKind` from `CHECK_KINDS`. The evaluator is
  * scope-agnostic: it takes a Check, a target path, and optional
- * runtime context (counts, source-file totals); it returns a Proof.
+ * runtime context (counts, source-file totals); it returns a CheckResult.
  *
  * The same evaluator serves stage-level checks, artifact-level checks,
  * and (for `qa_match`) user-level checks. Build Plans and user-defined
  * verification declare `Check[]`; the runtime invokes this evaluator
- * to produce `Proof[]`.
+ * to produce `CheckResult[]`.
  *
- * This evaluator is the source of truth for declared verification
- * checks. Legacy stage-acceptance rules were retired after the
- * artifact-first migration.
+ * This evaluator is the source of truth for declared verification checks.
  */
 export interface CheckEvaluationContext {
     /**
-     * Filesystem root the check evaluates against. For artifact checks
-     * this is the verifiable-context root; the artifact's path is
+     * Filesystem root the Artifact diagnostic evaluates against. For Artifact diagnostics
+     * this is the context-graph 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.
      */
@@ -43,21 +41,21 @@ export interface CheckEvaluationContext {
      */
     agentAnswer?: string;
 }
-export type CheckEvaluator = (check: Check, context: CheckEvaluationContext) => Proof;
+export type CheckEvaluator = (check: Check, context: CheckEvaluationContext) => CheckResult;
 /**
- * Evaluate a single Check against a context, returning a Proof.
+ * Evaluate a single Check against a context, returning a CheckResult.
  */
-export declare function evaluateCheck(check: Check, context: CheckEvaluationContext): Proof;
+export declare function evaluateCheck(check: Check, context: CheckEvaluationContext): CheckResult;
 /**
  * Evaluate a list of checks. Aggregate ready/not_ready verdict over
- * the proofs: `ready` if every required check passed, otherwise
+ * the check_results: `ready` if every required check passed, otherwise
  * `not_ready`. Soft checks (required: false) that fail produce a
- * proof but don't change the verdict.
+ * check result but don't change the verdict.
  */
 export declare function evaluateChecks(checks: readonly Check[], context: CheckEvaluationContext): {
-    proofs: Proof[];
+    check_results: CheckResult[];
     ready: boolean;
-    failures: Proof[];
+    failures: CheckResult[];
 };
 /**
  * Type guard for the canonical CheckKinds. Useful at parse boundaries