@interf/compiler 0.22.2 → 0.50.0

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

@@ -0,0 +1,318 @@
+import { mkdirSync, existsSync, readFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { buildRuntimeExecutorInfo } from "../agents/lib/executors.js";
+import { stageExecutionWorkspaceLogPaths, writeStageExecutionWorkspaceManifest, } from "../agents/lib/shell-workspace.js";
+import { ExecutionStageLedgerSchema, } from "./lib/schema.js";
+import { supportsStageEvidenceHarness, writeStageHarnessProjection, } from "./stage-evidence.js";
+import { getBuildPlanStageDefinition, getBuildPlanStagePosition, getBuildPlanStages, } from "../../build-plans/package/build-plan-definitions.js";
+import { InterfIdPattern, } from "../../contracts/lib/schema.js";
+import { contextGraphRuntimeArchivedStageContractPath, contextGraphExecutionStageLedgerHistoryPath, contextGraphExecutionStageLedgerPath, contextGraphRuntimeStageContractPath, } from "./context-graph-paths.js";
+import { eventLogPath, promptLogPath, statusLogPath, } from "./runtime-log-paths.js";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { appendJsonlAtomic, writeFileAtomic, writeJsonAtomic } from "./atomic-fs.js";
+import { initContextGraphState, loadState, saveState, } from "./state.js";
+import { projectSessionFinishedFromLedger, writeStageExecutionSessionStartedFromLedger, } from "./stage-session.js";
+export function loadExecutionStageLedger(dirPath) {
+    const path = contextGraphExecutionStageLedgerPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const parsed = ExecutionStageLedgerSchema.safeParse(raw);
+        if (parsed.success)
+            return parsed.data;
+        warnInterf(`Warning: failed to validate runtime run at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    catch (error) {
+        warnInterf(`Warning: failed to read runtime run at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+export function saveExecutionStageLedger(dirPath, run) {
+    writeJsonAtomic(contextGraphExecutionStageLedgerPath(dirPath), run);
+}
+export function writeStageContract(dirPath, contract) {
+    mkdirSync(dirname(contextGraphRuntimeStageContractPath(dirPath)), { recursive: true });
+    const path = contextGraphRuntimeStageContractPath(dirPath);
+    writeJsonAtomic(path, contract);
+    return path;
+}
+function writeArchivedStageContract(dirPath, runId, contract) {
+    const path = contextGraphRuntimeArchivedStageContractPath(dirPath, runId);
+    writeJsonAtomic(path, contract);
+    return path;
+}
+export async function runExecutorStage(options) {
+    const startedRun = startExecutionStageLedger(options);
+    if (options.executionPath &&
+        supportsStageEvidenceHarness({ contractType: options.contractType })) {
+        writeStageHarnessProjection({
+            executionPath: options.executionPath,
+            contract: startedRun.contract,
+        });
+    }
+    const prompt = options.buildPrompt(startedRun.activeContractPath);
+    writeExecutionStageLedgerPrompt(startedRun.logPaths.promptLogPath, prompt);
+    writeStageExecutionSessionStartedFromLedger({
+        contextGraphPath: options.contextGraphPath,
+        run: startedRun.run,
+        contract: startedRun.contract,
+        buildRunId: options.buildRunId ?? null,
+        shellRoot: options.executionPath ?? null,
+        promptPath: startedRun.logPaths.promptLogPath,
+        eventStreamPath: startedRun.logPaths.eventLogPath,
+        statusPath: startedRun.logPaths.statusLogPath,
+    });
+    const executionPath = options.executionPath ?? options.contextGraphPath;
+    // Reasoning lands in the shell's runtime/ dir so it sits beside the other
+    // inspectable runtime files, is referenced by the session's reasoning_path,
+    // and is preserved when the shell is frozen. Without a shell there is nowhere
+    // durable to keep it, so reasoning capture is skipped (null).
+    const reasoningLogPath = options.executionPath
+        ? join(options.executionPath, "runtime", "agent-reasoning.jsonl")
+        : null;
+    const code = await options.executor.execute(executionPath, prompt, {
+        eventLogPath: startedRun.logPaths.eventLogPath,
+        statusLogPath: startedRun.logPaths.statusLogPath,
+        reasoningLogPath,
+        completionCheck: options.completionCheck,
+        onStatus: options.onStatus,
+    });
+    finalizeExecutionStageLedger(options.contextGraphPath, code);
+    return code;
+}
+export function beginExecutionStageLedger(dirPath, run) {
+    saveExecutionStageLedger(dirPath, run);
+    return run;
+}
+export function updateExecutionStageLedger(dirPath, patch) {
+    const current = loadExecutionStageLedger(dirPath);
+    if (!current)
+        return null;
+    const next = {
+        ...current,
+        ...patch,
+        updated_at: new Date().toISOString(),
+    };
+    saveExecutionStageLedger(dirPath, next);
+    return next;
+}
+function updateContextGraphStageTerminalState(dirPath, run, options) {
+    const state = loadState(dirPath);
+    if (!state?.stages?.[run.stage])
+        return;
+    const nextStage = {
+        ...state.stages[run.stage],
+        status: options.status,
+        summary: options.summary,
+        finished_at: options.finishedAt,
+        run_id: run.run_id,
+    };
+    if (options.status === "failed") {
+        delete nextStage.fingerprint;
+    }
+    saveState(dirPath, {
+        ...state,
+        stages: {
+            ...state.stages,
+            [run.stage]: nextStage,
+        },
+    });
+}
+function updateContextGraphStageStartedState(dirPath, run) {
+    const state = loadState(dirPath) ?? initContextGraphState();
+    const currentStage = state.stages?.[run.stage] ?? {};
+    saveState(dirPath, {
+        ...state,
+        stages: {
+            ...(state.stages ?? {}),
+            [run.stage]: {
+                ...currentStage,
+                contract_type: run.contract_type,
+                status: "running",
+                started_at: run.started_at,
+                finished_at: null,
+                counts: { ...run.counts },
+                artifacts: [...run.output_artifacts],
+                summary: run.summary,
+                run_id: run.run_id,
+            },
+        },
+    });
+}
+export function markExecutionStageLedgerFailedAfterValidation(dirPath, summary) {
+    const current = loadExecutionStageLedger(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = current.finished_at ?? new Date().toISOString();
+    const next = {
+        ...current,
+        status: "failed",
+        updated_at: new Date().toISOString(),
+        finished_at: finishedAt,
+        exit_code: 1,
+        error: summary,
+        summary,
+    };
+    saveExecutionStageLedger(dirPath, next);
+    updateContextGraphStageTerminalState(dirPath, next, {
+        status: "failed",
+        summary,
+        finishedAt,
+    });
+    projectSessionFinishedFromLedger(dirPath, next);
+    appendJsonlAtomic(contextGraphExecutionStageLedgerHistoryPath(dirPath), next);
+    return next;
+}
+export function markExecutionStageLedgerSucceededAfterValidation(dirPath, summary) {
+    const current = loadExecutionStageLedger(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = current.finished_at ?? new Date().toISOString();
+    const next = {
+        ...current,
+        status: "succeeded",
+        updated_at: new Date().toISOString(),
+        finished_at: finishedAt,
+        exit_code: 0,
+        error: null,
+        summary,
+    };
+    saveExecutionStageLedger(dirPath, next);
+    updateContextGraphStageTerminalState(dirPath, next, {
+        status: "succeeded",
+        summary,
+        finishedAt,
+    });
+    projectSessionFinishedFromLedger(dirPath, next);
+    appendJsonlAtomic(contextGraphExecutionStageLedgerHistoryPath(dirPath), next);
+    return next;
+}
+function startExecutionStageLedger(options) {
+    const runId = createRunId();
+    const generatedAt = new Date().toISOString();
+    const buildPlanStages = getBuildPlanStages(options.buildPlan, options.buildPlanSourcePath);
+    const stagePosition = getBuildPlanStagePosition(options.buildPlan, options.stage, options.buildPlanSourcePath);
+    const stageDefinition = getBuildPlanStageDefinition(options.buildPlan, options.stage, options.buildPlanSourcePath);
+    const project = options.contract.project ?? {
+        id: InterfIdPattern.test(options.contextGraphName) ? options.contextGraphName : "project",
+        intent: null,
+    };
+    const contract = {
+        kind: "interf-stage-contract",
+        version: 1,
+        generated_at: generatedAt,
+        run_id: runId,
+        target_type: "context-graph",
+        target_name: options.contextGraphName,
+        project,
+        build_plan: {
+            id: options.buildPlan,
+            stage_index: stagePosition?.stageIndex ?? null,
+            stage_total: stagePosition?.stageTotal ?? buildPlanStages.length,
+            stages: stagePosition?.stages ?? buildPlanStages,
+        },
+        stage: options.stage,
+        stage_label: stageDefinition?.label ?? options.stageLabel,
+        contract_type: options.contractType,
+        executor: buildRuntimeExecutorInfo(options.executor),
+        instructions: options.contract.instructions,
+        counts: options.contract.counts,
+        artifacts: options.contract.artifacts,
+        context_checks: options.contract.context_checks,
+        policies: options.contract.policies,
+    };
+    const activeContractPath = writeStageContract(options.contextGraphPath, contract);
+    const archivedContractPath = writeArchivedStageContract(options.contextGraphPath, runId, contract);
+    if (options.executionPath) {
+        writeJsonAtomic(join(options.executionPath, "runtime", "stage-contract.json"), contract);
+    }
+    const logPaths = options.executionPath
+        ? stageExecutionWorkspaceLogPaths(options.executionPath, runId)
+        : {
+            promptLogPath: promptLogPath(options.contextGraphPath, runId),
+            eventLogPath: eventLogPath(options.contextGraphPath, runId),
+            statusLogPath: statusLogPath(options.contextGraphPath, runId),
+        };
+    const run = {
+        kind: "interf-run",
+        version: 1,
+        run_id: runId,
+        target_type: "context-graph",
+        target_name: options.contextGraphName,
+        build_plan: options.buildPlan,
+        stage: options.stage,
+        stage_label: stageDefinition?.label ?? options.stageLabel,
+        contract_type: options.contractType,
+        status: "running",
+        executor: buildRuntimeExecutorInfo(options.executor),
+        started_at: generatedAt,
+        updated_at: generatedAt,
+        finished_at: null,
+        contract_path: relative(options.contextGraphPath, archivedContractPath),
+        ...(options.executionPath ? { execution_path: relative(options.contextGraphPath, options.executionPath) } : {}),
+        counts: { ...contract.counts },
+        output_artifacts: [...contract.artifacts.writes],
+        logs: {
+            prompt_path: relative(options.contextGraphPath, logPaths.promptLogPath),
+            event_stream_path: relative(options.contextGraphPath, logPaths.eventLogPath),
+            status_path: relative(options.contextGraphPath, logPaths.statusLogPath),
+        },
+        summary: options.summary,
+        exit_code: null,
+        error: null,
+    };
+    const startedRun = beginExecutionStageLedger(options.contextGraphPath, run);
+    updateContextGraphStageStartedState(options.contextGraphPath, startedRun);
+    if (options.executionPath) {
+        writeStageExecutionWorkspaceManifest({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot: options.executionPath,
+            buildPlanId: options.buildPlan,
+            stage: {
+                id: options.stage,
+                label: stageDefinition?.label ?? options.stageLabel,
+                contractType: options.contractType,
+            },
+            run: startedRun,
+            contract,
+            logPaths,
+        });
+    }
+    return {
+        run: startedRun,
+        activeContractPath: options.executionPath
+            ? "runtime/stage-contract.json"
+            : relative(options.contextGraphPath, activeContractPath),
+        contract,
+        logPaths,
+    };
+}
+function finalizeExecutionStageLedger(dirPath, code) {
+    const current = loadExecutionStageLedger(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = new Date().toISOString();
+    const status = code === 0 ? "succeeded" : "failed";
+    const next = {
+        ...current,
+        status,
+        updated_at: finishedAt,
+        finished_at: finishedAt,
+        exit_code: code,
+        error: code === 0 ? null : `Executor exited with code ${code}.`,
+        summary: code === 0
+            ? `${current.stage_label} completed successfully.`
+            : `${current.stage_label} failed with exit code ${code}.`,
+    };
+    saveExecutionStageLedger(dirPath, next);
+    projectSessionFinishedFromLedger(dirPath, next);
+    return next;
+}
+function writeExecutionStageLedgerPrompt(path, prompt) {
+    writeFileAtomic(path, `${prompt}\n`);
+}
+function createRunId() {
+    return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}

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

@@ -1,15 +1,16 @@
 import { type AgentExecutor } from "../agents/lib/executors.js";
-import { type RuntimeRun, type RuntimeStageContract, type RuntimeStageInstructions } from "./lib/schema.js";
+import { type ExecutionStageLedger, type RuntimeProjectContext, type RuntimeStageContract, type RuntimeStageInstructions } from "./lib/schema.js";
 import type { Check, BuildPlanId, RuntimeContractType, RuntimeStage } from "../../contracts/lib/schema.js";
-export type RuntimeRunStatus = "running" | "succeeded" | "failed";
+export type ExecutionStageLedgerStatus = "running" | "succeeded" | "failed";
 export type RuntimeStageContractDraft = Omit<RuntimeStageContract, "kind" | "version" | "generated_at" | "run_id" | "target_type" | "target_name" | "build_plan" | "stage" | "stage_label" | "contract_type" | "executor">;
 export interface RuntimeStageExecutionOptions {
     executor: AgentExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     executionPath?: string;
-    verifiableContextName: string;
+    contextGraphName: string;
     buildPlan: BuildPlanId;
     buildPlanSourcePath?: string;
+    buildRunId?: string | null;
     stage: RuntimeStage;
     stageLabel: string;
     contractType: RuntimeContractType;
@@ -20,7 +21,8 @@ export interface RuntimeStageExecutionOptions {
     onStatus?: (line: string) => void;
 }
 export interface RuntimeStageContractOptions {
-    verifiableContextName: string;
+    contextGraphName: string;
+    project: RuntimeProjectContext;
     stageId: string;
     stageLabel: string;
     counts?: Record<string, number>;
@@ -32,9 +34,10 @@ export interface RuntimeStageContractOptions {
         path: string;
         checks: Check[];
     }>;
+    contextChecks?: RuntimeStageContract["context_checks"];
     buildPlanNotes?: string[];
     localSkillDocs?: string[];
     instructions: RuntimeStageInstructions;
 }
-export interface RuntimeRunPatch extends Partial<Pick<RuntimeRun, "counts" | "summary" | "status" | "error" | "exit_code" | "finished_at">> {
+export interface ExecutionStageLedgerPatch extends Partial<Pick<ExecutionStageLedger, "counts" | "summary" | "status" | "error" | "exit_code" | "finished_at" | "evidence_path" | "evidence">> {
 }

package/dist/packages/runtime/build/runtime-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,8 @@
+export type { ExecutionStageLedgerPatch, ExecutionStageLedgerStatus, RuntimeStageContractDraft, RuntimeStageExecutionOptions, RuntimeStageContractOptions, } from "./runtime-types.js";
+export { contextGraphRuntimeArchivedStageContractPath as archivedStageContractPath, contextGraphRuntimeLogsRoot as logsDirPath, contextGraphExecutionStageLedgerHistoryPath as runHistoryPath, contextGraphExecutionStageLedgerPath as runPath, contextGraphRuntimeStageContractPath as stageContractPath, } from "./context-graph-paths.js";
+export { eventLogPath, promptLogPath, statusLogPath, } from "./runtime-log-paths.js";
+export { buildStagePrompt } from "./runtime-prompt.js";
+export { buildRuntimeStageContract, } from "./runtime-contracts.js";
+export { reconcileStageEvidence, supportsStageEvidenceHarness, writeStageHarnessProjection, } from "./stage-evidence.js";
+export { listStageExecutionSessions, markStageExecutionSessionsShellPreserved, recordStageExecutionSessionValidationAttempt, writeStageExecutionSessionFinished, writeStageExecutionSessionStarted, writeStageExecutionSessionStartedFromLedger, } from "./stage-session.js";
+export { beginExecutionStageLedger, loadExecutionStageLedger, markExecutionStageLedgerFailedAfterValidation, markExecutionStageLedgerSucceededAfterValidation, runExecutorStage, saveExecutionStageLedger, updateExecutionStageLedger, writeStageContract, } from "./runtime-runs.js";

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

@@ -0,0 +1,7 @@
+export { contextGraphRuntimeArchivedStageContractPath as archivedStageContractPath, contextGraphRuntimeLogsRoot as logsDirPath, contextGraphExecutionStageLedgerHistoryPath as runHistoryPath, contextGraphExecutionStageLedgerPath as runPath, contextGraphRuntimeStageContractPath as stageContractPath, } from "./context-graph-paths.js";
+export { eventLogPath, promptLogPath, statusLogPath, } from "./runtime-log-paths.js";
+export { buildStagePrompt } from "./runtime-prompt.js";
+export { buildRuntimeStageContract, } from "./runtime-contracts.js";
+export { reconcileStageEvidence, supportsStageEvidenceHarness, writeStageHarnessProjection, } from "./stage-evidence.js";
+export { listStageExecutionSessions, markStageExecutionSessionsShellPreserved, recordStageExecutionSessionValidationAttempt, writeStageExecutionSessionFinished, writeStageExecutionSessionStarted, writeStageExecutionSessionStartedFromLedger, } from "./stage-session.js";
+export { beginExecutionStageLedger, loadExecutionStageLedger, markExecutionStageLedgerFailedAfterValidation, markExecutionStageLedgerSucceededAfterValidation, runExecutorStage, saveExecutionStageLedger, updateExecutionStageLedger, writeStageContract, } from "./runtime-runs.js";

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

@@ -0,0 +1,58 @@
+import { type SourceFile, type SourceFiles, type SourceManifest, 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 { buildBuildStageInputs, buildShellSourceState, computeFileIndexHash, loadBuildStageInputs, loadContextGraphSourceFiles, loadContextGraphSourceManifest, loadContextGraphSourceState, materializeStageSourceSlice, selectStageSourceSlice, sourceManifestToSourceFiles, sourceManifestToSourceState, writeBuildSourceRuntimeFromManifest, writeBuildStageInputs, } from "./source-manifest.js";
+/**
+ * Compatibility/test helpers for local-folder discovery.
+ *
+ * Production build runs should get source inventory from `runSourceInventory`
+ * and write runtime state through `writeBuildSourceRuntimeFromManifest`.
+ * The helpers in this module remain for fixtures, migration tools, and
+ * compatibility projections only; new runtime code should consume
+ * Source Manifest / Stage Inputs directly.
+ */
+export declare function sourceFileContentHash(file: Pick<SourceFile, "locator">): string;
+export declare function sourceManifestFromSourceFiles(options: {
+    contextGraphPath: string;
+    sourceFiles: SourceFiles;
+    generatedAt?: string;
+    runId?: string | null;
+    scanner?: SourceManifest["scanner"];
+}): SourceManifest;
+export declare function buildContextGraphSourceFiles(contextGraphPath: string, sourcePath?: string, generatedAt?: string): SourceFiles;
+export declare function writeContextGraphSourceFiles(contextGraphPath: string, sourcePath?: string, generatedAt?: string): SourceFiles;
+export declare function writeContextGraphSourceManifest(options: {
+    contextGraphPath: string;
+    sourceFiles?: SourceFiles;
+    sourcePath?: string;
+    runId?: string | null;
+    generatedAt?: string;
+    scanner?: SourceManifest["scanner"];
+}): SourceManifest;
+export declare function buildContextGraphSourceState(options: {
+    contextGraphPath: string;
+    sourceFiles?: SourceFiles;
+    sourcePath?: string;
+    runId?: string | null;
+    generatedAt?: string;
+}): SourceState;
+export declare function writeContextGraphSourceState(options: {
+    contextGraphPath: string;
+    sourceFiles?: SourceFiles;
+    sourcePath?: string;
+    runId?: string | null;
+    generatedAt?: string;
+}): SourceState;
+export declare function writeBuildSourceRuntime(options: {
+    contextGraphPath: string;
+    buildPlanId: string;
+    stageIds: string[];
+    stages?: Pick<BuildPlanStageDefinition, "id" | "contractType" | "reads">[];
+    schema?: ContextInterface | null;
+    sourcePath?: string;
+    runId?: string | null;
+}): {
+    sourceFiles: SourceFiles;
+    sourceState: SourceState;
+    stageInputs: StageInputs[];
+};

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

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { SourceFilesSchema, SourceManifestSchema, SourceStateSchema, } from "../../contracts/lib/schema.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { contextGraphRuntimeSourceManifestPath, contextGraphRuntimeSourceFilesPath, contextGraphRuntimeSourceStatePath, } from "./context-graph-paths.js";
+import { readInterfConfig, resolveSourceInputPath } from "../../projects/interf-detect.js";
+import { writeJsonAtomic } from "./atomic-fs.js";
+import { computeFileIndexHash, sourceManifestToSourceState, writeBuildSourceRuntimeFromManifest, } from "./source-manifest.js";
+export { buildBuildStageInputs, buildShellSourceState, computeFileIndexHash, loadBuildStageInputs, loadContextGraphSourceFiles, loadContextGraphSourceManifest, loadContextGraphSourceState, materializeStageSourceSlice, selectStageSourceSlice, sourceManifestToSourceFiles, sourceManifestToSourceState, writeBuildSourceRuntimeFromManifest, writeBuildStageInputs, } from "./source-manifest.js";
+function shortHash(value, length = 16) {
+    return createHash("sha256")
+        .update(value)
+        .digest("hex")
+        .slice(0, length);
+}
+/**
+ * Canonicalize ONLY the path separators (`\` -> `/`) so a file's stable hash id
+ * is identical on Windows and POSIX. This is deliberately NOT the canonical
+ * `normalizeLayerPath` (`contracts/lib/context-graph-layer.ts`): it must NOT
+ * strip a leading `./` or a trailing slash, because the resulting string is
+ * stored as `SourceFile.path` and fed verbatim into the file-id hash. Touching
+ * the leading/trailing characters here would change every existing source-file
+ * id. Separators-only is the intended, stable difference.
+ */
+function normalizeSeparatorsForFileId(path) {
+    return path.replaceAll("\\", "/");
+}
+/**
+ * Compatibility/test helpers for local-folder discovery.
+ *
+ * Production build runs should get source inventory from `runSourceInventory`
+ * and write runtime state through `writeBuildSourceRuntimeFromManifest`.
+ * The helpers in this module remain for fixtures, migration tools, and
+ * compatibility projections only; new runtime code should consume
+ * Source Manifest / Stage Inputs directly.
+ */
+export function sourceFileContentHash(file) {
+    return createHash("sha256")
+        .update(readFileSync(file.locator))
+        .digest("hex");
+}
+function buildSource(sourcePath) {
+    const locator = resolve(sourcePath);
+    return {
+        id: `src-${shortHash(locator, 12)}`,
+        kind: "local-folder",
+        locator,
+    };
+}
+function buildSourceFile(source, sourcePath, relativePath) {
+    const normalizedPath = normalizeSeparatorsForFileId(relativePath);
+    const absolutePath = resolve(sourcePath, relativePath);
+    return {
+        id: `file-${shortHash(`${source.id}\0${normalizedPath}`)}`,
+        path: normalizedPath,
+        locator: absolutePath,
+        size_bytes: statSync(absolutePath).size,
+    };
+}
+function inferManifestFileKind(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".pdf"))
+        return "pdf";
+    if (/\.(docx?|odt|rtf)$/i.test(lower))
+        return "document";
+    if (/\.(xlsx?|csv|tsv)$/i.test(lower))
+        return "spreadsheet";
+    if (/\.(pptx?|key)$/i.test(lower))
+        return "presentation";
+    if (/\.(png|jpe?g|gif|webp|heic|tiff?)$/i.test(lower))
+        return "image";
+    if (/\.(md|txt|json|ya?ml|xml|html?)$/i.test(lower))
+        return "text";
+    return "other";
+}
+function sourceManifestId(options) {
+    const fingerprint = {
+        file_index_hash: computeFileIndexHash(options.sourceFiles),
+        generated_at: options.generatedAt,
+        run_id: options.runId ?? null,
+    };
+    return `manifest-${shortHash(JSON.stringify(fingerprint))}`;
+}
+function projectNameForContextGraph(contextGraphPath) {
+    return readInterfConfig(contextGraphPath)?.name ?? "unknown-project";
+}
+export function sourceManifestFromSourceFiles(options) {
+    const generatedAt = options.generatedAt ?? options.sourceFiles.generated_at ?? new Date().toISOString();
+    return SourceManifestSchema.parse({
+        kind: "interf-source-manifest",
+        version: 1,
+        manifest_id: sourceManifestId({
+            sourceFiles: options.sourceFiles,
+            generatedAt,
+            runId: options.runId ?? null,
+        }),
+        generated_at: generatedAt,
+        run_id: options.runId ?? null,
+        project: projectNameForContextGraph(options.contextGraphPath),
+        source: options.sourceFiles.source,
+        scanner: options.scanner ?? {
+            executor: "interf-runtime-local-discovery",
+            agent_label: "Interf runtime local discovery",
+            attempt: 1,
+        },
+        source_total: options.sourceFiles.files.length,
+        files: options.sourceFiles.files.map((file) => ({
+            ...file,
+            kind: inferManifestFileKind(file.path),
+            confidence: "high",
+            evidence: [
+                {
+                    kind: "connector-metadata",
+                    summary: "Compatibility manifest projected from the current local Source discovery path.",
+                },
+            ],
+        })),
+        warnings: [],
+    });
+}
+function writeJson(filePath, value) {
+    writeJsonAtomic(filePath, value);
+}
+export function buildContextGraphSourceFiles(contextGraphPath, sourcePath = resolveSourceInputPath(contextGraphPath), generatedAt = new Date().toISOString()) {
+    const discovery = discoverSourceFiles(sourcePath, contextGraphPath);
+    const source = buildSource(sourcePath);
+    const files = discovery.sourceFiles.map((relativePath) => buildSourceFile(source, sourcePath, relativePath));
+    return {
+        kind: "interf-source-files",
+        version: 1,
+        generated_at: generatedAt,
+        source,
+        source_total: files.length,
+        files,
+    };
+}
+export function writeContextGraphSourceFiles(contextGraphPath, sourcePath = resolveSourceInputPath(contextGraphPath), generatedAt = new Date().toISOString()) {
+    const sourceFiles = buildContextGraphSourceFiles(contextGraphPath, sourcePath, generatedAt);
+    const parsed = SourceFilesSchema.parse(sourceFiles);
+    writeJson(contextGraphRuntimeSourceFilesPath(contextGraphPath), parsed);
+    return parsed;
+}
+export function writeContextGraphSourceManifest(options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const sourceFiles = options.sourceFiles
+        ?? buildContextGraphSourceFiles(options.contextGraphPath, options.sourcePath ?? resolveSourceInputPath(options.contextGraphPath), generatedAt);
+    const manifest = sourceManifestFromSourceFiles({
+        contextGraphPath: options.contextGraphPath,
+        sourceFiles,
+        generatedAt,
+        runId: options.runId ?? null,
+        scanner: options.scanner,
+    });
+    writeJson(contextGraphRuntimeSourceManifestPath(options.contextGraphPath), manifest);
+    return manifest;
+}
+export function buildContextGraphSourceState(options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const sourceFiles = options.sourceFiles
+        ?? buildContextGraphSourceFiles(options.contextGraphPath, options.sourcePath ?? resolveSourceInputPath(options.contextGraphPath), generatedAt);
+    return sourceManifestToSourceState(sourceManifestFromSourceFiles({
+        contextGraphPath: options.contextGraphPath,
+        sourceFiles,
+        generatedAt,
+        runId: options.runId ?? null,
+    }));
+}
+export function writeContextGraphSourceState(options) {
+    const manifest = writeContextGraphSourceManifest(options);
+    const sourceState = SourceStateSchema.parse(sourceManifestToSourceState(manifest));
+    writeJson(contextGraphRuntimeSourceStatePath(options.contextGraphPath), sourceState);
+    return sourceState;
+}
+export function writeBuildSourceRuntime(options) {
+    const generatedAt = new Date().toISOString();
+    const sourceFiles = buildContextGraphSourceFiles(options.contextGraphPath, options.sourcePath ?? resolveSourceInputPath(options.contextGraphPath), generatedAt);
+    const sourceManifest = writeContextGraphSourceManifest({
+        contextGraphPath: options.contextGraphPath,
+        sourceFiles,
+        runId: options.runId ?? null,
+        generatedAt,
+    });
+    return writeBuildSourceRuntimeFromManifest({
+        contextGraphPath: options.contextGraphPath,
+        buildPlanId: options.buildPlanId,
+        stageIds: options.stageIds,
+        stages: options.stages,
+        schema: options.schema,
+        sourceManifest,
+        runId: options.runId ?? null,
+    });
+}

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

@@ -0,0 +1,28 @@
+import { type SourceManifest } 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";
+import type { AgentExecutor } from "../agents/lib/executors.js";
+import type { RunEventSink } from "../execution/events.js";
+import type { StageRunLogs } from "../execution/lib/schema.js";
+export type SourceInventoryResult = {
+    ok: boolean;
+    code: number;
+    summary: string;
+    manifest: SourceManifest | null;
+    logs?: StageRunLogs;
+};
+export declare function runSourceInventory(options: {
+    executor: AgentExecutor;
+    contextGraphPath: string;
+    project: string;
+    projectIntent?: string | null;
+    sourceLocator: string;
+    buildPlanId: string;
+    stageIds: string[];
+    stages?: Pick<BuildPlanStageDefinition, "id" | "contractType" | "reads">[];
+    schema?: ContextInterface | null;
+    runId?: string | null;
+    events?: RunEventSink;
+    maxAttempts?: number;
+}): Promise<SourceInventoryResult>;
+export declare function sourceManifestExists(contextGraphPath: string): boolean;