@interf/compiler 0.6.1 → 0.6.4

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

@@ -0,0 +1,3 @@
+export declare function extractAgentFailureStatus(event: Record<string, unknown>): string | null;
+export declare function classifyTerminalVisibleStatus(text: string | null | undefined): "done" | "failure" | null;
+export declare function hasAgentStalled(lastActivityAt: number, now: number, stallTimeoutMs: number | null | undefined): boolean;

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

@@ -0,0 +1,58 @@
+export function extractAgentFailureStatus(event) {
+    const candidates = [];
+    const directMessage = pickString(event.message) ??
+        pickString(event.text) ??
+        pickString(event.content) ??
+        pickString(event.output) ??
+        pickString(event.summary);
+    if (directMessage)
+        candidates.push(directMessage);
+    const item = event.item;
+    if (item && typeof item === "object") {
+        const itemRecord = item;
+        const itemText = pickString(itemRecord.text);
+        if (itemText)
+            candidates.push(itemText);
+        if (typeof itemRecord.aggregated_output === "string") {
+            candidates.push(itemRecord.aggregated_output);
+        }
+    }
+    for (const candidate of candidates) {
+        const lines = candidate
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        for (const text of lines) {
+            if (text.startsWith("BLOCKED:") || text.startsWith("ERROR:")) {
+                return text;
+            }
+        }
+    }
+    return null;
+}
+export function classifyTerminalVisibleStatus(text) {
+    if (!text)
+        return null;
+    if (text.startsWith("DONE:"))
+        return "done";
+    if (text.startsWith("BLOCKED:") || text.startsWith("ERROR:"))
+        return "failure";
+    return null;
+}
+export function hasAgentStalled(lastActivityAt, now, stallTimeoutMs) {
+    return typeof stallTimeoutMs === "number" && stallTimeoutMs > 0 && now - lastActivityAt >= stallTimeoutMs;
+}
+function pickString(value) {
+    if (typeof value === "string")
+        return value;
+    if (!Array.isArray(value))
+        return null;
+    for (const entry of value) {
+        if (typeof entry === "string")
+            return entry;
+        if (entry && typeof entry === "object" && "text" in entry && typeof entry.text === "string") {
+            return entry.text;
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,30 @@
+import type { WorkflowExecutionProfile } from "./executors.js";
+export interface Agent {
+    name: string;
+    displayName: string;
+    skillsDir: string;
+    command: string;
+}
+export interface AgentPreflightResult {
+    ok: boolean;
+    code: number | null;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+    error: string | null;
+}
+export type AgentSpawnSync = typeof import("node:child_process").spawnSync;
+export interface AgentPreflightOptions {
+    timeoutMs?: number;
+    spawnSyncImpl?: AgentSpawnSync;
+}
+export interface AgentAutomationReadiness {
+    ok: boolean;
+    error?: string;
+}
+export interface SpawnAgentOptions {
+    eventLogPath?: string | null;
+    statusLogPath?: string | null;
+    executionProfile?: WorkflowExecutionProfile;
+    completionCheck?: (() => boolean) | null;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -1,5 +1,6 @@
 import { type InterfUserConfig } from "./schema.js";
 export type { InterfUserConfig } from "./schema.js";
+export declare const INTERF_HOME: string;
 export declare const USER_CONFIG_PATH: string;
 export declare function loadUserConfig(): InterfUserConfig | null;
 export declare function saveUserConfig(config: InterfUserConfig): void;

package/dist/{lib → packages/agents/lib}/user-config.js

@@ -1,8 +1,9 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
-import { INTERF_HOME } from "./config.js";
-import { readJsonFileWithSchema } from "./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");
 export function loadUserConfig() {
     if (!existsSync(USER_CONFIG_PATH))

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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,4 @@
+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("/") : ".";
+}

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

@@ -0,0 +1,39 @@
+import { type WorkflowExecutor } from "../agents/lib/executors.js";
+import { type WorkflowReporter, type WorkflowStageResult } from "../workflow-package/workflow-helpers.js";
+import { type CompiledStageExecutionDefinition } from "./compiled-target.js";
+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 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>;

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

@@ -0,0 +1,134 @@
+import { join } from "node:path";
+import { refreshCompiledBootstrapGuidance, } from "../agents/lib/compiled-bootstrap.js";
+import { validateWorkflowPackage } from "../workflow-package/local-workflows.js";
+import { reportValidationFailure, } from "../workflow-package/workflow-helpers.js";
+import { validateCompiledWorkflow, } from "./validate.js";
+import { pruneStageExecutionShells, } from "../agents/lib/shells.js";
+import { syncCompiledRawSnapshot } from "./raw-snapshot.js";
+import { compiledExecutionStages, resolveCompiledContext, } from "./compiled-target.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { runCompiledStage } from "./compiled-stage-runner.js";
+import { resolveSourceInputPath } from "../project-model/interf-detect.js";
+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);
+        }
+    }
+}

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

