@interf/compiler 0.6.3 → 0.6.5

package/dist/packages/agents/lib/compiled-bootstrap.d.ts

@@ -0,0 +1,3 @@
+import { renderClaudeBootstrap } from "./shells.js";
+export { renderClaudeBootstrap };
+export declare function refreshCompiledBootstrapGuidance(dirPath: string): boolean;

package/dist/packages/agents/lib/compiled-bootstrap.js

@@ -0,0 +1,18 @@
+import { basename } from "node:path";
+import { readInterfConfig } from "../../project-model/interf-detect.js";
+import { projectCompiledQueryShell, renderClaudeBootstrap } from "./shells.js";
+export { renderClaudeBootstrap };
+export function refreshCompiledBootstrapGuidance(dirPath) {
+    const config = readInterfConfig(dirPath);
+    if (!config)
+        return false;
+    const compiledName = config.name ?? basename(dirPath);
+    const workflowId = config.workflow ?? "interf";
+    const workflowOriginSelected = config.workflow_origin?.selected ?? workflowId;
+    const workflowLocalDraft = config.workflow_origin?.local_draft === true;
+    const about = typeof config.about === "string" && config.about.length > 0 ? config.about : undefined;
+    return projectCompiledQueryShell(dirPath, compiledName, workflowId, about, {
+        workflowOriginSelected,
+        workflowLocalDraft,
+    });
+}

