@interf/compiler 0.6.3 → 0.6.4

package/dist/packages/project-model/interf-detect.js

@@ -1,11 +1,11 @@
 import { existsSync, readdirSync, statSync, } from "node:fs";
 import { join, resolve } from "node:path";
-import { warnInterf } from "../../lib/logger.js";
-import { readJsonFileUnchecked } from "../../lib/parse.js";
+import { warnInterf } from "../shared/logger.js";
+import { readJsonFileUnchecked } from "../shared/parse.js";
 import { compiledCompiledPathForDataset, projectInterfRoot, } from "./project-paths.js";
-import { resolveSourceControlPathForCompiled, compiledInterfConfigPath, } from "./compiled-paths.js";
+import { resolveSourceControlPathForCompiled, compiledInterfConfigPath, } from "../compiler/compiled-paths.js";
 import { InterfConfigSchema, } from "./lib/schema.js";
-import { assertPathWithinRoot } from "../../lib/util.js";
+import { assertPathWithinRoot } from "../shared/path-guards.js";
 export const INTERF_CONTAINER_NAME = "interf";
 export const WORKFLOW_CONTAINER_NAME = "workflows";
 export const TEST_CONTAINER_NAME = "tests";

package/dist/packages/project-model/interf-scaffold.js

@@ -2,14 +2,14 @@ import { mkdirSync, existsSync, writeFileSync, } from "node:fs";
 import { basename, join, relative, sep } from "node:path";
 import { getCompiledWorkflow } from "../workflow-package/workflow-definitions.js";
 import { initializeCompiledRuntimeState, } from "../compiler/state.js";
+import { refreshCompiledBootstrapGuidance } from "../agents/lib/compiled-bootstrap.js";
+import { syncCompiledRawSnapshot } from "../compiler/raw-snapshot.js";
 import { assertCompiledContainer, assertWritableTargetDir, assertCompiledName, } from "./interf-detect.js";
-import { refreshCompiledBootstrapGuidance } from "./interf-bootstrap.js";
 import { seedCompiledWorkflowPackage } from "../workflow-package/interf-workflow-package.js";
 import { compiledCompiledPathForDataset } from "./project-paths.js";
-import { syncCompiledRawSnapshot } from "./compiled-raw.js";
 import { ensureCompiledZoneTargets, readCompiledSchemaFile } from "../compiler/compiled-schema.js";
 import { findSourceDatasetConfig, listSourceDatasetConfigs, loadSourceFolderConfig, resolveSourceDatasetPath, saveCompiledInterfConfig, } from "./source-config.js";
