@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/build/source-manifest.js

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { SourceFilesSchema, SourceManifestSchema, SourceStateSchema, StageInputsSchema, } from "../../contracts/lib/schema.js";
+import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { isFilesystemArtifact } from "../../contracts/utils/filesystem.js";
+import { contextGraphRuntimeSourceManifestPath, contextGraphRuntimeSourceFilesPath, contextGraphRuntimeSourceStatePath, contextGraphRuntimeStageInputsPath, } from "./context-graph-paths.js";
+import { writeJsonAtomic } from "./atomic-fs.js";
+function shortHash(value, length = 16) {
+    return createHash("sha256")
+        .update(value)
+        .digest("hex")
+        .slice(0, length);
+}
+function stageReadsSource(stage, _schema) {
+    if (stage.contractType === "build-file-evidence")
+        return true;
+    return stage.reads.includes("source");
+}
+export function selectStageSourceSlice(sourceState, stage, schema) {
+    if (!stageReadsSource(stage, schema))
+        return [];
+    return [...sourceState.files];
+}
+export function materializeStageSourceSlice(options) {
+    return StageInputsSchema.parse({
+        ...options.stageInputs,
+        input_total: options.stageInputs.inputs.length,
+        inputs: options.stageInputs.inputs,
+    });
+}
+export function buildShellSourceState(sourceState, stageInputs) {
+    const byId = new Map(sourceState.files.map((file) => [file.id, file]));
+    return SourceStateSchema.parse({
+        ...sourceState,
+        source: {
+            ...sourceState.source,
+            locator: sourceState.source.locator,
+        },
+        source_total: stageInputs.inputs.length,
+        files: stageInputs.inputs.map((input) => ({
+            ...(byId.get(input.source_file_id) ?? {
+                id: input.source_file_id,
+                path: input.path,
+                locator: input.locator,
+            }),
+            path: input.path,
+            locator: input.locator,
+        })),
+    });
+}
+/**
+ * Drop OS-generated filesystem junk (`.DS_Store`, AppleDouble forks, `Thumbs.db`,
+ * etc.) from the Source Manifest before it is materialized into runtime coverage
+ * inputs. These are not Source content, so they must never become required
+ * `expected` inputs — otherwise a Source folder shows "not ready" purely because
+ * Finder/Explorer left a sidecar behind. Matched by filename only (provable),
+ * never by an agent's `not-relevant` label, so a genuinely skipped content file
+ * still counts toward readiness. `source_total` is recomputed to stay equal to
+ * the filtered file count.
+ */
+export function dropFilesystemArtifacts(manifest) {
+    const files = manifest.files.filter((file) => !isFilesystemArtifact(file.path));
+    if (files.length === manifest.files.length)
+        return manifest;
+    return SourceManifestSchema.parse({
+        ...manifest,
+        source_total: files.length,
+        files,
+    });
+}
+export function sourceManifestToSourceFiles(manifest) {
+    return SourceFilesSchema.parse({
+        kind: "interf-source-files",
+        version: 1,
+        generated_at: manifest.generated_at,
+        source: manifest.source,
+        source_total: manifest.source_total,
+        files: manifest.files.map((file) => ({
+            id: file.id,
+            path: file.path,
+            locator: file.locator,
+            ...(typeof file.size_bytes === "number" ? { size_bytes: file.size_bytes } : {}),
+        })),
+    });
+}
+export function sourceManifestToSourceState(manifest) {
+    const sourceFiles = sourceManifestToSourceFiles(manifest);
+    return SourceStateSchema.parse({
+        kind: "interf-source-state",
+        version: 1,
+        graph_id: manifest.manifest_id,
+        generated_at: manifest.generated_at,
+        run_id: manifest.run_id,
+        source: manifest.source,
+        source_total: manifest.source_total,
+        files: sourceFiles.files,
+    });
+}
+/**
+ * Pure file-index hash. Excludes generated_at and run_id so the same source
+ * file index has a stable fingerprint across observations.
+ */
+export function computeFileIndexHash(sourceFiles) {
+    const fingerprint = {
+        source: sourceFiles.source,
+        files: sourceFiles.files.map((file) => [file.id, file.path, file.locator, file.size_bytes]),
+    };
+    return shortHash(JSON.stringify(fingerprint));
+}
+function writeJson(filePath, value) {
+    writeJsonAtomic(filePath, value);
+}
+export function buildBuildStageInputs(options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const sourceFiles = options.sourceFiles ?? options.sourceState.files;
+    return {
+        kind: "interf-stage-inputs",
+        version: 3,
+        generated_at: generatedAt,
+        run_id: options.runId ?? options.sourceState.run_id ?? null,
+        build_plan: options.buildPlanId,
+        stage: options.stageId,
+        source_state_id: options.sourceState.graph_id,
+        source_manifest_id: options.sourceManifestId ?? options.sourceState.graph_id,
+        input_total: sourceFiles.length,
+        inputs: sourceFiles.map((file) => {
+            const input = {
+                source_file_id: file.id,
+                path: file.path,
+                locator: file.locator,
+            };
+            const manifestFile = file;
+            if (typeof manifestFile.kind === "string")
+                input.kind = manifestFile.kind;
+            if (typeof manifestFile.size_bytes === "number")
+                input.size_bytes = manifestFile.size_bytes;
+            if (typeof manifestFile.page_count === "number")
+                input.page_count = manifestFile.page_count;
+            if (Array.isArray(manifestFile.inspectable_units))
+                input.inspectable_units = manifestFile.inspectable_units;
+            if (typeof manifestFile.content_hash === "string")
+                input.content_hash = manifestFile.content_hash;
+            return input;
+        }),
+    };
+}
+export function writeBuildStageInputs(options) {
+    const stageInputs = StageInputsSchema.parse(buildBuildStageInputs(options));
+    writeJson(contextGraphRuntimeStageInputsPath(options.contextGraphPath, options.stageId), stageInputs);
+    return stageInputs;
+}
+export function writeBuildSourceRuntimeFromManifest(options) {
+    const sourceManifest = dropFilesystemArtifacts(SourceManifestSchema.parse({
+        ...options.sourceManifest,
+        run_id: options.runId ?? options.sourceManifest.run_id,
+    }));
+    writeJson(contextGraphRuntimeSourceManifestPath(options.contextGraphPath), sourceManifest);
+    const sourceFiles = sourceManifestToSourceFiles(sourceManifest);
+    writeJson(contextGraphRuntimeSourceFilesPath(options.contextGraphPath), sourceFiles);
+    const sourceState = SourceStateSchema.parse(sourceManifestToSourceState(sourceManifest));
+    writeJson(contextGraphRuntimeSourceStatePath(options.contextGraphPath), sourceState);
+    const manifestFilesById = new Map(sourceManifest.files.map((file) => [file.id, file]));
+    const stagesById = new Map((options.stages ?? []).map((stage) => [stage.id, stage]));
+    const stageInputs = options.stageIds.map((stageId) => {
+        const stage = stagesById.get(stageId);
+        const stateSlice = stage
+            ? selectStageSourceSlice(sourceState, stage, options.schema)
+            : sourceState.files;
+        const sourceFilesForStage = stateSlice
+            .map((file) => manifestFilesById.get(file.id) ?? file);
+        return writeBuildStageInputs({
+            contextGraphPath: options.contextGraphPath,
+            buildPlanId: options.buildPlanId,
+            stageId,
+            sourceState,
+            sourceFiles: sourceFilesForStage,
+            sourceManifestId: sourceManifest.manifest_id,
+            runId: options.runId ?? null,
+            generatedAt: sourceManifest.generated_at,
+        });
+    });
+    return { sourceFiles, sourceState, stageInputs };
+}
+export function loadContextGraphSourceManifest(contextGraphPath) {
+    const filePath = contextGraphRuntimeSourceManifestPath(contextGraphPath);
+    if (!existsSync(filePath))
+        return null;
+    return readJsonFileWithSchema(filePath, "context-graph source manifest", SourceManifestSchema);
+}
+// COMPAT — source-files.json / source-state.json file fallbacks are read by
+// loaders only when no Source Manifest exists (pre-refactor builds). Every
+// current Build writes the Source Manifest first via
+// writeBuildSourceRuntimeFromManifest; the manifest is the authority. Removal
+// path: once no live Context Graph predates Source Manifest, drop the file
+// fallbacks and have these loaders return null whenever the manifest is
+// missing.
+export function loadContextGraphSourceFiles(contextGraphPath) {
+    const manifest = loadContextGraphSourceManifest(contextGraphPath);
+    if (manifest)
+        return sourceManifestToSourceFiles(manifest);
+    const filePath = contextGraphRuntimeSourceFilesPath(contextGraphPath);
+    if (!existsSync(filePath))
+        return null;
+    return readJsonFileWithSchema(filePath, "context-graph source files", SourceFilesSchema);
+}
+export function loadContextGraphSourceState(contextGraphPath) {
+    const manifest = loadContextGraphSourceManifest(contextGraphPath);
+    if (manifest)
+        return sourceManifestToSourceState(manifest);
+    const filePath = contextGraphRuntimeSourceStatePath(contextGraphPath);
+    if (!existsSync(filePath))
+        return null;
+    return readJsonFileWithSchema(filePath, "context-graph source state", SourceStateSchema);
+}
+export function loadBuildStageInputs(contextGraphPath, stageId) {
+    const filePath = contextGraphRuntimeStageInputsPath(contextGraphPath, stageId);
+    if (!existsSync(filePath))
+        return null;
+    return readJsonFileWithSchema(filePath, "context-graph stage inputs", StageInputsSchema);
+}

