@interf/compiler 0.22.2 → 0.50.0

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

@@ -0,0 +1,512 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { SourceManifestSchema, } from "../../contracts/lib/schema.js";
+import { buildRuntimeExecutorInfo } from "../agents/lib/executors.js";
+import { shellEventLogPath, shellPromptLogPath, shellStatusLogPath, } from "../agents/lib/shell-paths.js";
+import { renderClaudeBootstrap, } from "../agents/lib/shell-templates.js";
+import { freezePreservedShell, writeIfChanged, writeNativeSkillCopies, } from "../agents/lib/shell-fs.js";
+import { writeStageExecutionWorkspaceManifest, } from "../agents/lib/shell-workspace.js";
+import { contextGraphRuntimeSourceManifestPath, stageExecutionShellsRoot, } from "./context-graph-paths.js";
+import { dropFilesystemArtifacts, loadContextGraphSourceManifest, writeBuildSourceRuntimeFromManifest, } from "./source-manifest.js";
+import { writeSourceStageManifest, } from "./stage-manifest.js";
+import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
+import { markStageExecutionSessionsShellPreserved, recordStageExecutionSessionValidationAttempt, writeStageExecutionSessionFinished, writeStageExecutionSessionStarted, } from "./stage-session.js";
+function sourceInventoryShellRoot(contextGraphPath, attempt) {
+    return join(stageExecutionShellsRoot(contextGraphPath), `source-inventory-${Date.now().toString(36)}-${attempt}`);
+}
+function sourceInventoryPrompt(options) {
+    const runtimeInfo = buildRuntimeExecutorInfo(options.executor);
+    const skeleton = {
+        kind: "interf-source-manifest",
+        version: 1,
+        manifest_id: `manifest-${options.runId ?? "run"}-${options.attempt}`,
+        generated_at: new Date().toISOString(),
+        run_id: options.runId ?? null,
+        project: options.project,
+        source: {
+            id: "src-agent-observed",
+            kind: "local-folder",
+            locator: options.sourceLocator,
+        },
+        scanner: {
+            executor: runtimeInfo.name,
+            agent_label: runtimeInfo.display_name,
+            attempt: options.attempt,
+        },
+        source_total: 1,
+        files: [
+            {
+                id: "file-example",
+                path: "relative/path/from/source.pdf",
+                locator: "agent-readable/source/ref",
+                kind: "pdf",
+                page_count: 1,
+                inspectable_units: [
+                    { kind: "page", index: 1, label: "page 1" },
+                ],
+                confidence: "high",
+                evidence: [
+                    {
+                        kind: "agent-observation",
+                        summary: "Replace this with what you observed.",
+                    },
+                ],
+            },
+        ],
+        warnings: [],
+    };
+    return [
+        "You are the Interf Source inventory agent.",
+        "Interf does not read or copy the user's Source files. You own Source access through your normal tools.",
+        `Project: ${options.project}`,
+        ...(options.projectIntent ? [`Project intent: ${options.projectIntent}`] : []),
+        `Source locator: ${options.sourceLocator}`,
+        "Read `runtime/source-locator.json` first.",
+        "List every Source file you can access. Use paths relative to the Source locator.",
+        "Use canonical file kinds only: pdf, document, spreadsheet, presentation, image, text, other. Markdown, txt, and plain-text files must use kind `text`.",
+        "For plain text or markdown files, use an inspectable unit like `{ \"kind\": \"file\", \"index\": 1, \"label\": \"whole file\" }` when useful.",
+        "For PDFs, decks, sheets, and other multi-unit files, record page/slide/sheet/table/image/section units when you can.",
+        "Do not copy Source files into this shell.",
+        "Write exactly one JSON file at runtime/source-manifest.json.",
+        "The JSON must match this shape, with real values replacing the example:",
+        JSON.stringify(skeleton, null, 2),
+        ...(options.feedback ? ["", `Previous validation feedback: ${options.feedback}`] : []),
+        "",
+        "Emit DONE: source inventory complete after runtime/source-manifest.json is written.",
+    ].join("\n");
+}
+function renderSourceInventoryAgents(options) {
+    return [
+        `# ${options.project} — Source Inventory Execution Shell`,
+        "",
+        "This is an isolated Interf execution shell for Source inventory.",
+        "It is a replayable stage workspace: prompts, logs, contract, input locator, and output manifest live here.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/stage-contract.json` now.",
+        "2. Read `runtime/source-locator.json` now.",
+        "3. Use the local native `interf-stage` skill now.",
+        "4. Write exactly one output: `runtime/source-manifest.json`.",
+        "",
+        "## Boundaries",
+        "",
+        `- Build Plan: \`${options.buildPlanId}\`.`,
+        "- Stage: `source-inventory`.",
+        "- Do not copy Source files into this shell.",
+        "- Source files remain read-only and external to Interf.",
+        "- Record every accessible Source file, inspectable units, and human-readable evidence.",
+        "",
+        "## Goal",
+        "",
+        "- produce a Source Manifest that future stages can use deterministically",
+        "- preserve Source file paths relative to the Source locator",
+        "- stop once `runtime/source-manifest.json` is valid",
+        "",
+    ].join("\n");
+}
+function renderSourceInventorySkill() {
+    return [
+        "---",
+        "name: interf-stage",
+        "description: >",
+        "  Native local execution skill for the Interf Source inventory stage.",
+        "  Use it only inside an automated Source inventory execution shell.",
+        "---",
+        "",
+        "# Interf Source Inventory",
+        "",
+        "Read `runtime/stage-contract.json` and `runtime/source-locator.json` first.",
+        "Inspect the Source through your own tools. Do not copy Source files into the shell.",
+        "Write `runtime/source-manifest.json` with every accessible Source file, Source-relative path, inspectable units, and evidence.",
+        "Emit DONE only after the manifest exists and matches the contract.",
+        "",
+    ].join("\n");
+}
+function writeSourceInventoryShellSurface(options) {
+    const agents = renderSourceInventoryAgents({
+        project: options.project,
+        buildPlanId: options.buildPlanId,
+    });
+    writeIfChanged(join(options.shellRoot, "AGENTS.md"), `${agents.trimEnd()}\n`);
+    writeIfChanged(join(options.shellRoot, "CLAUDE.md"), renderClaudeBootstrap(agents));
+    writeNativeSkillCopies(options.shellRoot, "interf-stage", renderSourceInventorySkill());
+}
+function readShellManifest(shellRoot) {
+    const manifestPath = join(shellRoot, "runtime", "source-manifest.json");
+    const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+    return SourceManifestSchema.parse(normalizeSourceManifestCandidate(raw));
+}
+function normalizeSourceManifestCandidate(value) {
+    if (!value || typeof value !== "object" || !Array.isArray(value.files)) {
+        return value;
+    }
+    return {
+        ...value,
+        files: (value.files).map((file) => {
+            if (!file || typeof file !== "object")
+                return file;
+            const candidate = file;
+            return {
+                ...candidate,
+                kind: normalizeSourceFileKind(candidate.kind, candidate.path),
+            };
+        }),
+    };
+}
+function normalizeSourceFileKind(kind, path) {
+    const raw = typeof kind === "string" ? kind.trim().toLowerCase() : "";
+    const normalized = raw.replaceAll("_", "-").replace(/\s+/g, "-");
+    if (["pdf", "document", "spreadsheet", "presentation", "image", "text", "other"].includes(normalized)) {
+        return normalized;
+    }
+    if (["markdown", "md", "txt", "plain-text", "text-file", "source-text"].includes(normalized))
+        return "text";
+    if (["doc", "docx", "word"].includes(normalized))
+        return "document";
+    if (["sheet", "sheets", "table", "csv", "tsv", "xls", "xlsx"].includes(normalized))
+        return "spreadsheet";
+    if (["deck", "slide", "slides", "ppt", "pptx"].includes(normalized))
+        return "presentation";
+    if (["jpg", "jpeg", "png", "gif", "webp", "svg"].includes(normalized))
+        return "image";
+    if (typeof path === "string") {
+        if (/\.(md|markdown|txt|text)$/i.test(path))
+            return "text";
+        if (/\.(doc|docx|rtf|odt)$/i.test(path))
+            return "document";
+        if (/\.(csv|tsv|xls|xlsx)$/i.test(path))
+            return "spreadsheet";
+        if (/\.(ppt|pptx|odp)$/i.test(path))
+            return "presentation";
+        if (/\.(jpe?g|png|gif|webp|svg)$/i.test(path))
+            return "image";
+        if (/\.pdf$/i.test(path))
+            return "pdf";
+    }
+    return kind === undefined ? undefined : "other";
+}
+function contextGraphRelativePath(contextGraphPath, filePath) {
+    return relative(contextGraphPath, filePath).replaceAll("\\", "/");
+}
+function sourceInventoryShellLogs(options) {
+    return {
+        prompt_path: contextGraphRelativePath(options.contextGraphPath, shellPromptLogPath(options.shellRoot, options.inventoryRunId)),
+        event_stream_path: contextGraphRelativePath(options.contextGraphPath, shellEventLogPath(options.shellRoot, options.inventoryRunId)),
+        status_path: contextGraphRelativePath(options.contextGraphPath, shellStatusLogPath(options.shellRoot, options.inventoryRunId)),
+        contract_path: contextGraphRelativePath(options.contextGraphPath, join(options.shellRoot, "runtime", "stage-contract.json")),
+    };
+}
+function validateScannerManifest(options) {
+    const runtimeInfo = buildRuntimeExecutorInfo(options.executor);
+    if (options.manifest.project !== options.project) {
+        throw new Error(`Source Manifest project ${options.manifest.project} does not match ${options.project}.`);
+    }
+    if (options.manifest.source.locator !== options.sourceLocator) {
+        throw new Error("Source Manifest source locator does not match the Project Source locator.");
+    }
+    if (options.manifest.scanner.executor !== runtimeInfo.name) {
+        throw new Error(`Source Manifest scanner executor ${options.manifest.scanner.executor} does not match ${runtimeInfo.name}.`);
+    }
+    if (options.manifest.scanner.attempt !== options.attempt) {
+        throw new Error(`Source Manifest scanner attempt ${options.manifest.scanner.attempt} does not match ${options.attempt}.`);
+    }
+    return options.manifest;
+}
+function validateReusableManifest(options) {
+    if (options.manifest.project !== options.project) {
+        throw new Error(`Existing Source Manifest project ${options.manifest.project} does not match ${options.project}.`);
+    }
+    if (options.manifest.source.locator !== options.sourceLocator) {
+        throw new Error("Existing Source Manifest source locator does not match the Project Source locator.");
+    }
+    return options.manifest;
+}
+async function emitInventoryEvent(sink, runId, type, summary, logs) {
+    if (!sink || !runId)
+        return;
+    const base = {
+        event_id: createRunEventId("event"),
+        run_id: runId,
+        timestamp: createRunEventTimestamp(),
+        stage_id: "source-inventory",
+    };
+    if (type === "stage.started") {
+        await sink.emit({ ...base, type, ...(logs ? { logs } : {}) });
+    }
+    else if (type === "stage.passed") {
+        await sink.emit({ ...base, type, ...(summary ? { summary } : {}) });
+    }
+    else {
+        await sink.emit({ ...base, type, error: summary ?? "Source inventory failed." });
+    }
+}
+export async function runSourceInventory(options) {
+    const existing = loadContextGraphSourceManifest(options.contextGraphPath);
+    if (existing) {
+        try {
+            validateReusableManifest({
+                manifest: existing,
+                project: options.project,
+                sourceLocator: options.sourceLocator,
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                code: 1,
+                summary: error instanceof Error ? error.message : String(error),
+                manifest: null,
+            };
+        }
+        writeBuildSourceRuntimeFromManifest({
+            contextGraphPath: options.contextGraphPath,
+            buildPlanId: options.buildPlanId,
+            stageIds: options.stageIds,
+            stages: options.stages,
+            schema: options.schema,
+            sourceManifest: existing,
+            runId: options.runId ?? existing.run_id,
+        });
+        const existingContent = dropFilesystemArtifacts(existing);
+        writeSourceStageManifest({
+            contextGraphPath: options.contextGraphPath,
+            buildPlanId: options.buildPlanId,
+            sourceManifest: existingContent,
+            runId: options.runId ?? existingContent.run_id,
+        });
+        return {
+            ok: true,
+            code: 0,
+            summary: `Source Manifest already exists with ${existingContent.source_total} file(s).`,
+            manifest: existingContent,
+        };
+    }
+    const maxAttempts = Math.max(1, Math.min(5, Math.trunc(options.maxAttempts ?? 2)));
+    let feedback = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const shellRoot = sourceInventoryShellRoot(options.contextGraphPath, attempt);
+        const inventoryRunId = `${options.runId ?? "source-inventory"}-source-inventory-${attempt}`;
+        mkdirSync(join(shellRoot, "runtime"), { recursive: true });
+        mkdirSync(join(shellRoot, "logs"), { recursive: true });
+        writeSourceInventoryShellSurface({
+            shellRoot,
+            project: options.project,
+            buildPlanId: options.buildPlanId,
+        });
+        writeFileSync(join(shellRoot, "runtime", "source-locator.json"), `${JSON.stringify({
+            kind: "interf-source-locator",
+            version: 1,
+            generated_at: new Date().toISOString(),
+            project: options.project,
+            project_intent: options.projectIntent ?? null,
+            source: {
+                kind: "local-folder",
+                locator: options.sourceLocator,
+            },
+            note: "Interf does not pre-scan or copy Source files. The scanner agent inspects this locator through its own Source access.",
+        }, null, 2)}\n`);
+        writeFileSync(join(shellRoot, "runtime", "stage-contract.json"), `${JSON.stringify({
+            kind: "interf-source-inventory-contract",
+            version: 1,
+            generated_at: new Date().toISOString(),
+            run_id: options.runId ?? null,
+            project: options.project,
+            project_intent: options.projectIntent ?? null,
+            source: {
+                kind: "local-folder",
+                locator: options.sourceLocator,
+            },
+            stage_id: "source-inventory",
+            stage_ids: options.stageIds,
+            stages: options.stages ?? [],
+            outputs: ["runtime/source-manifest.json"],
+            checks: [
+                "source-manifest.json exists",
+                "manifest source_total equals files.length",
+                "manifest scanner executor and attempt match this shell",
+                "manifest paths are relative to the Source locator",
+            ],
+        }, null, 2)}\n`);
+        writeFileSync(join(shellRoot, "runtime", "paths.json"), `${JSON.stringify({
+            kind: "interf-execution-shell",
+            version: 1,
+            build_plan: options.buildPlanId,
+            stage: "source-inventory",
+            reads: [],
+            writes: [],
+        }, null, 2)}\n`);
+        const prompt = sourceInventoryPrompt({
+            project: options.project,
+            projectIntent: options.projectIntent ?? null,
+            sourceLocator: options.sourceLocator,
+            runId: options.runId ?? null,
+            executor: options.executor,
+            attempt,
+            feedback,
+        });
+        const logs = sourceInventoryShellLogs({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot,
+            inventoryRunId,
+        });
+        writeFileSync(shellPromptLogPath(shellRoot, inventoryRunId), prompt);
+        writeFileSync(shellEventLogPath(shellRoot, inventoryRunId), "");
+        writeFileSync(shellStatusLogPath(shellRoot, inventoryRunId), "");
+        writeStageExecutionWorkspaceManifest({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot,
+            buildPlanId: options.buildPlanId,
+            stage: {
+                id: "source-inventory",
+                label: "Source Inventory",
+                contractType: "source-inventory",
+            },
+            logPaths: {
+                promptLogPath: shellPromptLogPath(shellRoot, inventoryRunId),
+                eventLogPath: shellEventLogPath(shellRoot, inventoryRunId),
+                statusLogPath: shellStatusLogPath(shellRoot, inventoryRunId),
+            },
+        });
+        writeStageExecutionSessionStarted({
+            contextGraphPath: options.contextGraphPath,
+            jobType: "source-inventory",
+            project: options.project,
+            projectIntent: options.projectIntent ?? null,
+            buildPlanId: options.buildPlanId,
+            buildRunId: options.runId ?? null,
+            stageId: "source-inventory",
+            stageLabel: "Source Inventory",
+            contractType: "source-inventory",
+            stageRunId: inventoryRunId,
+            attempt,
+            executor: options.executor,
+            shellRoot,
+            contractPath: join(shellRoot, "runtime", "stage-contract.json"),
+            promptPath: shellPromptLogPath(shellRoot, inventoryRunId),
+            eventStreamPath: shellEventLogPath(shellRoot, inventoryRunId),
+            statusPath: shellStatusLogPath(shellRoot, inventoryRunId),
+            summary: "Collecting Source Manifest.",
+        });
+        await emitInventoryEvent(options.events, options.runId ?? undefined, "stage.started", undefined, logs);
+        const code = await options.executor.execute(shellRoot, prompt, {
+            eventLogPath: shellEventLogPath(shellRoot, inventoryRunId),
+            statusLogPath: shellStatusLogPath(shellRoot, inventoryRunId),
+            // Tee reasoning to the shell's runtime/ dir, the same convention the
+            // shared stage path uses (runtime-runs.ts). The session reader resolves
+            // reasoning_path to this file only when it exists, so a scan that emits
+            // no reasoning leaves it null. This makes the source-inventory session as
+            // legible as every other agent job (policy rule 6) without re-routing it
+            // through the shared stage path.
+            reasoningLogPath: join(shellRoot, "runtime", "agent-reasoning.jsonl"),
+            completionCheck: () => existsSync(join(shellRoot, "runtime", "source-manifest.json")),
+        });
+        if (code !== 0) {
+            feedback = `source inventory executor exited with code ${code}`;
+            recordStageExecutionSessionValidationAttempt({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                attempt,
+                status: "failed",
+                summary: feedback,
+            });
+            writeStageExecutionSessionFinished({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                status: "failed",
+                summary: feedback,
+                error: feedback,
+            });
+            freezePreservedShell(shellRoot, "stage-execution");
+            markStageExecutionSessionsShellPreserved({ contextGraphPath: options.contextGraphPath, shellRoot });
+            continue;
+        }
+        try {
+            const manifest = validateScannerManifest({
+                manifest: readShellManifest(shellRoot),
+                project: options.project,
+                sourceLocator: options.sourceLocator,
+                executor: options.executor,
+                attempt,
+            });
+            const written = dropFilesystemArtifacts(SourceManifestSchema.parse({
+                ...manifest,
+                run_id: options.runId ?? manifest.run_id,
+            }));
+            writeBuildSourceRuntimeFromManifest({
+                contextGraphPath: options.contextGraphPath,
+                buildPlanId: options.buildPlanId,
+                stageIds: options.stageIds,
+                stages: options.stages,
+                schema: options.schema,
+                sourceManifest: written,
+                runId: options.runId ?? null,
+            });
+            writeSourceStageManifest({
+                contextGraphPath: options.contextGraphPath,
+                buildPlanId: options.buildPlanId,
+                sourceManifest: written,
+                runId: options.runId ?? null,
+            });
+            await emitInventoryEvent(options.events, options.runId ?? undefined, "stage.passed", `Source Manifest captured ${written.source_total} file(s).`);
+            recordStageExecutionSessionValidationAttempt({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                attempt,
+                status: "succeeded",
+                summary: `Source Manifest captured ${written.source_total} file(s).`,
+            });
+            writeStageExecutionSessionFinished({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                status: "succeeded",
+                summary: `Source Manifest captured ${written.source_total} file(s).`,
+                error: null,
+            });
+            freezePreservedShell(shellRoot, "stage-execution");
+            markStageExecutionSessionsShellPreserved({ contextGraphPath: options.contextGraphPath, shellRoot });
+            return {
+                ok: true,
+                code: 0,
+                summary: `Source Manifest captured ${written.source_total} file(s).`,
+                manifest: written,
+                logs,
+            };
+        }
+        catch (error) {
+            feedback = error instanceof Error ? error.message : String(error);
+            recordStageExecutionSessionValidationAttempt({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                attempt,
+                status: "failed",
+                summary: feedback,
+            });
+            writeStageExecutionSessionFinished({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                status: "failed",
+                summary: feedback,
+                error: feedback,
+            });
+            freezePreservedShell(shellRoot, "stage-execution");
+            markStageExecutionSessionsShellPreserved({ contextGraphPath: options.contextGraphPath, shellRoot });
+        }
+    }
+    await emitInventoryEvent(options.events, options.runId ?? undefined, "stage.failed", feedback ?? "Source inventory failed.");
+    return {
+        ok: false,
+        code: 1,
+        summary: feedback ?? "Source inventory failed.",
+        manifest: null,
+    };
+}
+export function sourceManifestExists(contextGraphPath) {
+    return existsSync(contextGraphRuntimeSourceManifestPath(contextGraphPath));
+}

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

