@interf/compiler 0.22.2 → 0.33.0

package/dist/packages/{engine → runtime}/build/lib/schema.js

@@ -1,30 +1,22 @@
 import { z } from "zod";
 import { BUILD_PLAN_ARTIFACT_KINDS, } from "../build-plan-primitives.js";
-import { ArtifactIdSchema, ArtifactSchema, CheckSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceBuildMaxAttemptsSchema, SourceBuildMaxLoopsSchema, InterfIdPattern, BuildPlanIdSchema, } from "../../../contracts/lib/schema.js";
+import { ArtifactIdSchema, ArtifactSchema, CheckSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, SourceBuildMaxAttemptsSchema, SourceBuildMaxLoopsSchema, InterfIdPattern, BuildPlanIdSchema, isInterfRelativePath, } from "../../../contracts/lib/schema.js";
 // `ArtifactSchema` is used internally below in `BuildPlanContextRawSchema`'s
 // `artifacts[]` field. The other Artifact* schemas/types are NOT
-// re-exported through this module — callers import them directly
-// from `contracts/lib/schema.js`. The 0.17 PR cross-check pruned
-// re-exports that had zero consumers.
-export { GateStatusSchema, ReadinessGateSchema, ReadinessSchema, ReadinessStatusSchema, VerifyTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, SourceBuildMaxAttemptsSchema, SourceBuildMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, BuildPlanIdSchema, } from "../../../contracts/lib/schema.js";
+// re-exported through this module — callers import them directly from
+// `contracts/lib/schema.js`. Re-exports with zero consumers were pruned
+// to keep this barrel narrow.
+export { GateStatusSchema, ReadinessGateSchema, ReadinessSchema, ReadinessStatusSchema, VerifyTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceManifestAuditSchema, SourceManifestEvidenceSchema, SourceManifestFileKindSchema, SourceManifestFileSchema, SourceManifestScannerSchema, SourceManifestSchema, SourceInspectableUnitSchema, SourceSchema, SourceStateSchema, StageInputSchema, StageInputsSchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, SourceBuildMaxAttemptsSchema, SourceBuildMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, BuildPlanIdSchema, } from "../../../contracts/lib/schema.js";
 const JsonRecordSchema = z.record(z.string(), z.unknown());
-const COMPILED_RELATIVE_PATH_SEGMENT = /^(?!\.{1,2}$)[^/\\]+$/;
-function isVerifiableContextRelativePath(value) {
-    if (value.length === 0)
-        return false;
-    if (value.startsWith("/") || value.startsWith("\\"))
-        return false;
-    return value
-        .split(/[\\/]+/)
-        .every((segment) => COMPILED_RELATIVE_PATH_SEGMENT.test(segment));
-}
 export const BuildPlanArtifactIdSchema = z.string().regex(InterfIdPattern);
 export const BuildPlanArtifactKindSchema = z.enum(BUILD_PLAN_ARTIFACT_KINDS);
-export const BuildPlanArtifactRoleSchema = z.enum(["input", "working", "output", "runtime"]);
+export const BuildPlanArtifactRoleSchema = z.literal("output");
 export const BuildStageStatusSchema = z.enum(["idle", "running", "succeeded", "failed"]);
