@interf/compiler 0.22.2 → 0.50.0

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

@@ -0,0 +1,302 @@
+import { writeFileSync } from "node:fs";
+import { join, relative } 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 { persistStageReviewedInputsFromShell, writeStageExpectedInputs, writeStageManifestFromOutputs, } from "./stage-manifest.js";
+import { createNativeEntrypointExecutor, } from "./native-entrypoint.js";
+import { executeValidatedStage, } from "../../build-plans/package/build-plan-stage-runner.js";
+import { loadExecutionStageLedger, } from "./runtime.js";
+import { markStageExecutionSessionsShellPreserved, recordStageExecutionSessionValidationAttempt, } from "./stage-session.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 stageOutputValidationForActiveRun(validation, stageId) {
+    if (validation.ok)
+        return validation;
+    const terminalStateErrors = new Set([
+        `Stage "${stageId}" has no finished_at evidence in runtime state.`,
+        `Stage "${stageId}" is not marked succeeded in runtime state.`,
+    ]);
+    const activeOutputErrors = validation.errors.filter((error) => !terminalStateErrors.has(error));
+    if (activeOutputErrors.length > 0) {
+        return {
+            ...validation,
+            errors: activeOutputErrors,
+            summary: `Stage "${stageId}" failed — ${activeOutputErrors[0]}`,
+        };
+    }
+    return {
+        ...validation,
+        ok: true,
+        errors: [],
+        summary: `Stage "${stageId}" output checks passed.`,
+    };
+}
+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}`,
+        "This is a fresh retry shell. Read `runtime/retry-feedback.md`, use previous shells as read-only logs, fix the exact validation failure, then rerun `node runtime/check-stage.mjs` until it prints `VALID:`.",
+    ];
+}
+function contextGraphRelativePath(contextGraphPath, path) {
+    return relative(contextGraphPath, path).replaceAll("\\", "/");
+}
+function writeStageRetryFeedback(options) {
+    if (options.attempts.length === 0)
+        return;
+    writeFileSync(join(options.shellRoot, "runtime", "previous-attempts.json"), `${JSON.stringify({
+        kind: "interf-stage-previous-attempts",
+        version: 1,
+        stage_id: options.stageId,
+        attempts: options.attempts,
+    }, null, 2)}\n`);
+    writeFileSync(join(options.shellRoot, "runtime", "retry-feedback.md"), [
+        "# Retry Feedback",
+        "",
+        "This shell is a fresh retry for the current stage.",
+        "Previous attempt shells are preserved as read-only context. Do not mutate them.",
+        "Use their prompts, logs, outputs, and validation failures to repair this attempt.",
+        "",
+        "## Previous Attempts",
+        "",
+        ...options.attempts.flatMap((attempt) => [
+            `### Attempt ${attempt.attempt}`,
+            "",
+            `- stage_run_id: ${attempt.stage_run_id ?? "unknown"}`,
+            `- shell: ${attempt.context_graph_relative_shell_path}`,
+            `- status: ${attempt.status}`,
+            `- validation: ${attempt.summary}`,
+            "",
+        ]),
+        "## Required Action",
+        "",
+        "Write the declared outputs in this shell, record `runtime/reviewed-inputs.json`, and run `node runtime/check-stage.mjs` until it reports `VALID:`.",
+        "",
+    ].join("\n"));
+}
+export async function runBuildStage(options) {
+    const stageDefinition = options.stageDefinition;
+    const plan = buildBuildStageExecutionPlan(options.contextGraphPath, stageDefinition);
+    writeStageExpectedInputs({
+        contextGraphPath: options.contextGraphPath,
+        stage: stageDefinition,
+    });
+    if (options.reportStep !== false) {
+        reportBlankLine(options.reporter);
+        reportLine(options.reporter, `${formatActiveBuildPlanStageLabel(options.contextGraphPath, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
+    }
+    const executor = stageDefinition.contractType === "build-entrypoint"
+        ? createNativeEntrypointExecutor()
+        : options.executor;
+    const stageEvidenceHarness = supportsStageEvidenceHarness(stageDefinition);
+    const maxValidationAttempts = boundedStageValidationAttempts(options.maxValidationAttempts);
+    const validateStageOutputsAndEvidence = (shellRoot) => {
+        const shellInputValidation = validateStageExecutionShellInputs({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot,
+            stage: stageDefinition,
+        });
+        if (!shellInputValidation.ok)
+            return shellInputValidation;
+        const outputValidation = stageOutputValidationForActiveRun(validateBuildStage(options.contextGraphPath, stageDefinition.id), stageDefinition.id);
+        if (!outputValidation.ok)
+            return outputValidation;
+        if (stageEvidenceHarness) {
+            const reconciliation = reconcileStageEvidence({
+                contextGraphPath: options.contextGraphPath,
+                shellRoot,
+                stage: stageDefinition,
+            });
+            const evidenceFailure = stageEvidenceAcceptanceFailure(reconciliation);
+            if (evidenceFailure) {
+                return { ok: false, summary: evidenceFailure };
+            }
+        }
+        const reviewedInputs = persistStageReviewedInputsFromShell({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot,
+            stageId: stageDefinition.id,
+        });
+        if (!reviewedInputs.ok) {
+            return {
+                ok: false,
+                summary: `${outputValidation.summary} ${reviewedInputs.summary}`,
+            };
+        }
+        try {
+            const manifest = writeStageManifestFromOutputs({
+                contextGraphPath: options.contextGraphPath,
+                buildPlanId: plan.context.buildPlanId,
+                projectId: plan.context.contextGraphName,
+                runId: options.runId ?? null,
+                stage: stageDefinition,
+            });
+            if (!manifest) {
+                return { ok: false, summary: `Could not write StageManifest for ${stageDefinition.id}.` };
+            }
+            return {
+                ...outputValidation,
+                summary: `${outputValidation.summary} ${reviewedInputs.summary} StageManifest recorded ${manifest.produced.length} produced resource${manifest.produced.length === 1 ? "" : "s"}.`,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                summary: `Could not write StageManifest for ${stageDefinition.id}: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    };
+    let lastResult = { ok: false, code: 1 };
+    let lastFailureSummary = null;
+    const previousAttempts = [];
+    for (let attempt = 1; attempt <= maxValidationAttempts; attempt += 1) {
+        const shell = createStageExecutionShell(options.contextGraphPath, plan.context.contextGraphName, plan.context.buildPlanId, stageDefinition, plan.contract.artifacts.writes);
+        writeStageRetryFeedback({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot: shell.rootPath,
+            stageId: stageDefinition.id,
+            attempts: previousAttempts,
+        });
+        try {
+            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,
+                contextGraphPath: options.contextGraphPath,
+                executionPath: shell.rootPath,
+                targetName: plan.context.contextGraphName,
+                buildPlan: plan.context.buildPlanId,
+                buildPlanSourcePath: options.contextGraphPath,
+                buildRunId: options.runId ?? null,
+                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.",
+                        ]
+                        : []),
+                    "Read `runtime/expected-inputs.json` before writing outputs.",
+                    "Write `runtime/reviewed-inputs.json` with one decision per required expected input before DONE.",
+                    ...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 requested outputs.",
+                    `Emit DONE: ${stageDefinition.id} complete when the declared outputs, coverage review, and evidence are on disk.`,
+                ],
+                reporter: options.reporter,
+                completionCheck: () => validateStageOutputsAndEvidence(shell.rootPath).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(shell.rootPath),
+            });
+            lastResult = result;
+            const stageRun = loadExecutionStageLedger(options.contextGraphPath);
+            const stageRunId = stageRun?.stage === stageDefinition.id ? stageRun.run_id : null;
+            if (stageRun?.stage === stageDefinition.id) {
+                recordStageExecutionSessionValidationAttempt({
+                    contextGraphPath: options.contextGraphPath,
+                    stageId: stageDefinition.id,
+                    stageRunId: stageRun.run_id,
+                    attempt,
+                    status: result.ok ? "succeeded" : "failed",
+                    summary: result.summary ?? `${stageDefinition.label} ${result.ok ? "passed" : "failed"}.`,
+                });
+            }
+            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`);
+            previousAttempts.push({
+                attempt,
+                stage_run_id: stageRunId,
+                shell_path: shell.rootPath,
+                context_graph_relative_shell_path: contextGraphRelativePath(options.contextGraphPath, shell.rootPath),
+                status: "failed",
+                summary: lastFailureSummary,
+            });
+            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}).`,
+                });
+            }
+        }
+        finally {
+            freezeStageExecutionShell(shell.rootPath);
+            markStageExecutionSessionsShellPreserved({
+                contextGraphPath: options.contextGraphPath,
+                shellRoot: shell.rootPath,
+            });
+        }
+    }
+    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;
+}

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

