@interf/compiler 0.9.5 → 0.13.0

package/dist/packages/agents/lib/shells.js

@@ -1,11 +1,11 @@
 import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, symlinkSync, } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative, sep as pathSep } from "node:path";
 import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
-import { projectRawSnapshot } from "../../compiler/raw-snapshot.js";
+import { buildCompiledSourceFiles } from "../../compiler/source-files.js";
 import { METHOD_PACKAGE_DIR } from "../../project-model/interf-detect.js";
 import { CONTEXT_INTERFACE_FILE as METHOD_SCHEMA_FILE, contextInterfaceZoneAbsolutePath as compiledZoneAbsolutePath, readContextInterface as readCompiledSchemaFile, resolveContextInterfacePath as resolveMethodSchemaPath, } from "../../method-package/context-interface.js";
-import { stageExecutionShellsRoot, methodImprovementLoopRoot, methodPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, } from "../../compiler/compiled-paths.js";
+import { stageExecutionShellsRoot, methodImprovementLoopRoot, methodPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, compiledRuntimeSourceSnapshotPath, compiledRuntimeStageInputsPath, } from "../../compiler/compiled-paths.js";
 import { ensureCompiledZoneTargets } from "../../compiler/compiled-schema.js";
 import { listFilesRecursive } from "../../shared/filesystem.js";
 import { resolveMethodImprovementReviewSourcePaths } from "../../method-package/method-review-paths.js";
@@ -54,12 +54,12 @@ export function renderCompiledAgents(compiledPath, name, methodId, about, option
         "",
         "1. Use the local native `interf-query` skill that Interf generated for this portable context.",
         "2. Let the Method docs and declared output zones guide retrieval instead of assuming a fixed note layout.",
-        "3. Use `raw/` when you need direct quotes, exact chart values, table lookups, or verification.",
+        "3. Use `.interf/runtime/source-snapshot.json` when you need to inspect the source references behind the output.",
         "",
         "## How this portable context works",
         "",
         "- The Method package defines the context interface this portable context implements on disk.",
-        "- `.interf/interf.json` points to the local `raw/` snapshot via `source.path` and back to the Interf Workspace via `source.control_path`.",
+        "- `.interf/interf.json` records the selected source binding and back-reference to the Interf Workspace.",
         `- Method seed: \`${methodOriginSelected}\`.`,
         ...(methodLocalDraft
             ? ["- This portable context now carries a local Method draft improved from that seed. Recompiling this portable context reuses the local `.interf/method/` package."]
@@ -71,36 +71,34 @@ export function renderCompiledAgents(compiledPath, name, methodId, about, option
         "- `.interf/method/use/query/` is the editable source for the generated native query shell.",
         "- `.interf/method/compile/stages/` defines stage-specific docs that Interf projects into native execution shells for automated runs.",
         "- Native local query skills are generated under local agent skill directories such as `.claude/skills/` and `.codex/skills/`.",
-        "- `raw/` contains the local raw snapshot used for evidence and verification.",
+        "- `.interf/runtime/source-snapshot.json` records the source files assigned to the latest runtime snapshot.",
         `- Method zones are declared in \`.interf/method/${METHOD_SCHEMA_FILE}\`.`,
         ...zoneLines,
         "- `.interf/runtime/` holds runtime artifacts written by Interf.",
         "- `.interf/tests/` mirrors the latest saved readiness-check run and keeps detailed target runs plus preserved sandboxes.",
-        "- `.interf/tests/targets/` holds detailed raw and compiled target runs plus preserved test sandboxes.",
+        "- `.interf/tests/targets/` holds detailed source-files and compiled target runs plus preserved test sandboxes.",
         "",
         "## Manual query rules",
         "",
-        "- Prefer the Method-declared context outputs before `raw/`.",
+        "- Prefer the Method-declared context outputs before source re-checks.",
         "- Use the generated native `interf-query` skill for manual querying. The editable source lives at `.interf/method/use/query/SKILL.md`.",
         "- Treat `.interf/` as method/runtime metadata, not answer evidence, unless explicitly asked to inspect Method or test history.",
-        "- Use `raw/` for quotes, verification, ambiguity, or evidence the portable context does not expose well.",
-        "- If exact chart, table, or image-derived evidence matters, inspect the raw source and say whether the answer was text-derived, table-derived, or chart-derived.",
+        "- Use `.interf/runtime/source-snapshot.json` to find source references for quotes, verification, ambiguity, or evidence the portable context does not expose well.",
+        "- If exact chart, table, or image-derived evidence matters, inspect the source reference and say whether the answer was text-derived, table-derived, or chart-derived.",
         "",
         "## Commands",
         "",
         "```",
         "interf compile            build this portable context",
         "interf test               run checks against this portable context",
-        "interf verify stage <id>  verify one Method stage",
-        "interf verify portable-context    verify the full portable context output",
         "interf status             show deterministic health",
         "```",
         "",
         "## Rules",
         "",
-        "- Do not modify files under `raw/`.",
+        "- Do not modify source files while answering from this portable context.",
         "- Treat prepared notes as working context, not final truth.",
-        "- When confidence is low, verify against `raw/` before answering strongly.",
+        "- When confidence is low, verify against the source references before answering strongly.",
         "",
     ].join("\n");
 }
@@ -112,38 +110,38 @@ export function renderCompiledQuerySkill() {
         "",
         "Default loop:",
         "1. Read `.interf/method/README.md` and this file first.",
-        `2. Use the Method zones declared in \`.interf/method/${METHOD_SCHEMA_FILE}\` before consulting \`raw/\`.`,
-        "3. Use `raw/` for direct quotes, verification, exact lookups, and cases where the portable context is missing the needed evidence or is ambiguous.",
+        `2. Use the Method zones declared in \`.interf/method/${METHOD_SCHEMA_FILE}\` before consulting source references.`,
+        "3. Use `.interf/runtime/source-snapshot.json` for direct quotes, verification, exact lookups, and cases where the portable context is missing the needed evidence or is ambiguous.",
         "",
         "Answering rule:",
-        "- do not modify files under `raw/`",
+        "- do not modify source files while answering",
         "- treat the Method as the portable-context contract and use its zones as the working retrieval surface",
-        "- say explicitly when an answer depends on approximation, bounded inference, or a raw-source re-check",
-        "- use `raw/` to confirm source page, metric family, provenance, or exact wording when the portable context is missing the needed evidence or is ambiguous",
+        "- say explicitly when an answer depends on approximation, bounded inference, or a source re-check",
+        "- use source references to confirm source page, metric family, provenance, or exact wording when the portable context is missing the needed evidence or is ambiguous",
         "- do not invent navigation or note structure beyond what this Method declares",
-        "- when the portable context is insufficient, verify in `raw/` and then answer",
+        "- when the portable context is insufficient, verify against source references and then answer",
         "",
         "You can edit this file to bias manual question-answering behavior for this portable context.",
         "",
     ].join("\n");
 }