-export const VerifiableContextStageStateSchema = z.object({
+export const StageFingerprintSchema = z.string().regex(/^[a-f0-9]{64}$/);
+export const ContextGraphStageStateSchema = z.object({
     contract_type: RuntimeContractTypeSchema.optional(),
     status: BuildStageStatusSchema.optional(),
+    fingerprint: StageFingerprintSchema.optional(),
     started_at: z.string().nullable().optional(),
     finished_at: z.string().nullable().optional(),
     counts: z.record(z.string(), z.number()).optional(),
@@ -33,10 +25,10 @@ export const VerifiableContextStageStateSchema = z.object({
     summary: z.string().nullable().optional(),
     run_id: z.string().nullable().optional(),
 });
-export const VerifiableContextStateSchema = z.object({
+export const ContextGraphStateSchema = z.object({
     version: z.number().int().min(1),
     pending: z.array(z.string()),
-    stages: z.record(z.string().regex(InterfIdPattern), VerifiableContextStageStateSchema).optional(),
+    stages: z.record(z.string().regex(InterfIdPattern), ContextGraphStageStateSchema).optional(),
     last_add: z.string().nullable().optional(),
     last_build: z.string().nullable().optional(),
     warning_count: z.number().optional(),
@@ -44,7 +36,7 @@ export const VerifiableContextStateSchema = z.object({
 }).strict();
 export const ViewSectionSchema = z.object({
     id: z.string(),
-    type: z.enum(["status", "cards", "graph", "documents", "table"]),
+    type: z.enum(["status", "cards", "flow", "documents", "table"]),
     title: z.string(),
     path: z.string().optional(),
     paths: z.array(z.string()).optional(),
@@ -56,8 +48,8 @@ export const ViewCardSchema = z.object({
     denominator_metric: z.string().optional(),
     format: z.enum(["number", "fraction", "timestamp"]),
 });
-export const VerifiableContextHealthSchema = z.object({
-    kind: z.literal("verifiable-context-health"),
+export const ContextGraphHealthSchema = z.object({
+    kind: z.literal("context-graph-health"),
     version: z.number().int().min(1),
     generated_at: z.string(),
     target_name: z.string(),
@@ -70,15 +62,15 @@ export const VerifiableContextHealthSchema = z.object({
     metrics: z.record(z.string(), z.number()),
     checks: z.record(z.string(), z.boolean()),
 });
-export const VerifiableContextViewSpecSchema = z.object({
-    kind: z.literal("verifiable-context-view-spec"),
+export const ContextGraphViewSpecSchema = z.object({
+    kind: z.literal("context-graph-view-spec"),
     version: z.number().int().min(1),
     generated_at: z.string(),
     target_name: z.string(),
     health_source: z.string(),
     state_source: z.string(),
     default_note: z.string().nullable(),
-    graph_scope: z.array(z.string()),
+    document_scope: z.array(z.string()),
     cards: z.array(ViewCardSchema),
     sections: z.array(ViewSectionSchema),
 });
@@ -86,29 +78,37 @@ export const BuildPlanPurposeSchema = z.object({
     label: z.string().min(1),
     task_hint: z.string().min(1),
 }).strict();
-export const BuildPlanArtifactProjectionSchema = z.object({
+/**
+ * Runtime projection of a single Build Plan artifact — the resolved
+ * shape stored in `.interf/build-plan/build-plan.json`. Distinct from
+ * the user-facing `Artifact` declaration in
+ * `contracts/lib/schema.ts` (which carries `shape`, `checks`, and
+ * `built_by_stages` at declaration time) and from `ArtifactRef` in
+ * `execution/lib/schema.ts` (the run-time event reference). One artifact
+ * passes through three lifecycle shapes: declared, projected, referenced.
+ */
+export const BuildPlanArtifactSchema = z.object({
     id: BuildPlanArtifactIdSchema,
     role: BuildPlanArtifactRoleSchema,
-    path: z.string().min(1).refine(isVerifiableContextRelativePath, {
-        message: "Artifact paths must stay inside the verifiable context root",
+    path: z.string().min(1).refine(isInterfRelativePath, {
+        message: "Artifact paths must stay inside the context graph root",
     }),
     kind: BuildPlanArtifactKindSchema,
     required: z.boolean(),
     owned_by: z.array(z.string().regex(InterfIdPattern)),
     description: z.string().min(1),
 });
-export const BuildPlanArtifactSchema = BuildPlanArtifactProjectionSchema;
 // Persisted schema for the Build Plan-defined artifact interface that one
-// verifiable context must implement on disk.
+// context graph must implement on disk.
 export const BuildPlanContextRawSchema = z.object({
     kind: z.literal("build-plan-schema"),
     version: z.literal(1),
-    target_type: z.literal("verifiable-context"),
+    target_type: z.literal("context-graph"),
     label: z.string().min(1),
     artifacts: z.array(ArtifactSchema).min(1),
 }).strict();
 export const BuildPlanContextSchemaSchema = BuildPlanContextRawSchema;
-export const BuildPlanEngineApiSchema = z.object({
+export const BuildPlanRuntimeApiSchema = z.object({
     kind: z.literal("build"),
     version: z.literal(1),
 });
@@ -178,7 +178,7 @@ export const RuntimeStageContractSchema = z.object({
         }).optional(),
     }),
 });
-export const RuntimeRunSchema = z.object({
+export const ExecutionStageLedgerSchema = z.object({
     kind: z.literal("interf-run"),
     version: z.literal(1),
     run_id: z.string(),
@@ -202,11 +202,31 @@ export const RuntimeRunSchema = z.object({
         event_stream_path: z.string(),
         status_path: z.string().optional(),
     }).optional(),
+    evidence_path: z.string().min(1).optional(),
+    evidence: z.lazy(() => StageEvidenceReconciliationSchema).optional(),
     summary: z.string(),
     exit_code: z.number().nullable(),
     error: z.string().nullable(),
 });
-export const RuntimeInventoryEntrySchema = z.object({
+export const RejectedStageEvidenceSchema = z.object({
+    kind: z.enum(["count", "item", "edge", "file"]),
+    id: z.string().min(1),
+    reason: z.string().min(1),
+}).strict();
+export const StageEvidenceReconciliationSchema = z.object({
+    kind: z.literal("interf-stage-evidence-reconciliation"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    evidence_path: z.string().min(1).nullable(),
+    accepted: z.object({
+        counts: z.array(StageEvidenceCountSchema).default([]),
+        items: z.array(StageEvidenceItemSchema).default([]),
+        edges: z.array(StageEvidenceEdgeSchema).default([]),
+    }).strict(),
+    rejected: z.array(RejectedStageEvidenceSchema).default([]),
+    warnings: z.array(z.string().min(1)).default([]),
+}).strict();
+export const ExecutionInventoryEntrySchema = z.object({
     input_artifact: ArtifactIdSchema.optional(),
     input_path: z.string().min(1).optional(),
     output_artifact: ArtifactIdSchema,
@@ -214,11 +234,11 @@ export const RuntimeInventoryEntrySchema = z.object({
     state: z.string().min(1).optional(),
     metadata: JsonRecordSchema.optional(),
 }).strict();
-export const RuntimeInventorySchema = z.object({
-    kind: z.literal("verifiable-context-runtime-ledger").optional(),
+export const ExecutionInventorySchema = z.object({
+    kind: z.literal("context-graph-runtime-ledger").optional(),
     version: z.number().int().min(1).optional(),
     stage: RuntimeStageSchema.optional(),
-    entries: z.array(RuntimeInventoryEntrySchema),
+    entries: z.array(ExecutionInventoryEntrySchema),
     total: z.number().int().nonnegative(),
 });
 export const BuildPlanImprovementLoopSummarySchema = z.object({
@@ -244,13 +264,13 @@ export const BuildPlanImprovementContextSchema = z.object({
     max_attempts: SourceBuildMaxAttemptsSchema,
     review_paths: z.object({
         build_plan_root: z.string(),
-        verifiable_context_runtime: z.string().nullable(),
-        readiness_runs: z.string().nullable(),
+        context_graph_runtime: z.string().nullable(),
+        benchmark_runs: z.string().nullable(),
         execution_shells: z.string().nullable(),
         test_runs: z.string().nullable(),
         test_sandboxes: z.string().nullable(),
     }),
-    readiness_checks: z.object({
+    benchmark_questions: z.object({
         count: z.number().int().min(0),
         questions: z.array(z.object({
             id: z.string(),
@@ -265,7 +285,7 @@ export const PreservedShellTypeSchema = z.enum([
     "build-plan-authoring",
     "build-plan-improvement",
 ]);
-export const PreservedShellSnapshotSchema = z.object({
+export const PreservedShellStateSchema = z.object({
     kind: z.literal("interf-preserved-shell"),
     version: z.literal(1),
     shell_type: PreservedShellTypeSchema,

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,4 +1,4 @@
-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 ?? [];
@@ -23,9 +23,9 @@ export function buildRuntimeStageContract(options) {
             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}".`,
                 "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.`,
+                `Use \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` as the deterministic requested Artifact contract for this context graph.`,
                 "Honor the declared read and write artifacts 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.",
@@ -36,8 +36,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/{engine → runtime}/build/runtime-paths.js

@@ -1,19 +1,19 @@
 import { join } from "node:path";
-import { verifiableContextRuntimeArchivedStageContractPath, verifiableContextRuntimeLogsRoot, verifiableContextRuntimeRunHistoryPath, verifiableContextRuntimeRunPath, verifiableContextRuntimeStageContractPath, } from "./verifiable-context-paths.js";
+import { contextGraphRuntimeArchivedStageContractPath, contextGraphRuntimeLogsRoot, contextGraphExecutionStageLedgerHistoryPath, contextGraphExecutionStageLedgerPath, contextGraphRuntimeStageContractPath, } from "./context-graph-paths.js";
 export function runPath(dirPath) {
-    return verifiableContextRuntimeRunPath(dirPath);
+    return contextGraphExecutionStageLedgerPath(dirPath);
 }
 export function runHistoryPath(dirPath) {
-    return verifiableContextRuntimeRunHistoryPath(dirPath);
+    return contextGraphExecutionStageLedgerHistoryPath(dirPath);
 }
 export function stageContractPath(dirPath) {
-    return verifiableContextRuntimeStageContractPath(dirPath);
+    return contextGraphRuntimeStageContractPath(dirPath);
 }
 export function archivedStageContractPath(dirPath, runId) {
-    return verifiableContextRuntimeArchivedStageContractPath(dirPath, runId);
+    return contextGraphRuntimeArchivedStageContractPath(dirPath, runId);
 }
 export function logsDirPath(dirPath) {
-    return verifiableContextRuntimeLogsRoot(dirPath);
+    return contextGraphRuntimeLogsRoot(dirPath);
 }
 export function promptLogPath(dirPath, runId) {
     return join(logsDirPath(dirPath), `${runId}.prompt.txt`);

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.",
             ]
             : [
@@ -23,16 +23,17 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         `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.",
+        "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.",
+        "Read only the files named by the contract's `artifacts.reads` list, `runtime/source-manifest.json`, `runtime/stage-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 +44,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;