package/dist/packages/agents/lib/executors.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeExecutorInfo } from "../../../lib/schema.js";
+import type { RuntimeExecutorInfo } from "../../compiler/lib/schema.js";
 import type { Agent } from "./types.js";
 export type WorkflowExecutorKind = "local-agent" | "connected-provider" | "managed";
 export interface WorkflowExecutionProfile {
@@ -20,7 +20,7 @@ export interface WorkflowExecutor {
     executionProfile?: WorkflowExecutionProfile;
     execute(rootPath: string, prompt: string, options?: WorkflowExecuteOptions): Promise<number>;
 }
-export type { RuntimeExecutorInfo } from "../../../lib/schema.js";
+export type { RuntimeExecutorInfo } from "../../compiler/lib/schema.js";
 export declare function buildRuntimeExecutorInfo(executor: WorkflowExecutor): RuntimeExecutorInfo;
 export declare function createLocalAgentExecutor(agent: Agent, executionProfile?: WorkflowExecutionProfile): WorkflowExecutor;
 export declare function resolveLocalExecutor(options?: {

package/dist/packages/agents/lib/shells.d.ts

@@ -1,4 +1,6 @@
-import type { RuntimeContractType, SourceTruthCheck, WorkflowImprovementContext, WorkflowZoneId } from "../../../lib/schema.js";
+import type { RuntimeContractType, WorkflowImprovementContext } from "../../compiler/lib/schema.js";
+import type { SourceTruthCheck } from "../../project-model/lib/schema.js";
+import { type ContextInterfaceZoneId as WorkflowZoneId } from "../../workflow-package/context-interface.js";
 export interface NativeStageDefinition {
     id: string;
     label: string;

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

@@ -1,12 +1,13 @@
 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 "../../../lib/chart-guidance.js";
-import { projectRawSnapshot } from "../../../lib/compiled-raw.js";
-import { WORKFLOW_PACKAGE_DIR } from "../../../lib/interf-detect.js";
-import { WORKFLOW_SCHEMA_FILE, ensureCompiledZoneTargets, readCompiledSchemaFile, compiledZoneAbsolutePath, resolveWorkflowSchemaPath, } from "../../../lib/compiled-schema.js";
-import { stageExecutionShellsRoot, workflowImprovementLoopRoot, workflowPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, } from "../../../lib/compiled-paths.js";
-import { listFilesRecursive } from "../../../lib/filesystem.js";
+import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
+import { projectRawSnapshot } from "../../compiler/raw-snapshot.js";
+import { WORKFLOW_PACKAGE_DIR } from "../../project-model/interf-detect.js";
+import { CONTEXT_INTERFACE_FILE as WORKFLOW_SCHEMA_FILE, contextInterfaceZoneAbsolutePath as compiledZoneAbsolutePath, readContextInterface as readCompiledSchemaFile, resolveContextInterfacePath as resolveWorkflowSchemaPath, } from "../../workflow-package/context-interface.js";
+import { stageExecutionShellsRoot, workflowImprovementLoopRoot, workflowPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, } from "../../compiler/compiled-paths.js";
+import { ensureCompiledZoneTargets } from "../../compiler/compiled-schema.js";
+import { listFilesRecursive } from "../../shared/filesystem.js";
 import { resolveWorkflowImprovementReviewSourcePaths } from "../../workflow-package/workflow-review-paths.js";
 const LOCAL_SKILL_ROOTS = [
     ".claude/skills",
@@ -40,8 +41,8 @@ export function renderCompiledAgents(compiledPath, name, workflowId, about, opti
     return [
         `# ${name}`,
         "",
-        "This is a context folder built by Interf.",
-        "Technically, it is the compiled context for this dataset entry: a file-based task context layer on top of the raw files, prepared for agents to navigate, retrieve evidence, and reach source-backed answers more reliably.",
+        "This is portable context built by Interf.",
+        "Technically, it is the compiled context for this dataset entry: a file-based context layer on top of the raw files, prepared for agents to navigate, retrieve evidence, and answer more reliably from the source files.",
         "",
         ...(about
             ? [
@@ -49,22 +50,23 @@ export function renderCompiledAgents(compiledPath, name, workflowId, about, opti
                 "",
             ]
             : []),
-        "## How to use this context folder",
+        "## How to use this portable context",
         "",
-        "1. Use the local native `interf-query` skill that Interf generated for this context folder.",
+        "1. Use the local native `interf-query` skill that Interf generated for this portable context.",
         "2. Let the workflow docs and declared output zones guide retrieval instead of assuming a fixed note layout.",
         "3. Use `raw/` when you need direct quotes, exact chart values, table lookups, or verification.",
         "",
         "## How this compiled context works",
         "",
+        "- The workflow package defines the context interface this compiled context implements on disk.",
         "- `.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 context now carries a local workflow draft improved from that seed. Recompiling this context folder reuses the local `.interf/workflow/` package."]
+            ? ["- This compiled context now carries a local workflow draft improved from that seed. Recompiling this portable context reuses the local `.interf/workflow/` package."]
             : []),
         `- Active local workflow id: \`${workflowId}\`.`,
         "- `.interf/workflow/` is the local editable method package for this compiled context.",
-        `- \`.interf/workflow/${WORKFLOW_SCHEMA_FILE}\` is the deterministic zone contract for this compiled context.`,
+        `- \`.interf/workflow/${WORKFLOW_SCHEMA_FILE}\` is the deterministic context interface for this compiled context.`,
         "- `.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 projects into native execution shells for automated runs.",
@@ -87,8 +89,8 @@ export function renderCompiledAgents(compiledPath, name, workflowId, about, opti
         "## Commands",
         "",
         "```",
-        "interf compile            build this context folder",
-        "interf test               run checks against this context folder",
+        "interf compile            build this portable context",
+        "interf test               run checks against this portable context",
         "interf verify stage <id>  verify one workflow stage",
         "interf verify compiled    verify the full compiled context output",
         "interf status             show deterministic health",
@@ -97,7 +99,7 @@ export function renderCompiledAgents(compiledPath, name, workflowId, about, opti
         "## Rules",
         "",
         "- Do not modify files under `raw/`.",
-        "- Treat compiled notes as working task context artifacts, not final truth.",
+        "- Treat compiled notes as working context artifacts, not final truth.",
         "- When confidence is low, verify against `raw/` before answering strongly.",
         "",
     ].join("\n");
@@ -121,7 +123,7 @@ export function renderCompiledQuerySkill() {
         "- do not invent navigation or note structure beyond what this workflow declares",
         "- when the compiled context is insufficient, verify in `raw/` and then answer",
         "",
-        "You can edit this file to bias manual question-answering behavior for this context folder.",
+        "You can edit this file to bias manual question-answering behavior for this portable context.",
         "",
     ].join("\n");
 }
@@ -396,7 +398,7 @@ function renderCompiledQueryNativeSkill(querySkillContent) {
         "---",
         "name: interf-query",
         "description: >",
-        "  Native local query skill for this context folder built by Interf",
+        "  Native local query skill for this portable context built by Interf",
         "  Compiler. Use it for manual questions against the compiled context",
         "  and its raw fallback.",
         "---",
@@ -404,7 +406,7 @@ function renderCompiledQueryNativeSkill(querySkillContent) {
         "# Interf Query",
         "",
         "This is the native local query skill for a compiled context built by Interf.",
-        "Use it when reading this context folder manually.",
+        "Use it when reading this portable context manually.",
         "Editable source: `.interf/workflow/use/query/SKILL.md`.",
         "",
         querySkillContent.trim(),
@@ -687,7 +689,7 @@ function renderWorkflowAuthoringAgents(options) {
         "## Goal",
         "",
         "- produce one standalone workflow tuned to the files and checks in this task",
-        "- preserve deterministic stage and zone contracts",
+        "- preserve deterministic stage and context-interface contracts",
         "- stop once the workflow edits are complete",
         "",
     ].join("\n");
@@ -853,7 +855,7 @@ function renderWorkflowImprovementAgents(compiledName, workflowId, loopIndex) {
         "",
         "## Goal",
         "",
-        "- create a better workflow variation for this task",
+        "- create a better workflow variation for this kind of work",
         "- preserve deterministic compiled-context structure",
         "- stop after the workflow edits are complete",
         "",

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

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readJsonFileWithSchema } from "../../../lib/parse.js";
+import { readJsonFileWithSchema } from "../../shared/parse.js";
 import { InterfUserConfigSchema } from "./schema.js";
 export const INTERF_HOME = join(homedir(), ".interf");
 export const USER_CONFIG_PATH = join(INTERF_HOME, "config.json");

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

@@ -1,48 +1,4 @@
-import { type WorkflowExecutor } from "../agents/lib/executors.js";
-import { type CompiledWorkflowId, type WorkflowStageDefinition } from "../workflow-package/workflow-definitions.js";
-import { type WorkflowReporter, type WorkflowStageResult } from "../workflow-package/workflow-helpers.js";
-export interface CompiledStageExecutionDefinition extends WorkflowStageDefinition {
-}
-export interface CompiledSummarizeResult extends WorkflowStageResult {
-    skipped: boolean;
-    plan: {
-        sourceCount: number;
-        summaryCount: number;
-        targetCount: number;
-    };
-}
-export interface CompiledCompileResult {
-    ok: boolean;
-    stageResults: Record<string, WorkflowStageResult>;
-    failedStage: string | null;
-}
-export type StageShellRetentionMode = "on-failure" | "always";
-export declare function resolveCompiledContext(compiledPath: string): {
-    compiledName: string;
-    sourcePath: string;
-    controlPath: string;
-    workflowId: CompiledWorkflowId;
-};
-export declare function compiledExecutionStages(workflowId: CompiledWorkflowId, compiledPath: string): CompiledStageExecutionDefinition[];
-export declare function runCompiledSummarize(options: {
-    executor: WorkflowExecutor;
-    compiledPath: string;
-    reporter?: WorkflowReporter;
-    reportSummary?: boolean;
-    reportStep?: boolean;
-    stageDefinition?: CompiledStageExecutionDefinition;
-    fullPass?: boolean;
-}): Promise<CompiledSummarizeResult>;
-export declare function runCompiledCompile(options: {
-    executor: WorkflowExecutor;
-    compiledPath: string;
-    reporter?: WorkflowReporter;
-    reportStep?: boolean;
-    preserveStageShells?: StageShellRetentionMode;
-}): Promise<WorkflowStageResult>;
-export declare function compileCompiled(options: {
-    executor: WorkflowExecutor;
-    compiledPath: string;
-    reporter?: WorkflowReporter;
-    preserveStageShells?: StageShellRetentionMode;
-}): Promise<CompiledCompileResult>;
+export * from "./compiled-target.js";
+export * from "./compiled-stage-plan.js";
+export * from "./compiled-stage-runner.js";
+export * from "./compiled-pipeline.js";

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

@@ -1,256 +1,4 @@
-import { join } from "node:path";
-import { createStageExecutionShell, freezeStageExecutionShell, pruneStageExecutionShells, syncStageExecutionShellWrites, } from "../agents/lib/shells.js";
-import { readInterfConfig, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, } from "../project-model/interf-detect.js";
-import { refreshCompiledBootstrapGuidance, } from "../project-model/interf-bootstrap.js";
-import { reconcileCompiledStageRun, } from "./runtime-reconcile.js";
-import { refreshCompiledArtifacts, } from "./state.js";
-import { buildRuntimeStageContract, } from "./runtime.js";
-import { validateWorkflowPackage } from "../workflow-package/local-workflows.js";
-import { formatActiveCompiledWorkflowStageStep, getActiveCompiledStagePolicyNotes, getActiveCompiledWorkflow, resolveRequiredCompiledWorkflowFromConfig, resolveActiveCompiledStageAcceptance, } from "../workflow-package/workflow-definitions.js";
-import { validateCompiledStage, validateCompiledWorkflow, } from "./validate.js";
-import { buildLocalSkillContractExtension, buildStageInstructions, reportBlankLine, reportLine, reportValidationFailure, workflowCompileStageDirectory, } from "../workflow-package/workflow-helpers.js";
-import { executeValidatedStage, } from "../workflow-package/workflow-stage-runner.js";
-import { syncCompiledRawSnapshot } from "../project-model/compiled-raw.js";
-import { workflowPackagePathForCompiled, } from "../project-model/compiled-paths.js";
-import { compiledContractArtifactPathsForZoneIds, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
-import { discoverSourceFiles } from "../../lib/discovery.js";
-import { listFilesRecursive } from "../../lib/filesystem.js";
-export function resolveCompiledContext(compiledPath) {
-    const config = readInterfConfig(compiledPath);
-    const workflowId = resolveRequiredCompiledWorkflowFromConfig(config, `.interf/interf.json for ${compiledPath}`);
-    return {
-        compiledName: config?.name ?? "compiled",
-        sourcePath: resolveSourceFolderPath(compiledPath, config),
-        controlPath: resolveSourceControlPath(compiledPath),
-        workflowId,
-    };
-}
-export function compiledExecutionStages(workflowId, compiledPath) {
-    return getActiveCompiledWorkflow(compiledPath, workflowId)
-        .stages;
-}
-function zoneArtifactCount(compiledPath, zonePath, kind) {
-    const absolutePath = join(compiledPath, zonePath);
-    try {
-        if (kind === "file") {
-            return listFilesRecursive(absolutePath).length > 0 ? 1 : 0;
-        }
-    }
-    catch {
-        if (kind === "file")
-            return 0;
-    }
-    return listFilesRecursive(absolutePath).length;
-}
-function resolveStageContractArtifacts(compiledPath, stageDefinition) {
-    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
-    if (!schema) {
-        throw new Error(`Missing workflow schema for stage "${stageDefinition.id}" at ${workflowPackagePathForCompiled(compiledPath)}.`);
-    }
-    return {
-        reads: compiledContractArtifactPathsForZoneIds(schema, stageDefinition.reads),
-        writes: compiledContractArtifactPathsForZoneIds(schema, stageDefinition.writes),
-    };
-}
-function buildStageCounts(compiledPath, stageDefinition) {
-    const context = resolveCompiledContext(compiledPath);
-    const sourceTotal = discoverSourceFiles(context.sourcePath, compiledPath).totalCount;
-    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
-    const zoneCounts = {};
-    if (schema) {
-        for (const zoneId of new Set([...stageDefinition.reads, ...stageDefinition.writes])) {
-            const zone = findCompiledSchemaZone(schema, zoneId);
-            if (!zone)
-                continue;
-            zoneCounts[zoneId] = zoneArtifactCount(compiledPath, zone.path, zone.kind);
-        }
-    }
-    return {
-        source_total: sourceTotal,
-        read_zone_total: stageDefinition.reads.length,
-        write_zone_total: stageDefinition.writes.length,
-        ...zoneCounts,
-    };
-}
-function buildStageContract(compiledPath, workflowId, stageDefinition) {
-    const config = readInterfConfig(compiledPath);
-    const localSkills = buildLocalSkillContractExtension(compiledPath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use them to refine this workflow stage while still honoring the declared reads, writes, and proof rules.");
-    const instructions = buildStageInstructions(stageDefinition.skillDir, localSkills);
-    const stageArtifacts = resolveStageContractArtifacts(compiledPath, stageDefinition);
-    return buildRuntimeStageContract({
-        compiledName: config?.name ?? "compiled",
-        stageId: stageDefinition.id,
-        stageLabel: stageDefinition.label,
-        counts: buildStageCounts(compiledPath, stageDefinition),
-        stageReadArtifacts: stageArtifacts.reads,
-        stageWriteArtifacts: stageArtifacts.writes,
-        workflowNotes: getActiveCompiledStagePolicyNotes(compiledPath, workflowId, stageDefinition.id),
-        localSkillDocs: localSkills.reads,
-        instructions,
-        acceptance: resolveActiveCompiledStageAcceptance(compiledPath, workflowId, stageDefinition.id),
-    });
-}
-async function runCompiledStage(options) {
-    const context = resolveCompiledContext(options.compiledPath);
-    const stageDefinition = options.stageDefinition;
-    const contract = buildStageContract(options.compiledPath, context.workflowId, stageDefinition);
-    const localSkills = buildLocalSkillContractExtension(options.compiledPath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use them to refine this workflow stage while still honoring the declared reads, writes, and proof rules.");
-    const instructions = buildStageInstructions(stageDefinition.skillDir, localSkills);
-    if (options.reportStep !== false) {
-        reportBlankLine(options.reporter);
-        reportLine(options.reporter, `${formatActiveCompiledWorkflowStageStep(options.compiledPath, context.workflowId, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
-    }
-    const shell = createStageExecutionShell(options.compiledPath, context.compiledName, context.workflowId, stageDefinition, contract.artifacts.writes);
-    try {
-        return await executeValidatedStage({
-            executor: options.executor,
-            compiledPath: options.compiledPath,
-            executionPath: shell.rootPath,
-            targetName: context.compiledName,
-            workflow: context.workflowId,
-            workflowSourcePath: options.compiledPath,
-            stageDefinition,
-            instructions,
-            summary: `Executing ${stageDefinition.label.toLowerCase()}.`,
-            contract,
-            statusLines: [
-                `Emit exactly one startup line: STATUS: loaded ${stageDefinition.label.toLowerCase()} stage.`,
-                "Emit STATUS: reading declared inputs after you confirm the shell contract and local docs.",
-                "Emit STATUS: writing declared outputs after the stage starts updating the compiled zones.",
-                `Emit DONE: ${stageDefinition.id} complete when the declared outputs and proof are on disk.`,
-            ],
-            reporter: options.reporter,
-            completionCheck: () => validateCompiledStage(options.compiledPath, stageDefinition.id).ok,
-            syncWrites: () => syncStageExecutionShellWrites(options.compiledPath, shell.rootPath, stageDefinition, contract.artifacts.writes),
-            reconcile: () => reconcileCompiledStageRun(options.compiledPath, stageDefinition),
-            refreshArtifacts: () => refreshCompiledArtifacts(options.compiledPath, { ensureViewSpec: true }),
-            validate: () => validateCompiledStage(options.compiledPath, stageDefinition.id),
-        });
-    }
-    finally {
-        freezeStageExecutionShell(shell.rootPath);
-    }
-}
-export async function runCompiledSummarize(options) {
-    const context = resolveCompiledContext(options.compiledPath);
-    const stageDefinition = options.stageDefinition
-        ?? compiledExecutionStages(context.workflowId, options.compiledPath).find((stage) => stage.id === "summarize");
-    if (!stageDefinition) {
-        return {
-            ok: false,
-            code: 1,
-            skipped: true,
-            plan: { sourceCount: 0, summaryCount: 0, targetCount: 0 },
-            summary: "Workflow does not declare a summarize stage.",
-        };
-    }
-    const sourceCount = discoverSourceFiles(context.sourcePath, options.compiledPath).totalCount;
-    const result = await runCompiledStage({
-        executor: options.executor,
-        compiledPath: options.compiledPath,
-        reporter: options.reporter,
-        reportStep: options.reportStep,
-        stageDefinition,
-    });
-    return {
-        ...result,
-        skipped: false,
-        plan: {
-            sourceCount,
-            summaryCount: 0,
-            targetCount: sourceCount,
-        },
-    };
-}
-export async function runCompiledCompile(options) {
-    const preserveMode = options.preserveStageShells ?? "on-failure";
-    if (preserveMode !== "always") {
-        pruneStageExecutionShells(options.compiledPath);
-    }
-    let lastResult = { ok: true, code: 0 };
-    try {
-        const context = resolveCompiledContext(options.compiledPath);
-        for (const stageDefinition of compiledExecutionStages(context.workflowId, options.compiledPath)) {
-            const result = await runCompiledStage({
-                executor: options.executor,
-                compiledPath: options.compiledPath,
-                reporter: options.reporter,
-                reportStep: options.reportStep,
-                stageDefinition,
-            });
-            lastResult = result;
-            if (!result.ok)
-                return result;
-        }
-        return lastResult;
-    }
-    finally {
-        if (preserveMode !== "always" && lastResult.ok) {
-            pruneStageExecutionShells(options.compiledPath);
-        }
-    }
-}
-export async function compileCompiled(options) {
-    const preserveMode = options.preserveStageShells ?? "on-failure";
-    if (preserveMode !== "always") {
-        pruneStageExecutionShells(options.compiledPath);
-    }
-    let result = {
-        ok: true,
-        stageResults: {},
-        failedStage: null,
-    };
-    try {
-        const sourceInputPath = resolveSourceInputPath(options.compiledPath);
-        syncCompiledRawSnapshot(options.compiledPath, sourceInputPath);
-        refreshCompiledBootstrapGuidance(options.compiledPath);
-        const workflowValidation = validateWorkflowPackage(join(options.compiledPath, ".interf", "workflow"));
-        if (!workflowValidation.ok) {
-            reportValidationFailure(options.reporter, workflowValidation.summary, workflowValidation.errors);
-            return {
-                ...result,
-                ok: false,
-                failedStage: "workflow",
-                stageResults: {
-                    ...result.stageResults,
-                    workflow: {
-                        ok: false,
-                        code: 1,
-                        summary: workflowValidation.summary,
-                    },
-                },
-            };
-        }
-        const context = resolveCompiledContext(options.compiledPath);
-        const stages = compiledExecutionStages(context.workflowId, options.compiledPath);
-        for (const stageDefinition of stages) {
-            const stageResult = await runCompiledStage({
-                executor: options.executor,
-                compiledPath: options.compiledPath,
-                reporter: options.reporter,
-                reportStep: true,
-                stageDefinition,
-            });
-            result.stageResults[stageDefinition.id] = stageResult;
-            if (!stageResult.ok) {
-                result.ok = false;
-                result.failedStage = stageDefinition.id;
-                return result;
-            }
-        }
-        const workflowValidationResult = validateCompiledWorkflow(options.compiledPath);
-        result.ok = workflowValidationResult.ok;
-        result.failedStage = workflowValidationResult.ok ? null : workflowValidationResult.stage;
-        result.stageResults.compiled = {
-            ok: workflowValidationResult.ok,
-            code: workflowValidationResult.ok ? 0 : 1,
-            summary: workflowValidationResult.summary,
-        };
-        return result;
-    }
-    finally {
-        if (preserveMode !== "always" && result.ok) {
-            pruneStageExecutionShells(options.compiledPath);
-        }
-    }
-}
+export * from "./compiled-target.js";
+export * from "./compiled-stage-plan.js";
+export * from "./compiled-stage-runner.js";
+export * from "./compiled-pipeline.js";

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

@@ -0,0 +1,40 @@
+export declare const COMPILED_INTERF_DIR = ".interf";
+export declare const COMPILED_CONFIG_FILE = "interf.json";
+export declare const COMPILED_WORKFLOW_DIR = "workflow";
+export declare const COMPILED_TEST_DIR = "tests";
+export declare const COMPILED_TEST_TARGETS_DIR = "targets";
+export declare const COMPILED_RUNTIME_DIR = "runtime";
+export declare const COMPILED_RUNTIME_STATE_FILE = "state.json";
+export declare const COMPILED_RUNTIME_HEALTH_FILE = "health.json";
+export declare const COMPILED_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
+export declare const COMPILED_RUNTIME_RAW_SNAPSHOT_FILE = "raw-snapshot.json";
+export declare const COMPILED_RUNTIME_INVENTORY_FILE = "inventory.json";
+export declare const COMPILED_RUNTIME_RUN_FILE = "run.json";
+export declare const COMPILED_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
+export declare const COMPILED_RUNTIME_STAGE_CONTRACT_FILE = "stage-contract.json";
+export declare function compiledRuntimeRoot(compiledPath: string): string;
+export declare function compiledRuntimeFilePath(compiledPath: string, fileName: string): string;
+export declare function compiledInterfRoot(compiledPath: string): string;
+export declare function compiledInterfConfigPath(compiledPath: string): string;
+export declare function workflowPackagePathForCompiled(compiledPath: string): string;
+export declare function testRootForCompiled(compiledPath: string): string;
+export declare function testTargetsRootForCompiled(compiledPath: string): string;
+export declare function stageExecutionShellsRoot(compiledPath: string): string;
+export declare function workflowImprovementLoopsRoot(compiledPath: string): string;
+export declare function workflowImprovementRunRoot(compiledPath: string, runId: string): string;
+export declare function workflowImprovementLoopRoot(compiledPath: string, runId: string, loopIndex: number): string;
+export declare function targetTestRunsRootForCompiled(compiledPath: string): string;
+export declare function targetTestSandboxesRootForCompiled(compiledPath: string): string;
+export declare function compiledRuntimeLogsRoot(compiledPath: string): string;
+export declare function compiledRuntimeArchivedStageContractPath(compiledPath: string, runId: string): string;
+export declare function compiledQueryAcceptanceRoot(compiledPath: string): string;
+export declare function compiledRuntimeStatePath(compiledPath: string): string;
+export declare function compiledRuntimeHealthPath(compiledPath: string): string;
+export declare function compiledRuntimeViewSpecPath(compiledPath: string): string;
+export declare function compiledRawSnapshotMetadataPath(compiledPath: string): string;
+export declare function compiledRuntimeInventoryPath(compiledPath: string): string;
+export declare function compiledRuntimeRunPath(compiledPath: string): string;
+export declare function compiledRuntimeRunHistoryPath(compiledPath: string): string;
+export declare function compiledRuntimeStageContractPath(compiledPath: string): string;
+export declare function resolveSourceControlPathForCompiled(compiledPath: string): string;
+export declare function defaultControlPathForCompiled(compiledPath: string): string;

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

@@ -0,0 +1,106 @@
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+export const COMPILED_INTERF_DIR = ".interf";
+export const COMPILED_CONFIG_FILE = "interf.json";
+export const COMPILED_WORKFLOW_DIR = "workflow";
+export const COMPILED_TEST_DIR = "tests";
+export const COMPILED_TEST_TARGETS_DIR = "targets";
+export const COMPILED_RUNTIME_DIR = "runtime";
+export const COMPILED_RUNTIME_STATE_FILE = "state.json";
+export const COMPILED_RUNTIME_HEALTH_FILE = "health.json";
+export const COMPILED_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
+export const COMPILED_RUNTIME_RAW_SNAPSHOT_FILE = "raw-snapshot.json";
+export const COMPILED_RUNTIME_INVENTORY_FILE = "inventory.json";
+export const COMPILED_RUNTIME_RUN_FILE = "run.json";
+export const COMPILED_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
+export const COMPILED_RUNTIME_STAGE_CONTRACT_FILE = "stage-contract.json";
+export function compiledRuntimeRoot(compiledPath) {
+    return join(compiledPath, COMPILED_INTERF_DIR, COMPILED_RUNTIME_DIR);
+}
+export function compiledRuntimeFilePath(compiledPath, fileName) {
+    return join(compiledRuntimeRoot(compiledPath), fileName);
+}
+export function compiledInterfRoot(compiledPath) {
+    return join(compiledPath, COMPILED_INTERF_DIR);
+}
+export function compiledInterfConfigPath(compiledPath) {
+    return join(compiledInterfRoot(compiledPath), COMPILED_CONFIG_FILE);
+}
+export function workflowPackagePathForCompiled(compiledPath) {
+    return join(compiledInterfRoot(compiledPath), COMPILED_WORKFLOW_DIR);
+}
+export function testRootForCompiled(compiledPath) {
+    return join(compiledInterfRoot(compiledPath), COMPILED_TEST_DIR);
+}
+export function testTargetsRootForCompiled(compiledPath) {
+    return join(testRootForCompiled(compiledPath), COMPILED_TEST_TARGETS_DIR);
+}
+export function stageExecutionShellsRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "execution-shells");
+}
+export function workflowImprovementLoopsRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "improvement-loops");
+}
+export function workflowImprovementRunRoot(compiledPath, runId) {
+    return join(workflowImprovementLoopsRoot(compiledPath), runId);
+}
+export function workflowImprovementLoopRoot(compiledPath, runId, loopIndex) {
+    return join(workflowImprovementRunRoot(compiledPath, runId), `loop-${String(loopIndex).padStart(2, "0")}`);
+}
+export function targetTestRunsRootForCompiled(compiledPath) {
+    return join(testTargetsRootForCompiled(compiledPath), "runs");
+}
+export function targetTestSandboxesRootForCompiled(compiledPath) {
+    return join(testTargetsRootForCompiled(compiledPath), "sandboxes");
+}
+export function compiledRuntimeLogsRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "logs");
+}
+export function compiledRuntimeArchivedStageContractPath(compiledPath, runId) {
+    return join(compiledRuntimeLogsRoot(compiledPath), `${runId}.stage-contract.json`);
+}
+export function compiledQueryAcceptanceRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "query-acceptance");
+}
+export function compiledRuntimeStatePath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_STATE_FILE);
+}
+export function compiledRuntimeHealthPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_HEALTH_FILE);
+}
+export function compiledRuntimeViewSpecPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_VIEW_SPEC_FILE);
+}
+export function compiledRawSnapshotMetadataPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_RAW_SNAPSHOT_FILE);
+}
+export function compiledRuntimeInventoryPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_INVENTORY_FILE);
+}
+export function compiledRuntimeRunPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_RUN_FILE);
+}
+export function compiledRuntimeRunHistoryPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_RUN_HISTORY_FILE);
+}
+export function compiledRuntimeStageContractPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_STAGE_CONTRACT_FILE);
+}
+export function resolveSourceControlPathForCompiled(compiledPath) {
+    let cursor = resolve(compiledPath);
+    while (true) {
+        const parent = dirname(cursor);
+        if (basename(parent) === "interf" &&
+            basename(cursor) !== "tests" &&
+            basename(cursor) !== "workflows") {
+            return dirname(parent);
+        }
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    throw new Error(`Context folder is not under the canonical project layout: ${compiledPath}`);
+}
+export function defaultControlPathForCompiled(compiledPath) {
+    const relativePath = relative(compiledPath, resolveSourceControlPathForCompiled(compiledPath));
+    return relativePath.length > 0 ? relativePath.split(sep).join("/") : ".";
+}