@interf/compiler 0.5.0 → 0.6.1

package/dist/lib/agent-shells.js

@@ -1,17 +1,20 @@
-import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, symlinkSync, } from "node:fs";
+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 { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
+import { projectRawSnapshot } from "./compiled-raw.js";
 import { WORKFLOW_PACKAGE_DIR } from "./interf-detect.js";
-import { ensureCompiledZoneTargets, readCompiledSchemaFile, compiledZoneAbsolutePath, } from "./compiled-schema.js";
+import { WORKFLOW_SCHEMA_FILE, ensureCompiledZoneTargets, readCompiledSchemaFile, compiledZoneAbsolutePath, resolveWorkflowSchemaPath, } from "./compiled-schema.js";
 import { stageExecutionShellsRoot, workflowImprovementLoopRoot, workflowPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, } from "./compiled-paths.js";
 import { resolveWorkflowImprovementReviewSourcePaths } from "./workflow-review-paths.js";
+import { listFilesRecursive } from "./filesystem.js";
 const LOCAL_SKILL_ROOTS = [
     ".claude/skills",
     ".codex/skills",
     ".agents/skills",
     ".cursor/skills",
 ];
-function writeNativeAgentSurface(rootPath, agentsContent, skillName, skillContent) {
+export function writeNativeAgentSurface(rootPath, agentsContent, skillName, skillContent) {
     let changed = false;
     changed = writeIfChanged(join(rootPath, "AGENTS.md"), `${agentsContent.trimEnd()}\n`) || changed;
     changed =
@@ -25,10 +28,10 @@ function compiledQuerySkillSourcePath(compiledPath) {
 function compiledZoneSummaryLines(compiledPath) {
     const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
     if (!schema)
-        return ["- No compiled schema is available yet."];
+        return ["- No workflow schema is available yet."];
     return schema.zones
-        .filter((zone) => zone.id !== "raw" && zone.kind !== "runtime")
-        .map((zone) => `- \`${zone.id}\` -> \`${zone.path}\` (${zone.kind})`);
+        .filter((zone) => zone.kind !== "runtime")
+        .map((zone) => `- \`${zone.id}\` -> \`${zone.path}\` (${zone.role} ${zone.kind})`);
 }
 export function renderCompiledAgents(compiledPath, name, workflowId, about, options = {}) {
     const workflowOriginSelected = options.workflowOriginSelected ?? workflowId;
@@ -37,8 +40,8 @@ export function renderCompiledAgents(compiledPath, name, workflowId, about, opti
     return [
         `# ${name}`,
         "",
-        "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.",
+        "This is a compiled dataset built by Interf.",
+        "It is a file-based layer on top of the raw files, built for agents to navigate, retrieve evidence, and reach source-backed answers more reliably.",
         "",
         ...(about
             ? [
@@ -48,29 +51,29 @@ export function renderCompiledAgents(compiledPath, name, workflowId, about, opti
             : []),
         "## How to use this compiled dataset",
         "",
-        "1. Use the local native `interf-query` skill that Interf Compiler generated for this compiled dataset.",
+        "1. Use the local native `interf-query` skill that Interf 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 compiled dataset works",
         "",
-        "- `.interf/interf.json` points to the 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 project root via `source.control_path`.",
         `- Workflow seed: \`${workflowOriginSelected}\`.`,
         ...(workflowLocalDraft
             ? ["- 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 compiled dataset.",
-        "- `.interf/workflow/compiled.schema.json` is the deterministic output shape for this compiled dataset.",
+        `- \`.interf/workflow/${WORKFLOW_SCHEMA_FILE}\` is the deterministic zone contract 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.",
+        "- `.interf/workflow/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.",
-        "- Compiled output zones are declared in `.interf/workflow/compiled.schema.json`.",
+        `- Workflow zones are declared in \`.interf/workflow/${WORKFLOW_SCHEMA_FILE}\`.`,
         ...zoneLines,
         "- `.interf/runtime/` holds CLI-owned runtime artifacts.",
-        "- `.interf/tests/` holds saved raw-vs-compiled test comparisons for this compiled dataset.",
+        "- `.interf/tests/` mirrors the latest dataset-level comparison and keeps detailed target runs plus preserved sandboxes.",
         "- `.interf/tests/targets/` holds detailed raw and compiled target runs plus preserved test sandboxes.",
         "",
         "## Manual query rules",
@@ -100,7 +103,6 @@ export function renderCompiledAgents(compiledPath, name, workflowId, about, opti
     ].join("\n");
 }
 export function renderCompiledQuerySkill() {
-    const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note.toLowerCase()}`);
     return [
         "# Manual Query Loop",
         "",
@@ -108,15 +110,15 @@ export function renderCompiledQuerySkill() {
         "",
         "Default loop:",
         "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.",
+        `2. Use the workflow zones declared in \`workflow/${WORKFLOW_SCHEMA_FILE}\` before falling back to \`raw/\`.`,
+        "3. Use `raw/` for direct quotes, verification, exact 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",
-        "- use `raw/` to confirm source page, metric family, or provenance when the compiled layer is missing or ambiguous",
-        ...chartNotes,
+        "- treat the workflow as the method layer and the compiled 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 compiled layer is missing or ambiguous",
+        "- do not invent navigation or note structure beyond what this workflow declares",
         "- 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 compiled dataset.",
@@ -128,7 +130,7 @@ function renderRawTestAgents() {
     return [
         "# Raw Test Shell",
         "",
-        "This is an isolated raw-files test shell generated by Interf Compiler.",
+        "This is an isolated raw-files test shell generated by Interf.",
         "There is no compiled dataset in this shell.",
         "",
         "## How to use this shell",
@@ -229,7 +231,7 @@ function loadCompiledSchema(compiledPath) {
     const workflowRoot = workflowPackagePathForCompiled(compiledPath);
     const schema = readCompiledSchemaFile(workflowRoot);
     if (!schema) {
-        throw new Error(`Missing workflow compiled schema at ${join(workflowRoot, "compiled.schema.json")}`);
+        throw new Error(`Missing workflow schema at ${join(workflowRoot, WORKFLOW_SCHEMA_FILE)}`);
     }
     return schema;
 }
@@ -239,7 +241,7 @@ function zoneMap(schema) {
 function zoneOrThrow(zones, zoneId) {
     const zone = zones.get(zoneId);
     if (!zone) {
-        throw new Error(`Missing compiled schema zone "${zoneId}" for stage shell projection.`);
+        throw new Error(`Missing workflow schema zone "${zoneId}" for stage shell projection.`);
     }
     return zone;
 }
@@ -312,7 +314,7 @@ function renderStageExecutionAgents(compiledName, workflowId, stage) {
     return [
         `# ${compiledName} — ${stage.label} Execution Shell`,
         "",
-        "This is an ephemeral stage-execution shell generated by Interf Compiler.",
+        "This is an ephemeral stage-execution shell generated by Interf.",
         "It is for automated pipeline execution only, not for manual querying.",
         "",
         "## Start Here",
@@ -329,7 +331,7 @@ function renderStageExecutionAgents(compiledName, workflowId, stage) {
         "- For file zones, `runtime/paths.json` points to the exact file path inside those mount roots.",
         "- 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, compiled schema, and docs for the current stage only.",
+        "- `workflow/` = workflow metadata, workflow schema, and docs for the current stage only.",
         "",
         "## Boundaries",
         "",
@@ -360,12 +362,12 @@ function renderStageExecutionSkill(stage, stageMethodDoc) {
         "name: interf-stage",
         "description: >",
         `  Native local execution skill for the ${stage.label} stage in this`,
-        "  Interf Compiler run. Use it only inside an automated stage execution shell.",
+        "  Interf run. Use it only inside an automated stage execution shell.",
         "---",
         "",
-        `# Interf Compiler Stage Execution — ${stage.label}`,
+        `# Interf Stage Execution — ${stage.label}`,
         "",
-        "This local native skill exists for automated Interf Compiler stage execution.",
+        "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.",
         "Do not switch into manual query mode.",
@@ -399,9 +401,9 @@ function renderCompiledQueryNativeSkill(querySkillContent) {
         "  its raw fallback.",
         "---",
         "",
-        "# Interf Compiler Query",
+        "# Interf Query",
         "",
-        "This is the native local query skill for a compiled dataset built by Interf Compiler.",
+        "This is the native local query skill for a compiled dataset built by Interf.",
         "Use it when reading this compiled dataset manually.",
         "Editable source: `.interf/workflow/use/query/SKILL.md`.",
         "",
@@ -417,9 +419,9 @@ function projectWorkflowMetadata(compiledPath, shellRoot, stage) {
     if (existsSync(workflowJsonPath)) {
         linkPath(workflowJsonPath, join(shellWorkflowRoot, "workflow.json"));
     }
-    const compiledSchemaPath = join(compiledWorkflowRoot, "compiled.schema.json");
-    if (existsSync(compiledSchemaPath)) {
-        linkPath(compiledSchemaPath, join(shellWorkflowRoot, "compiled.schema.json"));
+    const compiledSchemaPath = resolveWorkflowSchemaPath(compiledWorkflowRoot);
+    if (compiledSchemaPath) {
+        linkPath(compiledSchemaPath, join(shellWorkflowRoot, WORKFLOW_SCHEMA_FILE));
     }
     const readmePath = join(compiledWorkflowRoot, "README.md");
     if (existsSync(readmePath)) {
@@ -509,6 +511,13 @@ export function syncStageExecutionShellWrites(compiledPath, shellRoot, stage, wr
             continue;
         const compiledZonePath = compiledZoneAbsolutePath(compiledPath, zone);
         if (shellZoneStat.isDirectory()) {
+            const shellZoneFiles = listFilesRecursive(shellZonePath);
+            const compiledZoneFiles = existsSync(compiledZonePath)
+                ? listFilesRecursive(compiledZonePath)
+                : [];
+            if (shellZoneFiles.length === 0 && compiledZoneFiles.length > 0) {
+                continue;
+            }
             rmSync(compiledZonePath, { recursive: true, force: true });
             mkdirSync(dirname(compiledZonePath), { recursive: true });
             cpSync(shellZonePath, compiledZonePath, {
@@ -645,26 +654,191 @@ function freezePreservedShell(rootPath, shellType) {
 }
 export function renderClaudeBootstrap(content) {
     return [
-        "<!-- Generated compatibility mirror of AGENTS.md. Interf Compiler may rewrite this file. -->",
+        "<!-- Generated compatibility mirror of AGENTS.md. Interf may rewrite this file. -->",
         "",
         content.trimEnd(),
         "",
     ].join("\n");
 }
+function renderWorkflowAuthoringAgents(options) {
+    return [
+        `# ${options.label} — Workflow Authoring Shell`,
+        "",
+        "This is an automated workflow-authoring shell generated by Interf.",
+        "It exists to create or refine one standalone workflow for the files and checks in this dataset.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/authoring-context.json` now.",
+        `2. Read \`workflow/README.md\`, \`workflow/workflow.json\`, and \`workflow/${WORKFLOW_SCHEMA_FILE}\` now.`,
+        "3. Review `artifacts/source-dataset/raw/` and `artifacts/preview-compiled/` if present.",
+        "4. Use the local native `interf-workflow-author` skill now.",
+        "",
+        "## Boundaries",
+        "",
+        `- New workflow id: \`${options.workflowId}\`.`,
+        `- Seed workflow: \`${options.baseWorkflowId}\`.`,
+        "- Edit only files under `workflow/`.",
+        "- Do not edit raw dataset files or preview artifacts.",
+        "- Keep the workflow valid for the current compiler API and workflow schema.",
+        "- 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.",
+        "",
+        "## Goal",
+        "",
+        "- produce one standalone workflow tuned to the files and checks in this dataset",
+        "- preserve deterministic stage and zone contracts",
+        "- stop once the workflow edits are complete",
+        "",
+    ].join("\n");
+}
+function renderWorkflowAuthoringSkill() {
+    return [
+        "---",
+        "name: interf-workflow-author",
+        "description: >",
+        "  Native local workflow-authoring skill for an automated Interf workflow draft run.",
+        "---",
+        "",
+        "# Interf Workflow Authoring",
+        "",
+        "Read `runtime/authoring-context.json` first.",
+        "Then review the seeded package under `workflow/`, the raw dataset snapshot under `artifacts/source-dataset/raw/`, and any preview compiled outputs under `artifacts/preview-compiled/`.",
+        "",
+        "Rules:",
+        "- edit only `workflow/`",
+        `- keep \`workflow.json\`, \`${WORKFLOW_SCHEMA_FILE}\`, and any changed stage docs aligned`,
+        "- prefer small, defensible package edits over random churn",
+        "- keep the package standalone; do not introduce runtime inheritance or fallback assumptions",
+        "- do not introduce wikilinks unless the workflow also creates the target note by exact basename or explicit relative path",
+        "- respect stage boundaries: do not make structure outputs link to notes or entrypoints first created by later stages",
+        "- prefer conservative routing changes over speculative note sprawl",
+        "- 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",
+        "- do not hardcode benchmark answers into workflow docs",
+        "- do not edit raw dataset files or preview artifacts",
+        "",
+    ].join("\n");
+}
+function authoringCopyIfExists(sourcePath, targetPath) {
+    if (!existsSync(sourcePath))
+        return;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    cpSync(sourcePath, targetPath, {
+        recursive: true,
+        force: true,
+        errorOnExist: false,
+        preserveTimestamps: true,
+    });
+}
+function projectCompiledPreviewSnapshot(previewCompiledPath, shellRoot) {
+    const previewRoot = join(shellRoot, "artifacts", "preview-compiled");
+    mkdirSync(previewRoot, { recursive: true });
+    authoringCopyIfExists(join(previewCompiledPath, "AGENTS.md"), join(previewRoot, "AGENTS.md"));
+    authoringCopyIfExists(join(previewCompiledPath, "CLAUDE.md"), join(previewRoot, "CLAUDE.md"));
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(previewCompiledPath));
+    for (const zone of schema?.zones ?? []) {
+        if (zone.kind === "runtime" || zone.role === "input")
+            continue;
+        const absolutePath = compiledZoneAbsolutePath(previewCompiledPath, zone);
+        if (!existsSync(absolutePath))
+            continue;
+        authoringCopyIfExists(absolutePath, join(previewRoot, zone.path));
+    }
+}
+function projectCompiledPreviewRuntime(previewCompiledPath, shellRoot) {
+    const targetRoot = join(shellRoot, "artifacts", "preview-runtime");
+    mkdirSync(targetRoot, { recursive: true });
+    const runtimeRoot = compiledRuntimeRoot(previewCompiledPath);
+    for (const artifactName of [
+        "run.json",
+        "state.json",
+        "health.json",
+        "view-spec.json",
+        "raw-snapshot.json",
+        "execution-shells",
+        "logs",
+    ]) {
+        authoringCopyIfExists(join(runtimeRoot, artifactName), join(targetRoot, artifactName));
+    }
+}
 function improvementWorkflowDocsPath(compiledPath) {
     return join(workflowPackagePathForCompiled(compiledPath), "improve");
 }
+export function createWorkflowAuthoringShell(options) {
+    const shellRoot = mkdtempSync(join(tmpdir(), `interf-workflow-author-${options.workflowId}-`));
+    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
+    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
+    mkdirSync(join(shellRoot, "logs"), { recursive: true });
+    const context = {
+        kind: "interf-workflow-authoring",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        workflow_id: options.workflowId,
+        workflow_label: options.label,
+        seed_workflow_id: options.baseWorkflowId,
+        task_prompt: options.taskPrompt,
+        dataset: {
+            source_path: options.datasetPath,
+            checks: {
+                count: options.checks.length,
+                questions: options.checks.map((check, index) => ({
+                    id: check.id ?? `check-${index + 1}`,
+                    question: check.question,
+                })),
+            },
+        },
+        preview: options.preview
+            ? {
+                prepared: true,
+                compile_ok: options.preview.compileResult.ok,
+                failed_stage: options.preview.compileResult.failedStage,
+            }
+            : {
+                prepared: false,
+                compile_ok: null,
+                failed_stage: null,
+            },
+    };
+    writeFileSync(join(shellRoot, "runtime", "authoring-context.json"), `${JSON.stringify(context, null, 2)}\n`);
+    projectRawSnapshot({
+        sourcePath: options.datasetPath,
+        destinationPath: join(shellRoot, "artifacts", "source-dataset", "raw"),
+        compiledPath: shellRoot,
+        mode: "copy",
+        prune: true,
+        preserveTimestamps: true,
+    });
+    if (options.preview) {
+        projectCompiledPreviewSnapshot(options.preview.compiledPath, shellRoot);
+        projectCompiledPreviewRuntime(options.preview.compiledPath, shellRoot);
+    }
+    linkPath(options.workflowPath, join(shellRoot, "workflow"));
+    writeNativeAgentSurface(shellRoot, renderWorkflowAuthoringAgents({
+        workflowId: options.workflowId,
+        label: options.label,
+        baseWorkflowId: options.baseWorkflowId,
+    }), "interf-workflow-author", renderWorkflowAuthoringSkill());
+    return {
+        rootPath: shellRoot,
+        workflowBeforePath: join(shellRoot, "artifacts", "workflow-before"),
+        workflowAfterPath: join(shellRoot, "artifacts", "workflow-after"),
+        promptLogPath: join(shellRoot, "logs", "workflow-author.prompt.txt"),
+        eventLogPath: join(shellRoot, "logs", "workflow-author.events.ndjson"),
+        statusLogPath: join(shellRoot, "logs", "workflow-author.status.log"),
+    };
+}
 function renderWorkflowImprovementAgents(compiledName, workflowId, loopIndex) {
     return [
         `# ${compiledName} — Workflow Improvement Shell`,
         "",
-        "This is an automated workflow-improvement shell generated by Interf Compiler.",
+        "This is an automated workflow-improvement shell generated by Interf.",
         "It exists to review failed compile/test runs and edit the workflow package for the next variation.",
         "",
         "## Start Here",
         "",
         "1. Read `runtime/loop-context.json` now.",
-        "2. Read `workflow/README.md`, `workflow/workflow.json`, and `workflow/compiled.schema.json` now.",
+        `2. Read \`workflow/README.md\`, \`workflow/workflow.json\`, and \`workflow/${WORKFLOW_SCHEMA_FILE}\` now.`,
         "3. Read `workflow/improve/SKILL.md` now.",
         "4. Use the local native `interf-workflow-improver` skill now.",
         "",
@@ -675,7 +849,7 @@ function renderWorkflowImprovementAgents(compiledName, workflowId, loopIndex) {
         "- Edit only files under `workflow/`.",
         "- 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.",
+        "- Keep the workflow valid for the current compiler API and workflow schema.",
         "",
         "## Goal",
         "",
@@ -696,11 +870,11 @@ function renderWorkflowImprovementSkill(workflowId, loopIndex, improvementDoc) {
         "---",
         "name: interf-workflow-improver",
         "description: >",
-        "  Native local workflow-improvement skill for this Interf Compiler run.",
+        "  Native local workflow-improvement skill for this Interf run.",
         "  Use it only inside an automated workflow-improvement shell.",
         "---",
         "",
-        `# Interf Compiler Workflow Improvement — ${workflowId}`,
+        `# Interf Workflow Improvement — ${workflowId}`,
         "",
         "This local native skill exists for automated workflow-improvement loops.",
         "Read `runtime/loop-context.json` first.",

package/dist/lib/agents.d.ts

@@ -2,5 +2,5 @@ export type { Agent, AgentAutomationReadiness, AgentPreflightOptions, AgentPrefl
 export { detectAgents, supportsAutomatedRuns, resolveAgent, } from "./agent-detection.js";
 export { buildAgentPreflightPrompt, runAgentPreflight, ensureAgentAutomatedRunReady, } from "./agent-preflight.js";
 export { spawnAgent, } from "./agent-execution.js";
-export { buildAgentArgs } from "./agent-args.js";
+export { buildAgentArgs, buildAgentEnv } from "./agent-args.js";
 export { extractAgentFailureStatus, classifyTerminalVisibleStatus, hasAgentStalled, } from "./agent-status.js";

package/dist/lib/agents.js

@@ -1,5 +1,5 @@
 export { detectAgents, supportsAutomatedRuns, resolveAgent, } from "./agent-detection.js";
 export { buildAgentPreflightPrompt, runAgentPreflight, ensureAgentAutomatedRunReady, } from "./agent-preflight.js";
 export { spawnAgent, } from "./agent-execution.js";
-export { buildAgentArgs } from "./agent-args.js";
+export { buildAgentArgs, buildAgentEnv } from "./agent-args.js";
 export { extractAgentFailureStatus, classifyTerminalVisibleStatus, hasAgentStalled, } from "./agent-status.js";

package/dist/lib/builtin-compiled-workflow.d.ts

@@ -0,0 +1,38 @@
+import { COMPILED_ZONE_KINDS, type CompiledZoneKind } from "./workflow-primitives.js";
+export declare const BUILTIN_COMPILED_STAGE_IDS: {
+    readonly SUMMARIZE: "summarize";
+    readonly STRUCTURE: "structure";
+    readonly SHAPE: "shape";
+};
+export type BuiltinCompiledStageId = typeof BUILTIN_COMPILED_STAGE_IDS[keyof typeof BUILTIN_COMPILED_STAGE_IDS];
+export declare const BUILTIN_COMPILED_ZONE_IDS: {
+    readonly RAW: "raw";
+    readonly SUMMARIES: "summaries";
+    readonly KNOWLEDGE_ENTITIES: "knowledge-entities";
+    readonly KNOWLEDGE_CLAIMS: "knowledge-claims";
+    readonly KNOWLEDGE_INDEXES: "knowledge-indexes";
+    readonly HOME: "home";
+    readonly RUNTIME: "runtime";
+};
+export type BuiltinCompiledZoneId = typeof BUILTIN_COMPILED_ZONE_IDS[keyof typeof BUILTIN_COMPILED_ZONE_IDS];
+export interface BuiltinCompiledZoneSpec {
+    id: BuiltinCompiledZoneId;
+    role: "input" | "working" | "output" | "runtime";
+    path: string;
+    kind: CompiledZoneKind;
+    required: boolean;
+    description: string;
+}
+export interface BuiltinCompiledStageAccessPattern {
+    id: BuiltinCompiledStageId;
+    contract_type: string;
+    reads: BuiltinCompiledZoneId[];
+    writes: BuiltinCompiledZoneId[];
+}
+export declare function listBuiltinCompiledZoneSpecs(): BuiltinCompiledZoneSpec[];
+export declare function listBuiltinCompiledFallbackStages(): BuiltinCompiledStageAccessPattern[];
+export declare function requiredCompiledZoneOwners<TStage extends {
+    id: string;
+    writes: readonly string[];
+}>(stages: readonly TStage[], zoneId: BuiltinCompiledZoneId): string[];
+export { COMPILED_ZONE_KINDS };

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

@@ -0,0 +1,94 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { PACKAGE_ROOT } from "./config.js";
+import { readJsonFileWithSchema } from "./parse.js";
+import { WorkflowCompiledSchemaSchema } from "./schema.js";
+import { COMPILED_ZONE_KINDS } from "./workflow-primitives.js";
+export const BUILTIN_COMPILED_STAGE_IDS = {
+    SUMMARIZE: "summarize",
+    STRUCTURE: "structure",
+    SHAPE: "shape",
+};
+export const BUILTIN_COMPILED_ZONE_IDS = {
+    RAW: "raw",
+    SUMMARIES: "summaries",
+    KNOWLEDGE_ENTITIES: "knowledge-entities",
+    KNOWLEDGE_CLAIMS: "knowledge-claims",
+    KNOWLEDGE_INDEXES: "knowledge-indexes",
+    HOME: "home",
+    RUNTIME: "runtime",
+};
+const BUILTIN_ZONE_ID_SET = new Set(Object.values(BUILTIN_COMPILED_ZONE_IDS));
+const BUILTIN_STAGE_ID_SET = new Set(Object.values(BUILTIN_COMPILED_STAGE_IDS));
+const BuiltinWorkflowStageSchema = z.object({
+    id: z.string(),
+    contract_type: z.string(),
+    reads: z.array(z.string()).min(1),
+    writes: z.array(z.string()).min(1),
+});
+const BuiltinWorkflowPackageSchema = z.object({
+    stages: z.array(BuiltinWorkflowStageSchema).min(1),
+});
+let builtinCompiledContractCache = null;
+function builtinWorkflowRootPath() {
+    return join(PACKAGE_ROOT, "builtin-workflows", "interf");
+}
+function builtinWorkflowPath(relativePath) {
+    return join(builtinWorkflowRootPath(), relativePath);
+}
+function assertBuiltinZoneId(value) {
+    if (!BUILTIN_ZONE_ID_SET.has(value)) {
+        throw new Error(`Built-in Interf workflow schema declares unsupported zone id "${value}".`);
+    }
+    return value;
+}
+function assertBuiltinStageId(value) {
+    if (!BUILTIN_STAGE_ID_SET.has(value)) {
+        throw new Error(`Built-in Interf workflow package declares unsupported stage id "${value}".`);
+    }
+    return value;
+}
+function loadBuiltinCompiledContract() {
+    if (builtinCompiledContractCache)
+        return builtinCompiledContractCache;
+    const schema = readJsonFileWithSchema(builtinWorkflowPath("workflow.schema.json"), "built-in Interf workflow schema", WorkflowCompiledSchemaSchema);
+    if (!schema) {
+        throw new Error(`Missing or invalid built-in workflow schema at ${builtinWorkflowPath("workflow.schema.json")}.`);
+    }
+    const workflow = readJsonFileWithSchema(builtinWorkflowPath("workflow.json"), "built-in Interf workflow package", BuiltinWorkflowPackageSchema);
+    if (!workflow) {
+        throw new Error(`Missing or invalid built-in workflow package at ${builtinWorkflowPath("workflow.json")}.`);
+    }
+    const zones = schema.zones.map((zone) => ({
+        id: assertBuiltinZoneId(zone.id),
+        role: zone.role,
+        path: zone.path,
+        kind: zone.kind,
+        required: zone.required,
+        description: zone.description,
+    }));
+    const stages = workflow.stages.map((stage) => ({
+        id: assertBuiltinStageId(stage.id),
+        contract_type: stage.contract_type,
+        reads: stage.reads.map(assertBuiltinZoneId),
+        writes: stage.writes.map(assertBuiltinZoneId),
+    }));
+    builtinCompiledContractCache = { zones, stages };
+    return builtinCompiledContractCache;
+}
+export function listBuiltinCompiledZoneSpecs() {
+    return loadBuiltinCompiledContract().zones.map((zone) => ({ ...zone }));
+}
+export function listBuiltinCompiledFallbackStages() {
+    return loadBuiltinCompiledContract().stages.map((stage) => ({
+        ...stage,
+        reads: [...stage.reads],
+        writes: [...stage.writes],
+    }));
+}
+export function requiredCompiledZoneOwners(stages, zoneId) {
+    return Array.from(new Set(stages
+        .filter((stage) => stage.writes.includes(zoneId))
+        .map((stage) => stage.id)));
+}
+export { COMPILED_ZONE_KINDS };

package/dist/lib/compiled-compile.d.ts

@@ -15,10 +15,6 @@ export interface CompiledCompileResult {
     ok: boolean;
     stageResults: Record<string, WorkflowStageResult>;
     failedStage: string | null;
-    summarize: CompiledSummarizeResult | null;
-    structure: WorkflowStageResult | null;
-    shape: WorkflowStageResult | null;
-    compile: WorkflowStageResult | null;
 }
 export type StageShellRetentionMode = "on-failure" | "always";
 export declare function resolveCompiledContext(compiledPath: string): {