@interf/compiler 0.5.1 → 0.6.3

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 "../../../lib/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,48 @@
+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>;

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

@@ -0,0 +1,256 @@
+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);
+        }
+    }
+}

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 "../../lib/logger.js";
+import { readJsonFileUnchecked } from "../../lib/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/index.d.ts

@@ -0,0 +1,24 @@
+export * as primitives from "./workflow-primitives.js";
+export * as schema from "./lib/schema.js";
+export * as compiledSchema from "./compiled-schema.js";
+export * as compile from "./compiled-compile.js";
+export * as runtime from "./runtime.js";
+export * as runtimeAcceptance from "./runtime-acceptance.js";
+export * as runtimeContracts from "./runtime-contracts.js";
+export * as runtimeInventory from "./runtime-inventory.js";
+export * as runtimePaths from "./runtime-paths.js";
+export * as runtimePrompt from "./runtime-prompt.js";
+export * as runtimeReconcile from "./runtime-reconcile.js";
+export * as runtimeRuns from "./runtime-runs.js";
+export * as runtimeTypes from "./runtime-types.js";
+export * as state from "./state.js";
+export * as stateArtifacts from "./state-artifacts.js";
+export * as stateHealth from "./state-health.js";
+export * as stateIo from "./state-io.js";
+export * as statePaths from "./state-paths.js";
+export * as stateView from "./state-view.js";
+export * as validate from "./validate.js";
+export * as validateCompiled from "./validate-compiled.js";
+export * as validateHelpers from "./validate-helpers.js";
+export * as workflows from "./workflows.js";
+export type { CompiledCompileResult, CompiledSummarizeResult, StageShellRetentionMode, } from "./workflows.js";

package/dist/packages/compiler/index.js

@@ -0,0 +1,23 @@
+export * as primitives from "./workflow-primitives.js";
+export * as schema from "./lib/schema.js";
+export * as compiledSchema from "./compiled-schema.js";
+export * as compile from "./compiled-compile.js";
+export * as runtime from "./runtime.js";
+export * as runtimeAcceptance from "./runtime-acceptance.js";
+export * as runtimeContracts from "./runtime-contracts.js";
+export * as runtimeInventory from "./runtime-inventory.js";
+export * as runtimePaths from "./runtime-paths.js";
+export * as runtimePrompt from "./runtime-prompt.js";
+export * as runtimeReconcile from "./runtime-reconcile.js";
+export * as runtimeRuns from "./runtime-runs.js";
+export * as runtimeTypes from "./runtime-types.js";
+export * as state from "./state.js";
+export * as stateArtifacts from "./state-artifacts.js";
+export * as stateHealth from "./state-health.js";
+export * as stateIo from "./state-io.js";
+export * as statePaths from "./state-paths.js";
+export * as stateView from "./state-view.js";
+export * as validate from "./validate.js";
+export * as validateCompiled from "./validate-compiled.js";
+export * as validateHelpers from "./validate-helpers.js";
+export * as workflows from "./workflows.js";