package/dist/packages/runtime/build/stage-evidence.d.ts

@@ -0,0 +1,22 @@
+import { type RuntimeStageContract, type StageEvidenceReconciliation } from "./lib/schema.js";
+interface StageEvidenceStageLike {
+    id: string;
+    contractType: string;
+    writes: readonly string[];
+}
+export declare function supportsStageEvidenceHarness(stage: {
+    contractType: string;
+}): boolean;
+export declare function shellStageEvidencePath(executionPath: string): string;
+export declare function shellStageHarnessPath(executionPath: string): string;
+export declare function writeStageHarnessProjection(options: {
+    executionPath: string;
+    contract: RuntimeStageContract;
+}): void;
+export declare function reconcileStageEvidence(options: {
+    contextGraphPath: string;
+    shellRoot: string;
+    stage: StageEvidenceStageLike;
+}): StageEvidenceReconciliation | null;
+export declare function stageEvidenceAcceptanceFailure(reconciliation: StageEvidenceReconciliation | null): string | null;
+export {};

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

@@ -0,0 +1,386 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { StageEvidenceSchema, } from "../../contracts/lib/schema.js";
+import { buildPlanPackagePathForContextGraph, contextGraphRuntimeLogsRoot, } from "./context-graph-paths.js";
+import { relativePathEqualsOrWithin } from "../agents/lib/shell-paths.js";
+import { findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./context-graph-schema.js";
+import { StageEvidenceReconciliationSchema, } from "./lib/schema.js";
+import { loadBuildStageInputs } from "./source-manifest.js";
+import { loadExecutionStageLedger, updateExecutionStageLedger, } from "./runtime-runs.js";
+/**
+ * Relativize a stage evidence/output-ref path so it is always graph-relative.
+ *
+ * This is intentionally MORE permissive than the canonical `normalizeLayerPath`
+ * (`contracts/lib/context-graph-layer.ts`): its leading regex is `/^\.?\//`, so
+ * it strips a bare leading `/` as well as a leading `./`. An agent-reported
+ * output ref may arrive as `/outputs/...` or `/runtime/...`; this strips the
+ * absolute-looking prefix so the downstream `runtime/`/`outputs/` membership
+ * tests compare graph-relative paths. It is NOT the canonical layer-path
+ * normalization and must not be swapped for it.
+ */
+function normalizeGraphRelativeRefPath(path) {
+    return path.replaceAll("\\", "/").replace(/^\.?\//, "").replace(/\/+$/g, "");
+}
+export function supportsStageEvidenceHarness(stage) {
+    return stage.contractType === "build-file-evidence";
+}
+export function shellStageEvidencePath(executionPath) {
+    return join(executionPath, "runtime", "stage-evidence.json");
+}
+export function shellStageHarnessPath(executionPath) {
+    return join(executionPath, "runtime", "stage.md");
+}
+export function writeStageHarnessProjection(options) {
+    if (!supportsStageEvidenceHarness({ contractType: options.contract.contract_type }))
+        return;
+    const runtimeRoot = join(options.executionPath, "runtime");
+    mkdirSync(runtimeRoot, { recursive: true });
+    const evidencePath = shellStageEvidencePath(options.executionPath);
+    if (!existsSync(evidencePath)) {
+        const starterEvidence = {
+            kind: "interf-stage-evidence",
+            version: 1,
+            run_id: options.contract.run_id,
+            stage: options.contract.stage,
+            counts: [],
+            items: [],
+            edges: [],
+        };
+        writeFileSync(evidencePath, `${JSON.stringify(starterEvidence, null, 2)}\n`);
+    }
+    writeFileSync(shellStageHarnessPath(options.executionPath), renderStageHarnessMarkdown(options.contract));
+}
+function renderStageHarnessMarkdown(contract) {
+    return [
+        "---",
+        "kind: interf-stage-harness",
+        "version: 1",
+        `run_id: ${contract.run_id}`,
+        `project_id: ${contract.target_name}`,
+        `build_plan: ${contract.build_plan.id}`,
+        `stage: ${contract.stage}`,
+        "contract_path: runtime/stage-contract.json",
+        "paths_path: runtime/paths.json",
+        "source_manifest_path: runtime/source-manifest.json",
+        "stage_inputs_path: runtime/stage-inputs.json",
+        "evidence_output_path: runtime/stage-evidence.json",
+        "---",
+        "",
+        "# Stage Harness",
+        "",
+        "Read the JSON contract first. This markdown file is a generated projection for the current stage only.",
+        "",
+        "## Evidence",
+        "",
+        "Write `runtime/stage-evidence.json` before you emit DONE.",
+        "Each evidence item must reference real assigned Source paths or declared output paths.",
+        "Do NOT list `runtime/reviewed-inputs.json` or any other `runtime/*` path in `output_refs`. Those files are runtime control surfaces, not stage outputs; the runner records them separately. Evidence outputs must live under a declared artifact path.",
+        "Agent status lines and self-reported completion do not count as accepted evidence.",
+        "",
+        "Minimum shape:",
+        "",
+        "```json",
+        JSON.stringify({
+            kind: "interf-stage-evidence",
+            version: 1,
+            run_id: contract.run_id,
+            stage: contract.stage,
+            counts: [
+                {
+                    key: "files_processed",
+                    label: "Files processed",
+                    value: 0,
+                    total: contract.counts.source_total ?? 0,
+                    unit: "files",
+                    source: "stage",
+                    stage_id: contract.stage,
+                    primary: true,
+                },
+            ],
+            items: [],
+            edges: [],
+        }, null, 2),
+        "```",
+        "",
+    ].join("\n");
+}
+export function reconcileStageEvidence(options) {
+    if (!supportsStageEvidenceHarness(options.stage))
+        return null;
+    const run = loadExecutionStageLedger(options.contextGraphPath);
+    if (!run)
+        return null;
+    const evidenceFilePath = shellStageEvidencePath(options.shellRoot);
+    const persistedEvidencePath = persistRawStageEvidence({
+        contextGraphPath: options.contextGraphPath,
+        evidenceFilePath,
+        run,
+    });
+    let parsed;
+    try {
+        parsed = StageEvidenceSchema.parse(JSON.parse(readFileSync(evidenceFilePath, "utf8")));
+    }
+    catch (error) {
+        const reconciliation = makeReconciliation({
+            evidencePath: persistedEvidencePath,
+            rejected: [{
+                    kind: "file",
+                    id: "stage-evidence-json",
+                    reason: `Invalid stage evidence JSON: ${error instanceof Error ? error.message : String(error)}`,
+                }],
+        });
+        updateExecutionStageLedger(options.contextGraphPath, {
+            evidence_path: persistedEvidencePath ?? undefined,
+            evidence: reconciliation,
+        });
+        return reconciliation;
+    }
+    const reconciliation = reconcileParsedStageEvidence({
+        contextGraphPath: options.contextGraphPath,
+        evidence: parsed,
+        evidencePath: persistedEvidencePath,
+        run,
+        stage: options.stage,
+    });
+    updateExecutionStageLedger(options.contextGraphPath, {
+        evidence_path: persistedEvidencePath ?? undefined,
+        evidence: reconciliation,
+    });
+    return reconciliation;
+}
+export function stageEvidenceAcceptanceFailure(reconciliation) {
+    if (!reconciliation) {
+        return "Stage evidence was not reconciled.";
+    }
+    if (reconciliation.rejected.length > 0) {
+        const first = reconciliation.rejected[0];
+        return `Stage evidence was rejected: ${first.id}: ${first.reason}`;
+    }
+    const acceptedItems = reconciliation.accepted.items;
+    if (acceptedItems.length === 0) {
+        return "Stage evidence needs at least one accepted source/output evidence item.";
+    }
+    const hasAcceptedRef = acceptedItems.some((item) => item.source_refs.length > 0 || item.output_refs.length > 0);
+    if (!hasAcceptedRef) {
+        return "Stage evidence items need accepted source or output refs.";
+    }
+    return null;
+}
+function persistRawStageEvidence(options) {
+    if (!existsSync(options.evidenceFilePath))
+        return null;
+    const targetPath = join(contextGraphRuntimeLogsRoot(options.contextGraphPath), `${options.run.run_id}.stage-evidence.json`);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    copyFileSync(options.evidenceFilePath, targetPath);
+    return relative(options.contextGraphPath, targetPath).replaceAll("\\", "/");
+}
+function reconcileParsedStageEvidence(options) {
+    const rejected = [];
+    if (options.evidence.run_id !== options.run.run_id) {
+        rejected.push({
+            kind: "file",
+            id: "run-id",
+            reason: `Evidence run_id "${options.evidence.run_id}" does not match active run "${options.run.run_id}".`,
+        });
+    }
+    if (options.evidence.stage !== options.stage.id || options.evidence.stage !== options.run.stage) {
+        rejected.push({
+            kind: "file",
+            id: "stage",
+            reason: `Evidence stage "${options.evidence.stage}" does not match active stage "${options.run.stage}".`,
+        });
+    }
+    if (rejected.length > 0) {
+        return makeReconciliation({ evidencePath: options.evidencePath, rejected });
+    }
+    const stageInputs = loadBuildStageInputs(options.contextGraphPath, options.stage.id);
+    const allowedSourcePaths = new Set((stageInputs?.inputs ?? []).map((input) => input.path));
+    const allowedSourceIds = new Set((stageInputs?.inputs ?? []).map((input) => input.source_file_id));
+    const acceptedItems = [];
+    const droppedRuntimeRefs = [];
+    for (const rawItem of options.evidence.items) {
+        const { item, droppedRuntimeRefs: itemDropped } = normalizeEvidenceItem({
+            contextGraphPath: options.contextGraphPath,
+            item: rawItem,
+        });
+        if (itemDropped.length > 0)
+            droppedRuntimeRefs.push(...itemDropped.map((p) => `${item.id}: ${p}`));
+        // If an item was entirely composed of runtime/* output refs (with no source refs),
+        // dropping those refs leaves nothing to validate. Skip with a warning instead of
+        // rejecting — the agent already records that coverage via runtime/reviewed-inputs.json.
+        const itemWasPurelyRuntime = itemDropped.length > 0 &&
+            item.output_refs.length === 0 &&
+            item.source_refs.length === 0;
+        if (itemWasPurelyRuntime)
+            continue;
+        const reason = invalidItemReason({
+            contextGraphPath: options.contextGraphPath,
+            item,
+            allowedSourceIds,
+            allowedSourcePaths,
+            stage: options.stage,
+        });
+        if (reason) {
+            rejected.push({ kind: "item", id: item.id, reason });
+        }
+        else {
+            acceptedItems.push(item);
+        }
+    }
+    const acceptedSourceRefCount = new Set(acceptedItems.flatMap((item) => item.source_refs.map((ref) => ref.path))).size;
+    const acceptedCounts = [];
+    for (const count of options.evidence.counts) {
+        const reason = invalidCountReason({
+            count,
+            acceptedItems,
+            acceptedSourceRefCount,
+            stage: options.stage,
+        });
+        if (reason) {
+            rejected.push({ kind: "count", id: count.key, reason });
+        }
+        else {
+            acceptedCounts.push(count);
+        }
+    }
+    const acceptedItemIds = new Set(acceptedItems.map((item) => item.id));
+    const acceptedEdges = [];
+    const warnings = [...(options.evidence.warnings ?? [])];
+    for (const dropped of droppedRuntimeRefs) {
+        warnings.push(`Dropped output ref ${dropped}; runtime/* paths are control surfaces, not stage outputs.`);
+    }
+    for (const edge of options.evidence.edges) {
+        if (edge.stage_id !== options.stage.id) {
+            rejected.push({ kind: "edge", id: `${edge.from}:${edge.to}`, reason: "Edge stage does not match the active stage." });
+        }
+        else if (!acceptedItemIds.has(edge.from) || !acceptedItemIds.has(edge.to)) {
+            warnings.push(`Dropped evidence edge ${edge.from}:${edge.to}; endpoints were not both accepted evidence items.`);
+        }
+        else {
+            acceptedEdges.push(edge);
+        }
+    }
+    return makeReconciliation({
+        evidencePath: options.evidencePath,
+        accepted: {
+            counts: acceptedCounts,
+            items: acceptedItems,
+            edges: acceptedEdges,
+        },
+        rejected,
+        warnings,
+    });
+}
+function normalizeEvidenceItem(options) {
+    const droppedRuntimeRefs = [];
+    const output_refs = [];
+    for (const outputRef of options.item.output_refs) {
+        const normalized = normalizeEvidenceOutputRef({
+            contextGraphPath: options.contextGraphPath,
+            outputRef,
+        });
+        if (normalizeGraphRelativeRefPath(normalized.path).startsWith("runtime/")) {
+            droppedRuntimeRefs.push(normalized.path);
+            continue;
+        }
+        output_refs.push(normalized);
+    }
+    return {
+        item: { ...options.item, output_refs },
+        droppedRuntimeRefs,
+    };
+}
+function normalizeEvidenceOutputRef(options) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(options.contextGraphPath));
+    const artifact = schema ? findBuildPlanContextArtifact(schema, options.outputRef.artifact_id) : null;
+    if (!artifact)
+        return options.outputRef;
+    const path = normalizeGraphRelativeRefPath(options.outputRef.path);
+    const artifactRoot = normalizeGraphRelativeRefPath(artifact.path);
+    const outputMount = `outputs/${options.outputRef.artifact_id}`;
+    if (path === outputMount) {
+        return { ...options.outputRef, path: artifactRoot };
+    }
+    if (path.startsWith(`${outputMount}/`)) {
+        return {
+            ...options.outputRef,
+            path: normalizeGraphRelativeRefPath(`${artifactRoot}/${path.slice(outputMount.length + 1)}`),
+        };
+    }
+    if (path.startsWith("outputs/")) {
+        const stripped = normalizeGraphRelativeRefPath(path.slice("outputs/".length));
+        if (relativePathEqualsOrWithin(artifactRoot, stripped)) {
+            return { ...options.outputRef, path: stripped };
+        }
+    }
+    return options.outputRef;
+}
+function invalidItemReason(options) {
+    if (options.item.stage_id !== options.stage.id)
+        return "Item stage does not match the active stage.";
+    if (options.item.source_refs.length === 0 && options.item.output_refs.length === 0) {
+        return "Evidence items need at least one source or output ref.";
+    }
+    for (const sourceRef of options.item.source_refs) {
+        if (!options.allowedSourcePaths.has(sourceRef.path)) {
+            return `Source ref "${sourceRef.path}" is not assigned to this stage.`;
+        }
+        if (sourceRef.source_file_id && !options.allowedSourceIds.has(sourceRef.source_file_id)) {
+            return `Source file id "${sourceRef.source_file_id}" is not assigned to this stage.`;
+        }
+    }
+    for (const outputRef of options.item.output_refs) {
+        const reason = invalidOutputRefReason(options.contextGraphPath, outputRef, options.stage);
+        if (reason)
+            return reason;
+    }
+    return null;
+}
+function invalidOutputRefReason(contextGraphPath, outputRef, stage) {
+    if (!stage.writes.includes(outputRef.artifact_id)) {
+        return `Output ref artifact "${outputRef.artifact_id}" is not declared as a stage write.`;
+    }
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
+    const artifact = schema ? findBuildPlanContextArtifact(schema, outputRef.artifact_id) : null;
+    if (!artifact)
+        return `Output ref artifact "${outputRef.artifact_id}" is not in the Build Plan schema.`;
+    if (!relativePathEqualsOrWithin(artifact.path, outputRef.path)) {
+        return `Output ref path "${outputRef.path}" is outside artifact "${artifact.id}".`;
+    }
+    if (!existsSync(join(contextGraphPath, outputRef.path))) {
+        return `Output ref path "${outputRef.path}" does not exist in the Context Graph.`;
+    }
+    return null;
+}
+function invalidCountReason(options) {
+    if (options.count.source === "engine")
+        return "Stage evidence cannot claim engine-owned counts.";
+    if (options.count.stage_id && options.count.stage_id !== options.stage.id) {
+        return "Count stage does not match the active stage.";
+    }
+    if (options.count.artifact_id && !options.stage.writes.includes(options.count.artifact_id)) {
+        return `Count artifact "${options.count.artifact_id}" is not declared as a stage write.`;
+    }
+    if (options.count.key === "files_processed" && options.count.value > options.acceptedSourceRefCount) {
+        return "files_processed cannot exceed accepted source refs.";
+    }
+    if (options.count.value > 0 && options.acceptedItems.length === 0) {
+        return "Positive stage counts need at least one accepted evidence item.";
+    }
+    return null;
+}
+function makeReconciliation(options) {
+    return StageEvidenceReconciliationSchema.parse({
+        kind: "interf-stage-evidence-reconciliation",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        evidence_path: options.evidencePath,
+        accepted: options.accepted ?? {
+            counts: [],
+            items: [],
+            edges: [],
+        },
+        rejected: options.rejected ?? [],
+        warnings: options.warnings ?? [],
+    });
+}