-function renderRawTestAgents() {
+function renderSourceFilesTestAgents() {
     const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note}`);
     return [
-        "# Raw Test Shell",
+        "# Source Files Test Shell",
         "",
-        "This is an isolated raw-files test shell generated by Interf.",
+        "This is an isolated source-files test shell generated by Interf.",
         "There is no portable context in this shell.",
         "",
         "## How to use this shell",
         "",
         "1. Read this file first.",
         "2. Use the local native `interf-query` skill available in this shell.",
-        "3. Read only from `raw/`.",
+        "3. Read `runtime/source-files.json` and use only the listed source references.",
         "",
         "## Rules",
         "",
-        "- Answer only from the files under `raw/`.",
+        "- Answer only from source files listed in `runtime/source-files.json`.",
         "- There is no portable context here, so do not assume any portable-context output zones exist.",
         "- Do not treat hidden runtime files or test artifacts as evidence.",
         ...chartNotes,
@@ -151,23 +149,23 @@ function renderRawTestAgents() {
         "",
     ].join("\n");
 }
-function renderRawTestQuerySkill() {
+function renderSourceFilesTestQuerySkill() {
     const chartNotes = CHART_APPROXIMATION_NOTES.map((note, index) => `${index + 3}. ${note}`);
     return [
         "---",
         "name: interf-query",
         "description: >",
-        "  Native local query skill for an Interf raw test shell. Use it only",
-        "  to answer source-files readiness checks directly from `raw/`.",
+        "  Native local query skill for an Interf source-files test shell. Use it only",
+        "  to answer source-files readiness checks from `runtime/source-files.json` references.",
         "---",
         "",
-        "# Interf Raw Test Query",
+        "# Interf Source Files Test Query",
         "",
-        "This is the native local query skill for an isolated raw-files test shell.",
+        "This is the native local query skill for an isolated source-files test shell.",
         "",
         "Loop:",
-        "1. Read `raw/` directly.",
-        "2. Verify exact claims against the raw files before answering strongly.",
+        "1. Read `runtime/source-files.json`.",
+        "2. Verify exact claims against the listed source locators before answering strongly.",
         ...chartNotes,
         "8. Do not rely on portable-context artifacts because they do not exist in this shell.",
         "",
@@ -225,6 +223,11 @@ function linkPath(targetPath, linkPathname) {
     mkdirSync(dirname(linkPathname), { recursive: true });
     symlinkSync(targetPath, linkPathname);
 }
+function linkIfExists(targetPath, linkPathname) {
+    if (!existsSync(targetPath))
+        return;
+    linkPath(targetPath, linkPathname);
+}
 function linkRelativePath(targetPath, linkPathname) {
     mkdirSync(dirname(linkPathname), { recursive: true });
     symlinkSync(relative(dirname(linkPathname), targetPath), linkPathname);
@@ -322,15 +325,18 @@ function renderStageExecutionAgents(compiledName, methodId, stage) {
         "## Start Here",
         "",
         "1. Read `runtime/stage-contract.json` now.",
-        "2. Read `runtime/paths.json` now.",
-        "3. Use the local native `interf-stage` skill now.",
-        `4. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
+        "2. Read `runtime/source-snapshot.json` and `runtime/stage-inputs.json` now.",
+        "3. Read `runtime/paths.json` now.",
+        "4. Use the local native `interf-stage` skill now.",
+        `5. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
         "",
         "## Shell ABI",
         "",
         "- `inputs/<zone-id>/` = read mounts for the current stage.",
         "- `outputs/<zone-id>/` = write mounts for the current stage.",
         "- For file zones, `runtime/paths.json` points to the exact file path inside those mount roots.",
+        "- `runtime/source-snapshot.json` = source references captured for this run.",
+        "- `runtime/stage-inputs.json` = exact source references assigned to this stage.",
         "- declared compiled zone paths are also projected at the shell root so Method-relative contract paths stay valid.",
         "- `runtime/` = stage contract and machine-readable path map for this shell.",
         "- `method/` = Method metadata, `method.schema.json`, and docs for the current stage only.",
@@ -371,7 +377,8 @@ function renderStageExecutionSkill(stage, stageMethodDoc) {
         "",
         "This local native skill exists for automated Interf stage execution.",
         "Read `runtime/stage-contract.json` first.",
-        "Then read `runtime/paths.json` and use the mounted `inputs/` and `outputs/` zones for this stage.",
+        "Then read `runtime/source-snapshot.json`, `runtime/stage-inputs.json`, and `runtime/paths.json`.",
+        "Use the assigned source references and the mounted `inputs/` and `outputs/` zones for this stage.",
         "Do not switch into manual query mode.",
         "",
         "## Current Stage",
@@ -399,7 +406,7 @@ function renderCompiledQueryNativeSkill(querySkillContent) {
         "name: interf-query",
         "description: >",
         "  Native local query skill for this portable context built by Interf.",
-        "  Use it for manual questions against the portable context and source files under raw/.",
+        "  Use it for manual questions against the portable context and source references.",
         "---",
         "",
         "# Interf Query",
@@ -568,6 +575,44 @@ function shouldSkipFrozenStageShellRelativePath(relativePath) {
         normalized.endsWith("/improvement-loops") ||
         normalized.includes("/improvement-loops/");
 }
+/**
+ * System path prefixes a malicious symlink in a Method package must
+ * never reach. Without this, the freeze-snapshot logic could be
+ * tricked into copying anything the running user has access to —
+ * `/etc/passwd`, `~/.ssh/id_rsa`, etc. (CSO finding).
+ *
+ * We deliberately allow targets that escape the immediate freeze
+ * root: legitimate execution shells contain symlinks pointing back
+ * to the parent workspace's `interf.json`. The threat is only links
+ * that resolve into truly system-level paths.
+ */
+const FORBIDDEN_SYMLINK_TARGET_PREFIXES = [
+    "/etc",
+    "/sys",
+    "/proc",
+    "/dev",
+    "/var/run",
+    "/var/lib",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/boot",
+    "/root",
+];
+function ensureSymlinkTargetSafe(realTarget, symlinkPath) {
+    for (const prefix of FORBIDDEN_SYMLINK_TARGET_PREFIXES) {
+        if (realTarget === prefix || realTarget.startsWith(`${prefix}${pathSep}`)) {
+            throw new Error(`Refusing to follow symlink ${symlinkPath} → ${realTarget}: ` +
+                `resolves into system directory ${prefix}.`);
+        }
+    }
+    // Also refuse links that escape into another user's SSH directory
+    // even if the path is not on the literal forbidden list.
+    if (/\/\.ssh(\/|$)/.test(realTarget)) {
+        throw new Error(`Refusing to follow symlink ${symlinkPath} → ${realTarget}: ` +
+            `targets a .ssh directory.`);
+    }
+}
 function copyResolvedTree(options) {
     const relativePath = options.relativePath ?? "";
     if (options.shellType === "stage-execution" && shouldSkipFrozenStageShellRelativePath(relativePath)) {
@@ -575,7 +620,24 @@ function copyResolvedTree(options) {
     }
     const stat = lstatSync(options.sourcePath);
     if (stat.isSymbolicLink()) {
+        // existsSync follows symlinks, so a dangling link (target absent)
+        // returns false. Skip those entries: realpathSync would throw
+        // ENOENT, and the freeze step is best-effort review material —
+        // losing one unresolvable link is better than aborting the whole
+        // snapshot. Production trigger: createStageExecutionShell links
+        // runtime/stage-contract.json before writeStageContract runs, so
+        // any failure between those two points leaves a dangling link
+        // that the per-stage finally-block freeze would otherwise hit.
+        if (!existsSync(options.sourcePath)) {
+            return { materializedSymlinks: 0 };
+        }
         const realTarget = realpathSync(options.sourcePath);
+        // Refuse symlinks resolving into system paths (CSO finding). We
+        // deliberately allow links that escape the immediate freeze root
+        // because legitimate execution shells contain links back to the
+        // parent workspace's interf.json — the only thing we care about
+        // is that the realpath does not land in /etc, /sys, /proc, etc.
+        ensureSymlinkTargetSafe(realTarget, options.sourcePath);
         const realStat = statSync(realTarget);
         if (realStat.isDirectory()) {
             const mappedTarget = options.materializedRealPaths?.get(realTarget);
@@ -672,7 +734,7 @@ function renderMethodAuthoringAgents(options) {
         "",
         "1. Read `runtime/authoring-context.json` now.",
         `2. Read \`method/README.md\`, \`method/method.json\`, and \`method/${METHOD_SCHEMA_FILE}\` now.`,
-        "3. Review `artifacts/source-folder/raw/`.",
+        "3. Read `runtime/source-files.json` and review the listed source locators.",
         "4. Use the local native `interf-method-author` skill now.",
         "",
         "## Boundaries",
@@ -712,7 +774,7 @@ function renderMethodAuthoringSkill() {
         "# Interf Method Authoring",
         "",
         "Read `runtime/authoring-context.json` first.",
-        "Then review the neutral Method package scaffold under `method/` and the raw snapshot under `artifacts/source-folder/raw/`.",
+        "Then review the neutral Method package scaffold under `method/`, read `runtime/source-files.json`, and inspect the listed source locators when needed.",
         "",
         "Rules:",
         "- edit only `method/`",
@@ -762,14 +824,7 @@ export function createMethodAuthoringShell(options) {
         },
     };
     writeFileSync(join(shellRoot, "runtime", "authoring-context.json"), `${JSON.stringify(context, null, 2)}\n`);
-    projectRawSnapshot({
-        sourcePath: options.sourceFolderPath,
-        destinationPath: join(shellRoot, "artifacts", "source-folder", "raw"),
-        compiledPath: shellRoot,
-        mode: "copy",
-        prune: true,
-        preserveTimestamps: true,
-    });
+    writeFileSync(join(shellRoot, "runtime", "source-files.json"), `${JSON.stringify(buildCompiledSourceFiles(shellRoot, options.sourceFolderPath), null, 2)}\n`);
     copyResolvedTree({
         sourcePath: options.methodPath,
         targetPath: join(shellRoot, "method"),
@@ -808,7 +863,7 @@ function renderMethodImprovementAgents(compiledName, methodId, loopIndex) {
         `- Method: \`${methodId}\`.`,
         `- Improvement loop: ${loopIndex}.`,
         "- Edit only files under `method/`.",
-        "- Do not edit checks, test specs, raw files, or generated context outputs.",
+        "- Do not edit checks, test specs, source files, or generated context outputs.",
         "- Review context outputs under `artifacts/compiled-view/` and test/runtime evidence under `artifacts/`.",
         "- Keep the Method package valid for the current compiler API and `method.schema.json`.",
         "- For acceptance criteria, use `zone_counts_at_least` for numeric fixed minimums and `zone_counts_at_least_counts` only for runtime count-key strings such as `source_total`.",
@@ -862,7 +917,7 @@ function projectCompiledReviewArtifactsSnapshot(compiledPath, shellRoot, schema)
     const compiledViewRoot = join(shellRoot, "artifacts", "compiled-view");
     mkdirSync(compiledViewRoot, { recursive: true });
     for (const zone of schema.zones) {
-        if (zone.kind === "runtime" || zone.path === "raw")
+        if (zone.kind === "runtime" || zone.path === "source-files")
             continue;
         const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
         if (!existsSync(sourcePath))
@@ -893,7 +948,9 @@ function projectCompiledRuntimeArtifacts(compiledPath, shellRoot) {
         "state.json",
         "health.json",
         "view-spec.json",
-        "raw-snapshot.json",
+        "source-files.json",
+        "source-snapshot.json",
+        "stages",
         "logs",
     ];
     for (const artifactName of artifactNames) {
@@ -908,8 +965,8 @@ export function projectCompiledQueryShell(compiledPath, compiledName, methodId,
     const querySkillContent = readCompiledQuerySkillSource(compiledPath);
     return writeNativeAgentSurface(compiledPath, agentsContent, "interf-query", renderCompiledQueryNativeSkill(querySkillContent));
 }
-export function projectRawTestQueryShell(rootPath) {
-    return writeNativeAgentSurface(rootPath, renderRawTestAgents(), "interf-query", renderRawTestQuerySkill());
+export function projectSourceFilesTestQueryShell(rootPath) {
+    return writeNativeAgentSurface(rootPath, renderSourceFilesTestAgents(), "interf-query", renderSourceFilesTestQuerySkill());
 }
 export function createStageExecutionShell(compiledPath, compiledName, methodId, stage, writeArtifacts = []) {
     const schema = ensureCompiledExecutionSurface(compiledPath);
@@ -922,6 +979,8 @@ export function createStageExecutionShell(compiledPath, compiledName, methodId,
     mkdirSync(join(shellRoot, "outputs"), { recursive: true });
     linkPath(compiledInterfConfigPath(compiledPath), join(shellRoot, "interf.json"));
     linkPath(join(compiledRuntimeRoot(compiledPath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
+    linkIfExists(compiledRuntimeSourceSnapshotPath(compiledPath), shellRuntimePath(shellRoot, "source-snapshot.json"));
+    linkIfExists(compiledRuntimeStageInputsPath(compiledPath, stage.id), shellRuntimePath(shellRoot, "stage-inputs.json"));
     projectCompiledSchemaZones(compiledPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedZones);
     projectMethodMetadata(compiledPath, shellRoot, stage);
     projectStageZoneMountAliases(shellRoot, stage, schema);

package/dist/packages/agents/lib/user-config.d.ts

@@ -1,6 +1,8 @@
 import { type InterfUserConfig } from "./schema.js";
 export type { InterfUserConfig } from "./schema.js";
-export declare const INTERF_HOME: string;
-export declare const USER_CONFIG_PATH: string;
+/** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
+export declare function interfHome(): string;
+/** `~/.interf/config.json` — local executor preferences. */
+export declare function userConfigPath(): string;
 export declare function loadUserConfig(): InterfUserConfig | null;
 export declare function saveUserConfig(config: InterfUserConfig): void;

package/dist/packages/agents/lib/user-config.js

@@ -1,16 +1,24 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { readJsonFileWithSchema } from "../../shared/parse.js";
+import { interfHomeRoot } from "../../contracts/lib/preparation-paths.js";
 import { InterfUserConfigSchema } from "./schema.js";
-export const INTERF_HOME = join(homedir(), ".interf");
-export const USER_CONFIG_PATH = join(INTERF_HOME, "config.json");
+/** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
+export function interfHome() {
+    return interfHomeRoot();
+}
+/** `~/.interf/config.json` — local executor preferences. */
+export function userConfigPath() {
+    return join(interfHome(), "config.json");
+}
 export function loadUserConfig() {
-    if (!existsSync(USER_CONFIG_PATH))
+    const configPath = userConfigPath();
+    if (!existsSync(configPath))
         return null;
-    return readJsonFileWithSchema(USER_CONFIG_PATH, "user config", InterfUserConfigSchema);
+    return readJsonFileWithSchema(configPath, "user config", InterfUserConfigSchema);
 }
 export function saveUserConfig(config) {
-    mkdirSync(INTERF_HOME, { recursive: true });
-    writeFileSync(USER_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+    const home = interfHome();
+    mkdirSync(home, { recursive: true });
+    writeFileSync(userConfigPath(), JSON.stringify(config, null, 2) + "\n");
 }

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

@@ -7,7 +7,10 @@ export declare const COMPILED_RUNTIME_DIR = "runtime";
 export declare const COMPILED_RUNTIME_STATE_FILE = "state.json";
 export declare const COMPILED_RUNTIME_HEALTH_FILE = "health.json";
 export declare const COMPILED_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
-export declare const COMPILED_RUNTIME_RAW_SNAPSHOT_FILE = "raw-snapshot.json";
+export declare const COMPILED_RUNTIME_SOURCE_FILES_FILE = "source-files.json";
+export declare const COMPILED_RUNTIME_SOURCE_SNAPSHOT_FILE = "source-snapshot.json";
+export declare const COMPILED_RUNTIME_STAGE_INPUTS_DIR = "stages";
+export declare const COMPILED_RUNTIME_STAGE_INPUTS_FILE = "inputs.json";
 export declare const COMPILED_RUNTIME_INVENTORY_FILE = "inventory.json";
 export declare const COMPILED_RUNTIME_RUN_FILE = "run.json";
 export declare const COMPILED_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
@@ -31,7 +34,11 @@ export declare function compiledQueryAcceptanceRoot(compiledPath: string): strin
 export declare function compiledRuntimeStatePath(compiledPath: string): string;
 export declare function compiledRuntimeHealthPath(compiledPath: string): string;
 export declare function compiledRuntimeViewSpecPath(compiledPath: string): string;
-export declare function compiledRawSnapshotMetadataPath(compiledPath: string): string;
+export declare function compiledRuntimeSourceFilesPath(compiledPath: string): string;
+export declare function compiledRuntimeSourceSnapshotPath(compiledPath: string): string;
+export declare function compiledRuntimeStagesRoot(compiledPath: string): string;
+export declare function compiledRuntimeStageRoot(compiledPath: string, stageId: string): string;
+export declare function compiledRuntimeStageInputsPath(compiledPath: string, stageId: string): string;
 export declare function compiledRuntimeInventoryPath(compiledPath: string): string;
 export declare function compiledRuntimeRunPath(compiledPath: string): string;
 export declare function compiledRuntimeRunHistoryPath(compiledPath: string): string;

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

@@ -8,7 +8,10 @@ export const COMPILED_RUNTIME_DIR = "runtime";
 export const COMPILED_RUNTIME_STATE_FILE = "state.json";
 export const COMPILED_RUNTIME_HEALTH_FILE = "health.json";
 export const COMPILED_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
-export const COMPILED_RUNTIME_RAW_SNAPSHOT_FILE = "raw-snapshot.json";
+export const COMPILED_RUNTIME_SOURCE_FILES_FILE = "source-files.json";
+export const COMPILED_RUNTIME_SOURCE_SNAPSHOT_FILE = "source-snapshot.json";
+export const COMPILED_RUNTIME_STAGE_INPUTS_DIR = "stages";
+export const COMPILED_RUNTIME_STAGE_INPUTS_FILE = "inputs.json";
 export const COMPILED_RUNTIME_INVENTORY_FILE = "inventory.json";
 export const COMPILED_RUNTIME_RUN_FILE = "run.json";
 export const COMPILED_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
@@ -70,8 +73,20 @@ export function compiledRuntimeHealthPath(compiledPath) {
 export function compiledRuntimeViewSpecPath(compiledPath) {
     return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_VIEW_SPEC_FILE);
 }
-export function compiledRawSnapshotMetadataPath(compiledPath) {
-    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_RAW_SNAPSHOT_FILE);
+export function compiledRuntimeSourceFilesPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_SOURCE_FILES_FILE);
+}
+export function compiledRuntimeSourceSnapshotPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_SOURCE_SNAPSHOT_FILE);
+}
+export function compiledRuntimeStagesRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), COMPILED_RUNTIME_STAGE_INPUTS_DIR);
+}
+export function compiledRuntimeStageRoot(compiledPath, stageId) {
+    return join(compiledRuntimeStagesRoot(compiledPath), stageId);
+}
+export function compiledRuntimeStageInputsPath(compiledPath, stageId) {
+    return join(compiledRuntimeStageRoot(compiledPath, stageId), COMPILED_RUNTIME_STAGE_INPUTS_FILE);
 }
 export function compiledRuntimeInventoryPath(compiledPath) {
     return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_INVENTORY_FILE);
@@ -86,19 +101,19 @@ export function compiledRuntimeStageContractPath(compiledPath) {
     return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_STAGE_CONTRACT_FILE);
 }
 export function resolveSourceControlPathForCompiled(compiledPath) {
-    let cursor = resolve(compiledPath);
-    while (true) {
-        const parent = dirname(cursor);
-        if (basename(parent) === "interf" &&
-            basename(cursor) !== "tests" &&
-            basename(cursor) !== "methods") {
-            return dirname(parent);
-        }
-        if (parent === cursor)
-            break;
-        cursor = parent;
+    // Flat workspace layout: the portable context lives at
+    // `<workspace>/<preparation>/`, so the workspace root is the parent of the
+    // portable context. Reject the filesystem root (which has no parent) and the
+    // legacy `<workspace>/interf/<preparation>/` shape so stale fixtures fail loudly.
+    const compiledAbsolute = resolve(compiledPath);
+    const parent = dirname(compiledAbsolute);
+    if (parent === compiledAbsolute) {
+        throw new Error(`Portable context is not under the canonical Interf Workspace layout: ${compiledPath}`);
+    }
+    if (basename(parent) === "interf") {
+        throw new Error(`Portable context is not under the canonical Interf Workspace layout: ${compiledPath}`);
     }
-    throw new Error(`Portable context is not under the canonical Interf Workspace layout: ${compiledPath}`);
+    return parent;
 }
 export function defaultControlPathForCompiled(compiledPath) {
     const relativePath = relative(compiledPath, resolveSourceControlPathForCompiled(compiledPath));

package/dist/packages/compiler/compiled-pipeline.js

@@ -4,12 +4,12 @@ import { reportValidationFailure, } from "../method-package/method-helpers.js";
 import { validateCompiledMethod, } from "./validate.js";
 import { pruneStageExecutionShells, } from "../agents/lib/shells.js";
 import { resetCompiledGeneratedState } from "./reset.js";
-import { syncCompiledRawSnapshot } from "./raw-snapshot.js";
 import { compiledExecutionStages, resolveCompiledContext, } from "./compiled-target.js";
 import { discoverSourceFiles } from "./discovery.js";
 import { runCompiledStage } from "./compiled-stage-runner.js";
 import { resolveSourceInputPath } from "../project-model/interf-detect.js";
 import { methodPackagePathForCompiled } from "./compiled-paths.js";
+import { writeCompiledSourceRuntime } from "./source-files.js";
 export async function runCompiledSummarize(options) {
     const context = resolveCompiledContext(options.compiledPath);
     const stageDefinition = options.stageDefinition
@@ -23,6 +23,13 @@ export async function runCompiledSummarize(options) {
         };
     }
     const sourceCount = discoverSourceFiles(context.sourcePath, options.compiledPath).totalCount;
+    writeCompiledSourceRuntime({
+        compiledPath: options.compiledPath,
+        methodId: context.methodId,
+        stageIds: [stageDefinition.id],
+        sourcePath: context.sourcePath,
+        runId: options.runId ?? null,
+    });
     const result = await runCompiledStage({
         executor: options.executor,
         compiledPath: options.compiledPath,
@@ -50,6 +57,13 @@ export async function runCompiledCompile(options) {
     try {
         const context = resolveCompiledContext(options.compiledPath);
         const stages = compiledExecutionStages(context.methodId, options.compiledPath);
+        writeCompiledSourceRuntime({
+            compiledPath: options.compiledPath,
+            methodId: context.methodId,
+            stageIds: stages.map((stage) => stage.id),
+            sourcePath: context.sourcePath,
+            runId: options.runId ?? null,
+        });
         for (const [index, stageDefinition] of stages.entries()) {
             const result = await runCompiledStage({
                 executor: options.executor,
@@ -86,8 +100,6 @@ export async function compileCompiled(options) {
         failedStage: null,
     };
     try {
-        const sourceInputPath = resolveSourceInputPath(options.compiledPath);
-        syncCompiledRawSnapshot(options.compiledPath, sourceInputPath);
         refreshCompiledBootstrapGuidance(options.compiledPath);
         const methodValidation = validateMethodPackage(methodPackagePathForCompiled(options.compiledPath));
         if (!methodValidation.ok) {
@@ -107,7 +119,15 @@ export async function compileCompiled(options) {
             };
         }
         const context = resolveCompiledContext(options.compiledPath);
+        const sourceInputPath = resolveSourceInputPath(options.compiledPath);
         const stages = compiledExecutionStages(context.methodId, options.compiledPath);
+        writeCompiledSourceRuntime({
+            compiledPath: options.compiledPath,
+            methodId: context.methodId,
+            stageIds: stages.map((stage) => stage.id),
+            sourcePath: sourceInputPath,
+            runId: options.runId ?? null,
+        });
         for (const [index, stageDefinition] of stages.entries()) {
             const stageResult = await runCompiledStage({
                 executor: options.executor,

package/dist/packages/compiler/compiled-stage-plan.js

@@ -59,6 +59,10 @@ export function buildStageContract(compiledPath, stageDefinition, instructions)
         stageId: stageDefinition.id,
         stageLabel: stageDefinition.label,
         counts: buildStageCounts(compiledPath, stageDefinition),
+        extraReadArtifacts: [
+            ".interf/runtime/source-snapshot.json",
+            `.interf/runtime/stages/${stageDefinition.id}/inputs.json`,
+        ],
         stageReadArtifacts: stageArtifacts.reads,
         stageWriteArtifacts: stageArtifacts.writes,
         methodNotes: getActiveCompiledStagePolicyNotes(compiledPath, stageDefinition.id),

package/dist/packages/compiler/compiled-target.d.ts

@@ -5,7 +5,7 @@ export interface CompiledStageExecutionDefinition extends MethodStageDefinition
 export declare function resolveCompiledContext(compiledPath: string): {
     compiledName: string;
     sourcePath: string;
-    controlPath: string;
+    prepDataDir: string;
     methodId: CompiledMethodId;
 };
 export declare function compiledExecutionStages(_methodId: CompiledMethodId, compiledPath: string): CompiledStageExecutionDefinition[];

package/dist/packages/compiler/compiled-target.js

@@ -6,7 +6,7 @@ export function resolveCompiledContext(compiledPath) {
     return {
         compiledName: config?.name ?? "compiled",
         sourcePath: resolveSourceFolderPath(compiledPath, config),
-        controlPath: resolveSourceControlPath(compiledPath),
+        prepDataDir: resolveSourceControlPath(compiledPath),
         methodId,
     };
 }

package/dist/packages/compiler/index.d.ts

@@ -11,6 +11,7 @@ export * as runtimePrompt from "./runtime-prompt.js";
 export * as runtimeReconcile from "./runtime-reconcile.js";
 export * as runtimeRuns from "./runtime-runs.js";
 export * as runtimeTypes from "./runtime-types.js";
+export * as sourceFiles from "./source-files.js";
 export * as state from "./state.js";
 export * as stateArtifacts from "./state-artifacts.js";
 export * as stateHealth from "./state-health.js";

package/dist/packages/compiler/index.js

@@ -11,6 +11,7 @@ export * as runtimePrompt from "./runtime-prompt.js";
 export * as runtimeReconcile from "./runtime-reconcile.js";
 export * as runtimeRuns from "./runtime-runs.js";
 export * as runtimeTypes from "./runtime-types.js";
+export * as sourceFiles from "./source-files.js";
 export * as state from "./state.js";
 export * as stateArtifacts from "./state-artifacts.js";
 export * as stateHealth from "./state-health.js";