@@ -0,0 +1,31 @@
+import { type BuiltinCompiledZoneId } from "../workflow-package/builtin-compiled-workflow.js";
+import { type WorkflowCompiledSchema, type WorkflowCompiledZone, type WorkflowZoneId } from "./lib/schema.js";
+export interface WorkflowSchemaStageLike {
+    id: string;
+    writes: readonly string[];
+}
+export { BUILTIN_COMPILED_ZONE_IDS } from "../workflow-package/builtin-compiled-workflow.js";
+export declare const WORKFLOW_SCHEMA_FILE = "workflow.schema.json";
+export declare function workflowSchemaFilePath(rootPath: string): string;
+export declare function resolveWorkflowSchemaPath(rootPath: string): string | null;
+export declare function workflowSchemaExists(rootPath: string): boolean;
+export declare function workflowSchemaRelativePath(): string;
+export declare function listCompiledSchemaZones(schema: WorkflowCompiledSchema): WorkflowCompiledZone[];
+export declare function findCompiledSchemaZone(schema: WorkflowCompiledSchema, zoneId: WorkflowZoneId): WorkflowCompiledZone | null;
+export declare function compiledZoneAbsolutePath(compiledPath: string, zone: Pick<WorkflowCompiledZone, "path">): string;
+export declare function compiledContractArtifactPath(zone: Pick<WorkflowCompiledZone, "path" | "kind">): string;
+export declare function compiledContractArtifactPathsForZoneIds(schema: WorkflowCompiledSchema, zoneIds: readonly WorkflowZoneId[]): string[];
+export declare function builtinCompiledZoneRelativePath(zoneId: BuiltinCompiledZoneId): string;
+export declare function builtinCompiledZoneAbsolutePath(compiledPath: string, zoneId: BuiltinCompiledZoneId): string;
+export declare function compiledSummariesPath(compiledPath: string): string;
+export declare function compiledKnowledgeEntitiesPath(compiledPath: string): string;
+export declare function compiledKnowledgeClaimsPath(compiledPath: string): string;
+export declare function compiledKnowledgeIndexesPath(compiledPath: string): string;
+export declare function compiledKnowledgeRootPath(compiledPath: string): string;
+export declare function compiledHomePath(compiledPath: string): string;
+export declare function ensureCompiledZoneTargets(compiledPath: string, schema: WorkflowCompiledSchema): void;
+export declare function buildWorkflowSchema(stages: WorkflowSchemaStageLike[], label?: string): WorkflowCompiledSchema;
+export declare function writeWorkflowSchemaFile(rootPath: string, stages: WorkflowSchemaStageLike[], label?: string): WorkflowCompiledSchema;
+export declare function writeWorkflowSchemaDocument(rootPath: string, schema: WorkflowCompiledSchema): WorkflowCompiledSchema;
+export declare function readWorkflowSchemaFile(rootPath: string): WorkflowCompiledSchema | null;
+export declare function readCompiledSchemaFile(rootPath: string): WorkflowCompiledSchema | null;

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

