@interf/compiler 0.6.1 → 0.6.3

package/dist/packages/compiler/runtime-contracts.js

@@ -0,0 +1,48 @@
+import { WORKFLOW_SCHEMA_FILE } from "./compiled-schema.js";
+export function buildRuntimeStageContract(options) {
+    const localSkillDocs = options.localSkillDocs ?? [];
+    const workflowNotes = options.workflowNotes ?? [];
+    return {
+        instructions: options.instructions,
+        counts: {
+            ...(options.counts ?? {}),
+            local_skill_docs: localSkillDocs.length,
+        },
+        ...(options.acceptance ? { acceptance: options.acceptance } : {}),
+        artifacts: {
+            reads: [
+                "interf.json",
+                `workflow/${WORKFLOW_SCHEMA_FILE}`,
+                ...(options.extraReadArtifacts ?? []),
+                ...options.stageReadArtifacts,
+                ...localSkillDocs,
+            ],
+            writes: options.stageWriteArtifacts,
+            verifies: [
+                `interf verify stage ${options.stageId} --json`,
+            ],
+        },
+        policies: {
+            execution_mode: "deterministic",
+            status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
+            notes: [
+                `This is the "${options.stageLabel}" stage for the compiled context "${options.compiledName}".`,
+                "The workflow package is the authoritative method layer for this run.",
+                `Use \`workflow/${WORKFLOW_SCHEMA_FILE}\` as the deterministic zone-contract reference for this compiled context.`,
+                "Honor the declared read and write artifacts instead of inventing a parallel workflow.",
+                "Only create or update files that fall under the declared write targets for this stage.",
+                "Interf writes `.interf/runtime/` ledgers such as run, state, health, and view-spec files. Read them if needed, but do not create, edit, or replace them in this stage unless the contract explicitly marks a runtime artifact as stage-owned.",
+                "Keep scratch extraction commands single-purpose and non-destructive. Avoid wildcard cleanup and multi-command chains.",
+                ...workflowNotes,
+                ...(localSkillDocs.length > 0
+                    ? [
+                        "Read any local instruction docs listed in the contract before you write artifacts or declare the stage complete.",
+                        options.instructions.effective_mode === "override"
+                            ? "Local stage docs replace the default workflow guidance for this run, but they still do not bypass required writes, declared proof artifacts, or deterministic runtime reconciliation."
+                            : "Local stage docs can refine the stage behavior, but they do not bypass required writes, declared proof artifacts, or deterministic runtime reconciliation.",
+                    ]
+                    : []),
+            ],
+        },
+    };
+}

package/dist/packages/compiler/runtime-inventory.d.ts

@@ -0,0 +1,7 @@
+import { type CompiledInventory, type CompiledInventoryEntry } from "./lib/schema.js";
+export declare function emptyCompiledInventory(): CompiledInventory;
+export declare function compiledInventoryFromEntries(entries: CompiledInventoryEntry[], stage?: string): CompiledInventory;
+export declare function compiledInventoryEntryCount(inventory: CompiledInventory | null): number;
+export declare function compiledInventoryTotal(inventory: CompiledInventory | null): number;
+export declare function compiledInventoryFrontmatterScannedCount(inventory: CompiledInventory | null): number;
+export declare function compiledInventoryAbstractCoverageCount(inventory: CompiledInventory | null): number;

package/dist/packages/compiler/runtime-inventory.js

@@ -0,0 +1,29 @@
+export function emptyCompiledInventory() {
+    return {
+        kind: "compiled-runtime-ledger",
+        version: 1,
+        entries: [],
+        total: 0,
+    };
+}
+export function compiledInventoryFromEntries(entries, stage) {
+    return {
+        kind: "compiled-runtime-ledger",
+        version: 1,
+        ...(stage ? { stage } : {}),
+        entries,
+        total: entries.length,
+    };
+}
+export function compiledInventoryEntryCount(inventory) {
+    return inventory?.entries.length ?? 0;
+}
+export function compiledInventoryTotal(inventory) {
+    return inventory?.total ?? 0;
+}
+export function compiledInventoryFrontmatterScannedCount(inventory) {
+    return (inventory?.entries ?? []).filter((entry) => entry.metadata?.frontmatter_scanned === true).length;
+}
+export function compiledInventoryAbstractCoverageCount(inventory) {
+    return (inventory?.entries ?? []).filter((entry) => entry.metadata?.abstract_read === true || typeof entry.metadata?.abstract === "string").length;
+}

