@interf/compiler 0.9.4 → 0.13.0

package/dist/packages/compiler/lib/schema.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, TestCaseExpectSchema, TestTargetTypeSchema, MethodIdSchema } from "../../contracts/lib/schema.js";
-export { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, MethodIdSchema, } from "../../contracts/lib/schema.js";
+import { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, TestCaseExpectSchema, TestTargetTypeSchema, MethodIdSchema } from "../../contracts/lib/schema.js";
+export { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, MethodIdSchema, } from "../../contracts/lib/schema.js";
 export type RuntimeStatus = "idle" | "running" | "compiled" | "stale" | "failed";
 export type CompiledStage = "idle" | "compiled" | "failed" | string;
 export declare const MethodZoneIdSchema: z.ZodString;
@@ -10,24 +10,24 @@ export declare const MethodCompiledZoneKindSchema: z.ZodEnum<{
     directory: "directory";
 }>;
 export declare const MethodZoneRoleSchema: z.ZodEnum<{
-    output: "output";
     runtime: "runtime";
+    output: "output";
     input: "input";
     working: "working";
 }>;
 export declare const CompiledStageStatusSchema: z.ZodEnum<{
+    succeeded: "succeeded";
     failed: "failed";
-    idle: "idle";
     running: "running";
-    succeeded: "succeeded";
+    idle: "idle";
 }>;
 export declare const CompiledStageStateSchema: z.ZodObject<{
     contract_type: z.ZodOptional<z.ZodString>;
     status: z.ZodOptional<z.ZodEnum<{
+        succeeded: "succeeded";
         failed: "failed";
-        idle: "idle";
         running: "running";
-        succeeded: "succeeded";
+        idle: "idle";
     }>>;
     started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     finished_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -43,10 +43,10 @@ export declare const CompiledStateSchema: z.ZodObject<{
     stages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         contract_type: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodEnum<{
+            succeeded: "succeeded";
             failed: "failed";
-            idle: "idle";
             running: "running";
-            succeeded: "succeeded";
+            idle: "idle";
         }>>;
         started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         finished_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -94,8 +94,8 @@ export declare const CompiledHealthSchema: z.ZodObject<{
         compiled: "compiled";
         stale: "stale";
         failed: "failed";
-        idle: "idle";
         running: "running";
+        idle: "idle";
     }>;
     stage: z.ZodUnion<readonly [z.ZodEnum<{
         compiled: "compiled";
@@ -140,16 +140,6 @@ export declare const CompiledViewSpecSchema: z.ZodObject<{
         paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare const CompiledRawSnapshotSchema: z.ZodObject<{
-    kind: z.ZodLiteral<"compiled-raw-snapshot">;
-    version: z.ZodLiteral<1>;
-    generated_at: z.ZodString;
-    target_name: z.ZodString;
-    source_root: z.ZodString;
-    raw_root: z.ZodString;
-    source_total: z.ZodNumber;
-    sample_files: z.ZodArray<z.ZodString>;
-}, z.core.$strip>;
 export declare const MethodPurposeSchema: z.ZodObject<{
     label: z.ZodString;
     task_hint: z.ZodString;
@@ -157,8 +147,8 @@ export declare const MethodPurposeSchema: z.ZodObject<{
 export declare const MethodZoneSchema: z.ZodObject<{
     id: z.ZodString;
     role: z.ZodEnum<{
-        output: "output";
         runtime: "runtime";
+        output: "output";
         input: "input";
         working: "working";
     }>;
@@ -175,8 +165,8 @@ export declare const MethodZoneSchema: z.ZodObject<{
 export declare const MethodCompiledZoneSchema: z.ZodObject<{
     id: z.ZodString;
     role: z.ZodEnum<{
-        output: "output";
         runtime: "runtime";
+        output: "output";
         input: "input";
         working: "working";
     }>;
@@ -198,8 +188,8 @@ export declare const MethodSchemaSchema: z.ZodObject<{
     zones: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         role: z.ZodEnum<{
-            output: "output";
             runtime: "runtime";
+            output: "output";
             input: "input";
             working: "working";
         }>;
@@ -222,8 +212,8 @@ export declare const MethodCompiledSchemaSchema: z.ZodObject<{
     zones: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         role: z.ZodEnum<{
-            output: "output";
             runtime: "runtime";
+            output: "output";
             input: "input";
             working: "working";
         }>;
@@ -274,13 +264,13 @@ export declare const ExecutionShellPathsSchema: z.ZodObject<{
 export declare const RuntimeStageInstructionsSchema: z.ZodObject<{
     stage_skill_dir: z.ZodString;
     effective_mode: z.ZodEnum<{
+        override: "override";
         builtin: "builtin";
         extend: "extend";
-        override: "override";
     }>;
     local_mode: z.ZodNullable<z.ZodEnum<{
-        extend: "extend";
         override: "override";
+        extend: "extend";
     }>>;
     local_docs: z.ZodArray<z.ZodString>;
     mode_sources: z.ZodArray<z.ZodString>;
@@ -334,13 +324,13 @@ export declare const RuntimeStageContractSchema: z.ZodObject<{
     instructions: z.ZodObject<{
         stage_skill_dir: z.ZodString;
         effective_mode: z.ZodEnum<{
+            override: "override";
             builtin: "builtin";
             extend: "extend";
-            override: "override";
         }>;
         local_mode: z.ZodNullable<z.ZodEnum<{
-            extend: "extend";
             override: "override";
+            extend: "extend";
         }>>;
         local_docs: z.ZodArray<z.ZodString>;
         mode_sources: z.ZodArray<z.ZodString>;
@@ -363,7 +353,6 @@ export declare const RuntimeStageContractSchema: z.ZodObject<{
     artifacts: z.ZodObject<{
         reads: z.ZodArray<z.ZodString>;
         writes: z.ZodArray<z.ZodString>;
-        verifies: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
     policies: z.ZodObject<{
         execution_mode: z.ZodLiteral<"deterministic">;
@@ -392,9 +381,9 @@ export declare const RuntimeRunSchema: z.ZodObject<{
     stage_label: z.ZodString;
     contract_type: z.ZodString;
     status: z.ZodEnum<{
+        succeeded: "succeeded";
         failed: "failed";
         running: "running";
-        succeeded: "succeeded";
     }>;
     executor: z.ZodObject<{
         kind: z.ZodEnum<{
@@ -475,7 +464,7 @@ export declare const MethodImprovementContextSchema: z.ZodObject<{
     review_paths: z.ZodObject<{
         method_root: z.ZodString;
         compiled_runtime: z.ZodNullable<z.ZodString>;
-        test_comparisons: z.ZodNullable<z.ZodString>;
+        readiness_runs: z.ZodNullable<z.ZodString>;
         execution_shells: z.ZodNullable<z.ZodString>;
         test_runs: z.ZodNullable<z.ZodString>;
         test_sandboxes: z.ZodNullable<z.ZodString>;
@@ -635,7 +624,13 @@ export type ViewSection = z.infer<typeof ViewSectionSchema>;
 export type ViewCard = z.infer<typeof ViewCardSchema>;
 export type CompiledHealth = z.infer<typeof CompiledHealthSchema>;
 export type CompiledViewSpec = z.infer<typeof CompiledViewSpecSchema>;
-export type CompiledRawSnapshot = z.infer<typeof CompiledRawSnapshotSchema>;
+export type SourceKind = z.infer<typeof SourceKindSchema>;
+export type Source = z.infer<typeof SourceSchema>;
+export type SourceFile = z.infer<typeof SourceFileSchema>;
+export type SourceFiles = z.infer<typeof SourceFilesSchema>;
+export type SourceSnapshot = z.infer<typeof SourceSnapshotSchema>;
+export type StageInput = z.infer<typeof StageInputSchema>;
+export type StageInputs = z.infer<typeof StageInputsSchema>;
 export type MethodCompiledZone = z.infer<typeof MethodCompiledZoneSchema>;
 export type MethodCompiledSchema = z.infer<typeof MethodCompiledSchemaSchema>;
 export type MethodCompiledZoneKind = z.infer<typeof MethodCompiledZoneKindSchema>;

package/dist/packages/compiler/lib/schema.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { COMPILED_ZONE_KINDS, } from "../method-primitives.js";
 import { RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, InterfIdPattern, MethodIdSchema, } from "../../contracts/lib/schema.js";
-export { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, MethodIdSchema, } from "../../contracts/lib/schema.js";
+export { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, MethodIdSchema, } from "../../contracts/lib/schema.js";
 const JsonRecordSchema = z.record(z.string(), z.unknown());
 const COMPILED_RELATIVE_PATH_SEGMENT = /^(?!\.{1,2}$)[^/\\]+$/;
 function isCompiledRelativePath(value) {
@@ -77,16 +77,6 @@ export const CompiledViewSpecSchema = z.object({
     cards: z.array(ViewCardSchema),
     sections: z.array(ViewSectionSchema),
 });
-export const CompiledRawSnapshotSchema = z.object({
-    kind: z.literal("compiled-raw-snapshot"),
-    version: z.literal(1),
-    generated_at: z.string(),
-    target_name: z.string(),
-    source_root: z.string(),
-    raw_root: z.string(),
-    source_total: z.number(),
-    sample_files: z.array(z.string()),
-});
 export const MethodPurposeSchema = z.object({
     label: z.string().min(1),
     task_hint: z.string().min(1),
@@ -177,7 +167,6 @@ export const RuntimeStageContractSchema = z.object({
     artifacts: z.object({
         reads: z.array(z.string()),
         writes: z.array(z.string()),
-        verifies: z.array(z.string()).optional(),
     }),
     policies: z.object({
         execution_mode: z.literal("deterministic"),
@@ -260,7 +249,7 @@ export const MethodImprovementContextSchema = z.object({
     review_paths: z.object({
         method_root: z.string(),
         compiled_runtime: z.string().nullable(),
-        test_comparisons: z.string().nullable(),
+        readiness_runs: z.string().nullable(),
         execution_shells: z.string().nullable(),
         test_runs: z.string().nullable(),
         test_sandboxes: z.string().nullable(),

package/dist/packages/compiler/method-runs.d.ts

@@ -1,6 +1,5 @@
 import { type InterfConfig } from "../project-model/interf-detect.js";
-export type { MethodReporter, MethodStageResult, LocalSkillContractExtension } from "../method-package/method-helpers.js";
-export { methodQueryDirectory, methodImproveDirectory, methodCompileStageDirectory, emptyLocalSkillContractExtension, buildLocalSkillContractExtension, buildLocalSkillContractExtensionRelativeTo, mergeLocalSkillContractExtensions, buildStageInstructions, reportLine, reportBlankLine, reportValidationFailure, resolveStageAcceptance, validateStageOutcome, } from "../method-package/method-helpers.js";
+export type { MethodReporter } from "../method-package/method-helpers.js";
 export type CompiledCheck = "compiled" | "stage";
 export interface DetectedInterfTarget {
     path: string;
@@ -9,7 +8,7 @@ export interface DetectedInterfTarget {
     config: InterfConfig;
 }
 export declare function detectCompiled(cwd: string): DetectedInterfTarget | null;
-export declare function createCompiled(name: string, sourcePath: string, methodId?: string, about?: string, sourceFolderPath?: string): string;
+export declare function createCompiled(name: string, sourcePath: string, methodId: string | undefined, about: string | undefined, sourceFolderPath: string): string;
 export declare function verifyCompiledCheck(check: CompiledCheck, compiledPath: string): import("./validate-compiled.js").CompiledMethodValidation;
 export { runCompiledSummarize, runCompiledCompile, compileCompiled, resolveCompiledContext, compiledExecutionStages, } from "./compiled-compile.js";
 export type { CompiledSummarizeResult, CompiledCompileResult, CompiledStageExecutionDefinition, StageShellRetentionMode, } from "./compiled-compile.js";

package/dist/packages/compiler/method-runs.js

@@ -2,7 +2,6 @@ import { createCompiled as createCompiledScaffold, } from "../project-model/inte
 import { detectInterf } from "../project-model/interf-detect.js";
 import { validateCompiledCompile, } from "./validate.js";
 import { DEFAULT_METHOD_ID } from "../methods/method-resolution.js";
-export { methodQueryDirectory, methodImproveDirectory, methodCompileStageDirectory, emptyLocalSkillContractExtension, buildLocalSkillContractExtension, buildLocalSkillContractExtensionRelativeTo, mergeLocalSkillContractExtensions, buildStageInstructions, reportLine, reportBlankLine, reportValidationFailure, resolveStageAcceptance, validateStageOutcome, } from "../method-package/method-helpers.js";
 export function detectCompiled(cwd) {
     const detected = detectInterf(cwd);
     if (!detected)
@@ -14,8 +13,8 @@ export function detectCompiled(cwd) {
         config: detected.config,
     };
 }
-export function createCompiled(name, sourcePath, methodId = DEFAULT_METHOD_ID, about, sourceFolderPath = sourcePath) {
-    return createCompiledScaffold(name, sourcePath, methodId, about, sourceFolderPath);
+export function createCompiled(name, sourcePath, methodId, about, sourceFolderPath) {
+    return createCompiledScaffold(name, sourcePath, methodId ?? DEFAULT_METHOD_ID, about, sourceFolderPath);
 }
 export function verifyCompiledCheck(check, compiledPath) {
     switch (check) {

package/dist/packages/compiler/reset.js

@@ -14,8 +14,10 @@ const COMPILE_RUNTIME_RESET_ENTRIES = [
     "view-spec.json",
     "inventory.json",
     "run.json",
-    "raw-snapshot.json",
+    "source-files.json",
+    "source-snapshot.json",
     "stage-contract.json",
+    "stages",
 ];
 const PRESERVED_COMPILED_ROOTS = new Set([
     ".agents",

package/dist/packages/compiler/runtime-contracts.js

@@ -18,9 +18,6 @@ export function buildRuntimeStageContract(options) {
                 ...localSkillDocs,
             ],
             writes: options.stageWriteArtifacts,
-            verifies: [
-                `interf verify stage ${options.stageId} --json`,
-            ],
         },
         policies: {
             execution_mode: "deterministic",

package/dist/packages/compiler/runtime-prompt.js

@@ -39,7 +39,7 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         "Do not narrate intentions, plans, or reasoning to the user.",
         "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
         "Those status lines are progress hints for the operator. The CLI decides stage completion from artifacts, validation, and reconcile checks rather than trusting status text alone.",
-        "Before any long-running raw inspection or shell-based helper step, emit a STATUS: line that names the current subtask.",
+        "Before any long-running source inspection or shell-based helper step, emit a STATUS: line that names the current subtask.",
         "If work stays in progress, do not remain silent for more than about one minute. Emit another STATUS: line when you switch files, page groups, targets, or extraction methods.",
         "If you respond conversationally instead of executing the stage, the run will be treated as failed.",
         "As soon as the required proof artifacts are complete, stop. Do not keep browsing or auditing after the contract is satisfied.",

package/dist/packages/compiler/source-files.d.ts

@@ -0,0 +1,46 @@
+import { type SourceFiles, type SourceSnapshot, type StageInputs } from "../contracts/lib/schema.js";
+export declare function buildCompiledSourceFiles(compiledPath: string, sourcePath?: string, generatedAt?: string): SourceFiles;
+export declare function writeCompiledSourceFiles(compiledPath: string, sourcePath?: string, generatedAt?: string): SourceFiles;
+export declare function buildCompiledSourceSnapshot(options: {
+    compiledPath: string;
+    sourceFiles?: SourceFiles;
+    sourcePath?: string;
+    runId?: string | null;
+    generatedAt?: string;
+}): SourceSnapshot;
+export declare function writeCompiledSourceSnapshot(options: {
+    compiledPath: string;
+    sourceFiles?: SourceFiles;
+    sourcePath?: string;
+    runId?: string | null;
+    generatedAt?: string;
+}): SourceSnapshot;
+export declare function buildCompiledStageInputs(options: {
+    methodId: string;
+    stageId: string;
+    snapshot: SourceSnapshot;
+    runId?: string | null;
+    generatedAt?: string;
+}): StageInputs;
+export declare function writeCompiledStageInputs(options: {
+    compiledPath: string;
+    methodId: string;
+    stageId: string;
+    snapshot: SourceSnapshot;
+    runId?: string | null;
+    generatedAt?: string;
+}): StageInputs;
+export declare function writeCompiledSourceRuntime(options: {
+    compiledPath: string;
+    methodId: string;
+    stageIds: string[];
+    sourcePath?: string;
+    runId?: string | null;
+}): {
+    sourceFiles: SourceFiles;
+    snapshot: SourceSnapshot;
+    stageInputs: StageInputs[];
+};
+export declare function loadCompiledSourceFiles(compiledPath: string): SourceFiles | null;
+export declare function loadCompiledSourceSnapshot(compiledPath: string): SourceSnapshot | null;
+export declare function loadCompiledStageInputs(compiledPath: string, stageId: string): StageInputs | null;

package/dist/packages/compiler/source-files.js

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { SourceFilesSchema, SourceSnapshotSchema, StageInputsSchema, } from "../contracts/lib/schema.js";
+import { readJsonFileWithSchema } from "../shared/parse.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { compiledRuntimeSourceFilesPath, compiledRuntimeSourceSnapshotPath, compiledRuntimeStageInputsPath, } from "./compiled-paths.js";
+import { resolveSourceInputPath } from "../project-model/interf-detect.js";
+function shortHash(value, length = 16) {
+    return createHash("sha256")
+        .update(value)
+        .digest("hex")
+        .slice(0, length);
+}
+function normalizeRelativePath(path) {
+    return path.replaceAll("\\", "/");
+}
+function buildSource(sourcePath) {
+    const locator = resolve(sourcePath);
+    return {
+        id: `src-${shortHash(locator, 12)}`,
+        kind: "local-folder",
+        locator,
+    };
+}
+function buildSourceFile(source, sourcePath, relativePath) {
+    const normalizedPath = normalizeRelativePath(relativePath);
+    return {
+        id: `file-${shortHash(`${source.id}\0${normalizedPath}`)}`,
+        path: normalizedPath,
+        locator: resolve(sourcePath, relativePath),
+    };
+}
+function buildSnapshotId(options) {
+    const fingerprint = {
+        source: options.sourceFiles.source,
+        files: options.sourceFiles.files.map((file) => [file.id, file.path, file.locator]),
+        generated_at: options.generatedAt,
+        run_id: options.runId ?? null,
+    };
+    return `snap-${shortHash(JSON.stringify(fingerprint))}`;
+}
+function writeJson(filePath, value) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+export function buildCompiledSourceFiles(compiledPath, sourcePath = resolveSourceInputPath(compiledPath), generatedAt = new Date().toISOString()) {
+    const discovery = discoverSourceFiles(sourcePath, compiledPath);
+    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 writeCompiledSourceFiles(compiledPath, sourcePath = resolveSourceInputPath(compiledPath), generatedAt = new Date().toISOString()) {
+    const sourceFiles = buildCompiledSourceFiles(compiledPath, sourcePath, generatedAt);
+    const parsed = SourceFilesSchema.parse(sourceFiles);
+    writeJson(compiledRuntimeSourceFilesPath(compiledPath), parsed);
+    return parsed;
+}
+export function buildCompiledSourceSnapshot(options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const sourceFiles = options.sourceFiles
+        ?? buildCompiledSourceFiles(options.compiledPath, options.sourcePath ?? resolveSourceInputPath(options.compiledPath), generatedAt);
+    return {
+        kind: "interf-source-snapshot",
+        version: 1,
+        snapshot_id: buildSnapshotId({
+            sourceFiles,
+            generatedAt,
+            runId: options.runId ?? null,
+        }),
+        generated_at: generatedAt,
+        run_id: options.runId ?? null,
+        source: sourceFiles.source,
+        source_total: sourceFiles.source_total,
+        files: sourceFiles.files,
+    };
+}
+export function writeCompiledSourceSnapshot(options) {
+    const snapshot = SourceSnapshotSchema.parse(buildCompiledSourceSnapshot(options));
+    writeJson(compiledRuntimeSourceSnapshotPath(options.compiledPath), snapshot);
+    return snapshot;
+}
+export function buildCompiledStageInputs(options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    return {
+        kind: "interf-stage-inputs",
+        version: 1,
+        generated_at: generatedAt,
+        run_id: options.runId ?? options.snapshot.run_id ?? null,
+        method: options.methodId,
+        stage: options.stageId,
+        source_snapshot_id: options.snapshot.snapshot_id,
+        input_total: options.snapshot.files.length,
+        inputs: options.snapshot.files.map((file) => ({
+            source_file_id: file.id,
+            path: file.path,
+            locator: file.locator,
+        })),
+    };
+}
+export function writeCompiledStageInputs(options) {
+    const stageInputs = StageInputsSchema.parse(buildCompiledStageInputs(options));
+    writeJson(compiledRuntimeStageInputsPath(options.compiledPath, options.stageId), stageInputs);
+    return stageInputs;
+}
+export function writeCompiledSourceRuntime(options) {
+    const generatedAt = new Date().toISOString();
+    const sourceFiles = writeCompiledSourceFiles(options.compiledPath, options.sourcePath ?? resolveSourceInputPath(options.compiledPath), generatedAt);
+    const snapshot = writeCompiledSourceSnapshot({
+        compiledPath: options.compiledPath,
+        sourceFiles,
+        runId: options.runId ?? null,
+        generatedAt,
+    });
+    const stageInputs = options.stageIds.map((stageId) => writeCompiledStageInputs({
+        compiledPath: options.compiledPath,
+        methodId: options.methodId,
+        stageId,
+        snapshot,
+        runId: options.runId ?? null,
+        generatedAt,
+    }));
+    return { sourceFiles, snapshot, stageInputs };
+}
+export function loadCompiledSourceFiles(compiledPath) {
+    const filePath = compiledRuntimeSourceFilesPath(compiledPath);
+    if (!existsSync(filePath))
+        return null;
+    return readJsonFileWithSchema(filePath, "compiled source files", SourceFilesSchema);
+}
+export function loadCompiledSourceSnapshot(compiledPath) {
+    const filePath = compiledRuntimeSourceSnapshotPath(compiledPath);
+    if (!existsSync(filePath))
+        return null;
+    return readJsonFileWithSchema(filePath, "compiled source snapshot", SourceSnapshotSchema);
+}
+export function loadCompiledStageInputs(compiledPath, stageId) {
+    const filePath = compiledRuntimeStageInputsPath(compiledPath, stageId);
+    if (!existsSync(filePath))
+        return null;
+    return readJsonFileWithSchema(filePath, "compiled stage inputs", StageInputsSchema);
+}

package/dist/packages/compiler/state-artifacts.d.ts

@@ -1,8 +1,9 @@
-import { type CompiledHealth, type CompiledRawSnapshot, type CompiledViewSpec } from "./lib/schema.js";
+import { type CompiledHealth, type CompiledViewSpec, type SourceFiles, type SourceSnapshot } from "./lib/schema.js";
 export declare function refreshCompiledArtifacts(dirPath: string, options?: {
     ensureViewSpec?: boolean;
 }): {
     health: CompiledHealth;
     viewSpec?: CompiledViewSpec;
-    rawSnapshot: CompiledRawSnapshot;
+    sourceFiles: SourceFiles;
+    sourceSnapshot: SourceSnapshot;
 };

package/dist/packages/compiler/state-artifacts.js

@@ -1,13 +1,14 @@
 import { saveCompiledHealth, } from "./state-io.js";
 import { computeCompiledHealth, } from "./state-health.js";
-import { ensureCompiledRawSnapshot, ensureCompiledViewSpec, } from "./state-view.js";
+import { ensureCompiledSourceFiles, ensureCompiledSourceSnapshot, ensureCompiledViewSpec, } from "./state-view.js";
 export function refreshCompiledArtifacts(dirPath, options) {
     const health = computeCompiledHealth(dirPath);
     saveCompiledHealth(dirPath, health);
-    const rawSnapshot = ensureCompiledRawSnapshot(dirPath);
+    const sourceFiles = ensureCompiledSourceFiles(dirPath);
+    const sourceSnapshot = ensureCompiledSourceSnapshot(dirPath, sourceFiles);
     let viewSpec;
     if (options?.ensureViewSpec) {
         viewSpec = ensureCompiledViewSpec(dirPath);
     }
-    return { health, viewSpec, rawSnapshot };
+    return { health, viewSpec, sourceFiles, sourceSnapshot };
 }

package/dist/packages/compiler/state-io.d.ts

@@ -1,10 +1,11 @@
-import { type CompiledHealth, type CompiledRawSnapshot, type CompiledState, type CompiledViewSpec } from "./lib/schema.js";
+import { type CompiledHealth, type CompiledState, type CompiledViewSpec, type SourceFiles, type SourceSnapshot } from "./lib/schema.js";
 export declare function loadState<T>(dirPath: string): T | null;
 export declare function saveState<T>(dirPath: string, state: T): void;
 export declare function loadCompiledHealth(dirPath: string): CompiledHealth | null;
 export declare function saveCompiledHealth(dirPath: string, health: CompiledHealth): void;
 export declare function loadCompiledViewSpec(dirPath: string): CompiledViewSpec | null;
 export declare function saveCompiledViewSpec(dirPath: string, viewSpec: CompiledViewSpec): void;
-export declare function loadCompiledRawSnapshot(dirPath: string): CompiledRawSnapshot | null;
+export declare function loadCompiledSourceFiles(dirPath: string): SourceFiles | null;
+export declare function loadCompiledSourceSnapshot(dirPath: string): SourceSnapshot | null;
 export declare function saveEmptyCompiledInventory(dirPath: string): void;
 export declare function initCompiledState(): CompiledState;

package/dist/packages/compiler/state-io.js

@@ -1,9 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import { warnInterf } from "../shared/logger.js";
 import { readJsonFileUnchecked, readJsonFileWithSchema } from "../shared/parse.js";
-import { CompiledHealthSchema, CompiledRawSnapshotSchema, CompiledStateSchema, CompiledViewSpecSchema, } from "./lib/schema.js";
+import { CompiledHealthSchema, CompiledStateSchema, CompiledViewSpecSchema, SourceFilesSchema, SourceSnapshotSchema, } from "./lib/schema.js";
 import { emptyCompiledInventory, } from "./runtime-inventory.js";
-import { healthPath, rawSnapshotPath, statePath, viewSpecPath } from "./state-paths.js";
+import { healthPath, sourceFilesPath, sourceSnapshotPath, statePath, viewSpecPath, } from "./state-paths.js";
 import { compiledRuntimeInventoryPath, compiledRuntimeRoot, } from "./compiled-paths.js";
 export function loadState(dirPath) {
     const path = statePath(dirPath);
@@ -43,11 +43,17 @@ export function saveCompiledViewSpec(dirPath, viewSpec) {
     mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });
     writeFileSync(viewSpecPath(dirPath), JSON.stringify(viewSpec, null, 2) + "\n");
 }
-export function loadCompiledRawSnapshot(dirPath) {
-    const path = rawSnapshotPath(dirPath);
+export function loadCompiledSourceFiles(dirPath) {
+    const path = sourceFilesPath(dirPath);
     if (!existsSync(path))
         return null;
-    return readJsonFileWithSchema(path, "compiled raw snapshot", CompiledRawSnapshotSchema);
+    return readJsonFileWithSchema(path, "compiled source files", SourceFilesSchema);
+}
+export function loadCompiledSourceSnapshot(dirPath) {
+    const path = sourceSnapshotPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "compiled source snapshot", SourceSnapshotSchema);
 }
 export function saveEmptyCompiledInventory(dirPath) {
     mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });

package/dist/packages/compiler/state-paths.d.ts

@@ -1,4 +1,5 @@
 export declare function statePath(dirPath: string): string;
 export declare function healthPath(dirPath: string): string;
 export declare function viewSpecPath(dirPath: string): string;
-export declare function rawSnapshotPath(dirPath: string): string;
+export declare function sourceFilesPath(dirPath: string): string;
+export declare function sourceSnapshotPath(dirPath: string): string;

package/dist/packages/compiler/state-paths.js

@@ -1,4 +1,4 @@
-import { compiledRawSnapshotMetadataPath, compiledRuntimeHealthPath, compiledRuntimeStatePath, compiledRuntimeViewSpecPath, } from "./compiled-paths.js";
+import { compiledRuntimeHealthPath, compiledRuntimeSourceFilesPath, compiledRuntimeSourceSnapshotPath, compiledRuntimeStatePath, compiledRuntimeViewSpecPath, } from "./compiled-paths.js";
 export function statePath(dirPath) {
     return compiledRuntimeStatePath(dirPath);
 }
@@ -8,6 +8,9 @@ export function healthPath(dirPath) {
 export function viewSpecPath(dirPath) {
     return compiledRuntimeViewSpecPath(dirPath);
 }
-export function rawSnapshotPath(dirPath) {
-    return compiledRawSnapshotMetadataPath(dirPath);
+export function sourceFilesPath(dirPath) {
+    return compiledRuntimeSourceFilesPath(dirPath);
+}
+export function sourceSnapshotPath(dirPath) {
+    return compiledRuntimeSourceSnapshotPath(dirPath);
 }

package/dist/packages/compiler/state-view.d.ts

@@ -1,4 +1,5 @@
-import { type CompiledRawSnapshot, type CompiledViewSpec } from "./lib/schema.js";
+import { type CompiledViewSpec, type SourceFiles, type SourceSnapshot } from "./lib/schema.js";
 export declare function ensureCompiledViewSpec(dirPath: string): CompiledViewSpec;
-export declare function ensureCompiledRawSnapshot(dirPath: string): CompiledRawSnapshot;
+export declare function ensureCompiledSourceFiles(dirPath: string): SourceFiles;
+export declare function ensureCompiledSourceSnapshot(dirPath: string, sourceFiles?: SourceFiles): SourceSnapshot;
 export declare function normalizeCompiledViewSpec(existing: CompiledViewSpec, defaults?: CompiledViewSpec): CompiledViewSpec;