package/dist/packages/runtime/build/stage-manifest.d.ts

@@ -0,0 +1,45 @@
+import { type ExpectedInputsFile, type GraphManifest, type SourceManifest, type StageManifest, type StageInputs } from "../../contracts/lib/schema.js";
+import type { BuildPlanStageDefinition } from "../../build-plans/package/build-plan-definitions.js";
+export declare function persistStageReviewedInputsFromShell(options: {
+    contextGraphPath: string;
+    shellRoot: string;
+    stageId: string;
+}): {
+    ok: boolean;
+    summary: string;
+};
+export declare function writeStageExpectedInputs(options: {
+    contextGraphPath: string;
+    stage: Pick<BuildPlanStageDefinition, "id" | "reads" | "writes" | "contractType">;
+    generatedAt?: string;
+}): ExpectedInputsFile | null;
+export declare function writeSourceStageManifest(options: {
+    contextGraphPath: string;
+    buildPlanId: string;
+    sourceManifest: SourceManifest;
+    runId?: string | null;
+    generatedAt?: string;
+}): StageManifest;
+export declare function loadStageManifest(contextGraphPath: string, stageId: string): StageManifest | null;
+export declare function listStageManifests(contextGraphPath: string): StageManifest[];
+export declare function writeStageManifestFromOutputs(options: {
+    contextGraphPath: string;
+    buildPlanId: string;
+    projectId: string;
+    runId?: string | null;
+    stage: BuildPlanStageDefinition;
+    generatedAt?: string;
+}): StageManifest | null;
+export declare function loadGraphManifest(contextGraphPath: string): GraphManifest | null;
+export declare function writeGraphManifest(options: {
+    contextGraphPath: string;
+    projectId: string;
+    buildPlanId: string;
+    intent?: string | null;
+    runId?: string | null;
+    graphId?: string | null;
+    generatedAt?: string;
+}): GraphManifest;
+export declare function reviewedInputsFilePath(contextGraphPath: string, stageId: string): string;
+export declare function expectedInputsFilePath(contextGraphPath: string, stageId: string): string;
+export declare function loadStageInputsForManifest(contextGraphPath: string, stageId: string): StageInputs | null;