package/dist/packages/compiler/runtime-paths.d.ts

@@ -0,0 +1,8 @@
+export declare function runPath(dirPath: string): string;
+export declare function runHistoryPath(dirPath: string): string;
+export declare function stageContractPath(dirPath: string): string;
+export declare function archivedStageContractPath(dirPath: string, runId: string): string;
+export declare function logsDirPath(dirPath: string): string;
+export declare function promptLogPath(dirPath: string, runId: string): string;
+export declare function eventLogPath(dirPath: string, runId: string): string;
+export declare function statusLogPath(dirPath: string, runId: string): string;

package/dist/packages/compiler/runtime-paths.js

@@ -0,0 +1,26 @@
+import { join } from "node:path";
+import { compiledRuntimeArchivedStageContractPath, compiledRuntimeLogsRoot, compiledRuntimeRunHistoryPath, compiledRuntimeRunPath, compiledRuntimeStageContractPath, } from "../project-model/compiled-paths.js";
+export function runPath(dirPath) {
+    return compiledRuntimeRunPath(dirPath);
+}
+export function runHistoryPath(dirPath) {
+    return compiledRuntimeRunHistoryPath(dirPath);
+}
+export function stageContractPath(dirPath) {
+    return compiledRuntimeStageContractPath(dirPath);
+}
+export function archivedStageContractPath(dirPath, runId) {
+    return compiledRuntimeArchivedStageContractPath(dirPath, runId);
+}
+export function logsDirPath(dirPath) {
+    return compiledRuntimeLogsRoot(dirPath);
+}
+export function promptLogPath(dirPath, runId) {
+    return join(logsDirPath(dirPath), `${runId}.prompt.txt`);
+}
+export function eventLogPath(dirPath, runId) {
+    return join(logsDirPath(dirPath), `${runId}.events.ndjson`);
+}
+export function statusLogPath(dirPath, runId) {
+    return join(logsDirPath(dirPath), `${runId}.status.log`);
+}

package/dist/packages/compiler/runtime-prompt.d.ts

@@ -0,0 +1,2 @@
+import { type RuntimeStageInstructions } from "./lib/schema.js";
+export declare function buildStagePrompt(instructions: RuntimeStageInstructions, contractPath: string, statusLines: string[]): string;

package/dist/packages/compiler/runtime-prompt.js

@@ -0,0 +1,48 @@
+export function buildStagePrompt(instructions, contractPath, statusLines) {
+    const stageSkillDir = instructions.stage_skill_dir || "stage";
+    const modeNotes = instructions.effective_mode === "override"
+        ? [
+            "Local stage instruction docs are authoritative for this run.",
+            "Do not fall back to bundled workflow heuristics unless the stage contract explicitly leaves room for them.",
+            "Interf still enforces the same required reads, writes, verifier outputs, and runtime reconciliation at stage close.",
+        ]
+        : instructions.effective_mode === "extend"
+            ? [
+                "Use the current compiled workflow docs as the default workflow for this run.",
+                "Then apply any additional local stage instruction docs referenced by the contract as stage-specific extensions.",
+            ]
+            : [
+                "Use the current compiled workflow docs as the default workflow for this run.",
+            ];
+    return [
+        `Interf workflow stage docs: workflow/compile/stages/${stageSkillDir}/`,
+        "",
+        "This is an automated Interf stage run, not an open-ended chat session.",
+        "The user has already invoked this stage through the Interf CLI. Execute it now.",
+        "Do not ask what the user wants, offer help, list tools, or wait for another instruction.",
+        `Read \`${contractPath}\` first. It is the authoritative contract for this stage.`,
+        "If `runtime/paths.json` exists in this shell, read it next. It maps workflow zone ids onto the shell-local `inputs/` and `outputs/` mounts for this stage.",
+        "For file-zone mounts, `runtime/paths.json` also gives the exact file path inside the `inputs/` or `outputs/` mount root.",
+        "Honor the contract's counts, artifact paths, and policies instead of inventing another workflow.",
+        "Read only the files named by the contract's `artifacts.reads` list plus any paths they explicitly direct you to open.",
+        "Prefer direct file-reading and search tools over shell commands when you inspect inputs, docs, or generated outputs.",
+        "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` for routine file inspection if a native read/search tool can do the same job.",
+        "If the contract lists `instructions.local_docs`, open every one of those files before you write artifacts or declare the stage complete.",
+        "If `AGENTS.md` is listed in the contract, use it only for context-folder routing that is directly relevant to this stage.",
+        "`.interf/runtime/run.json`, `.interf/runtime/state.json`, `.interf/runtime/health.json`, and `.interf/runtime/view-spec.json` are runtime artifacts written by Interf. You may read them, but do not create, edit, or replace them unless the contract explicitly marks a different proof artifact as stage-owned.",
+        "If a contract-listed output file does not exist yet, create it in one whole-file write. Do not attempt patch-style edits against a missing runtime path.",
+        "Stay inside the current compiled context. Do not try to open repo docs, repo source files, or other paths outside the compiled context unless the stage contract explicitly requires them.",
+        instructions.effective_mode === "override"
+            ? "Do not depend on any repo-root or globally installed skill cache for this run. Local stage instruction docs are the primary workflow layer for this run."
+            : "Do not depend on any repo-root or globally installed skill cache for this run. Use the current compiled workflow docs and the contract as the default behavior.",
+        ...modeNotes,
+        "Do not narrate intentions, plans, or reasoning to the user.",
+        "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
+        "Those status lines are progress hints for the operator. The CLI decides stage completion from artifacts, validation, and reconcile checks rather than trusting status text alone.",
+        "Before any long-running raw inspection or shell-based helper step, emit a STATUS: line that names the current subtask.",
+        "If work stays in progress, do not remain silent for more than about one minute. Emit another STATUS: line when you switch files, page groups, targets, or extraction methods.",
+        "If you respond conversationally instead of executing the stage, the run will be treated as failed.",
+        "As soon as the required proof artifacts are complete, stop. Do not keep browsing or auditing after the contract is satisfied.",
+        ...statusLines,
+    ].join("\n");
+}

