@interf/compiler 0.22.2 → 0.33.0

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

@@ -0,0 +1,273 @@
+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 { contextGraphRuntimeSourceManifestPath, stageExecutionShellsRoot, } from "./context-graph-paths.js";
+import { loadContextGraphSourceManifest, writeBuildSourceRuntimeFromManifest, } from "./source-manifest.js";
+import { createRunEventId, createRunEventTimestamp, } from "../execution/events.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}`,
+        `Source locator: ${options.sourceLocator}`,
+        "Read `runtime/source-locator.json` first.",
+        "List every Source file you can access. Use paths relative to the Source locator.",
+        "For PDFs, decks, sheets, and other multi-unit files, record page/slide/sheet 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 readShellManifest(shellRoot) {
+    const manifestPath = join(shellRoot, "runtime", "source-manifest.json");
+    const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+    return SourceManifestSchema.parse(raw);
+}
+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,
+        });
+        return {
+            ok: true,
+            code: 0,
+            summary: `Source Manifest already exists with ${existing.source_total} file(s).`,
+            manifest: existing,
+        };
+    }
+    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 });
+        writeFileSync(join(shellRoot, "runtime", "source-locator.json"), `${JSON.stringify({
+            kind: "interf-source-locator",
+            version: 1,
+            generated_at: new Date().toISOString(),
+            project: options.project,
+            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,
+            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`);
+        const prompt = sourceInventoryPrompt({
+            project: options.project,
+            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), "");
+        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),
+            completionCheck: () => existsSync(join(shellRoot, "runtime", "source-manifest.json")),
+        });
+        if (code !== 0) {
+            feedback = `source inventory executor exited with code ${code}`;
+            continue;
+        }
+        try {
+            const manifest = validateScannerManifest({
+                manifest: readShellManifest(shellRoot),
+                project: options.project,
+                sourceLocator: options.sourceLocator,
+                executor: options.executor,
+                attempt,
+            });
+            const written = 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,
+            });
+            await emitInventoryEvent(options.events, options.runId ?? undefined, "stage.passed", `Source Manifest captured ${written.source_total} file(s).`);
+            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);
+        }
+    }
+    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,52 @@
+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;
+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;

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

@@ -0,0 +1,192 @@
+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 { 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,
+        })),
+    });
+}
+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 = 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);
+}
+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 {};