@@ -0,0 +1,141 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { warnInterf } from "../shared/logger.js";
+import { readJsonFileUnchecked } from "../shared/parse.js";
+import { BUILTIN_COMPILED_ZONE_IDS, listBuiltinCompiledZoneSpecs, requiredCompiledZoneOwners, } from "../workflow-package/builtin-compiled-workflow.js";
+import { WorkflowCompiledSchemaSchema, } from "./lib/schema.js";
+export { BUILTIN_COMPILED_ZONE_IDS } from "../workflow-package/builtin-compiled-workflow.js";
+export const WORKFLOW_SCHEMA_FILE = "workflow.schema.json";
+const BUILTIN_COMPILED_ZONE_SPEC_BY_ID = new Map(listBuiltinCompiledZoneSpecs().map((zone) => [zone.id, zone]));
+export function workflowSchemaFilePath(rootPath) {
+    return join(rootPath, WORKFLOW_SCHEMA_FILE);
+}
+export function resolveWorkflowSchemaPath(rootPath) {
+    const path = workflowSchemaFilePath(rootPath);
+    return existsSync(path) ? path : null;
+}
+export function workflowSchemaExists(rootPath) {
+    return existsSync(workflowSchemaFilePath(rootPath));
+}
+export function workflowSchemaRelativePath() {
+    return `workflow/${WORKFLOW_SCHEMA_FILE}`;
+}
+export function listCompiledSchemaZones(schema) {
+    return [...schema.zones];
+}
+export function findCompiledSchemaZone(schema, zoneId) {
+    return schema.zones.find((zone) => zone.id === zoneId) ?? null;
+}
+export function compiledZoneAbsolutePath(compiledPath, zone) {
+    return join(compiledPath, zone.path);
+}
+export function compiledContractArtifactPath(zone) {
+    if (zone.kind === "file")
+        return zone.path;
+    return zone.path.endsWith("/") ? zone.path : `${zone.path}/`;
+}
+export function compiledContractArtifactPathsForZoneIds(schema, zoneIds) {
+    return zoneIds.map((zoneId) => {
+        const zone = findCompiledSchemaZone(schema, zoneId);
+        if (!zone) {
+            throw new Error(`Compiled schema is missing declared zone "${zoneId}".`);
+        }
+        return compiledContractArtifactPath(zone);
+    });
+}
+export function builtinCompiledZoneRelativePath(zoneId) {
+    const zone = BUILTIN_COMPILED_ZONE_SPEC_BY_ID.get(zoneId);
+    if (!zone) {
+        throw new Error(`Missing built-in compiled zone "${zoneId}".`);
+    }
+    return zone.path;
+}
+export function builtinCompiledZoneAbsolutePath(compiledPath, zoneId) {
+    return join(compiledPath, builtinCompiledZoneRelativePath(zoneId));
+}
+export function compiledSummariesPath(compiledPath) {
+    return builtinCompiledZoneAbsolutePath(compiledPath, BUILTIN_COMPILED_ZONE_IDS.SUMMARIES);
+}
+export function compiledKnowledgeEntitiesPath(compiledPath) {
+    return builtinCompiledZoneAbsolutePath(compiledPath, BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_ENTITIES);
+}
+export function compiledKnowledgeClaimsPath(compiledPath) {
+    return builtinCompiledZoneAbsolutePath(compiledPath, BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_CLAIMS);
+}
+export function compiledKnowledgeIndexesPath(compiledPath) {
+    return builtinCompiledZoneAbsolutePath(compiledPath, BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_INDEXES);
+}
+export function compiledKnowledgeRootPath(compiledPath) {
+    return dirname(compiledKnowledgeEntitiesPath(compiledPath));
+}
+export function compiledHomePath(compiledPath) {
+    return builtinCompiledZoneAbsolutePath(compiledPath, BUILTIN_COMPILED_ZONE_IDS.HOME);
+}
+export function ensureCompiledZoneTargets(compiledPath, schema) {
+    for (const zone of schema.zones) {
+        if (zone.kind === "directory" || zone.kind === "runtime") {
+            mkdirSync(compiledZoneAbsolutePath(compiledPath, zone), { recursive: true });
+            continue;
+        }
+        mkdirSync(dirname(compiledZoneAbsolutePath(compiledPath, zone)), { recursive: true });
+    }
+}
+function pushZone(zones, zone) {
+    if (zones.some((existing) => existing.path === zone.path))
+        return;
+    zones.push(zone);
+}
+function normalizeWorkflowSchema(schema) {
+    return {
+        ...schema,
+        kind: "workflow-schema",
+    };
+}
+export function buildWorkflowSchema(stages, label = "Workflow schema") {
+    const zones = [];
+    for (const zone of listBuiltinCompiledZoneSpecs()) {
+        pushZone(zones, {
+            id: zone.id,
+            role: zone.role,
+            path: zone.path,
+            kind: zone.kind,
+            required: zone.required,
+            owned_by: requiredCompiledZoneOwners(stages, zone.id),
+            description: zone.description,
+        });
+    }
+    return {
+        kind: "workflow-schema",
+        version: 1,
+        target_type: "compiled",
+        label,
+        zones,
+    };
+}
+export function writeWorkflowSchemaFile(rootPath, stages, label) {
+    const schema = buildWorkflowSchema(stages, label);
+    writeWorkflowSchemaDocument(rootPath, schema);
+    return schema;
+}
+export function writeWorkflowSchemaDocument(rootPath, schema) {
+    const normalized = normalizeWorkflowSchema(schema);
+    writeFileSync(workflowSchemaFilePath(rootPath), `${JSON.stringify(normalized, null, 2)}\n`);
+    return normalized;
+}
+export function readWorkflowSchemaFile(rootPath) {
+    const path = workflowSchemaFilePath(rootPath);
+    if (!existsSync(path))
+        return null;
+    const raw = readJsonFileUnchecked(path, "workflow schema");
+    if (raw === null)
+        return null;
+    const parsed = WorkflowCompiledSchemaSchema.safeParse(raw);
+    if (!parsed.success) {
+        warnInterf(`Warning: failed to validate workflow schema at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    return normalizeWorkflowSchema(parsed.data);
+}
+export function readCompiledSchemaFile(rootPath) {
+    return readWorkflowSchemaFile(rootPath);
+}

package/dist/packages/compiler/compiled-stage-plan.d.ts

@@ -0,0 +1,15 @@
+import { type RuntimeStageContractDraft } from "./runtime.js";
+import { type CompiledWorkflowId, type WorkflowStageDefinition } from "../workflow-package/workflow-definitions.js";
+import { resolveCompiledContext, type CompiledStageExecutionDefinition } from "./compiled-target.js";
+import type { RuntimeStageInstructions } from "./lib/schema.js";
+export declare function resolveStageContractArtifacts(compiledPath: string, stageDefinition: Pick<WorkflowStageDefinition, "id" | "reads" | "writes">): {
+    reads: string[];
+    writes: string[];
+};
+export declare function buildStageCounts(compiledPath: string, stageDefinition: WorkflowStageDefinition): Record<string, number>;
+export declare function buildStageContract(compiledPath: string, workflowId: CompiledWorkflowId, stageDefinition: WorkflowStageDefinition, instructions: RuntimeStageInstructions): RuntimeStageContractDraft;
+export declare function buildCompiledStageExecutionPlan(compiledPath: string, stageDefinition: CompiledStageExecutionDefinition): {
+    context: ReturnType<typeof resolveCompiledContext>;
+    contract: RuntimeStageContractDraft;
+    instructions: RuntimeStageInstructions;
+};