package/dist/packages/compiler/runtime-reconcile.d.ts

@@ -0,0 +1,2 @@
+import { type WorkflowStageDefinition } from "../workflow-package/workflow-definitions.js";
+export declare function reconcileCompiledStageRun(dirPath: string, stage: Pick<WorkflowStageDefinition, "id" | "contractType" | "reads" | "writes">): boolean;

package/dist/packages/compiler/runtime-reconcile.js

@@ -0,0 +1,193 @@
+import { existsSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { extname, join, relative } from "node:path";
+import { listFilesRecursive } from "../../lib/filesystem.js";
+import { compiledZoneAbsolutePath, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
+import { parseJsonFrontmatter } from "../../lib/parse.js";
+import { loadRuntimeRun } from "./runtime.js";
+import { initCompiledState, loadState, refreshCompiledArtifacts, saveState, } from "./state.js";
+import { compiledInventoryFromEntries } from "./runtime-inventory.js";
+import { compiledRuntimeRoot } from "../project-model/compiled-paths.js";
+import { extractSynthAbstract, isOutputMarkdownFile } from "./validate.js";
+function readActiveRunStartedAtMs(dirPath) {
+    const run = loadRuntimeRun(dirPath);
+    if (!run)
+        return null;
+    const startedAtMs = Date.parse(run.started_at);
+    return Number.isFinite(startedAtMs) ? startedAtMs : null;
+}
+function anyPathUpdatedSince(absolutePath, sinceMs) {
+    if (!existsSync(absolutePath))
+        return false;
+    try {
+        const stat = statSync(absolutePath);
+        if (stat.isFile())
+            return stat.mtimeMs >= sinceMs;
+    }
+    catch {
+        return false;
+    }
+    for (const filePath of listFilesRecursive(absolutePath)) {
+        try {
+            if (statSync(filePath).mtimeMs >= sinceMs)
+                return true;
+        }
+        catch {
+            continue;
+        }
+    }
+    return false;
+}
+function zoneArtifactCount(dirPath, zonePath, kind) {
+    const absolutePath = compiledZoneAbsolutePath(dirPath, { path: zonePath });
+    if (!existsSync(absolutePath))
+        return 0;
+    if (kind === "file")
+        return 1;
+    return listFilesRecursive(absolutePath).length;
+}
+function summaryAbstract(content) {
+    const parsed = parseJsonFrontmatter(content);
+    if (!parsed)
+        return null;
+    return extractSynthAbstract(parsed.frontmatter, parsed.body);
+}
+function listZoneArtifacts(dirPath, zone) {
+    const absolutePath = compiledZoneAbsolutePath(dirPath, zone);
+    if (!existsSync(absolutePath) || zone.kind === "runtime")
+        return [];
+    if (zone.kind === "file") {
+        try {
+            return statSync(absolutePath).isFile() ? [absolutePath] : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return listFilesRecursive(absolutePath);
+}
+function buildInventoryMetadata(options) {
+    const metadata = {
+        zone_id: options.zoneId,
+        zone_kind: options.zoneKind,
+        file_extension: extname(options.filePath).toLowerCase() || null,
+    };
+    if (!options.parsedFrontmatter) {
+        return metadata;
+    }
+    metadata.frontmatter_scanned = true;
+    const abstract = summaryAbstract(readFileSync(options.filePath, "utf8"));
+    if (abstract) {
+        metadata.abstract = abstract;
+        metadata.abstract_read = true;
+    }
+    const frontmatter = options.parsedFrontmatter.frontmatter;
+    if (typeof frontmatter.source_kind === "string") {
+        metadata.source_kind = frontmatter.source_kind;
+    }
+    if (typeof frontmatter.evidence_tier === "string") {
+        metadata.evidence_tier = frontmatter.evidence_tier;
+    }
+    if (typeof frontmatter.truth_mode === "string") {
+        metadata.truth_mode = frontmatter.truth_mode;
+    }
+    return metadata;
+}
+function buildStageInventoryEntries(dirPath, stage) {
+    const schema = readCompiledSchemaFile(join(dirPath, ".interf", "workflow"));
+    if (!schema)
+        return [];
+    const readableInputZones = stage.reads
+        .map((zoneId) => findCompiledSchemaZone(schema, zoneId))
+        .filter((zone) => zone !== null && zone.kind !== "runtime");
+    const outputZones = stage.writes
+        .map((zoneId) => findCompiledSchemaZone(schema, zoneId))
+        .filter((zone) => zone !== null && zone.kind !== "runtime");
+    if (outputZones.length === 0)
+        return [];
+    const entries = [];
+    for (const outputZone of outputZones) {
+        for (const filePath of listZoneArtifacts(dirPath, outputZone)) {
+            const relativeOutputPath = relative(dirPath, filePath).replaceAll("\\", "/");
+            const parsed = isOutputMarkdownFile(filePath)
+                ? parseJsonFrontmatter(readFileSync(filePath, "utf8"))
+                : null;
+            const sourcePath = typeof parsed?.frontmatter.source === "string"
+                ? parsed.frontmatter.source.trim()
+                : "";
+            const sourceZoneId = typeof parsed?.frontmatter.source_zone === "string"
+                ? parsed.frontmatter.source_zone.trim()
+                : "";
+            const inputZone = sourceZoneId.length > 0
+                ? readableInputZones.find((zone) => zone.id === sourceZoneId) ?? null
+                : readableInputZones.length === 1
+                    ? readableInputZones[0]
+                    : null;
+            entries.push({
+                ...(inputZone && sourcePath.length > 0
+                    ? {
+                        input_zone: inputZone.id,
+                        input_path: sourcePath,
+                    }
+                    : {}),
+                output_zone: outputZone.id,
+                output_path: relativeOutputPath,
+                ...(typeof parsed?.frontmatter.state === "string"
+                    ? { state: parsed.frontmatter.state }
+                    : {}),
+                metadata: buildInventoryMetadata({
+                    zoneId: outputZone.id,
+                    zoneKind: outputZone.kind,
+                    filePath,
+                    parsedFrontmatter: parsed,
+                }),
+            });
+        }
+    }
+    return entries.sort((left, right) => `${left.output_zone}:${left.output_path}`.localeCompare(`${right.output_zone}:${right.output_path}`));
+}
+function writeStageInventory(dirPath, stageId, entries) {
+    writeFileSync(join(compiledRuntimeRoot(dirPath), "inventory.json"), JSON.stringify(compiledInventoryFromEntries(entries, stageId), null, 2) + "\n");
+}
+function activeRunCounts(dirPath) {
+    return { ...(loadRuntimeRun(dirPath)?.counts ?? {}) };
+}
+export function reconcileCompiledStageRun(dirPath, stage) {
+    const startedAtMs = readActiveRunStartedAtMs(dirPath);
+    if (startedAtMs === null)
+        return false;
+    const schema = readCompiledSchemaFile(join(dirPath, ".interf", "workflow"));
+    if (!schema)
+        return false;
+    const writeZones = stage.writes
+        .map((zoneId) => findCompiledSchemaZone(schema, zoneId))
+        .filter((zone) => zone !== null);
+    if (writeZones.length === 0)
+        return false;
+    if (!writeZones.some((zone) => anyPathUpdatedSince(compiledZoneAbsolutePath(dirPath, zone), startedAtMs))) {
+        return false;
+    }
+    writeStageInventory(dirPath, stage.id, buildStageInventoryEntries(dirPath, stage));
+    const currentState = {
+        ...initCompiledState(),
+        ...(loadState(dirPath) ?? {}),
+        stages: {
+            ...(loadState(dirPath)?.stages ?? {}),
+        },
+    };
+    const now = new Date().toISOString();
+    currentState.stages[stage.id] = {
+        contract_type: stage.contractType,
+        status: "succeeded",
+        started_at: loadRuntimeRun(dirPath)?.started_at ?? now,
+        finished_at: now,
+        counts: activeRunCounts(dirPath),
+        zone_counts: Object.fromEntries(writeZones.map((zone) => [zone.id, zoneArtifactCount(dirPath, zone.path, zone.kind)])),
+        artifacts: writeZones.map((zone) => zone.kind === "file" ? zone.path : `${zone.path}/`),
+        summary: loadRuntimeRun(dirPath)?.summary ?? null,
+        run_id: loadRuntimeRun(dirPath)?.run_id ?? null,
+    };
+    currentState.last_compile = now;
+    saveState(dirPath, currentState);
+    refreshCompiledArtifacts(dirPath, { ensureViewSpec: true });
+    return true;
+}

package/dist/packages/compiler/runtime-runs.d.ts

@@ -0,0 +1,11 @@
+import { type RuntimeRun, type RuntimeStageContract } from "./lib/schema.js";
+import { type RuntimeRunPatch, type RuntimeStageExecutionOptions, type RuntimeSummarizeExecutionOptions } from "./runtime-types.js";
+export declare function loadRuntimeRun(dirPath: string): RuntimeRun | null;
+export declare function saveRuntimeRun(dirPath: string, run: RuntimeRun): void;
+export declare function writeStageContract(dirPath: string, contract: RuntimeStageContract): string;
+export declare function runExecutorStage(options: RuntimeStageExecutionOptions): Promise<number>;
+export declare function runExecutorSummarizeStage(options: RuntimeSummarizeExecutionOptions): Promise<number>;
+export declare function beginRuntimeRun(dirPath: string, run: RuntimeRun): RuntimeRun;
+export declare function updateRuntimeRun(dirPath: string, patch: RuntimeRunPatch): RuntimeRun | null;
+export declare function markRuntimeRunFailedAfterValidation(dirPath: string, summary: string): RuntimeRun | null;
+export declare function markRuntimeRunSucceededAfterValidation(dirPath: string, summary: string): RuntimeRun | null;

package/dist/packages/compiler/runtime-runs.js

@@ -0,0 +1,262 @@
+import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import chalk from "chalk";
+import { countFilesRecursive } from "../../lib/filesystem.js";
+import { buildRuntimeExecutorInfo } from "../agents/lib/executors.js";
+import { RuntimeRunSchema, } from "./lib/schema.js";
+import { getWorkflowStageDefinition, getWorkflowStagePosition, getWorkflowStages, } from "../workflow-package/workflow-definitions.js";
+import { archivedStageContractPath, eventLogPath, logsDirPath, promptLogPath, runHistoryPath, runPath, stageContractPath, statusLogPath, } from "./runtime-paths.js";
+import { warnInterf } from "../../lib/logger.js";
+export function loadRuntimeRun(dirPath) {
+    const path = runPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const parsed = RuntimeRunSchema.safeParse(raw);
+        if (parsed.success)
+            return parsed.data;
+        warnInterf(`Warning: failed to validate runtime run at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    catch (error) {
+        warnInterf(`Warning: failed to read runtime run at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+export function saveRuntimeRun(dirPath, run) {
+    mkdirSync(dirname(runPath(dirPath)), { recursive: true });
+    writeFileSync(runPath(dirPath), JSON.stringify(run, null, 2) + "\n");
+}
+export function writeStageContract(dirPath, contract) {
+    mkdirSync(dirname(stageContractPath(dirPath)), { recursive: true });
+    const path = stageContractPath(dirPath);
+    writeFileSync(path, JSON.stringify(contract, null, 2) + "\n");
+    return path;
+}
+function writeArchivedStageContract(dirPath, runId, contract) {
+    const path = archivedStageContractPath(dirPath, runId);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(contract, null, 2) + "\n");
+    return path;
+}
+export async function runExecutorStage(options) {
+    const startedRun = startRuntimeRun(options);
+    const prompt = options.buildPrompt(startedRun.activeContractPath);
+    writeRuntimeRunPrompt(options.compiledPath, startedRun.run.run_id, prompt);
+    const executionPath = options.executionPath ?? options.compiledPath;
+    const code = await options.executor.execute(executionPath, prompt, {
+        eventLogPath: eventLogPath(options.compiledPath, startedRun.run.run_id),
+        statusLogPath: statusLogPath(options.compiledPath, startedRun.run.run_id),
+        completionCheck: options.completionCheck,
+    });
+    finalizeRuntimeRun(options.compiledPath, code);
+    return code;
+}
+export async function runExecutorSummarizeStage(options) {
+    const startedRun = startRuntimeRun(options);
+    const prompt = options.buildPrompt(startedRun.activeContractPath);
+    let lastReported = 0;
+    writeRuntimeRunPrompt(options.compiledPath, startedRun.run.run_id, prompt);
+    const executionPath = options.executionPath ?? options.compiledPath;
+    const progressPromise = options.executor.execute(executionPath, prompt, {
+        eventLogPath: eventLogPath(options.compiledPath, startedRun.run.run_id),
+        statusLogPath: statusLogPath(options.compiledPath, startedRun.run.run_id),
+        completionCheck: options.completionCheck,
+    });
+    const timer = setInterval(() => {
+        const currentSummaryCount = countFilesRecursive(join(options.compiledPath, "summaries"));
+        const completed = Math.max(0, Math.min(options.targetCount, currentSummaryCount - options.startingSummaryCount));
+        if (completed <= lastReported)
+            return;
+        lastReported = completed;
+        updateRuntimeRun(options.compiledPath, {
+            counts: {
+                ...startedRun.run.counts,
+                completed_summaries: completed,
+                target_summaries: options.targetCount,
+            },
+            summary: `${options.stageLabel} ${completed}/${options.targetCount} source files into summaries.`,
+        });
+        console.log(chalk.dim(`  STATUS: wrote ${completed}/${options.targetCount} summaries`));
+    }, 10000);
+    try {
+        const code = await progressPromise;
+        finalizeRuntimeRun(options.compiledPath, code);
+        return code;
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+export function beginRuntimeRun(dirPath, run) {
+    saveRuntimeRun(dirPath, run);
+    return run;
+}
+export function updateRuntimeRun(dirPath, patch) {
+    const current = loadRuntimeRun(dirPath);
+    if (!current)
+        return null;
+    const next = {
+        ...current,
+        ...patch,
+        updated_at: new Date().toISOString(),
+    };
+    saveRuntimeRun(dirPath, next);
+    return next;
+}
+export function markRuntimeRunFailedAfterValidation(dirPath, summary) {
+    const current = loadRuntimeRun(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = current.finished_at ?? new Date().toISOString();
+    const next = {
+        ...current,
+        status: "failed",
+        updated_at: new Date().toISOString(),
+        finished_at: finishedAt,
+        exit_code: 1,
+        error: summary,
+        summary,
+    };
+    saveRuntimeRun(dirPath, next);
+    replaceOrAppendRunHistoryEntry(dirPath, next);
+    return next;
+}
+export function markRuntimeRunSucceededAfterValidation(dirPath, summary) {
+    const current = loadRuntimeRun(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = current.finished_at ?? new Date().toISOString();
+    const next = {
+        ...current,
+        status: "succeeded",
+        updated_at: new Date().toISOString(),
+        finished_at: finishedAt,
+        exit_code: 0,
+        error: null,
+        summary,
+    };
+    saveRuntimeRun(dirPath, next);
+    replaceOrAppendRunHistoryEntry(dirPath, next);
+    return next;
+}
+function startRuntimeRun(options) {
+    const runId = createRunId();
+    const generatedAt = new Date().toISOString();
+    const workflowStages = getWorkflowStages(options.workflow, options.workflowSourcePath);
+    const stagePosition = getWorkflowStagePosition(options.workflow, options.stage, options.workflowSourcePath);
+    const stageDefinition = getWorkflowStageDefinition(options.workflow, options.stage, options.workflowSourcePath);
+    const contract = {
+        kind: "interf-stage-contract",
+        version: 1,
+        generated_at: generatedAt,
+        run_id: runId,
+        target_type: "compiled",
+        target_name: options.compiledName,
+        workflow: {
+            id: options.workflow,
+            stage_index: stagePosition?.stageIndex ?? null,
+            stage_total: stagePosition?.stageTotal ?? workflowStages.length,
+            stages: stagePosition?.stages ?? workflowStages,
+        },
+        stage: options.stage,
+        stage_label: stageDefinition?.label ?? options.stageLabel,
+        contract_type: options.contractType,
+        executor: buildRuntimeExecutorInfo(options.executor),
+        instructions: options.contract.instructions,
+        counts: options.contract.counts,
+        ...(options.contract.acceptance ? { acceptance: options.contract.acceptance } : {}),
+        artifacts: options.contract.artifacts,
+        policies: options.contract.policies,
+    };
+    const activeContractPath = writeStageContract(options.compiledPath, contract);
+    const archivedContractPath = writeArchivedStageContract(options.compiledPath, runId, contract);
+    const run = {
+        kind: "interf-run",
+        version: 1,
+        run_id: runId,
+        target_type: "compiled",
+        target_name: options.compiledName,
+        workflow: options.workflow,
+        stage: options.stage,
+        stage_label: stageDefinition?.label ?? options.stageLabel,
+        contract_type: options.contractType,
+        status: "running",
+        executor: buildRuntimeExecutorInfo(options.executor),
+        started_at: generatedAt,
+        updated_at: generatedAt,
+        finished_at: null,
+        contract_path: relative(options.compiledPath, archivedContractPath),
+        ...(options.executionPath ? { execution_path: relative(options.compiledPath, options.executionPath) } : {}),
+        counts: { ...contract.counts },
+        output_artifacts: [...contract.artifacts.writes],
+        logs: {
+            prompt_path: relative(options.compiledPath, promptLogPath(options.compiledPath, runId)),
+            event_stream_path: relative(options.compiledPath, eventLogPath(options.compiledPath, runId)),
+            status_path: relative(options.compiledPath, statusLogPath(options.compiledPath, runId)),
+        },
+        summary: options.summary,
+        exit_code: null,
+        error: null,
+    };
+    return {
+        run: beginRuntimeRun(options.compiledPath, run),
+        activeContractPath: options.executionPath
+            ? "runtime/stage-contract.json"
+            : relative(options.compiledPath, activeContractPath),
+    };
+}
+function finalizeRuntimeRun(dirPath, code) {
+    const current = loadRuntimeRun(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = new Date().toISOString();
+    const next = {
+        ...current,
+        status: code === 0 ? "succeeded" : "failed",
+        updated_at: finishedAt,
+        finished_at: finishedAt,
+        exit_code: code,
+        error: code === 0 ? null : `Executor exited with code ${code}.`,
+        summary: code === 0
+            ? `${current.stage_label} completed successfully.`
+            : `${current.stage_label} failed with exit code ${code}.`,
+    };
+    saveRuntimeRun(dirPath, next);
+    appendFileSync(runHistoryPath(dirPath), JSON.stringify(next) + "\n");
+    return next;
+}
+function writeRuntimeRunPrompt(dirPath, runId, prompt) {
+    mkdirSync(logsDirPath(dirPath), { recursive: true });
+    writeFileSync(promptLogPath(dirPath, runId), `${prompt}\n`);
+}
+function createRunId() {
+    return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function replaceOrAppendRunHistoryEntry(dirPath, run) {
+    const historyPath = runHistoryPath(dirPath);
+    if (!existsSync(historyPath)) {
+        appendFileSync(historyPath, JSON.stringify(run) + "\n");
+        return;
+    }
+    const raw = readFileSync(historyPath, "utf8");
+    const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+    let replaced = false;
+    const nextLines = lines.map((line) => {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.run_id === run.run_id) {
+                replaced = true;
+                return JSON.stringify(run);
+            }
+        }
+        catch {
+            // preserve malformed history lines as-is
+        }
+        return line;
+    });
+    if (!replaced)
+        nextLines.push(JSON.stringify(run));
+    writeFileSync(historyPath, `${nextLines.join("\n")}\n`);
+}