@@ -0,0 +1,63 @@
+import { type SourceFile, type SourceFiles, type SourceManifest, type SourceManifestFile, type SourceState, type StageInputs } from "../../contracts/lib/schema.js";
+import type { BuildPlanStageDefinition } from "../../build-plans/package/build-plan-definitions.js";
+import type { ContextInterface } from "../../build-plans/package/context-interface.js";
+export declare function selectStageSourceSlice(sourceState: SourceState, stage: Pick<BuildPlanStageDefinition, "contractType" | "reads">, schema?: ContextInterface | null): SourceFile[];
+export declare function materializeStageSourceSlice(options: {
+    shellRoot: string;
+    stageInputs: StageInputs;
+}): StageInputs;
+export declare function buildShellSourceState(sourceState: SourceState, stageInputs: StageInputs): SourceState;
+/**
+ * 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 declare function dropFilesystemArtifacts(manifest: SourceManifest): SourceManifest;
+export declare function sourceManifestToSourceFiles(manifest: SourceManifest): SourceFiles;
+export declare function sourceManifestToSourceState(manifest: SourceManifest): SourceState;
+/**
+ * Pure file-index hash. Excludes generated_at and run_id so the same source
+ * file index has a stable fingerprint across observations.
+ */
+export declare function computeFileIndexHash(sourceFiles: SourceFiles): string;
+export declare function buildBuildStageInputs(options: {
+    buildPlanId: string;
+    stageId: string;
+    sourceState: SourceState;
+    sourceFiles?: Array<SourceFile | SourceManifestFile>;
+    sourceManifestId?: string | null;
+    runId?: string | null;
+    generatedAt?: string;
+}): StageInputs;
+export declare function writeBuildStageInputs(options: {
+    contextGraphPath: string;
+    buildPlanId: string;
+    stageId: string;
+    sourceState: SourceState;
+    sourceFiles?: Array<SourceFile | SourceManifestFile>;
+    sourceManifestId?: string | null;
+    runId?: string | null;
+    generatedAt?: string;
+}): StageInputs;
+export declare function writeBuildSourceRuntimeFromManifest(options: {
+    contextGraphPath: string;
+    buildPlanId: string;
+    stageIds: string[];
+    sourceManifest: SourceManifest;
+    stages?: Pick<BuildPlanStageDefinition, "id" | "contractType" | "reads">[];
+    schema?: ContextInterface | null;
+    runId?: string | null;
+}): {
+    sourceFiles: SourceFiles;
+    sourceState: SourceState;
+    stageInputs: StageInputs[];
+};
+export declare function loadContextGraphSourceManifest(contextGraphPath: string): SourceManifest | null;
+export declare function loadContextGraphSourceFiles(contextGraphPath: string): SourceFiles | null;
+export declare function loadContextGraphSourceState(contextGraphPath: string): SourceState | null;
+export declare function loadBuildStageInputs(contextGraphPath: string, stageId: string): StageInputs | null;