@interf/compiler 0.4.0 → 0.5.0

package/dist/lib/agent-shells.js

@@ -2,8 +2,8 @@ import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, re
 import { basename, dirname, join, relative } from "node:path";
 import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
 import { WORKFLOW_PACKAGE_DIR } from "./interf-detect.js";
-import { ensureWorkspaceZoneTargets, readWorkspaceSchemaFile, workspaceZoneAbsolutePath, } from "./workspace-schema.js";
-import { stageExecutionShellsRoot, workflowImprovementLoopRoot, workflowPackagePathForWorkspace, workspaceInterfConfigPath, workspaceRuntimeRoot, } from "./workspace-paths.js";
+import { ensureCompiledZoneTargets, readCompiledSchemaFile, compiledZoneAbsolutePath, } from "./compiled-schema.js";
+import { stageExecutionShellsRoot, workflowImprovementLoopRoot, workflowPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, } from "./compiled-paths.js";
 import { resolveWorkflowImprovementReviewSourcePaths } from "./workflow-review-paths.js";
 const LOCAL_SKILL_ROOTS = [
     ".claude/skills",
@@ -19,16 +19,25 @@ function writeNativeAgentSurface(rootPath, agentsContent, skillName, skillConten
     changed = writeNativeSkillCopies(rootPath, skillName, skillContent) || changed;
     return changed;
 }
-function workspaceQuerySkillSourcePath(workspacePath) {
-    return join(workflowPackagePathForWorkspace(workspacePath), "use", "query", "SKILL.md");
+function compiledQuerySkillSourcePath(compiledPath) {
+    return join(workflowPackagePathForCompiled(compiledPath), "use", "query", "SKILL.md");
 }
-export function renderWorkspaceAgents(name, workflowId, about, options = {}) {
+function compiledZoneSummaryLines(compiledPath) {
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
+    if (!schema)
+        return ["- No compiled schema is available yet."];
+    return schema.zones
+        .filter((zone) => zone.id !== "raw" && zone.kind !== "runtime")
+        .map((zone) => `- \`${zone.id}\` -> \`${zone.path}\` (${zone.kind})`);
+}
+export function renderCompiledAgents(compiledPath, name, workflowId, about, options = {}) {
     const workflowOriginSelected = options.workflowOriginSelected ?? workflowId;
     const workflowLocalDraft = options.workflowLocalDraft === true;
+    const zoneLines = compiledZoneSummaryLines(compiledPath);
     return [
         `# ${name}`,
         "",
-        "This is a compiled workspace built by Interf Compiler.",
+        "This is a compiled dataset built by Interf Compiler.",
         "It is a file-based layer on top of the raw files, built for agents to navigate, retrieve evidence, and answer more accurately.",
         "",
         ...(about
@@ -37,51 +46,48 @@ export function renderWorkspaceAgents(name, workflowId, about, options = {}) {
                 "",
             ]
             : []),
-        "## How to use this workspace",
+        "## How to use this compiled dataset",
         "",
-        "1. Use the local native `interf-query` skill that Interf Compiler generated for this workspace.",
-        "2. Start from `home.md`, then use `knowledge/` and `summaries/`.",
+        "1. Use the local native `interf-query` skill that Interf Compiler generated for this compiled dataset.",
+        "2. Let the workflow docs and compiled 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.",
         "",
-        "## How this workspace works",
+        "## How this compiled dataset works",
         "",
-        "- `.interf/interf.json` points to the workspace-local `raw/` snapshot via `source.path` and back to the dataset control plane via `source.control_path`.",
+        "- `.interf/interf.json` points to the local `raw/` snapshot via `source.path` and back to the dataset control plane via `source.control_path`.",
         `- Workflow seed: \`${workflowOriginSelected}\`.`,
         ...(workflowLocalDraft
-            ? ["- This workspace now carries a local workflow draft improved from that seed. Recompiling this workspace reuses the local `.interf/workflow/` package."]
+            ? ["- This compiled dataset now carries a local workflow draft improved from that seed. Recompiling this compiled dataset reuses the local `.interf/workflow/` package."]
             : []),
         `- Active local workflow id: \`${workflowId}\`.`,
-        "- `.interf/workflow/` is the local editable method package for this workspace.",
-        "- `.interf/workflow/workspace.schema.json` is the deterministic output shape for this workspace.",
+        "- `.interf/workflow/` is the local editable method package for this compiled dataset.",
+        "- `.interf/workflow/compiled.schema.json` is the deterministic output shape for this compiled dataset.",
         "- `.interf/workflow/improve/` is the editable source for workflow-improvement loops.",
         "- `.interf/workflow/use/query/` is the editable source for the generated native query shell.",
         "- `.interf/workflow/compile/stages/` defines stage-specific docs that Interf Compiler 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 workspace-local raw snapshot used for evidence and verification.",
-        "- `summaries/` contains per-file evidence objects.",
-        "- `knowledge/` contains the cross-file knowledge layer and navigation structure.",
-        "- `home.md` is the starting note.",
+        "- `raw/` contains the local raw snapshot used for evidence and verification.",
+        "- Compiled output zones are declared in `.interf/workflow/compiled.schema.json`.",
+        ...zoneLines,
         "- `.interf/runtime/` holds CLI-owned runtime artifacts.",
-        "- `.interf/tests/` holds saved raw-vs-compiled test comparisons for this workspace.",
+        "- `.interf/tests/` holds saved raw-vs-compiled test comparisons for this compiled dataset.",
         "- `.interf/tests/targets/` holds detailed raw and compiled target runs plus preserved test sandboxes.",
         "",
         "## Manual query rules",
         "",
-        "- Prefer `home.md`, `knowledge/`, and `summaries/` before `raw/`.",
+        "- Prefer the workflow-declared compiled outputs before `raw/`.",
         "- Use the generated native `interf-query` skill for manual querying. The editable source lives at `.interf/workflow/use/query/SKILL.md`.",
         "- Treat `.interf/` as method/runtime metadata, not answer evidence, unless explicitly asked to inspect workflow or test history.",
         "- Use `raw/` for quotes, verification, ambiguity, or evidence the compiled layer does not expose well.",
-        "- If the compiled layer already contains a bounded chart-derived read for the exact metric and year the user asked about, answer from that compiled read first.",
         "- 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.",
         "",
         "## Commands",
         "",
         "```",
-        "interf compile            build this compiled workspace",
-        "interf test               run saved truth checks against this workspace",
-        "interf verify summarize   verify summary coverage",
-        "interf verify structure   verify cross-file structure outputs",
-        "interf verify compile     verify compile outputs",
+        "interf compile            build this compiled dataset",
+        "interf test               run saved truth checks against this compiled dataset",
+        "interf verify stage <id>  verify one workflow stage",
+        "interf verify compiled    verify the full workflow output",
         "interf status             show deterministic health",
         "```",
         "",
@@ -93,7 +99,7 @@ export function renderWorkspaceAgents(name, workflowId, about, options = {}) {
         "",
     ].join("\n");
 }
-export function renderWorkspaceQuerySkill() {
+export function renderCompiledQuerySkill() {
     const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note.toLowerCase()}`);
     return [
         "# Manual Query Loop",
@@ -101,24 +107,19 @@ export function renderWorkspaceQuerySkill() {
         "This file is the editable authoring source for the generated native local `interf-query` skill.",
         "",
         "Default loop:",
-        "1. Read `home.md` first.",
-        "2. Browse `knowledge/` before `raw/`.",
-        "3. Use `summaries/` for source-grounded evidence.",
-        "4. Use `raw/` for direct quotes, verification, exact table lookups, and cases where the compiled layer is missing or ambiguous.",
+        "1. Read `workflow/README.md` and this file first.",
+        "2. Use the compiled output zones declared in `workflow/compiled.schema.json` before falling back to `raw/`.",
+        "3. Use `raw/` for direct quotes, verification, exact table lookups, and cases where the compiled layer is missing or ambiguous.",
         "",
         "Answering rule:",
         "- do not modify files under `raw/`",
+        "- treat the workflow package as the method layer and the compiled zones as the working retrieval surface",
         "- when a number is chart-derived, say that explicitly",
-        "- if the compiled layer already contains a bounded chart-derived read for the exact metric and year, answer from that compiled read first",
-        "- use `raw/` to confirm source page, metric family, or provenance, not to replace a good compiled bounded read with a second incompatible range",
-        "- when the compiled layer preserves a bounded chart-derived range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value",
-        "- when reading charts, verify you are on the correct metric family and year before answering",
-        "- keep historical annual charts separate from current-quarter snapshots, sector splits, or nearby lookalike panels",
+        "- use `raw/` to confirm source page, metric family, or provenance when the compiled layer is missing or ambiguous",
         ...chartNotes,
-        "- if multiple compiled notes mention the same chart read, keep the answer consistent with the most focused workspace note instead of synthesizing a new midpoint or shifted band",
         "- when the compiled layer is insufficient, verify in `raw/` and then answer",
         "",
-        "You can edit this file to bias manual question-answering behavior for this workspace.",
+        "You can edit this file to bias manual question-answering behavior for this compiled dataset.",
         "",
     ].join("\n");
 }
@@ -128,7 +129,7 @@ function renderRawTestAgents() {
         "# Raw Test Shell",
         "",
         "This is an isolated raw-files test shell generated by Interf Compiler.",
-        "There is no compiled workspace in this shell.",
+        "There is no compiled dataset in this shell.",
         "",
         "## How to use this shell",
         "",
@@ -139,7 +140,7 @@ function renderRawTestAgents() {
         "## Rules",
         "",
         "- Answer only from the files under `raw/`.",
-        "- There is no compiled workspace here, so do not assume `home.md`, `knowledge/`, or `summaries/` exist.",
+        "- There is no compiled dataset here, so do not assume any compiled output zones exist.",
         "- Do not treat hidden runtime files or test artifacts as evidence.",
         ...chartNotes,
         "- Write the requested answer and trace files, then stop.",
@@ -164,14 +165,14 @@ function renderRawTestQuerySkill() {
         "1. Read `raw/` directly.",
         "2. Verify exact claims against the raw files before answering strongly.",
         ...chartNotes,
-        "8. Do not rely on compiled workspace artifacts because they do not exist in this shell.",
+        "8. Do not rely on compiled dataset artifacts because they do not exist in this shell.",
         "",
     ].join("\n");
 }
-function readWorkspaceQuerySkillSource(workspacePath) {
-    const filePath = workspaceQuerySkillSourcePath(workspacePath);
+function readCompiledQuerySkillSource(compiledPath) {
+    const filePath = compiledQuerySkillSourcePath(compiledPath);
     if (!existsSync(filePath)) {
-        throw new Error(`Missing workspace query skill source at ${filePath}. Interf compile runs the workspace-local workflow package directly, so reseed or repair this workspace instead of auto-healing query docs.`);
+        throw new Error(`Missing compiled query skill source at ${filePath}. Interf compile runs the local workflow package directly, so reseed or repair this compiled dataset instead of auto-healing query docs.`);
     }
     return readFileSync(filePath, "utf8").trim();
 }
@@ -224,11 +225,11 @@ function linkRelativePath(targetPath, linkPathname) {
     mkdirSync(dirname(linkPathname), { recursive: true });
     symlinkSync(relative(dirname(linkPathname), targetPath), linkPathname);
 }
-function loadWorkspaceSchema(workspacePath) {
-    const workflowRoot = workflowPackagePathForWorkspace(workspacePath);
-    const schema = readWorkspaceSchemaFile(workflowRoot);
+function loadCompiledSchema(compiledPath) {
+    const workflowRoot = workflowPackagePathForCompiled(compiledPath);
+    const schema = readCompiledSchemaFile(workflowRoot);
     if (!schema) {
-        throw new Error(`Missing workflow workspace schema at ${join(workflowRoot, "workspace.schema.json")}`);
+        throw new Error(`Missing workflow compiled schema at ${join(workflowRoot, "compiled.schema.json")}`);
     }
     return schema;
 }
@@ -238,29 +239,78 @@ function zoneMap(schema) {
 function zoneOrThrow(zones, zoneId) {
     const zone = zones.get(zoneId);
     if (!zone) {
-        throw new Error(`Missing workspace schema zone "${zoneId}" for stage shell projection.`);
+        throw new Error(`Missing compiled schema zone "${zoneId}" for stage shell projection.`);
     }
     return zone;
 }
-function ensureWorkspaceExecutionSurface(workspacePath) {
-    mkdirSync(workspaceRuntimeRoot(workspacePath), { recursive: true });
-    mkdirSync(workflowPackagePathForWorkspace(workspacePath), { recursive: true });
-    const schema = loadWorkspaceSchema(workspacePath);
-    ensureWorkspaceZoneTargets(workspacePath, schema);
+function normalizeArtifactRelativePath(path) {
+    return path
+        .replaceAll("\\", "/")
+        .replace(/^\.?\//, "")
+        .replace(/\/+$/g, "");
+}
+function relativePathEqualsOrWithin(basePath, candidatePath) {
+    const base = normalizeArtifactRelativePath(basePath);
+    const candidate = normalizeArtifactRelativePath(candidatePath);
+    if (base.length === 0 || candidate.length === 0)
+        return false;
+    return candidate === base || candidate.startsWith(`${base}/`);
+}
+function stageWriteZoneSet(schema, stage) {
+    return new Set(stage.writes.filter((zoneId) => schema.zones.some((zone) => zone.id === zoneId)));
+}
+function stageMaterializedZoneSet(schema, stage, writeArtifacts = []) {
+    const materialized = stageWriteZoneSet(schema, stage);
+    for (const zone of schema.zones) {
+        if (zone.kind === "runtime" && stage.reads.includes(zone.id)) {
+            materialized.add(zone.id);
+        }
+    }
+    for (const artifactPath of writeArtifacts) {
+        const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
+        if (normalizedArtifactPath.length === 0)
+            continue;
+        const owner = schema.zones.find((zone) => relativePathEqualsOrWithin(zone.path, normalizedArtifactPath));
+        if (owner) {
+            materialized.add(owner.id);
+        }
+    }
+    return materialized;
+}
+function ensureShellLocalProjection(sourcePath, targetPath, zone) {
+    if (existsSync(sourcePath)) {
+        copyResolvedTree({
+            sourcePath,
+            targetPath,
+            shellType: "stage-execution",
+        });
+        return;
+    }
+    if (zone.kind === "file") {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        return;
+    }
+    mkdirSync(targetPath, { recursive: true });
+}
+function ensureCompiledExecutionSurface(compiledPath) {
+    mkdirSync(compiledRuntimeRoot(compiledPath), { recursive: true });
+    mkdirSync(workflowPackagePathForCompiled(compiledPath), { recursive: true });
+    const schema = loadCompiledSchema(compiledPath);
+    ensureCompiledZoneTargets(compiledPath, schema);
     return schema;
 }
-function readStageMethodDoc(workspacePath, stage) {
-    const path = join(workflowPackagePathForWorkspace(workspacePath), "compile", "stages", stage.skillDir, "SKILL.md");
+function readStageMethodDoc(compiledPath, stage) {
+    const path = join(workflowPackagePathForCompiled(compiledPath), "compile", "stages", stage.skillDir, "SKILL.md");
     if (!existsSync(path))
         return null;
     return readFileSync(path, "utf8").trim();
 }
-function stageWorkflowDocsPath(workspacePath, stage) {
-    return join(workflowPackagePathForWorkspace(workspacePath), "compile", "stages", stage.skillDir);
+function stageWorkflowDocsPath(compiledPath, stage) {
+    return join(workflowPackagePathForCompiled(compiledPath), "compile", "stages", stage.skillDir);
 }
-function renderStageExecutionAgents(workspaceName, workflowId, stage) {
+function renderStageExecutionAgents(compiledName, workflowId, stage) {
     return [
-        `# ${workspaceName} — ${stage.label} Execution Shell`,
+        `# ${compiledName} — ${stage.label} Execution Shell`,
         "",
         "This is an ephemeral stage-execution shell generated by Interf Compiler.",
         "It is for automated pipeline execution only, not for manual querying.",
@@ -277,16 +327,16 @@ function renderStageExecutionAgents(workspaceName, workflowId, stage) {
         "- `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.",
-        "- declared workspace zone paths are also projected at the shell root so workflow-relative contract paths stay valid.",
+        "- declared compiled zone paths are also projected at the shell root so workflow-relative contract paths stay valid.",
         "- `runtime/` = stage contract and machine-readable path map for this shell.",
-        "- `workflow/` = workflow metadata, workspace schema, and docs for the current stage only.",
+        "- `workflow/` = workflow metadata, compiled schema, and docs for the current stage only.",
         "",
         "## Boundaries",
         "",
         `- Workflow: \`${workflowId}\`.`,
         `- Contract type: \`${stage.contractType}\`.`,
-        "- This shell has its own AGENTS/CLAUDE/native skills. It does not inherit the compiled workspace query shell.",
-        "- The compiled workspace root itself is not linked into this shell.",
+        "- This shell has its own AGENTS/CLAUDE/native skills. It does not inherit the compiled-dataset query shell.",
+        "- The compiled dataset root itself is not linked into this shell.",
         "- Do not switch into query mode or act like a user-facing assistant.",
         "- Do not modify files under `inputs/` unless the same zone is also mounted under `outputs/`.",
         "",
@@ -339,62 +389,68 @@ function renderStageExecutionSkill(stage, stageMethodDoc) {
             : []),
     ].join("\n");
 }
-function renderWorkspaceQueryNativeSkill(querySkillContent) {
+function renderCompiledQueryNativeSkill(querySkillContent) {
     return [
         "---",
         "name: interf-query",
         "description: >",
-        "  Native local query skill for this compiled workspace built by Interf",
-        "  Compiler. Use it for manual questions against the compiled workspace and",
+        "  Native local query skill for this compiled dataset built by Interf",
+        "  Compiler. Use it for manual questions against the compiled dataset and",
         "  its raw fallback.",
         "---",
         "",
         "# Interf Compiler Query",
         "",
-        "This is the native local query skill for a compiled workspace built by Interf Compiler.",
-        "Use it when reading this workspace manually.",
+        "This is the native local query skill for a compiled dataset built by Interf Compiler.",
+        "Use it when reading this compiled dataset manually.",
         "Editable source: `.interf/workflow/use/query/SKILL.md`.",
         "",
         querySkillContent.trim(),
         "",
     ].join("\n");
 }
-function projectWorkflowMetadata(workspacePath, shellRoot, stage) {
+function projectWorkflowMetadata(compiledPath, shellRoot, stage) {
     const shellWorkflowRoot = stageShellWorkflowRoot(shellRoot);
     mkdirSync(join(shellWorkflowRoot, "compile", "stages"), { recursive: true });
-    const workspaceWorkflowRoot = workflowPackagePathForWorkspace(workspacePath);
-    const workflowJsonPath = join(workspaceWorkflowRoot, "workflow.json");
+    const compiledWorkflowRoot = workflowPackagePathForCompiled(compiledPath);
+    const workflowJsonPath = join(compiledWorkflowRoot, "workflow.json");
     if (existsSync(workflowJsonPath)) {
         linkPath(workflowJsonPath, join(shellWorkflowRoot, "workflow.json"));
     }
-    const workspaceSchemaPath = join(workspaceWorkflowRoot, "workspace.schema.json");
-    if (existsSync(workspaceSchemaPath)) {
-        linkPath(workspaceSchemaPath, join(shellWorkflowRoot, "workspace.schema.json"));
+    const compiledSchemaPath = join(compiledWorkflowRoot, "compiled.schema.json");
+    if (existsSync(compiledSchemaPath)) {
+        linkPath(compiledSchemaPath, join(shellWorkflowRoot, "compiled.schema.json"));
     }
-    const readmePath = join(workspaceWorkflowRoot, "README.md");
+    const readmePath = join(compiledWorkflowRoot, "README.md");
     if (existsSync(readmePath)) {
         linkPath(readmePath, join(shellWorkflowRoot, "README.md"));
     }
-    const stageDocsPath = stageWorkflowDocsPath(workspacePath, stage);
+    const stageDocsPath = stageWorkflowDocsPath(compiledPath, stage);
     if (existsSync(stageDocsPath)) {
         linkPath(stageDocsPath, join(shellWorkflowRoot, "compile", "stages", stage.skillDir));
     }
 }
-function projectWorkspaceSchemaZones(workspacePath, shellRoot, schema, zoneIds) {
+function projectCompiledSchemaZones(compiledPath, shellRoot, schema, zoneIds, materializedZoneIds) {
     const allowedZoneIds = zoneIds ? new Set(zoneIds) : null;
     for (const zone of schema.zones) {
         if (allowedZoneIds && !allowedZoneIds.has(zone.id))
             continue;
-        linkPath(workspaceZoneAbsolutePath(workspacePath, zone), join(shellRoot, zone.path));
+        const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
+        const targetPath = join(shellRoot, zone.path);
+        if (materializedZoneIds?.has(zone.id)) {
+            ensureShellLocalProjection(sourcePath, targetPath, zone);
+            continue;
+        }
+        linkPath(sourcePath, targetPath);
     }
 }
-function buildStageZoneMounts(workspacePath, shellRoot, stage, schema) {
+function buildStageZoneMounts(compiledPath, shellRoot, stage, schema) {
     const zones = zoneMap(schema);
     const mountFor = (zoneId) => {
         const zone = zoneOrThrow(zones, zoneId);
         return {
             zone_id: zone.id,
-            workspace_path: zone.path,
+            compiled_path: zone.path,
             shell_root_path: zone.path,
             input_mount_path: stage.reads.includes(zoneId)
                 ? describeShellZoneAliasMountPath(zone, "inputs")
@@ -409,16 +465,16 @@ function buildStageZoneMounts(workspacePath, shellRoot, stage, schema) {
         writes: stage.writes.map(mountFor),
     };
 }
-function projectStageZoneMountAliases(workspacePath, shellRoot, stage, schema) {
+function projectStageZoneMountAliases(shellRoot, stage, schema) {
     const zones = zoneMap(schema);
     for (const zoneId of new Set([...stage.reads, ...stage.writes])) {
         const zone = zoneOrThrow(zones, zoneId);
-        const targetPath = workspaceZoneAbsolutePath(workspacePath, zone);
+        const targetPath = join(shellRoot, zone.path);
         if (stage.reads.includes(zoneId)) {
-            linkPath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "inputs"));
+            linkRelativePath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "inputs"));
         }
         if (stage.writes.includes(zoneId)) {
-            linkPath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "outputs"));
+            linkRelativePath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "outputs"));
         }
     }
 }
@@ -433,29 +489,61 @@ function writeExecutionShellPathsFile(shellRoot, workflowId, stage, mounts) {
     };
     writeFileSync(shellRuntimePath(shellRoot, "paths.json"), `${JSON.stringify(paths, null, 2)}\n`);
 }
-export function syncStageExecutionShellWrites(workspacePath, shellRoot, stage) {
-    const schema = ensureWorkspaceExecutionSurface(workspacePath);
+export function syncStageExecutionShellWrites(compiledPath, shellRoot, stage, writeArtifacts = []) {
+    const schema = ensureCompiledExecutionSurface(compiledPath);
     const zones = zoneMap(schema);
-    for (const zoneId of new Set(stage.writes)) {
-        const zone = zoneOrThrow(zones, zoneId);
-        const shellZonePath = join(shellRoot, zone.path);
+    const stageWriteZones = Array.from(stageWriteZoneSet(schema, stage))
+        .map((zoneId) => zoneOrThrow(zones, zoneId));
+    for (const zone of stageWriteZones) {
+        const canonicalShellZonePath = join(shellRoot, zone.path);
+        const outputAliasPath = shellZoneAliasMountPath(shellRoot, zone, "outputs");
+        const shellZonePath = zone.kind === "file" &&
+            existsSync(outputAliasPath) &&
+            !lstatSync(outputAliasPath).isSymbolicLink()
+            ? outputAliasPath
+            : canonicalShellZonePath;
         if (!existsSync(shellZonePath))
             continue;
         const shellZoneStat = lstatSync(shellZonePath);
         if (shellZoneStat.isSymbolicLink())
             continue;
-        const workspaceZonePath = workspaceZoneAbsolutePath(workspacePath, zone);
+        const compiledZonePath = compiledZoneAbsolutePath(compiledPath, zone);
         if (shellZoneStat.isDirectory()) {
-            rmSync(workspaceZonePath, { recursive: true, force: true });
-            mkdirSync(dirname(workspaceZonePath), { recursive: true });
-            cpSync(shellZonePath, workspaceZonePath, {
+            rmSync(compiledZonePath, { recursive: true, force: true });
+            mkdirSync(dirname(compiledZonePath), { recursive: true });
+            cpSync(shellZonePath, compiledZonePath, {
+                recursive: true,
+                force: true,
+            });
+            continue;
+        }
+        mkdirSync(dirname(compiledZonePath), { recursive: true });
+        copyFileSync(shellZonePath, compiledZonePath);
+    }
+    for (const artifactPath of writeArtifacts) {
+        const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
+        if (normalizedArtifactPath.length === 0 ||
+            stageWriteZones.some((zone) => relativePathEqualsOrWithin(zone.path, normalizedArtifactPath))) {
+            continue;
+        }
+        const shellArtifactPath = join(shellRoot, normalizedArtifactPath);
+        if (!existsSync(shellArtifactPath))
+            continue;
+        const compiledArtifactPath = join(compiledPath, normalizedArtifactPath);
+        const shellArtifactStat = lstatSync(shellArtifactPath);
+        if (shellArtifactStat.isSymbolicLink())
+            continue;
+        if (shellArtifactStat.isDirectory()) {
+            rmSync(compiledArtifactPath, { recursive: true, force: true });
+            mkdirSync(dirname(compiledArtifactPath), { recursive: true });
+            cpSync(shellArtifactPath, compiledArtifactPath, {
                 recursive: true,
                 force: true,
             });
             continue;
         }
-        mkdirSync(dirname(workspaceZonePath), { recursive: true });
-        copyFileSync(shellZonePath, workspaceZonePath);
+        mkdirSync(dirname(compiledArtifactPath), { recursive: true });
+        copyFileSync(shellArtifactPath, compiledArtifactPath);
     }
 }
 function preservedShellManifestPath(rootPath) {
@@ -563,12 +651,12 @@ export function renderClaudeBootstrap(content) {
         "",
     ].join("\n");
 }
-function improvementWorkflowDocsPath(workspacePath) {
-    return join(workflowPackagePathForWorkspace(workspacePath), "improve");
+function improvementWorkflowDocsPath(compiledPath) {
+    return join(workflowPackagePathForCompiled(compiledPath), "improve");
 }
-function renderWorkflowImprovementAgents(workspaceName, workflowId, loopIndex) {
+function renderWorkflowImprovementAgents(compiledName, workflowId, loopIndex) {
     return [
-        `# ${workspaceName} — Workflow Improvement Shell`,
+        `# ${compiledName} — Workflow Improvement Shell`,
         "",
         "This is an automated workflow-improvement shell generated by Interf Compiler.",
         "It exists to review failed compile/test runs and edit the workflow package for the next variation.",
@@ -576,7 +664,7 @@ function renderWorkflowImprovementAgents(workspaceName, workflowId, loopIndex) {
         "## Start Here",
         "",
         "1. Read `runtime/loop-context.json` now.",
-        "2. Read `workflow/README.md`, `workflow/workflow.json`, and `workflow/workspace.schema.json` now.",
+        "2. Read `workflow/README.md`, `workflow/workflow.json`, and `workflow/compiled.schema.json` now.",
         "3. Read `workflow/improve/SKILL.md` now.",
         "4. Use the local native `interf-workflow-improver` skill now.",
         "",
@@ -585,20 +673,20 @@ function renderWorkflowImprovementAgents(workspaceName, workflowId, loopIndex) {
         `- Workflow: \`${workflowId}\`.`,
         `- Improvement loop: ${loopIndex}.`,
         "- Edit only files under `workflow/`.",
-        "- Do not edit truth checks, test specs, raw dataset files, or generated workspace outputs.",
-        "- Review compiled outputs under `artifacts/workspace-view/` and test/runtime evidence under `artifacts/`.",
-        "- Keep the workflow valid for the current compiler API and workspace schema.",
+        "- Do not edit truth checks, test specs, raw dataset files, or generated compiled outputs.",
+        "- Review compiled outputs under `artifacts/compiled-view/` and test/runtime evidence under `artifacts/`.",
+        "- Keep the workflow valid for the current compiler API and compiled schema.",
         "",
         "## Goal",
         "",
         "- create a better workflow variation for this dataset",
-        "- preserve deterministic workspace structure",
+        "- preserve deterministic compiled structure",
         "- stop after the workflow edits are complete",
         "",
     ].join("\n");
 }
-function readWorkflowImprovementDoc(workspacePath) {
-    const path = join(improvementWorkflowDocsPath(workspacePath), "SKILL.md");
+function readWorkflowImprovementDoc(compiledPath) {
+    const path = join(improvementWorkflowDocsPath(compiledPath), "SKILL.md");
     if (!existsSync(path))
         return null;
     return readFileSync(path, "utf8").trim();
@@ -616,7 +704,7 @@ function renderWorkflowImprovementSkill(workflowId, loopIndex, improvementDoc) {
         "",
         "This local native skill exists for automated workflow-improvement loops.",
         "Read `runtime/loop-context.json` first.",
-        "Then review the linked workflow package, `artifacts/workspace-view/`, preserved stage shells, runtime logs, and saved test outputs before editing `workflow/`.",
+        "Then review the linked workflow package, `artifacts/compiled-view/`, preserved stage shells, runtime logs, and saved test outputs before editing `workflow/`.",
         "",
         "## Current Loop",
         "",
@@ -634,18 +722,18 @@ function renderWorkflowImprovementSkill(workflowId, loopIndex, improvementDoc) {
             : []),
     ].join("\n");
 }
-function projectWorkspaceReviewArtifactsSnapshot(workspacePath, shellRoot, schema) {
-    const workspaceViewRoot = join(shellRoot, "artifacts", "workspace-view");
-    mkdirSync(workspaceViewRoot, { recursive: true });
+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")
             continue;
-        const sourcePath = workspaceZoneAbsolutePath(workspacePath, zone);
+        const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
         if (!existsSync(sourcePath))
             continue;
         copyResolvedTree({
             sourcePath,
-            targetPath: join(workspaceViewRoot, zone.path),
+            targetPath: join(compiledViewRoot, zone.path),
             shellType: "workflow-improvement",
         });
     }
@@ -664,10 +752,10 @@ function copyIfExists(sourcePath, targetPath, shellType) {
         shellType,
     });
 }
-function projectWorkspaceRuntimeArtifacts(workspacePath, shellRoot) {
-    const runtimeTarget = join(shellRoot, "artifacts", "workspace-runtime");
+function projectCompiledRuntimeArtifacts(compiledPath, shellRoot) {
+    const runtimeTarget = join(shellRoot, "artifacts", "compiled-runtime");
     mkdirSync(runtimeTarget, { recursive: true });
-    const runtimeRoot = workspaceRuntimeRoot(workspacePath);
+    const runtimeRoot = compiledRuntimeRoot(compiledPath);
     const artifactNames = [
         "run.json",
         "run-history.jsonl",
@@ -681,33 +769,34 @@ function projectWorkspaceRuntimeArtifacts(workspacePath, shellRoot) {
         copyIfExists(join(runtimeRoot, artifactName), join(runtimeTarget, artifactName), "workflow-improvement");
     }
 }
-export function pruneStageExecutionShells(workspacePath) {
-    rmSync(stageExecutionShellsRoot(workspacePath), { recursive: true, force: true });
+export function pruneStageExecutionShells(compiledPath) {
+    rmSync(stageExecutionShellsRoot(compiledPath), { recursive: true, force: true });
 }
-export function projectWorkspaceQueryShell(workspacePath, workspaceName, workflowId, about, options) {
-    const agentsContent = renderWorkspaceAgents(workspaceName, workflowId, about, options);
-    const querySkillContent = readWorkspaceQuerySkillSource(workspacePath);
-    return writeNativeAgentSurface(workspacePath, agentsContent, "interf-query", renderWorkspaceQueryNativeSkill(querySkillContent));
+export function projectCompiledQueryShell(compiledPath, compiledName, workflowId, about, options) {
+    const agentsContent = renderCompiledAgents(compiledPath, compiledName, workflowId, about, options);
+    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 createStageExecutionShell(workspacePath, workspaceName, workflowId, stage) {
-    const schema = ensureWorkspaceExecutionSurface(workspacePath);
-    const shellsRoot = stageExecutionShellsRoot(workspacePath);
+export function createStageExecutionShell(compiledPath, compiledName, workflowId, stage, writeArtifacts = []) {
+    const schema = ensureCompiledExecutionSurface(compiledPath);
+    const materializedZones = stageMaterializedZoneSet(schema, stage, writeArtifacts);
+    const shellsRoot = stageExecutionShellsRoot(compiledPath);
     const shellRoot = join(shellsRoot, `${stage.id}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
     mkdirSync(shellRoot, { recursive: true });
     mkdirSync(join(shellRoot, "runtime"), { recursive: true });
     mkdirSync(join(shellRoot, "inputs"), { recursive: true });
     mkdirSync(join(shellRoot, "outputs"), { recursive: true });
-    linkPath(workspaceInterfConfigPath(workspacePath), join(shellRoot, "interf.json"));
-    linkPath(join(workspaceRuntimeRoot(workspacePath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
-    projectWorkspaceSchemaZones(workspacePath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]));
-    projectWorkflowMetadata(workspacePath, shellRoot, stage);
-    projectStageZoneMountAliases(workspacePath, shellRoot, stage, schema);
-    writeExecutionShellPathsFile(shellRoot, workflowId, stage, buildStageZoneMounts(workspacePath, shellRoot, stage, schema));
-    const agentsContent = renderStageExecutionAgents(workspaceName, workflowId, stage);
-    writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageMethodDoc(workspacePath, stage)));
+    linkPath(compiledInterfConfigPath(compiledPath), join(shellRoot, "interf.json"));
+    linkPath(join(compiledRuntimeRoot(compiledPath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
+    projectCompiledSchemaZones(compiledPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedZones);
+    projectWorkflowMetadata(compiledPath, shellRoot, stage);
+    projectStageZoneMountAliases(shellRoot, stage, schema);
+    writeExecutionShellPathsFile(shellRoot, workflowId, stage, buildStageZoneMounts(compiledPath, shellRoot, stage, schema));
+    const agentsContent = renderStageExecutionAgents(compiledName, workflowId, stage);
+    writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageMethodDoc(compiledPath, stage)));
     return {
         rootPath: shellRoot,
     };
@@ -716,19 +805,19 @@ export function freezeStageExecutionShell(rootPath) {
     return freezePreservedShell(rootPath, "stage-execution");
 }
 export function createWorkflowImprovementShell(options) {
-    const schema = ensureWorkspaceExecutionSurface(options.workspacePath);
-    const loopRootPath = workflowImprovementLoopRoot(options.workspacePath, options.runId, options.loopIndex);
+    const schema = ensureCompiledExecutionSurface(options.compiledPath);
+    const loopRootPath = workflowImprovementLoopRoot(options.compiledPath, options.runId, options.loopIndex);
     const shellRoot = join(loopRootPath, "shell");
     mkdirSync(shellRoot, { recursive: true });
     mkdirSync(join(shellRoot, "runtime"), { recursive: true });
     mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
     mkdirSync(join(loopRootPath, "logs"), { recursive: true });
     writeFileSync(join(shellRoot, "runtime", "loop-context.json"), `${JSON.stringify(options.context, null, 2)}\n`);
-    projectWorkspaceReviewArtifactsSnapshot(options.workspacePath, shellRoot, schema);
-    linkPath(workflowPackagePathForWorkspace(options.workspacePath), join(shellRoot, "workflow"));
-    copyIfExists(workspaceInterfConfigPath(options.workspacePath), join(shellRoot, "interf.json"), "workflow-improvement");
-    projectWorkspaceRuntimeArtifacts(options.workspacePath, shellRoot);
-    const reviewSources = resolveWorkflowImprovementReviewSourcePaths(options.workspacePath);
+    projectCompiledReviewArtifactsSnapshot(options.compiledPath, shellRoot, schema);
+    linkPath(workflowPackagePathForCompiled(options.compiledPath), join(shellRoot, "workflow"));
+    copyIfExists(compiledInterfConfigPath(options.compiledPath), join(shellRoot, "interf.json"), "workflow-improvement");
+    projectCompiledRuntimeArtifacts(options.compiledPath, shellRoot);
+    const reviewSources = resolveWorkflowImprovementReviewSourcePaths(options.compiledPath);
     if (reviewSources.executionShells) {
         copyIfExists(reviewSources.executionShells, join(shellRoot, "artifacts", "execution-shells"), "workflow-improvement");
     }
@@ -741,8 +830,8 @@ export function createWorkflowImprovementShell(options) {
     if (reviewSources.targetTestSandboxes) {
         copyIfExists(reviewSources.targetTestSandboxes, join(shellRoot, "artifacts", "test-sandboxes"), "workflow-improvement");
     }
-    const agentsContent = renderWorkflowImprovementAgents(options.workspaceName, options.workflowId, options.loopIndex);
-    writeNativeAgentSurface(shellRoot, agentsContent, "interf-workflow-improver", renderWorkflowImprovementSkill(options.workflowId, options.loopIndex, readWorkflowImprovementDoc(options.workspacePath)));
+    const agentsContent = renderWorkflowImprovementAgents(options.compiledName, options.workflowId, options.loopIndex);
+    writeNativeAgentSurface(shellRoot, agentsContent, "interf-workflow-improver", renderWorkflowImprovementSkill(options.workflowId, options.loopIndex, readWorkflowImprovementDoc(options.compiledPath)));
     return {
         rootPath: shellRoot,
         loopRootPath,