-import { defaultControlPathForCompiled, workflowPackagePathForCompiled } from "./compiled-paths.js";
+import { defaultControlPathForCompiled, workflowPackagePathForCompiled } from "../compiler/compiled-paths.js";
 const DEFAULT_INTERFIGNORE = [
     ".claude/",
     ".codex/",
@@ -20,7 +20,7 @@ const DEFAULT_INTERFIGNORE = [
     ".interf/runtime/",
     "",
 ].join("\n");
-const UNCOMPILED_COMPILED_PLACEHOLDER = "Not yet compiled. Run `interf compile` to build this context folder.";
+const UNCOMPILED_COMPILED_PLACEHOLDER = "Not yet compiled. Run `interf compile` to build this portable context.";
 function renderUncompiledCompiledFile(compiledName, relativePath, about) {
     return [
         `# ${compiledName} — ${relativePath}`,
@@ -62,10 +62,10 @@ function scaffoldCompiledOutputs(compiledPath, compiledName, about) {
     }
 }
 export function createCompiled(name, sourcePath, workflowId = "interf", about, datasetPath) {
-    assertCompiledName(name, "Context folder");
+    assertCompiledName(name, "Portable context");
     assertCompiledContainer(sourcePath);
     const compiledPath = compiledCompiledPathForDataset(sourcePath, name);
-    assertWritableTargetDir(compiledPath, "Context folder");
+    assertWritableTargetDir(compiledPath, "Portable context");
     mkdirSync(compiledPath, { recursive: true });
     const savedCompiled = findSourceDatasetConfig(loadSourceFolderConfig(sourcePath), name);
     const selectedWorkflow = getCompiledWorkflow(workflowId, { sourcePath });
@@ -81,7 +81,7 @@ export function createCompiled(name, sourcePath, workflowId = "interf", about, d
         if (configuredDatasets.length === 1) {
             return resolveSourceDatasetPath(sourcePath, configuredDatasets[0]);
         }
-        throw new Error("Cannot infer the source folder for this context folder. Select a source folder first or pass an explicit dataset path.");
+        throw new Error("Cannot infer the source folder for this portable context. Select a source folder first or pass an explicit dataset path.");
     })();
     saveCompiledInterfConfig(compiledPath, {
         type: "compiled",

package/dist/packages/project-model/source-config.js

@@ -1,14 +1,15 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
-import { readInterfConfig, refreshCompiledBootstrapGuidance, } from "./interf.js";
+import { refreshCompiledBootstrapGuidance } from "../agents/lib/compiled-bootstrap.js";
+import { readInterfConfig, } from "./interf.js";
 import { seedCompiledWorkflowPackage } from "../workflow-package/interf-workflow-package.js";
-import { readJsonFileWithSchema } from "../../lib/parse.js";
+import { readJsonFileWithSchema } from "../shared/parse.js";
 import { getCompiledWorkflow } from "../workflow-package/workflow-definitions.js";
 import { SourceFolderConfigSchema, } from "./lib/schema.js";
-import { slugify } from "../../lib/util.js";
-import { assertPathWithinRoot } from "../../lib/util.js";
-import { defaultControlPathForCompiled, resolveSourceControlPathForCompiled, compiledInterfConfigPath, compiledInterfRoot, } from "./compiled-paths.js";
+import { slugify } from "../shared/naming.js";
+import { assertPathWithinRoot } from "../shared/path-guards.js";
+import { defaultControlPathForCompiled, resolveSourceControlPathForCompiled, compiledInterfConfigPath, compiledInterfRoot, } from "../compiler/compiled-paths.js";
 export const SOURCE_FOLDER_CONFIG_FILE = "interf.json";
 function sourceConfigPath(sourcePath) {
     return join(sourcePath, SOURCE_FOLDER_CONFIG_FILE);

package/dist/packages/shared/file-types.d.ts

@@ -0,0 +1 @@
+export declare function isMarkdownFile(filePath: string): boolean;

package/dist/packages/shared/file-types.js

@@ -0,0 +1,4 @@
+import { extname } from "node:path";
+export function isMarkdownFile(filePath) {
+    return extname(filePath).toLowerCase() === ".md";
+}

package/dist/packages/shared/filesystem.d.ts

@@ -0,0 +1,2 @@
+export declare function countFilesRecursive(dirPath: string): number;
+export declare function listFilesRecursive(dirPath: string, predicate?: (filePath: string) => boolean): string[];

package/dist/packages/shared/filesystem.js

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+export function countFilesRecursive(dirPath) {
+    if (!existsSync(dirPath))
+        return 0;
+    let total = 0;
+    walkFilesRecursive(dirPath, () => {
+        total += 1;
+    });
+    return total;
+}
+export function listFilesRecursive(dirPath, predicate) {
+    const files = [];
+    if (!existsSync(dirPath))
+        return files;
+    walkFilesRecursive(dirPath, (filePath) => {
+        if (!predicate || predicate(filePath)) {
+            files.push(filePath);
+        }
+    });
+    return files;
+}
+function walkFilesRecursive(dirPath, onFile, visitedDirs = new Set()) {
+    if (!existsSync(dirPath))
+        return;
+    walkFilesRecursiveInternal(dirPath, onFile, visitedDirs);
+}
+function walkFilesRecursiveInternal(dirPath, onFile, visitedDirs) {
+    let resolvedDir;
+    try {
+        resolvedDir = realpathSync(dirPath);
+    }
+    catch {
+        return;
+    }
+    if (visitedDirs.has(resolvedDir))
+        return;
+    visitedDirs.add(resolvedDir);
+    for (const entry of readdirSync(dirPath)) {
+        const fullPath = join(dirPath, entry);
+        let stat;
+        try {
+            stat = statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            walkFilesRecursiveInternal(fullPath, onFile, visitedDirs);
+        }
+        else if (stat.isFile()) {
+            onFile(fullPath);
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+export * from "./file-types.js";
+export * from "./filesystem.js";
+export * from "./logger.js";
+export * from "./naming.js";
+export * from "./parse.js";
+export * from "./path-guards.js";
+export * from "./util.js";

package/dist/packages/shared/index.js

@@ -0,0 +1,7 @@
+export * from "./file-types.js";
+export * from "./filesystem.js";
+export * from "./logger.js";
+export * from "./naming.js";
+export * from "./parse.js";
+export * from "./path-guards.js";
+export * from "./util.js";

package/dist/packages/shared/logger.d.ts

@@ -0,0 +1,3 @@
+export type InterfWarningHandler = (message: string) => void;
+export declare function setInterfWarningHandler(handler?: InterfWarningHandler): void;
+export declare function warnInterf(message: string): void;

package/dist/packages/shared/logger.js

@@ -0,0 +1,10 @@
+const defaultWarningHandler = (message) => {
+    console.warn(message);
+};
+let currentWarningHandler = defaultWarningHandler;
+export function setInterfWarningHandler(handler) {
+    currentWarningHandler = handler ?? defaultWarningHandler;
+}
+export function warnInterf(message) {
+    currentWarningHandler(message);
+}

package/dist/packages/shared/naming.d.ts

@@ -0,0 +1 @@
+export declare function slugify(input: string): string;

package/dist/packages/shared/naming.js

@@ -0,0 +1,8 @@
+export function slugify(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}

package/dist/packages/shared/parse.d.ts

@@ -0,0 +1,8 @@
+import type { ZodType } from "zod";
+export declare function readJsonFileUnchecked<T>(filePath: string, label: string): T | null;
+export declare function readJsonFileWithSchema<T>(filePath: string, label: string, schema: ZodType<T>): T | null;
+export declare function renderJsonFrontmatter(frontmatter: Record<string, unknown>): string;
+export declare function parseJsonFrontmatter(content: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+} | null;

package/dist/packages/shared/parse.js

@@ -0,0 +1,145 @@
+import { readFileSync } from "node:fs";
+import { warnInterf } from "./logger.js";
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function readJsonFileUnchecked(filePath, label) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch (error) {
+        warnInterf(`Warning: failed to parse ${label} at ${filePath}: ${formatError(error)}`);
+        return null;
+    }
+}
+export function readJsonFileWithSchema(filePath, label, schema) {
+    const raw = readJsonFileUnchecked(filePath, label);
+    if (raw === null)
+        return null;
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success) {
+        warnInterf(`Warning: failed to validate ${label} at ${filePath}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    return parsed.data;
+}
+export function renderJsonFrontmatter(frontmatter) {
+    return [
+        "---",
+        JSON.stringify(frontmatter, null, 2),
+        "---",
+    ].join("\n");
+}
+function parseQuotedString(value) {
+    if (value.length < 2)
+        return null;
+    const quote = value[0];
+    if ((quote !== "\"" && quote !== "'") || value[value.length - 1] !== quote)
+        return null;
+    const inner = value.slice(1, -1);
+    if (quote === "\"") {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return inner.replace(/\\'/g, "'");
+}
+function parseYamlScalar(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return "";
+    const quoted = parseQuotedString(trimmed);
+    if (quoted !== null)
+        return quoted;
+    if (trimmed === "true")
+        return true;
+    if (trimmed === "false")
+        return false;
+    if (trimmed === "null")
+        return null;
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    if ((trimmed.startsWith("[") && trimmed.endsWith("]"))
+        || (trimmed.startsWith("{") && trimmed.endsWith("}"))) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return trimmed;
+        }
+    }
+    return trimmed;
+}
+function parseYamlFrontmatter(frontmatterText) {
+    const lines = frontmatterText.split("\n");
+    const frontmatter = {};
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith("#"))
+            continue;
+        const match = line.match(/^([A-Za-z0-9_-]+):(?:\s+(.*))?$/);
+        if (!match)
+            return null;
+        const [, key, inlineValue] = match;
+        if (!key)
+            return null;
+        if (inlineValue && inlineValue.trim().length > 0) {
+            frontmatter[key] = parseYamlScalar(inlineValue);
+            continue;
+        }
+        const items = [];
+        let cursor = index + 1;
+        while (cursor < lines.length) {
+            const nextLine = lines[cursor] ?? "";
+            const nextTrimmed = nextLine.trim();
+            if (nextTrimmed.length === 0) {
+                cursor += 1;
+                continue;
+            }
+            const itemMatch = nextLine.match(/^\s*-\s+(.*)$/);
+            if (!itemMatch || !/^\s+/.test(nextLine))
+                break;
+            items.push(parseYamlScalar(itemMatch[1] ?? ""));
+            cursor += 1;
+        }
+        if (items.length > 0) {
+            frontmatter[key] = items;
+            index = cursor - 1;
+            continue;
+        }
+        frontmatter[key] = "";
+    }
+    return Object.keys(frontmatter).length > 0 ? frontmatter : null;
+}
+export function parseJsonFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return null;
+    const [, frontmatterText, body = ""] = match;
+    if (frontmatterText === undefined)
+        return null;
+    try {
+        const frontmatter = JSON.parse(frontmatterText);
+        if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+            return null;
+        }
+        return {
+            frontmatter: frontmatter,
+            body,
+        };
+    }
+    catch {
+        const frontmatter = parseYamlFrontmatter(frontmatterText);
+        if (!frontmatter)
+            return null;
+        return {
+            frontmatter,
+            body,
+        };
+    }
+}

package/dist/packages/shared/path-guards.d.ts

@@ -0,0 +1,2 @@
+export declare function isPathWithinRoot(rootPath: string, candidatePath: string): boolean;
+export declare function assertPathWithinRoot(rootPath: string, candidatePath: string, label: string): string;

package/dist/packages/shared/path-guards.js

@@ -0,0 +1,14 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+export function isPathWithinRoot(rootPath, candidatePath) {
+    const root = resolve(rootPath);
+    const candidate = resolve(candidatePath);
+    const relativePath = relative(root, candidate);
+    return relativePath === "" || (!isAbsolute(relativePath) && relativePath !== ".." && !relativePath.startsWith(`..${sep}`));
+}
+export function assertPathWithinRoot(rootPath, candidatePath, label) {
+    const resolvedPath = resolve(candidatePath);
+    if (!isPathWithinRoot(rootPath, resolvedPath)) {
+        throw new Error(`${label} must stay inside ${resolve(rootPath)}: ${resolvedPath}`);
+    }
+    return resolvedPath;
+}

package/dist/packages/shared/util.d.ts

@@ -0,0 +1,3 @@
+export { isMarkdownFile } from "./file-types.js";
+export { slugify } from "./naming.js";
+export { assertPathWithinRoot, isPathWithinRoot } from "./path-guards.js";

package/dist/packages/shared/util.js

@@ -0,0 +1,3 @@
+export { isMarkdownFile } from "./file-types.js";
+export { slugify } from "./naming.js";
+export { assertPathWithinRoot, isPathWithinRoot } from "./path-guards.js";

package/dist/packages/testing/test-execution.js

@@ -199,10 +199,10 @@ function buildTestQueryPrompt(target, testCase, answerPath, tracePath) {
         ? [
             "You are running an Interf test inside an isolated sandboxed compiled context.",
             "Read `AGENTS.md` first.",
-            "Use the local native `interf-query` skill available in this context folder.",
-            "Answer the check question the same way you would answer a real user inside this context folder.",
+            "Use the local native `interf-query` skill available in this portable context.",
+            "Answer the check question the same way you would answer a real user inside this portable context.",
             "Prefer the workflow-declared context outputs before raw fallback.",
-            "This sandbox is self-contained: the copied context folder has its own sanitized `raw/` fallback via `.interf/interf.json` `source.path`.",
+            "This sandbox is self-contained: the copied portable context has its own sanitized `raw/` fallback via `.interf/interf.json` `source.path`.",
             "The original project root is intentionally absent from this sandbox. Work only from this sandboxed compiled context and its embedded raw files.",
         ]
         : [

package/dist/packages/testing/test-paths.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, compiledInterfConfigPath, } from "../project-model/compiled-paths.js";
+import { targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, compiledInterfConfigPath, } from "../compiler/compiled-paths.js";
 const TEST_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,79}$/;
 export const TEST_SPEC_EXTENSIONS = new Set([".json"]);
 export function testSpecRootPath(sourcePath) {

package/dist/packages/testing/test-sandbox.js

@@ -1,14 +1,14 @@
 import { cpSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, relative, sep } from "node:path";
-import { refreshCompiledBootstrapGuidance } from "../project-model/interf-bootstrap.js";
+import { refreshCompiledBootstrapGuidance } from "../agents/lib/compiled-bootstrap.js";
 import { readInterfConfig, resolveCompiledRawPath } from "../project-model/interf.js";
 import { projectRawTestQueryShell } from "../agents/lib/shells.js";
 import { compiledCompiledPathForDataset } from "../project-model/project-paths.js";
 import { saveCompiledInterfConfig } from "../project-model/source-config.js";
+import { projectRawSnapshot } from "../compiler/raw-snapshot.js";
 import { refreshCompiledArtifacts } from "../compiler/state.js";
-import { projectRawSnapshot } from "../project-model/compiled-raw.js";
-import { testRootForCompiled, stageExecutionShellsRoot, targetTestSandboxesRootForCompiled, workflowImprovementLoopsRoot, compiledQueryAcceptanceRoot, compiledRuntimeLogsRoot, } from "../project-model/compiled-paths.js";
+import { testRootForCompiled, stageExecutionShellsRoot, targetTestSandboxesRootForCompiled, workflowImprovementLoopsRoot, compiledQueryAcceptanceRoot, compiledRuntimeLogsRoot, } from "../compiler/compiled-paths.js";
 function toPortableRelativePath(fromPath, toPath) {
     return relative(fromPath, toPath).split(sep).join("/");
 }

package/dist/packages/testing/test-specs.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync, } from "node:fs";
 import { basename, extname, join } from "node:path";
-import { readJsonFileWithSchema } from "../../lib/parse.js";
+import { readJsonFileWithSchema } from "../shared/parse.js";
 import { TestSpecSchema } from "./lib/schema.js";
 import { TEST_SPEC_EXTENSIONS, assertTestId, assertWritableTestSpecPath, testSpecFilePath, testSpecTypePath, normalizeTestId, } from "./test-paths.js";
 function readTestSpecFile(filePath) {

package/dist/packages/workflow-authoring/workflow-authoring.js

@@ -2,11 +2,11 @@ import { mkdtempSync, rmSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createWorkflowAuthoringShell } from "../agents/lib/shells.js";
-import { WORKFLOW_SCHEMA_FILE } from "../compiler/compiled-schema.js";
 import { seedLocalWorkflowPackageFromBase } from "../workflow-package/interf-workflow-package.js";
+import { CONTEXT_INTERFACE_FILE } from "../workflow-package/context-interface.js";
 import { validateWorkflowPackage, workflowDefinitionPath } from "../workflow-package/local-workflows.js";
 import { createCompiled, compileCompiled } from "../compiler/workflows.js";
-import { projectRawSnapshot } from "../project-model/compiled-raw.js";
+import { projectRawSnapshot } from "../compiler/raw-snapshot.js";
 import { runWorkflowEditSession } from "./workflow-edit-session.js";
 import { copyDirectory } from "./lib/workflow-edit-utils.js";
 function buildWorkflowAuthoringPrompt() {
@@ -15,14 +15,15 @@ function buildWorkflowAuthoringPrompt() {
         "Execute it now.",
         "Create one standalone workflow for the files and checks in this source folder.",
         "Read `runtime/authoring-context.json` first.",
-        `Then read \`workflow/README.md\`, \`workflow/workflow.json\`, and \`workflow/${WORKFLOW_SCHEMA_FILE}\`.`,
+        `Then read \`workflow/README.md\`, \`workflow/workflow.json\`, and \`workflow/${CONTEXT_INTERFACE_FILE}\`.`,
         "Review `artifacts/source-dataset/raw/` and any `artifacts/preview-compiled/` notes before editing the package.",
         "Prefer direct file-reading and search tools over shell commands for routine file inspection.",
         "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
         "Edit only files under `workflow/`.",
         "Keep the workflow valid for the current compiler API and workflow schema.",
         "Make the package materially more specific to this dataset task than the seeded base workflow. A no-op copy is not acceptable.",
-        "Prefer explicit stage-doc, stage-policy, purpose, and zone-contract edits over vague rewrites.",
+        "Treat the workflow package as four aligned layers: purpose, inputs, context interface, and stages.",
+        "Prefer explicit stage-doc, stage-policy, purpose, input-contract, and context-interface edits over vague rewrites.",
         "Do not introduce wikilinks unless the workflow also creates the target note by exact basename or explicit relative path.",
         "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read zones.",
         "Do not make one stage point at files or notes that are only created later by another stage.",

package/dist/packages/workflow-authoring/workflow-improvement.js

@@ -1,11 +1,11 @@
 import { appendFileSync, existsSync, mkdirSync, writeFileSync, } from "node:fs";
 import { join, relative } from "node:path";
 import { createWorkflowImprovementShell, freezeWorkflowImprovementShell, } from "../agents/lib/shells.js";
-import { WORKFLOW_SCHEMA_FILE } from "../compiler/compiled-schema.js";
 import { validateWorkflowPackage } from "../workflow-package/local-workflows.js";
-import { readJsonFileWithSchema } from "../../lib/parse.js";
+import { CONTEXT_INTERFACE_FILE } from "../workflow-package/context-interface.js";
+import { readJsonFileWithSchema } from "../shared/parse.js";
 import { resolveWorkflowImprovementReviewPaths } from "../workflow-package/workflow-review-paths.js";
-import { targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, workflowImprovementRunRoot, workflowPackagePathForCompiled, } from "../project-model/compiled-paths.js";
+import { targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, workflowImprovementRunRoot, workflowPackagePathForCompiled, } from "../compiler/compiled-paths.js";
 import { readInterfConfig } from "../project-model/interf.js";
 import { saveCompiledInterfConfig } from "../project-model/source-config.js";
 import { WorkflowImprovementRunLedgerSchema, } from "../compiler/lib/schema.js";
@@ -58,10 +58,11 @@ function buildWorkflowImprovementPrompt() {
         "This is an automated Interf workflow-improvement run, not an open-ended chat session.",
         "The user already invoked this through `interf compile` with self-improving loops enabled. Execute it now.",
         "Read `runtime/loop-context.json` first.",
-        `Then read \`workflow/README.md\`, \`workflow/workflow.json\`, \`workflow/${WORKFLOW_SCHEMA_FILE}\`, and \`workflow/improve/SKILL.md\` if it exists.`,
+        `Then read \`workflow/README.md\`, \`workflow/workflow.json\`, \`workflow/${CONTEXT_INTERFACE_FILE}\`, and \`workflow/improve/SKILL.md\` if it exists.`,
         "Review preserved evidence from earlier failures under `artifacts/` before you edit the workflow.",
         "Treat `workflow/improve/SKILL.md` as guidance for how to improve the workflow, not as the default file to edit.",
-        "Prefer editing the stage docs, workflow contract, or schema ownership that actually change compiled outputs.",
+        "Treat the workflow package as four aligned layers: purpose, inputs, context interface, and stages.",
+        "Prefer editing the stage docs, workflow contract, input contract, or schema ownership that actually change compiled outputs.",
         "Edit only files under `workflow/`.",
         "Do not edit checks, test specs, raw dataset files, or generated compiled outputs.",
         "Keep the workflow valid for the current compiler API and workflow schema.",

package/dist/packages/workflow-package/builtin-compiled-workflow.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { z } from "zod";
-import { readJsonFileWithSchema } from "../../lib/parse.js";
+import { readJsonFileWithSchema } from "../shared/parse.js";
 import { COMPILED_ZONE_KINDS } from "../compiler/workflow-primitives.js";
 import { WorkflowCompiledSchemaSchema } from "../compiler/lib/schema.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";

package/dist/packages/workflow-package/context-interface.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { type WorkflowCompiledSchema, type WorkflowCompiledZone, type WorkflowZoneId } from "../compiler/lib/schema.js";
+export declare const CONTEXT_INTERFACE_FILE = "workflow.schema.json";
+export declare const ContextInterfaceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"workflow-schema">;
+    version: z.ZodLiteral<1>;
+    target_type: z.ZodLiteral<"compiled">;
+    label: z.ZodString;
+    zones: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            output: "output";
+            runtime: "runtime";
+            input: "input";
+            working: "working";
+        }>;
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            runtime: "runtime";
+            directory: "directory";
+            file: "file";
+        }>;
+        required: z.ZodBoolean;
+        owned_by: z.ZodArray<z.ZodString>;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ContextInterfaceZoneSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        output: "output";
+        runtime: "runtime";
+        input: "input";
+        working: "working";
+    }>;
+    path: z.ZodString;
+    kind: z.ZodEnum<{
+        runtime: "runtime";
+        directory: "directory";
+        file: "file";
+    }>;
+    required: z.ZodBoolean;
+    owned_by: z.ZodArray<z.ZodString>;
+    description: z.ZodString;
+}, z.core.$strip>;
+export declare const ContextInterfaceZoneIdSchema: z.ZodString;
+export declare const ContextInterfaceZoneRoleSchema: z.ZodEnum<{
+    output: "output";
+    runtime: "runtime";
+    input: "input";
+    working: "working";
+}>;
+export declare const WorkflowInputSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const WorkflowInputContractSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>;
+export type ContextInterface = WorkflowCompiledSchema;
+export type ContextInterfaceZone = WorkflowCompiledZone;
+export type ContextInterfaceZoneId = WorkflowZoneId;
+export type ContextInterfaceZoneRole = z.infer<typeof ContextInterfaceZoneRoleSchema>;
+export type WorkflowInputSpec = z.infer<typeof WorkflowInputSpecSchema>;
+export interface ContextInterfaceStageLike {
+    id: string;
+    writes: readonly string[];
+}
+export interface ContextInterfaceSummary {
+    inputZones: ContextInterfaceZone[];
+    workingZones: ContextInterfaceZone[];
+    outputZones: ContextInterfaceZone[];
+    runtimeZones: ContextInterfaceZone[];
+}
+export declare function contextInterfaceFilePath(rootPath: string): string;
+export declare function resolveContextInterfacePath(rootPath: string): string | null;
+export declare function contextInterfaceExists(rootPath: string): boolean;
+export declare function contextInterfaceRelativePath(): string;
+export declare function listContextInterfaceZones(contextInterface: ContextInterface): ContextInterfaceZone[];
+export declare function findContextInterfaceZone(contextInterface: ContextInterface, zoneId: ContextInterfaceZoneId): ContextInterfaceZone | null;
+export declare function contextInterfaceZoneAbsolutePath(compiledPath: string, zone: Pick<ContextInterfaceZone, "path">): string;
+export declare function contextInterfaceArtifactPath(zone: Pick<ContextInterfaceZone, "path" | "kind">): string;
+export declare function contextInterfaceArtifactPathsForZoneIds(contextInterface: ContextInterface, zoneIds: readonly ContextInterfaceZoneId[]): string[];
+export declare function summarizeContextInterface(contextInterface: ContextInterface): ContextInterfaceSummary;
+export declare function deriveWorkflowInputsFromContextInterface(contextInterface: ContextInterface | null | undefined): WorkflowInputSpec[];
+export declare function buildContextInterface(stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
+export declare function writeContextInterfaceFile(rootPath: string, stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
+export declare function writeContextInterface(rootPath: string, contextInterface: ContextInterface): ContextInterface;
+export declare function readContextInterface(rootPath: string): ContextInterface | null;