@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/build/native-entrypoint.js

@@ -0,0 +1,286 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+import { appendAgentEventLog, } from "../agents/lib/logs.js";
+import { ExpectedInputsFileSchema, ResourceRefSchema, SourceManifestSchema, } from "../../contracts/lib/schema.js";
+import { normalizeLayerPath } from "../../contracts/lib/context-graph-layer.js";
+import { listFilesRecursive, } from "../../contracts/utils/filesystem.js";
+import { parseJsonFrontmatter, renderJsonFrontmatter, } from "../../contracts/utils/parse.js";
+function markdownTitle(path, content) {
+    const parsed = parseJsonFrontmatter(content);
+    const title = parsed && typeof parsed.frontmatter.title === "string"
+        ? parsed.frontmatter.title.trim()
+        : "";
+    if (title)
+        return title;
+    const body = parsed?.body ?? content;
+    const heading = body.split(/\r?\n/).find((line) => /^#{1,3}\s+\S/.test(line));
+    if (heading)
+        return heading.replace(/^#{1,3}\s+/, "").trim();
+    return basename(path, extname(path));
+}
+function markdownSummary(content) {
+    const parsed = parseJsonFrontmatter(content);
+    if (parsed && typeof parsed.frontmatter.summary === "string" && parsed.frontmatter.summary.trim()) {
+        return parsed.frontmatter.summary.trim();
+    }
+    const body = parsed?.body ?? content;
+    const paragraph = body
+        .split(/\n\s*\n/)
+        .map((block) => block.replace(/\s+/g, " ").trim())
+        .find((block) => block.length > 0 && !block.startsWith("#"));
+    if (!paragraph)
+        return null;
+    return paragraph.length > 180 ? `${paragraph.slice(0, 177)}...` : paragraph;
+}
+function safeReadJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function readExpectedInputs(shellRoot) {
+    const parsed = ExpectedInputsFileSchema.safeParse(safeReadJson(join(shellRoot, "runtime", "expected-inputs.json")));
+    return parsed.success ? parsed.data.expected : [];
+}
+function readSourceManifest(shellRoot) {
+    const raw = safeReadJson(join(shellRoot, "runtime", "source-manifest.json"));
+    const parsed = SourceManifestSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+function readProjectIntent(shellRoot) {
+    const contract = safeReadJson(join(shellRoot, "runtime", "stage-contract.json"));
+    const intent = typeof contract?.project?.intent === "string" ? contract.project.intent.trim() : "";
+    return intent || "Build a task-specific Context Graph from the Project Source.";
+}
+function collectMarkdownResources(shellRoot, directory) {
+    const root = join(shellRoot, directory);
+    if (!existsSync(root))
+        return [];
+    return listFilesRecursive(root, (filePath) => filePath.endsWith(".md"))
+        .sort((left, right) => left.localeCompare(right))
+        .map((filePath) => {
+        const path = normalizeLayerPath(relative(shellRoot, filePath));
+        const content = readFileSync(filePath, "utf8");
+        const parsed = parseJsonFrontmatter(content);
+        const sourceRefs = sourceRefsFromFrontmatter(parsed?.frontmatter ?? {});
+        return ResourceRefSchema.parse({
+            id: `${directory}:${path.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")}`,
+            role: directory === "knowledge" ? "knowledge" : "summary",
+            kind: directory === "knowledge" ? "knowledge.note" : "summary.note",
+            label: markdownTitle(path, content),
+            path,
+            source_refs: sourceRefs,
+            links: [],
+            metadata: {
+                ...(markdownSummary(content) ? { summary: markdownSummary(content) } : {}),
+            },
+        });
+    });
+}
+function sourceRefsFromFrontmatter(frontmatter) {
+    const values = [
+        frontmatter.source_refs,
+        frontmatter.source_ref,
+        frontmatter.source_path,
+        frontmatter.source,
+    ];
+    const refs = values.flatMap((value) => {
+        if (typeof value === "string" && value.trim())
+            return [value.trim()];
+        if (Array.isArray(value)) {
+            return value
+                .filter((item) => typeof item === "string" && item.trim().length > 0)
+                .map((item) => item.trim());
+        }
+        return [];
+    });
+    return [...new Set(refs)];
+}
+function collectSourceRefs(expected, manifest, notes) {
+    const refs = new Set();
+    for (const resource of [...expected, ...notes]) {
+        for (const ref of resource.source_refs)
+            refs.add(ref);
+    }
+    for (const file of manifest?.files ?? [])
+        refs.add(file.path);
+    return [...refs].sort((left, right) => left.localeCompare(right));
+}
+function markdownLink(resource) {
+    const path = resource.path ?? "";
+    return path ? `[${resource.label}](${path})` : resource.label;
+}
+function renderResourceList(resources, limit) {
+    return resources.slice(0, limit).map((resource) => {
+        const summary = typeof resource.metadata?.summary === "string" ? resource.metadata.summary : null;
+        return `- ${markdownLink(resource)}${summary ? ` - ${summary}` : ""}`;
+    });
+}
+function renderSourceRefList(sourceRefs, limit) {
+    return sourceRefs.slice(0, limit).map((ref) => `- \`${ref}\``);
+}
+function writeReviewedInputs(shellRoot, expected) {
+    const now = new Date().toISOString();
+    const reviewed = expected.map((resource) => ({
+        resource_id: resource.id,
+        decision: "used",
+        source_refs: resource.source_refs.length > 0 ? resource.source_refs : [resource.path ?? resource.id],
+        metadata: {
+            reviewer: "interf-native-entrypoint",
+        },
+    }));
+    writeFileSync(join(shellRoot, "runtime", "reviewed-inputs.json"), `${JSON.stringify({
+        kind: "interf-stage-reviewed-inputs",
+        version: 1,
+        generated_at: now,
+        stage_id: "entrypoint",
+        reviewed,
+    }, null, 2)}\n`);
+}
+function writeEntrypointOutputs(shellRoot) {
+    const intent = readProjectIntent(shellRoot);
+    const expected = readExpectedInputs(shellRoot);
+    const manifest = readSourceManifest(shellRoot);
+    const knowledge = collectMarkdownResources(shellRoot, "knowledge");
+    const summaries = collectMarkdownResources(shellRoot, "summaries");
+    const expectedByPath = new Map(expected.map((resource) => [resource.path, resource]));
+    const knowledgeForRouting = knowledge.length > 0
+        ? knowledge
+        : expected.filter((resource) => resource.role === "knowledge");
+    const notesForRefs = [...knowledgeForRouting, ...summaries, ...expectedByPath.values()];
+    const sourceRefs = collectSourceRefs(expected, manifest, notesForRefs);
+    const generatedAt = new Date().toISOString();
+    const topKnowledge = knowledgeForRouting.slice(0, 12);
+    const topSummaries = summaries.slice(0, 12);
+    const links = [
+        "artifacts/agent-handoff.md",
+        ...topKnowledge.map((resource) => resource.path).filter((path) => Boolean(path)),
+        ...topSummaries.slice(0, 6).map((resource) => resource.path).filter((path) => Boolean(path)),
+    ];
+    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
+    writeFileSync(join(shellRoot, "home.md"), [
+        renderJsonFrontmatter({
+            title: "Context Graph Home",
+            summary: "Primary agent entrypoint for the prepared Context Graph.",
+            task: intent,
+            source_refs: sourceRefs,
+            links,
+            generated_by: "interf-native-entrypoint",
+        }),
+        "",
+        "# Context Graph Home",
+        "",
+        `Project intent: ${intent}`,
+        "",
+        "Start with the task handoff, then follow the linked knowledge notes and summaries. Generated notes are routing and synthesis; original Source and source refs remain the authority for exact claims.",
+        "",
+        "## Start Here",
+        "",
+        "- [Agent handoff](artifacts/agent-handoff.md)",
+        ...renderResourceList(topKnowledge, 10),
+        "",
+        "## Coverage Routes",
+        "",
+        ...(topSummaries.length > 0
+            ? renderResourceList(topSummaries, 10)
+            : ["- No summary notes were available to route."]),
+        "",
+        "## Source Refs",
+        "",
+        ...(sourceRefs.length > 0
+            ? renderSourceRefList(sourceRefs, 20)
+            : ["- No source refs were recorded."]),
+        "",
+    ].join("\n"));
+    writeFileSync(join(shellRoot, "artifacts", "agent-handoff.md"), [
+        renderJsonFrontmatter({
+            title: "Agent Handoff",
+            summary: "Task-specific route through the prepared Context Graph.",
+            task: intent,
+            source_refs: sourceRefs,
+            handoff_type: "agent-context-handoff",
+            truth_mode: "source-backed routing",
+            verification_state: "Ready to use; follow original Source and source refs for exact claims.",
+            caveats: [
+                "Generated summaries and knowledge notes are prepared context, not replacement source material.",
+                "Use original Source and source refs when exact wording, table values, chart reads, dates, or provenance-sensitive claims matter.",
+            ],
+            links,
+            generated_at: generatedAt,
+            generated_by: "interf-native-entrypoint",
+        }),
+        "",
+        "# Agent Handoff",
+        "",
+        `Task: ${intent}`,
+        "",
+        "Use this Context Graph as prepared context. For exact claims, follow the original Source and source refs from the notes below back to the source files.",
+        "",
+        "## Useful Knowledge",
+        "",
+        ...(topKnowledge.length > 0
+            ? renderResourceList(topKnowledge, 12)
+            : ["- No knowledge notes were available."]),
+        "",
+        "## Coverage And Source Routes",
+        "",
+        ...(topSummaries.length > 0
+            ? renderResourceList(topSummaries, 12)
+            : ["- No summary notes were available."]),
+        "",
+        "## Source Refs To Recheck",
+        "",
+        ...(sourceRefs.length > 0
+            ? renderSourceRefList(sourceRefs, 30)
+            : ["- No source refs were recorded."]),
+        "",
+    ].join("\n"));
+    writeReviewedInputs(shellRoot, expected);
+}
+function appendStatus(options, line) {
+    appendAgentEventLog(options?.eventLogPath, {
+        type: "native-stage.status",
+        message: line,
+    });
+    options?.onStatus?.(line);
+    if (options?.statusLogPath) {
+        appendFileSync(options.statusLogPath, `${line}\n`);
+    }
+}
+function appendNativeEvent(options, event) {
+    appendAgentEventLog(options?.eventLogPath, {
+        type: "native-stage.event",
+        ...event,
+    });
+}
+export function createNativeEntrypointExecutor() {
+    return {
+        kind: "managed",
+        name: "interf-native-entrypoint",
+        displayName: "Interf native entrypoint",
+        command: null,
+        execute(rootPath, _prompt, options) {
+            try {
+                appendNativeEvent(options, { phase: "started", root_path: rootPath });
+                appendStatus(options, "STATUS: loaded entrypoint stage.");
+                appendStatus(options, "STATUS: reading declared inputs.");
+                writeEntrypointOutputs(rootPath);
+                appendStatus(options, "STATUS: writing declared outputs.");
+                appendStatus(options, "DONE: entrypoint complete.");
+                appendNativeEvent(options, { phase: "succeeded", root_path: rootPath });
+                return Promise.resolve(0);
+            }
+            catch (error) {
+                appendStatus(options, `ERROR: native entrypoint failed: ${error instanceof Error ? error.message : String(error)}`);
+                appendNativeEvent(options, {
+                    phase: "failed",
+                    root_path: rootPath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return Promise.resolve(1);
+            }
+        },
+    };
+}

package/dist/packages/runtime/build/reset.d.ts

@@ -0,0 +1,2 @@
+export declare function clearBuildRuntimeDerivedArtifacts(contextGraphPath: string): void;
+export declare function resetBuildGeneratedState(contextGraphPath: string, scope?: "build" | "all"): void;

package/dist/packages/runtime/build/reset.js

@@ -0,0 +1,62 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { initializeBuildRuntimeState } from "./state.js";
+import { stageExecutionShellsRoot, testRootForContextGraph, testTargetsRootForContextGraph, buildPlanImprovementLoopsRoot, contextGraphQueryAcceptanceRoot, contextGraphRuntimeRoot, contextGraphRuntimeLogsRoot, } from "./context-graph-paths.js";
+function removeIfExists(path) {
+    if (existsSync(path)) {
+        rmSync(path, { recursive: true, force: true });
+    }
+}
+const BUILD_RUNTIME_RESET_ENTRIES = [
+    "state.json",
+    "health.json",
+    "view-spec.json",
+    "inventory.json",
+    "run.json",
+    "source-manifest.json",
+    "source-manifest.audit.json",
+    "source-files.json",
+    "source-state.json",
+    "stage-contract.json",
+    "stages",
+];
+const PRESERVED_CONTEXT_GRAPH_ROOTS = new Set([
+    ".agents",
+    ".claude",
+    ".codex",
+    ".cursor",
+    ".gitignore",
+    ".interf",
+    ".interfignore",
+    "AGENTS.md",
+    "CLAUDE.md",
+]);
+export function clearBuildRuntimeDerivedArtifacts(contextGraphPath) {
+    const runtimeRoot = contextGraphRuntimeRoot(contextGraphPath);
+    for (const entry of BUILD_RUNTIME_RESET_ENTRIES) {
+        removeIfExists(join(runtimeRoot, entry));
+    }
+    removeIfExists(contextGraphQueryAcceptanceRoot(contextGraphPath));
+}
+function resetBuildGeneratedOutputs(contextGraphPath) {
+    for (const entry of readdirSync(contextGraphPath)) {
+        if (PRESERVED_CONTEXT_GRAPH_ROOTS.has(entry))
+            continue;
+        removeIfExists(join(contextGraphPath, entry));
+    }
+}
+export function resetBuildGeneratedState(contextGraphPath, scope = "build") {
+    resetBuildGeneratedOutputs(contextGraphPath);
+    // Stage reuse fingerprints live in state.json, so this is the load-bearing
+    // build reset path that forces a post-reset build to re-run every stage.
+    clearBuildRuntimeDerivedArtifacts(contextGraphPath);
+    initializeBuildRuntimeState(contextGraphPath);
+    if (scope === "all") {
+        removeIfExists(stageExecutionShellsRoot(contextGraphPath));
+        removeIfExists(buildPlanImprovementLoopsRoot(contextGraphPath));
+        removeIfExists(contextGraphRuntimeLogsRoot(contextGraphPath));
+        removeIfExists(join(contextGraphRuntimeRoot(contextGraphPath), "run-history.jsonl"));
+        removeIfExists(testRootForContextGraph(contextGraphPath));
+        removeIfExists(testTargetsRootForContextGraph(contextGraphPath));
+    }
+}

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

@@ -1,9 +1,10 @@
-import { BUILD_PLAN_SCHEMA_FILE } from "./verifiable-context-schema.js";
+import { BUILD_PLAN_SCHEMA_FILE } from "./context-graph-schema.js";
 export function buildRuntimeStageContract(options) {
     const localSkillDocs = options.localSkillDocs ?? [];
     const buildPlanNotes = options.buildPlanNotes ?? [];
     return {
         instructions: options.instructions,
+        project: options.project,
         counts: {
             ...(options.counts ?? {}),
             local_skill_docs: localSkillDocs.length,
@@ -19,16 +20,21 @@ export function buildRuntimeStageContract(options) {
             writes: options.stageWriteArtifacts,
             write_contracts: options.stageWriteContracts ?? [],
         },
+        context_checks: options.contextChecks ?? [],
         policies: {
             execution_mode: "deterministic",
             status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
             notes: [
-                `This is the "${options.stageLabel}" stage for the verifiable context "${options.verifiableContextName}".`,
+                `This is the "${options.stageLabel}" stage for the context graph "${options.contextGraphName}".`,
+                options.project.intent
+                    ? `Project intent: ${options.project.intent}`
+                    : "Project intent is not set. Keep outputs source-grounded and explicitly note missing task focus where it limits usefulness.",
                 "The Build Plan is the authoritative plan layer for this run.",
-                `Use \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` as the deterministic context-interface reference for this verifiable context.`,
-                "Honor the declared read and write artifacts instead of inventing a parallel process.",
+                `Use \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` as the deterministic requested output contract for this context graph.`,
+                "Use `context_checks[]` only as legacy coverage-goal context; StageManifest and GraphManifest metrics are the readiness proof.",
+                "Honor the declared read and write outputs instead of inventing a parallel process.",
                 "Only create or update files that fall under the declared write targets for this stage.",
-                "Before emitting DONE, satisfy every check listed under `artifacts.write_contracts[]` for the write Artifacts this stage owns.",
+                "Before emitting DONE, satisfy every check listed under `artifacts.write_contracts[]` for the write outputs this stage owns.",
                 "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.",
                 ...buildPlanNotes,
@@ -36,8 +42,8 @@ export function buildRuntimeStageContract(options) {
                     ? [
                         "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 Build Plan 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.",
+                            ? "Local stage docs replace the default Build Plan guidance for this run, but they still do not bypass required writes, declared evidence artifacts, or deterministic runtime reconciliation."
+                            : "Local stage docs can refine the stage behavior, but they do not bypass required writes, declared evidence artifacts, or deterministic runtime reconciliation.",
                     ]
                     : []),
             ],

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

@@ -0,0 +1,7 @@
+import { type ExecutionInventory, type ExecutionInventoryEntry } from "./lib/schema.js";
+export declare function emptyExecutionInventory(): ExecutionInventory;
+export declare function buildInventoryFromEntries(entries: ExecutionInventoryEntry[], stage?: string): ExecutionInventory;
+export declare function buildInventoryEntryCount(inventory: ExecutionInventory | null): number;
+export declare function buildInventoryTotal(inventory: ExecutionInventory | null): number;
+export declare function buildInventoryFrontmatterScannedCount(inventory: ExecutionInventory | null): number;
+export declare function buildInventoryAbstractCoverageCount(inventory: ExecutionInventory | null): number;

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

@@ -1,6 +1,6 @@
-export function emptyRuntimeInventory() {
+export function emptyExecutionInventory() {
     return {
-        kind: "verifiable-context-runtime-ledger",
+        kind: "context-graph-runtime-ledger",
         version: 1,
         entries: [],
         total: 0,
@@ -8,7 +8,7 @@ export function emptyRuntimeInventory() {
 }
 export function buildInventoryFromEntries(entries, stage) {
     return {
-        kind: "verifiable-context-runtime-ledger",
+        kind: "context-graph-runtime-ledger",
         version: 1,
         ...(stage ? { stage } : {}),
         entries,

package/dist/packages/runtime/build/runtime-log-paths.d.ts

@@ -0,0 +1,3 @@
+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/runtime/build/runtime-log-paths.js

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+import { contextGraphRuntimeLogsRoot } from "./context-graph-paths.js";
+// Canonical per-run log-file builders for stage execution without a shell.
+// They share the runtime logs root with the archived stage contract
+// (contextGraphRuntimeArchivedStageContractPath) and use the same
+// `<runId>.<suffix>` naming. Shell-backed runs use the parallel
+// shell-workspace builders instead.
+export function promptLogPath(dirPath, runId) {
+    return join(contextGraphRuntimeLogsRoot(dirPath), `${runId}.prompt.txt`);
+}
+export function eventLogPath(dirPath, runId) {
+    return join(contextGraphRuntimeLogsRoot(dirPath), `${runId}.events.ndjson`);
+}
+export function statusLogPath(dirPath, runId) {
+    return join(contextGraphRuntimeLogsRoot(dirPath), `${runId}.status.log`);
+}

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

@@ -8,7 +8,7 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         ]
         : instructions.effective_mode === "extend"
             ? [
-                "Use the current Build Plan docs as the default plan for this run.",
+                "Use the current Build Plan docs as the default instructions for this run.",
                 "Then apply any additional local stage instruction docs referenced by the contract as stage-specific extensions.",
             ]
             : [
@@ -21,18 +21,21 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         "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 Build Plan Artifact ids onto the shell-local `inputs/` and `outputs/` mounts for this stage.",
-        "For file Artifact mounts, `runtime/paths.json` also gives the exact file path inside the `inputs/` or `outputs/` mount root.",
+        "Use `project.intent` in that contract as the task focus for task-aware summaries, knowledge, entrypoints, and task note work.",
+        "Use `runtime/expected-inputs.json` as the coverage contract and write `runtime/reviewed-inputs.json` before DONE.",
+        "If `runtime/paths.json` exists in this shell, read it next. It maps Build Plan output ids onto the shell-local `inputs/` and `outputs/` mounts for this stage.",
+        "For file output mounts, `runtime/paths.json` also gives the exact file path inside the `inputs/` or `outputs/` mount root.",
+        "Before DONE, run `node runtime/check-stage.mjs` from the shell root and fix outputs until it prints `VALID:`.",
         "Honor the contract's counts, artifact paths, and policies instead of inventing another Build Plan.",
-        "The contract's `artifacts.write_contracts[]` lists the checks Interf will run against the Artifacts this stage writes. Treat those checks as required output constraints.",
-        "Read only the files named by the contract's `artifacts.reads` list plus any paths they explicitly direct you to open.",
+        "The contract's `artifacts.write_contracts[]` lists the checks Interf will run against the outputs this stage writes. Treat those checks as required output constraints.",
+        "Read only the files named by the contract's `artifacts.reads` list, `runtime/source-manifest.json`, `runtime/stage-inputs.json`, `runtime/expected-inputs.json`, and any paths those files explicitly assign to this stage. `runtime/source-state.json` is compatibility-only and is not stage authority.",
         "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 verifiable-context 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 `AGENTS.md` is listed in the contract, use it only for context-graph 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 evidence 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 verifiable context. Do not try to open repo docs, repo source files, or other paths outside this context unless the stage contract explicitly requires them.",
+        "Stay inside the current context graph. Do not try to open repo docs, repo source files, or other paths outside this 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 Build Plan layer for this run."
             : "Do not depend on any repo-root or globally installed skill cache for this run. Use the current Build Plan stage docs and the contract as the default behavior.",
@@ -43,7 +46,7 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         "Before any long-running source 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 passes.",
         "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.",
+        "As soon as the required evidence artifacts are complete, stop. Do not keep browsing or auditing after the contract is satisfied.",
         ...statusLines,
     ].join("\n");
 }

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

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

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

@@ -1,16 +1,18 @@
-import { existsSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, readFileSync, statSync, } from "node:fs";
 import { extname, join, relative } from "node:path";
 import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
-import { verifiableContextArtifactAbsolutePath, findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./verifiable-context-schema.js";
+import { contextGraphArtifactAbsolutePath, findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./context-graph-schema.js";
 import { parseJsonFrontmatter } from "../../contracts/utils/parse.js";
-import { loadRuntimeRun } from "./runtime.js";
-import { initVerifiableContextState, loadState, refreshVerifiableContextArtifacts, saveState, } from "./state.js";
+import { loadExecutionStageLedger } from "./runtime.js";
+import { initContextGraphState, loadState, refreshContextGraphArtifacts, saveState, } from "./state.js";
 import { buildInventoryFromEntries } from "./runtime-inventory.js";
 import { STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "../../contracts/lib/schema.js";
-import { verifiableContextRuntimeRoot, buildPlanPackagePathForVerifiableContext } from "./verifiable-context-paths.js";
+import { contextGraphRuntimeRoot, buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
 import { extractSynthAbstract, isOutputMarkdownFile } from "./validate.js";
+import { writeJsonAtomic } from "./atomic-fs.js";
+import { computeStageFingerprint } from "./stage-reuse.js";
 function readActiveRunStartedAtMs(dirPath) {
-    const run = loadRuntimeRun(dirPath);
+    const run = loadExecutionStageLedger(dirPath);
     if (!run)
         return null;
     const startedAtMs = Date.parse(run.started_at);
@@ -39,7 +41,7 @@ function anyPathUpdatedSince(absolutePath, sinceMs) {
     return false;
 }
 function artifactCount(dirPath, artifactPath, kind) {
-    const absolutePath = verifiableContextArtifactAbsolutePath(dirPath, { path: artifactPath });
+    const absolutePath = contextGraphArtifactAbsolutePath(dirPath, { path: artifactPath });
     if (!existsSync(absolutePath))
         return 0;
     if (kind === "file")
@@ -53,8 +55,8 @@ function summaryAbstract(content) {
     return extractSynthAbstract(parsed.frontmatter, parsed.body);
 }
 function listZoneArtifacts(dirPath, artifact) {
-    const absolutePath = verifiableContextArtifactAbsolutePath(dirPath, artifact);
-    if (!existsSync(absolutePath) || artifact.kind === "runtime")
+    const absolutePath = contextGraphArtifactAbsolutePath(dirPath, artifact);
+    if (!existsSync(absolutePath))
         return [];
     if (artifact.kind === "file") {
         try {
@@ -95,15 +97,15 @@ function buildInventoryMetadata(options) {
     return metadata;
 }
 function buildStageInventoryEntries(dirPath, stage) {
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(dirPath));
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(dirPath));
     if (!schema)
         return [];
     const readableInputArtifacts = stage.reads
         .map((artifactId) => findBuildPlanContextArtifact(schema, artifactId))
-        .filter((artifact) => artifact !== null && artifact.kind !== "runtime");
+        .filter((artifact) => artifact !== null);
     const outputArtifacts = stage.writes
         .map((artifactId) => findBuildPlanContextArtifact(schema, artifactId))
-        .filter((artifact) => artifact !== null && artifact.kind !== "runtime");
+        .filter((artifact) => artifact !== null);
     if (outputArtifacts.length === 0)
         return [];
     const entries = [];
@@ -148,16 +150,16 @@ function buildStageInventoryEntries(dirPath, stage) {
     return entries.sort((left, right) => `${left.output_artifact}:${left.output_path}`.localeCompare(`${right.output_artifact}:${right.output_path}`));
 }
 function writeStageInventory(dirPath, stageId, entries) {
-    writeFileSync(join(verifiableContextRuntimeRoot(dirPath), "inventory.json"), JSON.stringify(buildInventoryFromEntries(entries, stageId), null, 2) + "\n");
+    writeJsonAtomic(join(contextGraphRuntimeRoot(dirPath), "inventory.json"), buildInventoryFromEntries(entries, stageId));
 }
 function activeRunCounts(dirPath) {
-    return { ...(loadRuntimeRun(dirPath)?.counts ?? {}) };
+    return { ...(loadExecutionStageLedger(dirPath)?.counts ?? {}) };
 }
 export function reconcileBuildStageRun(dirPath, stage) {
     const startedAtMs = readActiveRunStartedAtMs(dirPath);
     if (startedAtMs === null)
         return false;
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(dirPath));
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(dirPath));
     if (!schema)
         return false;
     const writeArtifacts = stage.writes
@@ -165,31 +167,33 @@ export function reconcileBuildStageRun(dirPath, stage) {
         .filter((artifact) => artifact !== null);
     if (writeArtifacts.length === 0)
         return false;
-    if (!writeArtifacts.some((artifact) => anyPathUpdatedSince(verifiableContextArtifactAbsolutePath(dirPath, artifact), startedAtMs))) {
+    if (!writeArtifacts.some((artifact) => anyPathUpdatedSince(contextGraphArtifactAbsolutePath(dirPath, artifact), startedAtMs))) {
         return false;
     }
     writeStageInventory(dirPath, stage.id, buildStageInventoryEntries(dirPath, stage));
     const currentState = {
-        ...initVerifiableContextState(),
+        ...initContextGraphState(),
         ...(loadState(dirPath) ?? {}),
         stages: {
             ...(loadState(dirPath)?.stages ?? {}),
         },
     };
     const now = new Date().toISOString();
+    const fingerprint = computeStageFingerprint(dirPath, stage);
     currentState.stages[stage.id] = {
         contract_type: stage.contractType,
         status: "succeeded",
-        started_at: loadRuntimeRun(dirPath)?.started_at ?? now,
+        ...(fingerprint ? { fingerprint } : {}),
+        started_at: loadExecutionStageLedger(dirPath)?.started_at ?? now,
         finished_at: now,
         counts: activeRunCounts(dirPath),
         artifact_counts: Object.fromEntries(writeArtifacts.map((artifact) => [artifact.id, artifactCount(dirPath, artifact.path, artifact.kind)])),
         artifacts: writeArtifacts.map((artifact) => artifact.kind === "file" ? artifact.path : `${artifact.path}/`),
-        summary: loadRuntimeRun(dirPath)?.summary ?? null,
-        run_id: loadRuntimeRun(dirPath)?.run_id ?? null,
+        summary: loadExecutionStageLedger(dirPath)?.summary ?? null,
+        run_id: loadExecutionStageLedger(dirPath)?.run_id ?? null,
     };
     currentState.last_build = now;
     saveState(dirPath, currentState);
-    refreshVerifiableContextArtifacts(dirPath, { ensureViewSpec: true });
+    refreshContextGraphArtifacts(dirPath, { ensureViewSpec: true });
     return true;
 }

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

@@ -0,0 +1,10 @@
+import { type ExecutionStageLedger, type RuntimeStageContract } from "./lib/schema.js";
+import { type ExecutionStageLedgerPatch, type RuntimeStageExecutionOptions } from "./runtime-types.js";
+export declare function loadExecutionStageLedger(dirPath: string): ExecutionStageLedger | null;
+export declare function saveExecutionStageLedger(dirPath: string, run: ExecutionStageLedger): void;
+export declare function writeStageContract(dirPath: string, contract: RuntimeStageContract): string;
+export declare function runExecutorStage(options: RuntimeStageExecutionOptions): Promise<number>;
+export declare function beginExecutionStageLedger(dirPath: string, run: ExecutionStageLedger): ExecutionStageLedger;
+export declare function updateExecutionStageLedger(dirPath: string, patch: ExecutionStageLedgerPatch): ExecutionStageLedger | null;
+export declare function markExecutionStageLedgerFailedAfterValidation(dirPath: string, summary: string): ExecutionStageLedger | null;
+export declare function markExecutionStageLedgerSucceededAfterValidation(dirPath: string, summary: string): ExecutionStageLedger | null;