@@ -1,11 +1,14 @@
 import { type BuildPlanStageDefinition } from "../../build-plans/package/build-plan-definitions.js";
 import { type ResolvedBuildPlanId } from "../../build-plans/package/build-plan-definitions.js";
+import type { RuntimeProjectContext } from "./lib/schema.js";
 export interface BuildStageExecutionDefinition extends BuildPlanStageDefinition {
 }
-export declare function resolveBuildContext(verifiableContextPath: string): {
-    verifiableContextName: string;
+export declare function resolveBuildContext(contextGraphPath: string): {
+    contextGraphName: string;
+    project: RuntimeProjectContext;
+    projectIntent: string | null;
     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,40 @@
+import { getActiveBuildPlan, resolveRequiredBuildPlanFromConfig, } from "../../build-plans/package/build-plan-definitions.js";
+import { readInterfConfig, resolveSourceFolderPath, resolveSourceControlPath, } from "../../projects/interf-detect.js";
+function normalizedIntent(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function readPersistedProjectIntent(contextGraphPath, config) {
+    const parsedIntent = normalizedIntent(config?.intent);
+    if (parsedIntent)
+        return parsedIntent;
+    try {
+        return normalizedIntent(getActiveBuildPlan(contextGraphPath).brief?.intent);
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveBuildContext(contextGraphPath) {
+    const config = readInterfConfig(contextGraphPath);
+    const buildPlanId = resolveRequiredBuildPlanFromConfig(config, `.interf/interf.json for ${contextGraphPath}`);
+    const contextGraphName = config?.name ?? "context-graph";
+    const projectIntent = readPersistedProjectIntent(contextGraphPath, config);
+    return {
+        contextGraphName,
+        project: {
+            id: contextGraphName,
+            intent: projectIntent,
+        },
+        projectIntent,
+        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 deterministic output check evaluates against. For checks
+     * 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